Defines structures and function prototypes for creating, inspecting and disposing of messages published to the message broker. More...

#include "azure_c_shared_utility/macro_utils.h"
#include "azure_c_shared_utility/map.h"
#include "azure_c_shared_utility/constmap.h"
#include "azure_c_shared_utility/constbuffer.h"
#include "gateway_export.h"
#include <stdint.h>
#include <stddef.h>
#include "azure_c_shared_utility/umock_c_prod.h"

Data Structures
struct	MESSAGE_CONFIG_TAG
	Struct defining the Message configuration; messages are constructed using this structure. More...

struct	MESSAGE_BUFFER_CONFIG_TAG
	Struct defining the Message buffer configuration. More...

Macros
#define	GATEWAY_MESSAGE_VERSION_1 0x01

#define	GATEWAY_MESSAGE_VERSION_CURRENT GATEWAY_MESSAGE_VERSION_1

Typedefs
typedef struct MESSAGE_HANDLE_DATA_TAG *	MESSAGE_HANDLE
	Struct representing a particular message.

typedef struct MESSAGE_CONFIG_TAG	MESSAGE_CONFIG
	Struct defining the Message configuration; messages are constructed using this structure.

typedef struct MESSAGE_BUFFER_CONFIG_TAG	MESSAGE_BUFFER_CONFIG
	Struct defining the Message buffer configuration.

Functions
	MOCKABLE_FUNCTION (, GATEWAY_EXPORT MESSAGE_HANDLE, Message_Create, const MESSAGE_CONFIG *, cfg)
	Creates a new reference counted message from a MESSAGE_CONFIG structure with the reference count initialized to 1. More...

	MOCKABLE_FUNCTION (, GATEWAY_EXPORT MESSAGE_HANDLE, Message_CreateFromByteArray, const unsigned char *, source, int32_t, size)
	Creates a new reference counted message from a byte array containing the serialized form of a message. More...

	MOCKABLE_FUNCTION (, GATEWAY_EXPORT int32_t, Message_ToByteArray, MESSAGE_HANDLE, messageHandle, unsigned char *, buf, int32_t, size)
	Creates a byte array representation of a MESSAGE_HANDLE. More...

	MOCKABLE_FUNCTION (, GATEWAY_EXPORT MESSAGE_HANDLE, Message_CreateFromBuffer, const MESSAGE_BUFFER_CONFIG *, cfg)
	Creates a new message from a `CONSTBUFFER` source and `MAP_HANDLE`. More...

	MOCKABLE_FUNCTION (, GATEWAY_EXPORT MESSAGE_HANDLE, Message_Clone, MESSAGE_HANDLE, message)
	Creates a clone of the message. More...

	MOCKABLE_FUNCTION (, GATEWAY_EXPORT CONSTMAP_HANDLE, Message_GetProperties, MESSAGE_HANDLE, message)
	Gets the properties of a message. More...

	MOCKABLE_FUNCTION (, GATEWAY_EXPORT const CONSTBUFFER *, Message_GetContent, MESSAGE_HANDLE, message)
	Gets the content of a message. More...

	MOCKABLE_FUNCTION (, GATEWAY_EXPORT CONSTBUFFER_HANDLE, Message_GetContentHandle, MESSAGE_HANDLE, message)
	Gets the `CONSTBUFFER` handle that may be used to access the message content. More...

	MOCKABLE_FUNCTION (, GATEWAY_EXPORT void, Message_Destroy, MESSAGE_HANDLE, message)
	Disposes of resources allocated by the message. More...

Detailed Description

Defines structures and function prototypes for creating, inspecting and disposing of messages published to the message broker.

A message essentially has two components:

Properties represented as key/value pairs where both the key and value are strings
The content of the message which is simply a memory buffer (a BUFFER_HANDLE)

This header provides functions that enable the creation, inspection and destruction of messages. A message is represented via a MESSAGE_HANDLE which is an opaque reference to a message instance. Messages are immutable and reference counted; their lifetime is managed via the #Message_Clone and #Message_Destroy APIs which atomically increment and decrement the reference count respectively. #Message_Destroy deallocates the message completely when the reference count becomes zero.

Function Documentation

◆ MOCKABLE_FUNCTION() [1/9]

MOCKABLE_FUNCTION	(	GATEWAY_EXPORT	MESSAGE_HANDLE,
		Message_Create	,
		const MESSAGE_CONFIG *	,
		cfg
	)

Creates a new reference counted message from a MESSAGE_CONFIG structure with the reference count initialized to 1.

This function will create its own CONSTBUFFER and ConstMap with copies of the source and sourceProperties contained within the MESSAGE_CONFIG structure parameter. It is the responsibility of the Message to dispose of these resources.

Parameters

cfg	Pointer to a MESSAGE_CONFIG structure.

Returns: A non-NULL MESSAGE_HANDLE for the newly created message, or NULL upon failure.

◆ MOCKABLE_FUNCTION() [2/9]

MOCKABLE_FUNCTION	(	GATEWAY_EXPORT	MESSAGE_HANDLE,
		Message_CreateFromByteArray	,
		const unsigned char *	,
		source	,
		int32_t	,
		size
	)

