broker.h File Reference

Library for configuring and using the gateway's message broker. More...

#include "azure_c_shared_utility/macro_utils.h"
#include "message.h"
#include "module.h"
#include "gateway_export.h"
#include <stddef.h>

Go to the source code of this file.

Data Structures
struct	BROKER_LINK_DATA_TAG
	Link Data with MODULE_HANDLE for source and sink. More...

Typedefs
typedef struct BROKER_HANDLE_DATA_TAG *	BROKER_HANDLE
	Struct representing a message broker.
typedef struct BROKER_LINK_DATA_TAG	BROKER_LINK_DATA
	Link Data with MODULE_HANDLE for source and sink.
typedef enum BROKER_RESULT_TAG	BROKER_RESULT
	Enumeration describing the result of Broker_Publish, Broker_AddModule, Broker_AddLink, and Broker_RemoveModule.

Enumerations
enum	BROKER_RESULT_TAG {   BROKER_OK, BROKER_ERROR, BROKER_ADD_LINK_ERROR, BROKER_REMOVE_LINK_ERROR,   BROKER_INVALIDARG }
	Enumeration describing the result of Broker_Publish, Broker_AddModule, Broker_AddLink, and Broker_RemoveModule.

Functions
GATEWAY_EXPORT BROKER_HANDLE	Broker_Create (void)
	Creates a new message broker. More...
GATEWAY_EXPORT void	Broker_IncRef (BROKER_HANDLE broker)
	Increments the reference count of a message broker. More...
GATEWAY_EXPORT void	Broker_DecRef (BROKER_HANDLE broker)
	Decrements the reference count of a message broker. More...
GATEWAY_EXPORT BROKER_RESULT	Broker_Publish (BROKER_HANDLE broker, MODULE_HANDLE source, MESSAGE_HANDLE message)
	Publishes a message to the message broker. More...
GATEWAY_EXPORT BROKER_RESULT	Broker_AddModule (BROKER_HANDLE broker, const MODULE *module)
	Adds a module to the message broker. More...
GATEWAY_EXPORT BROKER_RESULT	Broker_RemoveModule (BROKER_HANDLE broker, const MODULE *module)
	Removes a module from the message broker. More...
GATEWAY_EXPORT BROKER_RESULT	Broker_AddLink (BROKER_HANDLE broker, const BROKER_LINK_DATA *link)
	Adds a route to the message broker. More...
GATEWAY_EXPORT BROKER_RESULT	Broker_RemoveLink (BROKER_HANDLE broker, const BROKER_LINK_DATA *link)
	Removes a route from the message broker. More...
GATEWAY_EXPORT void	Broker_Destroy (BROKER_HANDLE broker)
	Disposes of resources allocated by a message broker. More...

Detailed Description

Library for configuring and using the gateway's message broker.

This is the API to create a reference counted and thread safe gateway message broker. The broker sends messages to other modules. Messages published to the broker have a bag of properties (name, value) and an opaque array of bytes that constitute the message content.

Function Documentation

Broker_AddLink()

GATEWAY_EXPORT BROKER_RESULT Broker_AddLink	(	BROKER_HANDLE	broker,
		const BROKER_LINK_DATA *	link
	)

Adds a route to the message broker.

For details about threading with regard to the message broker and modules connected to it, see Broker High Level Design Documentation.

Parameters

broker	The BROKER_HANDLE onto which the module will be added.
link	The BROKER_LINK_DATA for the link that will be added to this message broker.

Returns

A BROKER_RESULT describing the result of the function.

Broker_AddModule()

GATEWAY_EXPORT BROKER_RESULT Broker_AddModule	(	BROKER_HANDLE	broker,
		const MODULE *	module
	)

Adds a module to the message broker.

For details about threading with regard to the message broker and modules connected to it, see Broker High Level Design Documentation.

Parameters

broker	The BROKER_HANDLE onto which the module will be added.
module	The MODULE for the module that will be added to this message broker.

Returns

A BROKER_RESULT describing the result of the function.

Broker_Create()

GATEWAY_EXPORT BROKER_HANDLE Broker_Create

(

void

)

Creates a new message broker.

Returns

A valid BROKER_HANDLE upon success, or NULL upon failure.

Broker_DecRef()

GATEWAY_EXPORT void Broker_DecRef

(

BROKER_HANDLE

broker

)

Decrements the reference count of a message broker.

This function will simply decrement the internal reference count of the provided BROKER_HANDLE, destroying the message broker when the reference count reaches 0.

Parameters

broker

The BROKER_HANDLE whose ref count will be decremented.

Broker_Destroy()

GATEWAY_EXPORT void Broker_Destroy

(

BROKER_HANDLE

broker

)

Disposes of resources allocated by a message broker.

Parameters

broker

The BROKER_HANDLE to be destroyed.

Broker_IncRef()

GATEWAY_EXPORT void Broker_IncRef

(

BROKER_HANDLE

broker

)

Increments the reference count of a message broker.

This function will simply increment the internal reference count of the provided BROKER_HANDLE.

Parameters

broker

The BROKER_HANDLE to be cloned.

Broker_Publish()

GATEWAY_EXPORT BROKER_RESULT Broker_Publish	(	BROKER_HANDLE	broker,
		MODULE_HANDLE	source,
		MESSAGE_HANDLE	message
	)

Publishes a message to the message broker.

For details about threading with regard to the message broker and modules connected to it, see Broker High Level Design Documentation.

Parameters

broker	The BROKER_HANDLE onto which the message will be published.
source	The MODULE_HANDLE from which the message will be published. The broker will not publish the message to this module. (optional, may be NULL)
message	The MESSAGE_HANDLE representing the message to be published.

Returns

A BROKER_RESULT describing the result of the function.

Broker_RemoveLink()

GATEWAY_EXPORT BROKER_RESULT Broker_RemoveLink	(	BROKER_HANDLE	broker,
		const BROKER_LINK_DATA *	link
	)

Removes a route from the message broker.

Parameters

broker	The BROKER_HANDLE from which the link will be removed.
link	The BROKER_LINK_DATA of the link to be removed.

Returns

A BROKER_RESULT describing the result of the function.

Broker_RemoveModule()

GATEWAY_EXPORT BROKER_RESULT Broker_RemoveModule	(	BROKER_HANDLE	broker,
		const MODULE *	module
	)

Removes a module from the message broker.

Parameters

broker	The BROKER_HANDLE from which the module will be removed.
module	The MODULE of the module to be removed.

Returns

A BROKER_RESULT describing the result of the function.