Core module implementation file. More...

#include "mcl_core/mcl_core.h"
#include "core.h"
#include "definitions.h"
#include "mcl_core/mcl_memory.h"
#include "string_util.h"

Include dependency graph for core.c:

Go to the source code of this file.

Macros
#define	USER_AGENT_HEADER_FORMAT "MCL/" MCL_VERSION_STRING " (%s)"

Functions
mcl_error_t	mcl_core_initialize (mcl_core_configuration_t configuration, mcl_core_t *core)

mcl_error_t	mcl_core_onboard (mcl_core_t *core)

mcl_error_t	mcl_core_rotate_key (mcl_core_t *core)

mcl_error_t	mcl_core_update_credentials (mcl_core_t *core)

mcl_error_t	mcl_core_get_access_token (mcl_core_t *core)

mcl_bool_t	mcl_core_is_onboarded (mcl_core_t *core)

mcl_error_t	mcl_core_get_last_access_token (mcl_core_t core, char *token)

mcl_error_t	mcl_core_get_last_token_time (mcl_core_t core, char *token_time)

mcl_http_client_t *	mcl_core_get_http_client (mcl_core_t *core)

const char *	mcl_core_get_host_name (mcl_core_t *core)

const char *	mcl_core_get_client_id (mcl_core_t *core)

mcl_error_t	mcl_core_destroy (mcl_core_t **core)

Detailed Description

Core module implementation file.

Copyright: Copyright (C) 2019 Siemens Aktiengesellschaft.
All rights reserved.

Definition in file core.c.

Macro Definition Documentation

#define USER_AGENT_HEADER_FORMAT "MCL/" MCL_VERSION_STRING " (%s)"

Definition at line 15 of file core.c.

Function Documentation

mcl_error_t mcl_core_destroy ( mcl_core_t ** core )

This function destroys the mcl_core_t object and frees any memory allocated.

Parameters

[in] core Preinitialized mcl_core_t object to destroy.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL in case input parameter is NULL.

Definition at line 358 of file core.c.

References core_processor_destroy(), MCL_DEBUG, MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_FREE, MCL_NULL, and MCL_OK.

Referenced by mcl_core_initialize().

Here is the call graph for this function:

Here is the caller graph for this function:

mcl_error_t mcl_core_get_access_token ( mcl_core_t * core )

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_UNAUTHORIZED is returned. The agent can use mcl_core_rotate_key function to renew its secret key if mcl_core_get_access_token function returns MCL_BAD_REQUEST.

Parameters

[in] core mcl_core_t object which is initialized and onboarded to MindSphere.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL if provided core is NULL.
MCL_NOT_ONBOARDED if the agent is not onboarded using core.
MCL_OUT_OF_MEMORY if there is not enough memory in the system to proceed.
MCL_COULD_NOT_RESOLVE_PROXY if the proxy host name can not be resolved.
MCL_COULD_NOT_RESOLVE_HOST if the remote host name can not be resolved.
MCL_SSL_HANDSHAKE_FAIL if a problem occurs during SSL handshake.
MCL_COULD_NOT_CONNECT if there is a connection error with the server.
MCL_SERVER_CERTIFICATE_NOT_VERIFIED if the server can not be verified.
MCL_IMPROPER_CERTIFICATE in case the certificate provided is in improper format and it can not be parsed.
MCL_NETWORK_SEND_FAIL in case of an error in sending data to network.
MCL_NETWORK_RECEIVE_FAIL in case of an error in receiving data from the network.
MCL_BAD_REQUEST if response status code of server is 400.
MCL_UNAUTHORIZED if response status code of server is 401.
MCL_SERVER_FAIL if response status code of server is 500.
MCL_FAIL in case of an internal error in MCL.

Definition at line 188 of file core.c.

References core_processor_get_access_token(), MCL_ASSERT_NOT_NULL, mcl_core_is_onboarded(), MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_ERROR, MCL_FUNCTION_LEAVE_LABEL, MCL_INFO, MCL_NOT_ONBOARDED, MCL_OK, and MCL_TRUE.

Here is the call graph for this function:

const char* mcl_core_get_client_id ( mcl_core_t * core )

This function returns the client id.

User should not free/manipulate the client id buffer.

Parameters

[in] core Preinitialized mcl_core_t object.

Returns

Pointer to client id in case of success.
NULL if core is either NULL or is not initialized.