Creates a new reference counted message from a byte array containing the serialized form of a message.

The newly created message shall have all the properties of the original message and the same content.

Parameters

source	Pointer to a byte array.
size	size in bytes of the array

Returns: A non-NULL MESSAGE_HANDLE for the newly created message, or NULL upon failure.

◆ MOCKABLE_FUNCTION() [3/9]

MOCKABLE_FUNCTION	(	GATEWAY_EXPORT	int32_t,
		Message_ToByteArray	,
		MESSAGE_HANDLE	,
		messageHandle	,
		unsigned char *	,
		buf	,
		int32_t	,
		size
	)

Creates a byte array representation of a MESSAGE_HANDLE.

The byte array created can be used with function #Message_CreateFromByteArray to reproduce the message. If buffer is not set, this function will return the serialization size.

Parameters

messageHandle	A MESSAGE_HANDLE. Must not be NULL.
buf	A pointer to a byte array in memory, or NULL.
size	An int32_t that specifies the size of buf.

Returns: An int32_t that specifies the size of the serialized message written when "buf" is not NULL. If "buf" is NULL, returns the size required for a full successful serialization. Returns a negative value when an error occurs.

◆ MOCKABLE_FUNCTION() [4/9]

MOCKABLE_FUNCTION	(	GATEWAY_EXPORT	MESSAGE_HANDLE,
		Message_CreateFromBuffer	,
		const MESSAGE_BUFFER_CONFIG *	,
		cfg
	)

Creates a new message from a CONSTBUFFER source and MAP_HANDLE.

This function will create a new message its own CONSTBUFFER and ConstMap with copies of the source and sourceProperties contained within the MESSAGE_CONFIG structure parameter. The message will be created with the reference count initialized to 1. It is the responsibility of the Message to dispose of these resources.

Parameters

cfg	Pointer to a MESSAGE_BUFFER_CONFIG structure.

Returns: A non-NULL MESSAGE_HANDLE for the newly created message, or NULL upon failure.

◆ MOCKABLE_FUNCTION() [5/9]

MOCKABLE_FUNCTION	(	GATEWAY_EXPORT	MESSAGE_HANDLE,
		Message_Clone	,
		MESSAGE_HANDLE	,
		message
	)

Creates a clone of the message.

Since messages are immutable, this function only increments the inner reference count.

Parameters

message The MESSAGE_HANDLE that will be cloned.

Returns: A non-NULL MESSAGE_HANDLE cloned from message, or NULL upon failure.

◆ MOCKABLE_FUNCTION() [6/9]

MOCKABLE_FUNCTION	(	GATEWAY_EXPORT	CONSTMAP_HANDLE,
		Message_GetProperties	,
		MESSAGE_HANDLE	,
		message
	)

Gets the properties of a message.

The returned CONSTMAP handle should be destroyed when no longer needed.

Parameters

message The MESSAGE_HANDLE from which properties will be fetched.

Returns: A non-NULL CONSTMAP_HANDLE representing the properties of the message, or NULL upon failure.

◆ MOCKABLE_FUNCTION() [7/9]

MOCKABLE_FUNCTION	(	GATEWAY_EXPORT const CONSTBUFFER *	,
		Message_GetContent	,
		MESSAGE_HANDLE	,
		message
	)

Gets the content of a message.

The returned CONSTBUFFER need not be freed by the caller.

Parameters

message The MESSAGE_HANDLE from which the content will be fetched.

Returns: A non-NULL pointer to a CONSTBUFFER representing the content of the message, or NULL upon failure.

◆ MOCKABLE_FUNCTION() [8/9]

MOCKABLE_FUNCTION	(	GATEWAY_EXPORT	CONSTBUFFER_HANDLE,
		Message_GetContentHandle	,
		MESSAGE_HANDLE	,
		message
	)

Gets the CONSTBUFFER handle that may be used to access the message content.

This handle must be destroyed when no longer needed.

Parameters

message The MESSAGE_HANDLE from which the content will be fetched.

Returns: A non-NULL CONSTBUFFER_HANDLE representing the message content, or NULL upon failure.

◆ MOCKABLE_FUNCTION() [9/9]

MOCKABLE_FUNCTION	(	GATEWAY_EXPORT	void,
		Message_Destroy	,
		MESSAGE_HANDLE	,
		message
	)

Disposes of resources allocated by the message.

Parameters

message The MESSAGE_HANDLE to be destroyed.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Function Documentation

◆ MOCKABLE_FUNCTION() [1/9]

◆ MOCKABLE_FUNCTION() [2/9]

◆ MOCKABLE_FUNCTION() [3/9]

◆ MOCKABLE_FUNCTION() [4/9]

◆ MOCKABLE_FUNCTION() [5/9]

◆ MOCKABLE_FUNCTION() [6/9]

◆ MOCKABLE_FUNCTION() [7/9]

◆ MOCKABLE_FUNCTION() [8/9]

◆ MOCKABLE_FUNCTION() [9/9]