The libirc library provides the KVM client development kit for the openUBMC community to enable users to integrate the KVM functions into tools and systems and call the interfaces provided by the libirc library to use and operate the KVM client.

For details about how to set up the compilation environment, see the libirc library README file.

Function Introduction ​

Integrating the libirc library allows you to send encapsulated WebSocket requests to the BMC (acting as the server). It enables connection establishment, operation execution, and connection termination to be easily integrated into the user's system via interface calls.

Currently, the libirc library supports the following functions:

• Authentication

  • Based on the Boost open-source software and OpenSSL, send an HTTPS POST request to /UI/Rest/KvmHandler to create a KVM session and obtain the token and KVM port number.

• WebSocket connection creation

  • Establish a WebSocket connection with the KVM server based on the Boost open-source software and OpenSSL.
  • Use the token obtained in the authentication phase to encapsulate KVM authentication packets and send them to the server to authenticate KVM sessions.
  • After the authentication, the heartbeat detection mechanism is started to periodically send encapsulated KVM heartbeat packets.
  • Receive KVM protocol packets sent by the service, parse the packets, and distribute them to other services for processing.
  • When the connection is closed, send the encapsulated KVM disconnection packet.

• BIOS boot option control

  • After the KVM is connected, the current configuration of the BIOS boot option is proactively obtained.
  • After receiving the BIOS boot option configuration response packet, update the current configuration of the BIOS boot option.
  • Encapsulate the BIOS boot option packet based on user input and send the packet to the KVM server.

• Power control

  • Encapsulate the power control packet based on user input and send the packet to the KVM server.

• Virtual CD/DVD-ROM drive control

  • Encapsulate virtual CD/DVD-ROM drive control packets based on user input and send the packets to the KVM server. The operation type includes removing and mounting virtual media.

After calling the interface, the client performs subsequent customized operations based on the return code of the interface.

Key Interfaces ​

The libirc library provides the following key interfaces to enable and disable KVM sessions and perform CD/DVD-ROM drive operations.

Key Interface Functions ​

• void SetErrorHandler(std::function<void(const std::exception&)> handler)

  The function is used to configure a custom error handler. The input parameter is the handler function, which itself accepts an exception parameter for customizing runtime error processing.

• void SetCloseHandler(std::function<void(const uint16_t&)> handler)

  The function is used to configure a close handler. The input parameter is the handler function, which itself accepts a KVM session close status code. For details about the definition, see [WebSocket Protocol Close Status Code](#WebSocket Protocol Close Status Code). This function is used to customize the processing of KVM session close.

• void SetLogHandler(std::function<void(const std::string&)> handler)

  The function is used to configure a log handler. The input parameter is the handler function, which itself accepts a log string for customizing runtime log processing.

• int OpenKvm(const char* host, const char* port, const char* userName, const char* password, const char* kvmMode)

  This function is used to open a KVM session. The input parameters are the host IP address, HTTPS port number, username, password, and KVM connection mode (0: shared; 1: exclusive). The output parameters are error codes. For details, see [Response Code](#Response Code).

• int CloseKvm()

  This function is used to close a KVM session. The output parameter is an error code. For details, see [Response Code](#Response Code).

• int GetBootOption(BootOption& option)

  This function is used to obtain the current system boot option. If successfully obtained, the result is set to the input reference. For details about the BootOption enumeration type definition, see [System Boot Option Definition](#System Boot Option Definition). The output parameter is the error response code.

• int SetBootOption(BootOption option)

  Sets the system boot option. The input parameter is the system boot option of the BootOption enumeration type, and the output parameter is an error code. For details about the error code definition, see [Response Code](#Response Code).

• int PowerControl(PowerControlOption option)

  This function is used for power control. The input parameter is the power control item of the PowerControlOption enumeration type. For details about the definition, see [Definition of Power Control Items](#Definition of Power Control Items). The output parameter is an error code. For details, see [Response Code](#Response Code).

• int OpenVmm(const std::string& filePath, MountType type)

  This function is used to mount VMM virtual media. The input parameters include the local image file path and mounting type. Currently, only image files can be mounted. The output parameter is an error code. For details, see [Response Code](#Response Code).

• int CloseVmm()

  This function is used to unload VMM virtual media. The output parameter is an error code. For details, see [Response Code](#Response Code).

Response Code ​

The libirc library defines 13 response codes, which are listed below.

WebSocket Protocol Close Status Code ​

When a WebSocket connection is closed, a close status code is returned. Customized processing is then performed based on the processing function registered via SetCloseHandler for different close status codes. The following table lists the close status codes.

By calling SetHandler to register the processing functions of the preceding status codes, customized processing can be implemented when the WebSocket connection is disconnected. For example, exit the KVM client when the connection is disconnected normally (close status code 1000), wait for a period of time when the server is being restarted (close status code 1012), and display a message when WebSocket connections are excessive (close status code 4000).

System Boot Option Definition ​

The libirc library defines six system boot options, which are listed below.

When the system boot option is successfully obtained, the input parameter of the enumeration type BootOption is set to one of the preceding boot options.

When the system boot option is set, the expected boot option needs to be transferred as the input parameter.

Power Control Item Definition ​

The libirc library defines six power control items, which are listed below.

During power control, the expected power control item needs to be transferred as an input parameter.

Example ​

The libirc code repository provides a simple demo. Run the demo to execute all external interfaces provided by the libirc library based on the command output.

The following uses GetBootOption as an example:

void handleGetBootOption(KvmClient& kvmClient) {
    BootOption option; // Initialize BootOption enumeration types.
    int result = kvmClient.GetBootOption(option); // Option is passed to GetBootOption as an input parameter, the result is stored in option, and the return code is received by result.
    // Process the scenario that fails to be executed.
    if (result != 0) {
        std::cerr << "Failed to get boot option, errorCode: " << result << "\n";
        return;
    }

    std::cout << "Current boot option: ";
    // Convert the value of the BootOption enumeration type to its corresponding meaning for output.
    switch (option) {
        case BootOption::None: std::cout << "None\n"; break;
        case BootOption::Hdd: std::cout << "Hdd\n"; break;
        case BootOption::Cd: std::cout << "Cd\n"; break;
        case BootOption::Floppy: std::cout << "Floppy\n"; break;
        case BootOption::Pxe: std::cout << "Pxe\n"; break;
        case BootOption::BiosSetup: std::cout << "BiosSetup\n"; break;
        default: std::cout << "Unknown\n"; break;
    }
}