Definition at line 342 of file core.c.

References mcl_core_is_onboarded(), MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_NULL, and MCL_TRUE.

Here is the call graph for this function:

const char* mcl_core_get_host_name ( mcl_core_t * core )

This function returns the host name.

Parameters

[in] core Preinitialized mcl_core_t object.

Returns

Pointer to host name in case of success.
NULL if core is either NULL or is not initialized.

Definition at line 326 of file core.c.

References MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, and MCL_NULL.

mcl_http_client_t* mcl_core_get_http_client ( mcl_core_t * core )

This function returns the http client.

Parameters

[in] core Preinitialized mcl_core_t object.

Returns

Pointer to mcl_http_client_t in case of success.
NULL if core is not initialized.

Definition at line 310 of file core.c.

References MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, and MCL_NULL.

mcl_error_t mcl_core_get_last_access_token	(	mcl_core_t *	core,
		char **	token
	)

This function returns a copy of last received access token.

Parameters

[in]	core	Preinitialized mcl_core_t object.
[out]	token	The lastly received access token.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL if provided core or token is NULL.
MCL_OUT_OF_MEMORY if there is not enough memory in the system to proceed.
MCL_NOT_ONBOARDED if the agent is not onboarded using core.
MCL_NO_ACCESS_TOKEN_EXISTS if core does not have an access token.
MCL_FAIL in case of an internal error in MCL.

Definition at line 235 of file core.c.

References MCL_ASSERT_NOT_NULL, MCL_CALLOC, mcl_core_is_onboarded(), MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_FUNCTION_LEAVE_LABEL, MCL_NO_ACCESS_TOKEN_EXISTS, MCL_NOT_ONBOARDED, MCL_NULL, MCL_OK, MCL_OUT_OF_MEMORY, MCL_TRUE, string_util_memcpy(), and string_util_strlen().

Here is the call graph for this function:

mcl_error_t mcl_core_get_last_token_time	(	mcl_core_t *	core,
		char **	token_time
	)

This function returns the time when last received access token is generated, NULL if server time is not received.

Parameters

[in]	core	Preinitialized # mcl_core_t object.
[out]	token_time	The epoch time when last received access token is generated.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL if provided core or token_time is NULL.
MCL_OUT_OF_MEMORY if there is not enough memory in the system to proceed.
MCL_NO_SERVER_TIME if server time is not received.
MCL_FAIL in case of an internal error in MCL.

Definition at line 274 of file core.c.

References MCL_ASSERT_NOT_NULL, MCL_CALLOC, MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_FUNCTION_LEAVE_LABEL, MCL_NO_SERVER_TIME, MCL_NULL, MCL_OK, MCL_OUT_OF_MEMORY, string_util_memcpy(), and string_util_strlen().

Here is the call graph for this function:

mcl_error_t mcl_core_initialize	(	mcl_core_configuration_t *	configuration,
		mcl_core_t **	core
	)

This function creates and initializes an object of type mcl_core_t according to the configuration parameters passed in as an argument. Memory is allocated for the core object and configuration parameters are copied to it.

Parameters

[in]	configuration	Data structure holding the configuration parameters for the `core` object.
[out]	core	Core handle which is going to be initialized.

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_NO_ACCESS_TOKEN_PROVIDED if neither initial access token nor loading/saving credentials callback functions are provided.

Definition at line 17 of file core.c.

References core_configuration_log(), core_configuration_validate(), core_processor_initialize(), MCL_ASSERT_CODE_MESSAGE, MCL_ASSERT_NOT_NULL, MCL_ASSERT_STATEMENT_CODE_MESSAGE, mcl_core_destroy(), MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_FUNCTION_LEAVE_LABEL, MCL_INFO, MCL_NEW, MCL_NULL, MCL_OK, and MCL_OUT_OF_MEMORY.

Here is the call graph for this function:

mcl_bool_t mcl_core_is_onboarded ( mcl_core_t * core )

This function is used to determine if core handle is onboarded.

Parameters

[in] core The core handle on which the onboarding check will be performed.

Returns: MCL_TRUE if core is onboarded. Otherwise MCL_FALSE.

Definition at line 220 of file core.c.

References MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_FALSE, MCL_NULL, and MCL_TRUE.

Referenced by mcl_core_get_access_token(), mcl_core_get_client_id(), mcl_core_get_last_access_token(), mcl_core_onboard(), mcl_core_rotate_key(), and mcl_core_update_credentials().

Here is the caller graph for this function:

mcl_error_t mcl_core_onboard ( mcl_core_t * core )

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

Parameters

[in] core Preinitialized mcl_core_t object.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL in case any input parameter is NULL.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_ALREADY_ONBOARDED in case the agent is already onboarded using core.
MCL_COULD_NOT_RESOLVE_PROXY if the proxy host name can not be resolved.
MCL_COULD_NOT_RESOLVE_HOST if the remote host name can not be resolved.
MCL_SSL_HANDSHAKE_FAIL if a problem occurs during SSL handshake.
MCL_COULD_NOT_CONNECT if there is a connection error with the server.
MCL_SERVER_CERTIFICATE_NOT_VERIFIED if the server can not be verified.
MCL_IMPROPER_CERTIFICATE in case the certificate provided is in improper format and it can not be parsed.
MCL_NETWORK_SEND_FAIL in case of an error in sending data to network.
MCL_NETWORK_RECEIVE_FAIL in case of an error in receiving data from the network.
MCL_UNAUTHORIZED if response status code of server is related to authorization.
MCL_SERVER_FAIL if the server returns 500 response status code.
MCL_FAIL in case of an internal error in MCL.

Definition at line 54 of file core.c.

References core_processor_register(), MCL_ALREADY_ONBOARDED, MCL_ASSERT_NOT_NULL, MCL_ASSERT_OK, mcl_core_is_onboarded(), MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_ERROR, MCL_FALSE, MCL_FUNCTION_LEAVE_LABEL, MCL_INFO, MCL_NULL, and MCL_OK.

Here is the call graph for this function:

mcl_error_t mcl_core_rotate_key ( mcl_core_t * core )

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] core mcl_core_t object which is initialized and onboarded to MindSphere.

Returns

MCL_OK in case of success.
MCL_TRIGGERED_WITH_NULL if provided core is NULL.
MCL_NOT_ONBOARDED if the agent is not onboarded using core.
MCL_OUT_OF_MEMORY if there is not enough memory in the system to proceed.
MCL_COULD_NOT_RESOLVE_PROXY if the proxy host name can not be resolved.
MCL_COULD_NOT_RESOLVE_HOST if the remote host name can not be resolved.
MCL_SSL_HANDSHAKE_FAIL if a problem occurs during SSL handshake.
MCL_COULD_NOT_CONNECT if there is a connection error with the server.
MCL_SERVER_CERTIFICATE_NOT_VERIFIED if the server can not be verified.
MCL_IMPROPER_CERTIFICATE in case the certificate provided is in improper format and it can not be parsed.
MCL_NETWORK_SEND_FAIL in case of an error in sending data to network.
MCL_NETWORK_RECEIVE_FAIL in case of an error in receiving data from the network.
MCL_UNAUTHORIZED if response status code of server is related to authorization.
MCL_SERVER_FAIL if the server returns 500 response status code.
MCL_FAIL in case of an internal error in MCL.

Definition at line 101 of file core.c.

References core_processor_register(), MCL_ASSERT_NOT_NULL, MCL_ASSERT_OK, mcl_core_is_onboarded(), MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_ERROR, MCL_FALSE, MCL_FUNCTION_LEAVE_LABEL, MCL_INFO, MCL_NOT_ONBOARDED, MCL_NULL, and MCL_OK.

Here is the call graph for this function:

mcl_error_t mcl_core_update_credentials ( mcl_core_t * core )

This function is used by the agent which is already onboarded to update credentials mcl_core_t handle bears typically because the credentials are changed by another process and the mcl_core_t handle has to be synchronized.

Parameters

[in] core mcl_core_t object which is initialized and onboarded to MindSphere.

Returns

MCL_OK in case of successful update.
MCL_CREDENTIALS_UP_TO_DATE if credentials of the mcl_core is already up to date.
MCL_FAIL in case of an internal error in MCL.

Definition at line 149 of file core.c.

References core_processor_update_credentials(), MCL_ASSERT_NOT_NULL, MCL_ASSERT_OK, mcl_core_is_onboarded(), MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_FUNCTION_LEAVE_LABEL, MCL_NOT_ONBOARDED, MCL_NULL, and MCL_TRUE.

Here is the call graph for this function:

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation