Communication module interface header file. More...
Go to the source code of this file.
Typedefs | |
typedef struct mcl_communication_t | mcl_communication_t |
Communication module interface header file.
Definition in file mcl_communication.h.
typedef struct mcl_communication_t mcl_communication_t |
This data structure is the main handle for Agent - MindSphere communication.
Definition at line 31 of file mcl_communication.h.
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_destroy | ( | mcl_communication_t ** | communication | ) |
This function destroys the mcl_communication_t
object and frees any memory allocated.
[in] | communication | Preinitialized mcl_communication_t object to destroy. |
Definition at line 241 of file communication.c.
References ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, http_processor_destroy(), MCL_DEBUG, MCL_FREE, MCL_NULL, MCL_OK, and string_destroy().
Referenced by mcl_communication_initialize().
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_exchange | ( | mcl_communication_t * | communication, |
mcl_store_t * | store, | ||
void ** | reserved | ||
) |
This function exchanges data in store
to MindSphere.
[in] | communication | Preinitialized mcl_communication_t object through which a connection is established to MindSphere. |
[in] | store | Container for the data to be uploaded to MindSphere. |
[out] | reserved | Reserved for future use. |
communication
is not initialized. communication
. communication
does not have an access token. store
has no data. Definition at line 473 of file communication.c.
References ASSERT_CODE_MESSAGE, ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, http_processor_exchange(), http_processor_stream(), mcl_communication_is_initialized(), mcl_communication_is_onboarded(), MCL_NO_ACCESS_TOKEN_EXISTS, MCL_NOT_INITIALIZED, MCL_NOT_ONBOARDED, MCL_NULL, and MCL_TRUE.
Referenced by mcl_communication_process().
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_get_access_token | ( | mcl_communication_t * | communication | ) |
This function is used to get access token from MindSphere. The access token contains the necessary authentication credentials for further exchange requests. The agent can use this function to get a new access token when mcl_communication_exchange function returns MCL_UNAUTHORIZED or MCL_NO_ACCESS_TOKEN_EXISTS error code. The agent can use mcl_communication_rotate_key function to renew its secret key if mcl_communication_get_access_token function returns MCL_BAD_REQUEST. A new access token will be automatically obtained by MCL after successful onboarding or key rotation so that the agent does not need to call mcl_communication_get_access_token after a call to mcl_communication_onboard and mcl_communication_rotate_key functions.
[in] | communication | mcl_communication_t object which is initialized and onboarded to MindSphere. |
communication
is NULL. communication
is not initialized. communication
. Definition at line 456 of file communication.c.
References ASSERT_CODE_MESSAGE, ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, http_processor_get_access_token(), mcl_communication_is_initialized(), mcl_communication_is_onboarded(), MCL_NOT_INITIALIZED, MCL_NOT_ONBOARDED, and MCL_TRUE.
Referenced by mcl_communication_process().
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_get_last_access_token | ( | mcl_communication_t * | communication, |
char ** | token | ||
) |
Returns the lastly received oauth access token, NULL if server time is not received.
[in] | communication | Preinitialized mcl_communication_t object through which a connection is established to MindSphere. |
[out] | token | The lastly received oauth access token. |
communication
does not have an access token. Definition at line 626 of file communication.c.
References ASSERT_CODE_MESSAGE, ASSERT_NOT_NULL, ASSERT_STATEMENT_CODE_MESSAGE, DEBUG_ENTRY, DEBUG_LEAVE, MCL_CALLOC, MCL_FAIL, MCL_FREE, MCL_NO_ACCESS_TOKEN_EXISTS, MCL_NULL, MCL_OK, MCL_OUT_OF_MEMORY, and string_util_snprintf().
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_get_last_token_time | ( | mcl_communication_t * | communication, |
char ** | token_time | ||
) |
Returns the time when lastly received oauth access token is received.
[in] | communication | Preinitialized mcl_communication_t object through which a connection is established to MindSphere. |
[out] | token_time | The epoch time when lastly received oauth access token is received. |
Definition at line 648 of file communication.c.
References ASSERT_CODE_MESSAGE, ASSERT_NOT_NULL, ASSERT_STATEMENT_CODE_MESSAGE, DEBUG_ENTRY, DEBUG_LEAVE, MCL_CALLOC, MCL_ERROR_RETURN, MCL_FREE, MCL_NO_SERVER_TIME, MCL_NULL, MCL_OK, MCL_OUT_OF_MEMORY, and string_util_snprintf().
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_initialize | ( | mcl_configuration_t * | configuration, |
mcl_communication_t ** | communication | ||
) |
This function creates and initializes an object of type mcl_communication_t according to the configuration parameters passed in as an argument. Memory is allocated for the communication
object and configuration parameters are copied to it.
[in] | configuration | Data structure holding the configuration parameters for the communication object. |
[out] | communication | Pointer of pointer to the new mcl_communication_t object. |
configuration
is either NULL or has zero length or its length exceeds maximum allowed length. configuration
is not NULL but has zero length or its length exceeds maximum allowed length. configuration
has zero length or its length exceeds maximum allowed length even though a valid proxy host name is provided and proxy user name is not NULL. configuration
is either NULL or has zero length or its length exceeds maximum allowed length even though valid proxy host name and user name are provided. configuration
has zero length or its length exceeds maximum allowed length even though valid proxy host name, user name and password are provided. configuration
is not one of the supported profiles. configuration
is either NULL or its length exceeds maximum allowed length. configuration
is NULL. configuration
is less than minimum or more than maximum allowed size. Definition at line 26 of file communication.c.
References _log_configuration(), ASSERT_CODE, ASSERT_CODE_MESSAGE, ASSERT_NOT_NULL, ASSERT_STATEMENT_CODE_MESSAGE, DEBUG_ENTRY, DEBUG_LEAVE, DEFAULT_HTTP_PAYLOAD_SIZE, mcl_configuration_t::enter_critical_section, http_processor_initialize(), mcl_configuration_t::http_request_timeout, mcl_configuration_t::initial_access_token, mcl_configuration_t::leave_critical_section, mcl_configuration_t::load_function, mcl_configuration_t::max_http_payload_size, MAXIMUM_HOST_NAME_LENGTH, MAXIMUM_PROXY_DOMAIN_LENGTH, MAXIMUM_PROXY_PASSWORD_LENGTH, MAXIMUM_PROXY_USER_NAME_LENGTH, MAXIMUM_USER_AGENT_LENGTH, mcl_communication_destroy(), MCL_FALSE, MCL_INFO, MCL_INVALID_HOST_NAME, MCL_INVALID_MAX_HTTP_PAYLOAD_SIZE, MCL_INVALID_PROXY_DOMAIN, MCL_INVALID_PROXY_HOST_NAME, MCL_INVALID_PROXY_PASSWORD, MCL_INVALID_PROXY_USER_NAME, MCL_INVALID_SECURITY_PROFILE, MCL_INVALID_TENANT, MCL_INVALID_USER_AGENT, MCL_MAXIMUM_HTTP_PAYLOAD_SIZE, MCL_NEW, MCL_NULL, MCL_OK, MCL_OUT_OF_MEMORY, MCL_PROXY_UNKNOWN, MCL_SECURITY_RSA_3072, MCL_SECURITY_SHARED_SECRET, MCL_TRUE, MIN_HTTP_PAYLOAD_SIZE, mcl_configuration_t::mindsphere_certificate, mcl_configuration_t::mindsphere_hostname, mcl_configuration_t::mindsphere_port, mcl_configuration_t::proxy_domain, mcl_configuration_t::proxy_hostname, mcl_configuration_t::proxy_password, mcl_configuration_t::proxy_port, mcl_configuration_t::proxy_type, mcl_configuration_t::proxy_username, mcl_configuration_t::save_function, mcl_configuration_t::security_profile, mcl_configuration_t::store_path, string_initialize_new(), string_util_snprintf(), string_util_strlen(), string_util_strnlen(), mcl_configuration_t::tenant, mcl_configuration_t::user_agent, and USER_AGENT_HEADER_FORMAT.
MCL_EXPORT mcl_bool_t mcl_communication_is_initialized | ( | mcl_communication_t * | communication | ) |
Can be used to determine if communication
handle is initialized.
[in] | communication | The communication handle on which the initialization check will be performed. |
communication
is initialized. Otherwise MCL_FALSE. Definition at line 598 of file communication.c.
References ASSERT_NOT_NULL, DEBUG_ENTRY, and DEBUG_LEAVE.
Referenced by mcl_communication_exchange(), mcl_communication_get_access_token(), mcl_communication_onboard(), mcl_communication_process(), mcl_communication_rotate_key(), and mcl_communication_update_security_information().
MCL_EXPORT mcl_bool_t mcl_communication_is_onboarded | ( | mcl_communication_t * | communication | ) |
Can be used to determine if communication
handle is onboarded.
[in] | communication | The communication handle on which the onboarding check will be performed. |
communication
is onboarded. Otherwise MCL_FALSE. Definition at line 612 of file communication.c.
References ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, MCL_FALSE, MCL_NULL, and MCL_TRUE.
Referenced by mcl_communication_exchange(), mcl_communication_get_access_token(), mcl_communication_onboard(), mcl_communication_process(), mcl_communication_rotate_key(), and mcl_communication_update_security_information().
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_onboard | ( | mcl_communication_t * | communication | ) |
This function connects the agent to MindSphere which is called Onboarding.
[in] | communication | Preinitialized mcl_communication_t object through which a connection will be established to MindSphere. |
communication
is not initialized. communication
. Definition at line 279 of file communication.c.
References ASSERT_CODE, ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, http_processor_get_access_token(), http_processor_register(), MCL_ALREADY_ONBOARDED, mcl_communication_is_initialized(), mcl_communication_is_onboarded(), MCL_ERROR, MCL_INFO, MCL_NOT_INITIALIZED, MCL_NULL, and MCL_OK.
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_process | ( | mcl_communication_t * | communication, |
mcl_store_t * | store, | ||
void ** | reserved | ||
) |
This function exchanges data in store
to MindSphere similar to mcl_communication_exchange but additionally, it performs a series of steps, such as get access token and key rotation if exchange fails.
[in] | communication | Preinitialized mcl_communication_t object through which a connection is established to MindSphere. |
[in] | store | Container for the data to be uploaded to MindSphere. |
[out] | reserved | Reserved for future use. |
communication
is not initialized. communication
. communication
does not have an access token. store
has no data. Definition at line 504 of file communication.c.
References ASSERT_CODE_MESSAGE, ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, MCL_BAD_REQUEST, mcl_communication_exchange(), mcl_communication_get_access_token(), mcl_communication_is_initialized(), mcl_communication_is_onboarded(), mcl_communication_rotate_key(), MCL_INFO, MCL_INVALID_PARAMETER, MCL_NO_ACCESS_TOKEN_EXISTS, MCL_NOT_INITIALIZED, MCL_NOT_ONBOARDED, MCL_NULL, MCL_OK, MCL_TRUE, MCL_UNAUTHORIZED, string_destroy(), and string_initialize_new().
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_rotate_key | ( | mcl_communication_t * | communication | ) |
This function is used by the agent which is already onboarded to MindSphere to generate a new authentication key using the authentication key acquired earlier. Key rotation can be applied only when there is an authentication key available. Onboarding key is not necessary for key rotation.
[in] | communication | mcl_communication_t object which is initialized and onboarded to MindSphere. |
communication
is NULL. communication
is not initialized. communication
. Definition at line 341 of file communication.c.
References ASSERT_CODE, ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, http_processor_get_access_token(), http_processor_register(), mcl_communication_is_initialized(), mcl_communication_is_onboarded(), MCL_ERROR, MCL_INFO, MCL_NOT_INITIALIZED, MCL_NOT_ONBOARDED, MCL_NULL, and MCL_OK.
Referenced by mcl_communication_process().
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_update_security_information | ( | mcl_communication_t * | communication | ) |
This function is used by the agent which is already onboarded to update security information.
[in] | communication | mcl_communication_t object which is initialized and onboarded to MindSphere. |
Definition at line 402 of file communication.c.
References ASSERT_CODE, ASSERT_NOT_NULL, DEBUG_ENTRY, DEBUG_LEAVE, http_processor_get_access_token(), http_processor_update_security_information(), mcl_communication_is_initialized(), mcl_communication_is_onboarded(), MCL_INFO, MCL_NOT_INITIALIZED, MCL_NOT_ONBOARDED, MCL_NULL, and MCL_OK.