MindConnect Library – 接口和引用¶

客户端应用使用 MCL 收集数据并将其发送到 MindSphere。为使用 MCL，需要在应用中包含其导出的接口（消息头文件），这些接口位于 {MCL_PROJECT_FOLDER}/include/mcl/*.h 中。

您只需在客户端应用中包含 mcl.h，其本身涵盖所有其它所需的消息头文件。

大多数 MCL 函数会返回一个错误码，客户端应用可以根据该错误码作出响应。请参见 mcl_common.h 和 Doxygen 文档获取完整的错误码列表及其说明。有关特定函数返回的错误码，请参见 Doxygen 文档中的函数引用。

通常，MCL 接口可根据其上下文划分为以下模块。有关各函数的参数的详细信息，请参见相关文档。

模块：配置¶

此模块用于为 MCL 提供在其初始化阶段使用的各种配置参数。

mcl_configuration_t 是一个定义的结构，包含以下条目：

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
主机名在使用 Launchpad 获取的配置对象中作为 baseURL 提供。此参数必填。

mindsphere_port
端口号，通常为 443。此参数可选，默认为 443，指向 https mindsphere_hostname。

mindsphere_certificate
MindSphere 证书是一个 PEM 格式的字符串。MCL 使用此证书来验证服务器身份。用户可以使用此参数提供根证书或完整证书链，因为这两种情况也会验证服务器身份。mindsphere_certificate 参数可选，默认为 NULL。在此情况下，MCL 尝试使用 CA 证书存储（在构建所需的 http 客户端时提供，默认为 libcurl）来验证服务器身份。单击此处获取 MindSphere Root CA 证书。

proxy_hostname
代理服务器的主机名，适用于通过代理服务器与 MindSphere 建立连接的情况。此参数可选，默认为 NULL。若设置为 NULL，MCLL 将忽略以下参数：proxy_port、proxy_type、proxy_username、proxy_password、proxy_domain。

proxy_port
代理服务器的端口号。如果提供了 proxy_hostname，则必须指定此参数。

proxy_type
代理服务器的类型。此参数可选，仅在提供 proxy_hostname 时有效。此参数默认为 MCL_PROXY_UNKNOWN。 请参见 mcl_common.h 中定义的 E_MCL_PROXY 类型了解可用选项。

proxy_username
代理服务器中使用的用户名。此参数可选，默认为 NULL。最多仅限 32 个字符。

proxy_password
proxy_username 的密码。如果提供了 proxy_username，则必须指定此参数。最多仅限 32 个字符。

proxy_domain
proxy_username 的域名。此参数可选，仅在提供 proxy_hostname 时有效。最多仅限 256 个字符。

security_profile
用于与 MindSphere 通信的安全配置文件。此参数可选，默认为 MCL_SECURITY_SHARED_SECRET，也可以设置为 MCL_SECURITY_RSA_3072。

max_http_payload_size
有效载荷的最大值（单位：字节），用于 MCL 发出的所有 HTTP 请求。用户可以使用此参数根据其系统限制调整 HTTP 请求的大小。此参数可选，默认为 16384，最小值和最大值分别为 400 和 10485760。

http_request_timeout
HTTP 请求的超时值（单位：秒）。此参数可选，默认为 300 秒。

user_agent
用户代理字符串，在 HTTP 请求的 User-Agent 消息头中使用，与 MCL 的版本字符串共同构成前缀。此参数必填，最多仅限 256 个字符。

tenant
MindSphere 上的租户名称。此参数必填。

initial_access_token
初始访问令牌，在使用 Launchpad 获取的配置对象中提供。对于首次上线的代理，必须指定此参数。 只有当 load_function 或 store_path 参数没有提供注册信息时，MCL 才使用此参数。

store_path
加载和保存注册信息的文件路径。此参数可选，默认为 NULL。如果设置了 save_function 和 load_function 参数，可忽略此参数。
如果回调设置为 NULL 且设置了 store_path 参数，MCL 将打开并读取 store_path 指定的文件以检查是否存在注册信息。 如果存在注册信息，MCL 将初始化为“已上线”。如果没有注册信息，必须提供有效的 initial_access_token 才能上线。注册产品将保存到 store_path。 如果回调设置为 NULL 且未设置 store_path，则使用 initial_access_token 参数进行上线，但不会保存注册产品。然而，mcl_communication_t 句柄在销毁之前将始终正常运行。此时，MCL 不会返回错误，但会在 MCL_LOG_UTIL_LEVEL_INFO 日志级别报告该情况。

load_function
用户提供的函数，用于在 MCL 初始化时加载注册信息。此参数可选，默认为 NULL。仅当定义 save_function 参数时，此参数才有效。save_function 和 load_function 中的任何一个参数设置为 NULL，这两个参数将同时被忽略。
有关函数签名，请参见 mcl_common.h。
此函数可为提供给它的每个参数设置值，设置成功后返回 MCL_OK。
如果没有可用的注册信息，此函数将返回 MCL_REGISTRATION_INFO_IS_NOT_LOADED，MCL 必须使用 initial_access_token 参数进行首次上线。
如果失败，此函数将返回 MCL_FAIL。

save_function
用户提供的函数，用于在上线后保存注册信息。此参数可选，默认为 NULL。仅当定义 load_function 参数时，此参数才有效。save_function 和 load_function 中的任何一个参数设置为 NULL，这两个参数将同时被忽略。
有关函数签名，请参见 mcl_common.h。
如果成功，此函数将返回 MCL_OK。
如果失败，此函数将返回 MCL_FAIL。
如果未保存注册产品，则在销毁 mcl_communication_t 句柄后，代理必须使用新的 initial_access_token 再次进行上线。

enter_critical_section
用户提供的函数，当进入 MCL 的关键部分（访问密钥、令牌等注册信息）时，在 MCL 内部调用。 此参数可选，默认为 NULL。只有在需要并发编程时指定此参数。

leave_critical_section
用户提供的函数，当离开 MCL 的关键部分（访问密钥、令牌等注册信息）时，在 MCL 内部调用。 此参数可选，默认为 NULL。只有在需要并发编程时指定此参数。

使用 mcl_configuration_initialize 函数创建 mcl_configuration_t 实例并分配参数。将 mcl_configuration_t 实例传给 mcl_communication_initialize 函数以初始化 MCL。

在 MCL 完成初始化后，可以使用 mcl_configuration_destroy 函数销毁 mcl_configuration_t 实例。

模块：通信¶

此模块用于与 MindSphere 进行通信。

要获得 mcl_communication_t 类型的通信句柄，需要调用提供配置参数 (mcl_configuration_t) 的 mcl_communication_initialize 函数。该句柄由此模块中的其它函数使用。

MindSphere 上的所有新建代理都需要使用 mcl_communication_onboard 函数进行上线，然后才能交换数据。

密钥过期后，已上线的代理可以使用 mcl_communication_rotate_key 函数轮换密钥。

拥有有效密钥的已上线代理可以使用 mcl_communication_get_access_token 函数获取访问令牌进行交换调用。您还可以在 mcl_communication_onboard 和 mcl_communication_rotate_key 函数中调用 mcl_communication_get_access_token 函数。

在与 MindSphere 交换数据前，应准备一个 mcl_store_t 类型的存储，其中包含需要上传的所有数据。有关存储初始化以及在存储中添加数据的详细信息，请参见下一节。

mcl_communication_exchange 和 mcl_communication_process 函数都可用于交换数据。此外，mcl_communication_process 函数会在访问令牌过期后自动更新访问令牌，并在客户端密钥到期后轮换密钥，然后重新执行交换操作。

模块：存储¶

此模块用于提供与 MindSphere 进行交换的数据。

在与 MindSphere 交换数据前，必须将需要交换的所有类型的数据添加到存储（即数据容器）中。初始化存储后，可以向其添加时间序列、事件或文件等新条目。存储准备就绪后，即可使用通信模块开始交换操作。

模块：时间序列¶

此模块用于在存储模块创建的时间序列内添加或修改条目。

模块：流数据¶

此模块用于在存储模块创建的流数据内添加或修改条目。流数据通过回调函数提供。

模块：数据源配置¶

此模块用于在存储模块创建的数据源配置内添加或修改条目。

模块：Json util¶

此模块用于创建可供其它 MCL 模块使用的 json 字符串。

模块：Random¶

此模块提供用于生成全局唯一标识符的函数。

模块：记录¶

此模块用于配置日志记录行为。在编译 MCL 期间，将删除日志级别低于所选日志级别的日志消息，并替换为无操作指令。此操作可缩小 MCL 的容量。如需设置编译的日志级别，请参见上述 CMake 命令选项中的 MCL_LOG_UTIL_LEVEL 选项。

编译日志级别会影响运行时的日志级别，例如，如果编译日志级别设置为 ERROR，则在运行时不会提供 DEBUG 日志消息。在此示例中，运行时可用的日志级别只能为 ERROR、FATAL 或 NONE。

模块：事件¶

此模块用于为需要上传到 MindSphere 的事件设置可选参数。