mcl_communication.h File Reference

Communication module interface header file. More...

#include "mcl/mcl_store.h"
#include "mcl/mcl_configuration.h"
#include "mcl/mcl_list.h"
Include dependency graph for mcl_communication.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct mcl_communication_t mcl_communication_t
 

Functions

MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_initialize (mcl_configuration_t *configuration, mcl_communication_t **communication)
 
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_destroy (mcl_communication_t **communication)
 
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_onboard (mcl_communication_t *communication)
 
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_rotate_key (mcl_communication_t *communication)
 
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_update_security_information (mcl_communication_t *communication)
 
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_get_access_token (mcl_communication_t *communication)
 
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_exchange (mcl_communication_t *communication, mcl_store_t *store, void **reserved)
 
MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_process (mcl_communication_t *communication, mcl_store_t *store, void **reserved)
 
MCL_EXPORT mcl_bool_t mcl_communication_is_initialized (mcl_communication_t *communication)
 Can be used to determine if communication handle is initialized. More...
 
MCL_EXPORT mcl_bool_t mcl_communication_is_onboarded (mcl_communication_t *communication)
 Can be used to determine if communication handle is onboarded. More...
 
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. More...
 
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. More...
 

Detailed Description

Communication module interface header file.


Date
Sep 8, 2016 This module implements MCL communication interface.

Definition in file mcl_communication.h.

Typedef Documentation

This data structure is the main handle for Agent - MindSphere communication.

Definition at line 31 of file mcl_communication.h.

Function Documentation

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.

Parameters
[in]communicationPreinitialized mcl_communication_t object to destroy.
Returns

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().

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Parameters
[in]communicationPreinitialized mcl_communication_t object through which a connection is established to MindSphere.
[in]storeContainer for the data to be uploaded to MindSphere.
[out]reservedReserved for future use.
Returns

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().

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Parameters
[in]communicationmcl_communication_t object which is initialized and onboarded to MindSphere.
Returns

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().

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Parameters
[in]communicationPreinitialized mcl_communication_t object through which a connection is established to MindSphere.
[out]tokenThe lastly received oauth access token.
Returns

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().

Here is the call graph for this function:

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.

Parameters
[in]communicationPreinitialized mcl_communication_t object through which a connection is established to MindSphere.
[out]token_timeThe epoch time when lastly received oauth access token is received.
Returns

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().

Here is the call graph for this function:

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.

Parameters
[in]configurationData structure holding the configuration parameters for the communication object.
[out]communicationPointer of pointer to the new mcl_communication_t object.
Returns
  • MCL_OK in case of success.
  • MCL_TRIGGERED_WITH_NULL in case any mandatory input parameter is NULL.
  • MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
  • MCL_INVALID_HOST_NAME in case the host name provided within configuration is either NULL or has zero length or its length exceeds maximum allowed length.
  • MCL_INVALID_PROXY_HOST_NAME in case the proxy host name provided within configuration is not NULL but has zero length or its length exceeds maximum allowed length.
  • MCL_INVALID_PROXY_USER_NAME in case proxy user name provided within 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.
  • MCL_INVALID_PROXY_PASSWORD in case the proxy password provided within 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.
  • MCL_INVALID_PROXY_DOMAIN in case the proxy domain provided within configuration has zero length or its length exceeds maximum allowed length even though valid proxy host name, user name and password are provided.
  • MCL_INVALID_SECURITY_PROFILE in case the security profile provided within configuration is not one of the supported profiles.
  • MCL_INVALID_USER_AGENT in case the user agent provided within configuration is either NULL or its length exceeds maximum allowed length.
  • MCL_INVALID_TENANT in case the tenant provided within configuration is NULL.
  • MCL_INVALID_MAX_HTTP_PAYLOAD_SIZE in case the max http payload size provided within configuration is less than minimum or more than maximum allowed size.
  • MCL_PATH_NOT_ACCESSIBLE in case the store path is not accessible.
  • MCL_NO_ACCESS_TOKEN_PROVIDED if neither initial access token - initial registration URI pair nor the store path with registration information is provided.
  • MCL_INITIALIZATION_FAIL in case initialization procedure fails due to malfunction of the library.

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.

Here is the call graph for this function:

MCL_EXPORT mcl_bool_t mcl_communication_is_initialized ( mcl_communication_t communication)

Can be used to determine if communication handle is initialized.

Parameters
[in]communicationThe communication handle on which the initialization check will be performed.
Returns
MCL_TRUE if 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().

Here is the caller graph for this function:

MCL_EXPORT mcl_bool_t mcl_communication_is_onboarded ( mcl_communication_t communication)

Can be used to determine if communication handle is onboarded.

Parameters
[in]communicationThe communication handle on which the onboarding check will be performed.
Returns
MCL_TRUE if 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().

Here is the caller graph for this function:

MCL_EXPORT E_MCL_ERROR_CODE mcl_communication_onboard ( mcl_communication_t communication)

This function connects the agent to MindSphere which is called Onboarding.

Parameters
[in]communicationPreinitialized mcl_communication_t object through which a connection will be established to MindSphere.
Returns

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.

Here is the call graph for this function:

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.

Parameters
[in]communicationPreinitialized mcl_communication_t object through which a connection is established to MindSphere.
[in]storeContainer for the data to be uploaded to MindSphere.
[out]reservedReserved for future use.
Returns

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().

Here is the call graph for this function:

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.

Parameters
[in]communicationmcl_communication_t object which is initialized and onboarded to MindSphere.
Returns

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().

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Parameters
[in]communicationmcl_communication_t object which is initialized and onboarded to MindSphere.
Returns

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.

Here is the call graph for this function: