mcl_event.h File Reference

Event module interface header file. More...

#include "mcl_connectivity/mcl_connectivity_common.h"

Include dependency graph for mcl_event.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct mcl_event_t	mcl_event_t

Enumerations
enum	E_MCL_EVENT_VERSION { MCL_EVENT_VERSION_1_0 = 0, MCL_EVENT_VERSION_2_0, MCL_EVENT_VERSION_END }
enum	E_MCL_EVENT_SEVERITY { MCL_EVENT_SEVERITY_ERROR = 0, MCL_EVENT_SEVERITY_WARNING, MCL_EVENT_SEVERITY_INFORMATION, MCL_EVENT_SEVERITY_END }
enum	E_MCL_EVENT_PARAMETER {   MCL_EVENT_PARAMETER_TYPE = 0, MCL_EVENT_PARAMETER_VERSION, MCL_EVENT_PARAMETER_SEVERITY, MCL_EVENT_PARAMETER_TIMESTAMP_ISO8601,   MCL_EVENT_PARAMETER_TIMESTAMP_EPOCH, MCL_EVENT_PARAMETER_DESCRIPTION, MCL_EVENT_PARAMETER_CORRELATION_ID, MCL_EVENT_PARAMETER_DETAILS,   MCL_EVENT_PARAMETER_END }

Functions
MCL_CONNECTIVITY_EXPORT mcl_error_t	mcl_event_initialize (E_MCL_EVENT_VERSION version, mcl_event_t **event)
MCL_CONNECTIVITY_EXPORT mcl_error_t	mcl_event_set_parameter (mcl_event_t *event, E_MCL_EVENT_PARAMETER parameter, const void *value)
MCL_CONNECTIVITY_EXPORT void	mcl_event_destroy (mcl_event_t **event)

Detailed Description

Event module interface header file.

Agents can upload event data to MindSphere. This module enables the agent to initialize an event data type using mcl_event_initialize function. Following initialization, the parameters of this event data type can be set using mcl_event_set_parameter function. Once the event data type is ready, it can be uploaded to MindSphere using mcl_connectivity_exchange function. Optionally, the event can be added to mcl_store_t and the store containing the event and possible other data can be uploaded to MindSphere. If the event data type is exchanged as a single item, the agent is expected to destroy the event after the exchange operation using mcl_event_destroy function. If the event is exchanged in a store, store will handle the destroy operation of the event and the agent does not need to take any action.

For more information, please look at example file "mcl_connectivity/examples/event_upload.c".

Copyright

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

Definition in file mcl_event.h.

Typedef Documentation

typedef struct mcl_event_t mcl_event_t

Handle for event.

Definition at line 34 of file mcl_event.h.

Enumeration Type Documentation

enum E_MCL_EVENT_PARAMETER

Parameters for events.

Enumerator
MCL_EVENT_PARAMETER_TYPE	Event payload type parameter as char*.
MCL_EVENT_PARAMETER_VERSION	Event payload version parameter as char*.
MCL_EVENT_PARAMETER_SEVERITY	Event payload severity parameter as E_MCL_EVENT_SEVERITY.
MCL_EVENT_PARAMETER_TIMESTAMP_ISO8601	Event payload timestamp parameter as char* (which is in yyyy-MM-ddTHH:mm:ss.SSSZ format).
MCL_EVENT_PARAMETER_TIMESTAMP_EPOCH	Event payload timestamp parameter as time_t*.
MCL_EVENT_PARAMETER_DESCRIPTION	Event payload description parameter as char* (optional).
MCL_EVENT_PARAMETER_CORRELATION_ID	Event payload correlation id parameter as char* (optional).
MCL_EVENT_PARAMETER_DETAILS	Event payload details parameter as mcl_json_t* (optional).
MCL_EVENT_PARAMETER_END

Definition at line 60 of file mcl_event.h.

enum E_MCL_EVENT_SEVERITY

Severity values for events.

Enumerator
MCL_EVENT_SEVERITY_ERROR	Severity level of event is ERROR.
MCL_EVENT_SEVERITY_WARNING	Severity level of event is WARNING.
MCL_EVENT_SEVERITY_INFORMATION	Severity level of event is INFORMATION.
MCL_EVENT_SEVERITY_END

Definition at line 49 of file mcl_event.h.

enum E_MCL_EVENT_VERSION

Version of event item payload.

Enumerator
MCL_EVENT_VERSION_1_0	Event version 1.0.
MCL_EVENT_VERSION_2_0	Event version 2.0.
MCL_EVENT_VERSION_END	End of event version enumeration.

Definition at line 39 of file mcl_event.h.

Function Documentation

MCL_CONNECTIVITY_EXPORT void mcl_event_destroy

(

mcl_event_t **

event

)

This function destroys event data structure.

Parameters

[in]

event

Event handle which is going to be destroyed.

Definition at line 186 of file event.c.

References MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_FREE, mcl_json_util_destroy(), and MCL_NULL.

Referenced by _item_destroy(), and mcl_event_initialize().

Here is the call graph for this function:

Here is the caller graph for this function:

MCL_CONNECTIVITY_EXPORT mcl_error_t mcl_event_initialize	(	E_MCL_EVENT_VERSION	version,
		mcl_event_t **	event
	)

This function creates and initializes a data struct of mcl_event_t.

Parameters

[in]	version	One of the versions listed in E_MCL_EVENT_VERSION.
[out]	event	Event handle which is going to be initialized.

Returns

• MCL_OK in case of success.
• MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
• MCL_INVALID_PARAMETER in case meta payload version parameter is invalid.

Definition at line 25 of file event.c.

References _event_severity_values, MCL_ASSERT_CODE_MESSAGE, MCL_ASSERT_NOT_NULL, MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, mcl_event_destroy(), MCL_EVENT_SEVERITY_INFORMATION, MCL_FUNCTION_LEAVE_LABEL, MCL_INVALID_PARAMETER, MCL_ITEM_PREAMBLE, MCL_ITEM_TYPE_EVENT, MCL_NEW, MCL_NULL, MCL_OK, MCL_OUT_OF_MEMORY, and mcl_random_generate_guid().

Here is the call graph for this function:

MCL_CONNECTIVITY_EXPORT mcl_error_t mcl_event_set_parameter	(	mcl_event_t *	event,
		E_MCL_EVENT_PARAMETER	parameter,
		const void *	value
	)

This function is used to set a parameter of an event.

Parameters

[in]	event	Event to set its parameter.
[in]	parameter	One of the parameters listed in E_MCL_EVENT_PARAMETER.
[in]	value	New value of the parameter.

Returns

• MCL_OK in case of success.
• MCL_TRIGGERED_WITH_NULL if provided event or value is NULL.
• MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
• MCL_INVALID_PARAMETER if provided parameter is invalid.
• MCL_FAIL in case of an internal error in MCL.

Definition at line 80 of file event.c.

References _event_severity_values, MCL_ASSERT_CODE_MESSAGE, MCL_ASSERT_NOT_NULL, MCL_DEBUG_ENTRY, MCL_DEBUG_LEAVE, MCL_EVENT_PARAMETER_CORRELATION_ID, MCL_EVENT_PARAMETER_DESCRIPTION, MCL_EVENT_PARAMETER_DESCRIPTION_MAXIMUM_LENGTH, MCL_EVENT_PARAMETER_DETAILS, MCL_EVENT_PARAMETER_SEVERITY, MCL_EVENT_PARAMETER_TIMESTAMP_EPOCH, MCL_EVENT_PARAMETER_TIMESTAMP_ISO8601, MCL_EVENT_PARAMETER_TYPE, MCL_EVENT_PARAMETER_VERSION, MCL_EVENT_SEVERITY_END, MCL_EVENT_SEVERITY_ERROR, MCL_FUNCTION_LEAVE_LABEL, MCL_INVALID_PARAMETER, mcl_json_util_destroy(), mcl_json_util_duplicate(), MCL_OK, mcl_string_util_memcpy(), mcl_string_util_reset(), mcl_string_util_strlen(), mcl_time_util_convert_to_iso_8601_format(), mcl_time_util_validate_timestamp(), MCL_TIMESTAMP_LENGTH, and MCL_TRUE.

Here is the call graph for this function: