MindConnect Library – Interfaces and References¶

The MCL is used by client applications to collect data and send them to Insights Hub. To use it, you need to include its exported interfaces (header files), which are located in {MCL_PROJECT_FOLDER}/include/mcl/*.h.

In your client application you only need to include mcl.h which internally includes all other required header files.

Most of the MCL functions return an error code which can be used by the client application to react accordingly. The complete list of error codes together with their descriptions can be found in mcl_common.h as well as in the Doxygen documentation. For error codes returned by a specific function, refer to the function reference in the Doxygen documentation.

The MCL interfaces are basically divided based on their context into the following modules. For more information about the parameters of each function refer to the documentation.

Module: Configuration¶

This module can be used to provide MCL with various configuration parameters which are used in its initialization phase.

mcl_configuration_t is a defined struct with the following entries:

typedef struct mcl_configuration_t
{
    char *mindsphere_hostname;
    mcl_uint16_t mindsphere_port;
    char *mindsphere_certificate;
    char *proxy_hostname;
    mcl_uint16_t proxy_port;
    E_MCL_PROXY proxy_type;
    char *proxy_username;
    char *proxy_password;
    char *proxy_domain;
    E_MCL_SECURITY_PROFILE security_profile;
    mcl_size_t max_http_payload_size;
    char *user_agent;
    char *initial_access_token;
    char *tenant;
    char *store_path;
    mcl_load_registration_information_callback_t load_function;
    mcl_save_registration_information_callback_t save_function;
    mcl_enter_critical_section_callback_t enter_critical_section;
    mcl_leave_critical_section_callback_t leave_critical_section;
} mcl_configuration_t;

mindsphere_hostname
Host name provided as baseURL in the configuration object obtained using Launchpad. This parameter is mandatory.

mindsphere_port
Port number which is typically 443. This parameter is optional and set to 443 for an https mindsphere_hostname by default.

mindsphere_certificate
Certificate of Insights Hub as a PEM formatted string. This certificate is used by MCL to verify server identity. Users can provide the root certificate or the full certificate chain with this parameter instead, since server identity is verified in these two cases as well. The parameter mindsphere_certificate is optional and set to NULL by default. In this case, MCL tries to use CA certificate store (provided at build-time of the http client used which is libcurl by default) to verify server identity. Insights Hub Root CA Certificate can be found here.

proxy_hostname
Host name of the proxy server, if the connection to Insights Hub is to be established via a proxy. This parameter is optional and set to NULL by default. If this parameter is NULL, MCLL ignores the parameters proxy_port, proxy_type, proxy_username, proxy_password, and proxy_domain.

proxy_port
Port number of the proxy server. This parameter is mandatory, if proxy_hostname is provided.

proxy_type
Type of the proxy server. This parameter is optional and only effective if proxy_hostname is provided. It is set to MCL_PROXY_UNKNOWN by default. Refer to the E_MCL_PROXY type defined in mcl_common.h for available options.

proxy_username
User name used in proxy server. This parameter is optional and set to NULL by default. It is limited to a maximum of 32 characters.

proxy_password
Password for proxy_username. This parameter is mandatory, if proxy_username is provided. It is limited to a maximum of 32 characters.

proxy_domain
Domain for proxy_username. This parameter is optional and only effective if proxy_hostname is provided. It is limited to a maximum of 256 characters.

security_profile
Security profile for the communication with Insights Hub. This parameter is optional and set to MCL_SECURITY_SHARED_SECRET by default. Alternatively, it can be set MCL_SECURITY_RSA_3072.

max_http_payload_size
Maximum payload size in bytes which will be used for all HTTP requests by MCL. With this parameter, users can adjust the size of HTTP requests depending on their system limitations. This parameter is optional and set to 16384 by default. Its minimum and maximum values are 400 and 10485760.

http_request_timeout
Timeout value for HTTP requests in seconds. This parameter is optional and set to 300 seconds by default.

user_agent
User agent string which is used in the User-Agent header of HTTP requests together with MCL's version string as prefix. This parameter is mandatory and limited to a maximum 256 characters.

tenant
Environment name on Insights Hub. This parameter is mandatory.

initial_access_token
Initial access token provided in the configuration object obtained using Launchpad. This parameter is mandatory for agents which onboard for the first time. It is used by MCL only if registration information is not provided by the load_function or the store_path parameter.

store_path
Path of the file to load and save registration information. This parameter is optional and set to NULL by default. It is ignored, if both save_function and load_function parameters are set.
If callbacks are set to NULL and the store_path parameter is set, the file specified by store_path is opened and read to check if registration information exists. If registration information exists, MCL is initialized as already onboarded. If registration information does not exist, a valid initial_access_token is required to onboard. The registration artifacts will be saved to store_path.
If callbacks are set to NULL and store_path is not set, the initial_access_token parameter is used to onboard, but registration artifacts will not be saved. However, the mcl_communication_t handle will be fully operational until it is destroyed. MCL will not return an error in this case but report the situation with on log level MCL_LOG_UTIL_LEVEL_INFO.

load_function
User provided function to be used when loading registration information during the initialization of MCL. This parameter is optional and set to NULL by default. It is only effective if the save_function parameter is defined as well. If any one of save_function and load_function is NULL, both of them are ignored.
Refer to mcl_common.h for the function signature.
The function is expected to set values for every argument provided to it and return MCL_OK in case of success.
The function is expected to return MCL_REGISTRATION_INFO_IS_NOT_LOADED in case there is no registration information available and MCL has to use the initial_access_token parameter to onboard for the first time.
The function is expected to return MCL_FAIL in case of a failure.

save_function
User provided function to save registration information after onboarding. This parameter is optional and set to NULL by default. It is only effective if the load_function parameter is defined as well. If any one of save_function and load_function is NULL, both of them are ignored.
Refer to mcl_common.h for the function signature.
The function is expected to return MCL_OK in case of success.
The function is expected to return MCL_FAIL in case of failure.
If the registration artifacts are not saved, the agent has to onboard again with a new initial_access_token after the mcl_communication_t handle is destroyed.

enter_critical_section
User provided function which is called internally by MCL when entering the critical section in MCL, where registration information (keys, token, etc.) is accessed. This parameter is optional and set to NULL by default. It is only needed if concurrent programming is required.

leave_critical_section
User provided function which is called internally by MCL when leaving the critical section in MCL, where the registration information (keys, token, etc.) is accessed. This parameter is optional and set to NULL by default. It is only needed if concurrent programming is required.

Create an mcl_configuration_t instance using the mcl_configuration_initialize function and assign each parameter. Pass the mcl_configuration_t instance to the mcl_communication_initialize function to initialize MCL.

You may destroy the mcl_configuration_t instance using mcl_configuration_destroy function once MCL is initialized.

Module: Communication¶

This module can be used to communicate with Insights Hub.

In order to obtain a communication handle of type mcl_communication_t, call the function mcl_communication_initialize providing configuration parameters (mcl_configuration_t). This handle is used by other functions in this module.

Every newly created agent on Insights Hub needs to be onboarded using the mcl_communication_onboard function before it can exchange any data.

Onboarded agents can rotate their keys using the mcl_communication_rotate_key function when their keys expire.

Onboarded agents with valid keys can get an access token for exchange calls using the mcl_communication_get_access_token function. The mcl_communication_get_access_token function is also called within the mcl_communication_onboard and mcl_communication_rotate_key functions.

Before data exchange with Insights Hub is possible, a store of type mcl_store_t must be prepared, which contains all data to be uploaded. Refer to the next section for details about initializing and adding data to a store.

Both the mcl_communication_exchange and the mcl_communication_process function exchange data. In addition, the mcl_communication_process function automatically renews the access token if it expires, rotates key if the client secret expires and retries the exchange operation afterwards.

Module: Store¶

This module can be used to provide data to be exchanged with Insights Hub.

Any type of data to be exchanged with Insights Hub must first be added into a store, which is a data container. After initialization, a store can be used to add new items like time series, event or file to it. When the store is ready to be exchanged, you may use the communication module to start the exchange operation.

Module: Time series¶

This module can be used to add/modify entries inside a time series which is created by the store module.

Module: Stream data¶

This module can be used to add/modify entries inside a stream data which is created by the store module. Stream data is provided via a callback function.

Module: Data source configuration¶

This module can be used to add/modify entries inside a data source configuration which is created by the store module.

Module: Json util¶

This module can be used to create json strings which may be used by other MCL modules.

Module: Random¶

This module provides a function to generate globally unique identifiers.

Module: Logging¶

This module can be used to configure logging behavior. Log messages for a lower log level than the selected one are removed during compilation of MCL and replaced by a no-op instruction. This reduces the size of the MCL. In order to set the log level for compilation, refer to the option MCL_LOG_UTIL_LEVEL in above CMake command options.

The compilation log level shadows the runtime log level, e.g., if the compilation log level is set to ERROR no DEBUG log messages are available at runtime. In this example the only log levels available at runtime are ERROR, FATAL or NONE.

Module: Event¶

This module can be used to set optional parameters of an event to be uploaded to Insights Hub.