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
MindSphere 的主机名在使用 MindSphere Launchpad 获取的配置对象中作为 baseURL 提供。此参数必填。
mindsphere_port
MindSphere 的端口号,通常为 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
初始访问令牌,在使用 MindSphere 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
日志级别报告该情况。
说明
使用 store_path
参数保存和加载注册产品并不安全。建议用户通过 load_function
和 save_function
提供安全回调。
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
实例。
说明
出于安全原因,请使用回调函数 load_function
和 save_function
来保存和加载注册产品,不要使用 store_path
。
模块:通信
此模块用于与 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 的事件设置可选参数。
还有问题?
除非另行声明,该网站内容遵循MindSphere开发许可协议.