module.h File Reference

Interface for modules which communicate with other modules via a message broker. More...

#include "azure_c_shared_utility/macro_utils.h"
#include "broker.h"
#include "message.h"

Go to the source code of this file.

Data Structures
struct	MODULE_TAG
	Structure used to represent/abstract the idea of a module. May contain Handle/FxnPtrs or an interface ptr or some unforseen representation. More...
struct	MODULE_API_TAG
	Structure returned by Module_GetApi containing the API version. By convention, the module returns a compound structure containing this structure and a function table. The version determines the function table attached to the structure. More...
struct	MODULE_API_1_TAG
	The module interface, version 1. An instance of this struct contains function pointers to module-specific implementations of the interface. More...

Macros
#define	MODULE_GETAPI_NAME   ("Module_GetApi")
	Returns the module APIS name.
#define	MODULE_STATIC_GETAPI(MODULE_NAME)   C2(Module_GetApi_, MODULE_NAME)
	Returns a unique name for pfModule_GetApi that is used when the module is statically linked.

Typedefs
typedef struct MODULE_TAG	MODULE
	Encapsulates a module's handle and a cached copy of its interface.
typedef void *	MODULE_HANDLE
	Represents a module instance.
typedef struct MODULE_API_TAG	MODULE_API
	Provides access to a module's interface.
typedef void *(*	pfModule_ParseConfigurationFromJson) (const char *configuration)
	Translates module configuration from a JSON string to a module specific data structure. More...
typedef void(*	pfModule_FreeConfiguration) (void *configuration)
	Frees the configuration object returned by the ParseConfigurationFromJson function. More...
typedef MODULE_HANDLE(*	pfModule_Create) (BROKER_HANDLE broker, const void *configuration)
	Creates an instance of a module. More...
typedef void(*	pfModule_Destroy) (MODULE_HANDLE moduleHandle)
	Disposes of the resources managed by this module. More...
typedef void(*	pfModule_Receive) (MODULE_HANDLE moduleHandle, MESSAGE_HANDLE messageHandle)
	Receives a message from the broker. More...
typedef void(*	pfModule_Start) (MODULE_HANDLE moduleHandle)
	Signals to the module that the broker is ready to send and receive messages. More...
typedef enum MODULE_API_VERSION_TAG	MODULE_API_VERSION
	Module API version.
typedef struct MODULE_API_1_TAG	MODULE_API_1
	The module interface, version 1. An instance of this struct contains function pointers to module-specific implementations of the interface.
typedef const MODULE_API *(*	pfModule_GetApi) (MODULE_API_VERSION gateway_api_version)
	This is the only function exported by a module. Using the exported function, the caller learns the functions for the particular module. More...

Enumerations
enum	MODULE_API_VERSION_TAG { MODULE_API_VERSION_1 }
	Module API version.

Functions
MODULE_EXPORT const MODULE_API *	Module_GetApi (MODULE_API_VERSION gateway_api_version)
	This is the only function exported by a module under a "by convention" name. Using the exported function, the caller learns the functions for the particular module.

Detailed Description

Interface for modules which communicate with other modules via a message broker.

Every module associated with the message broker must implement this interface. A module can only belong to one message broker; a message broker may have many modules associated with it.

Every module library exports a function (Module_GetApi) that returns a pointer to the MODULE_API structure.

Typedef Documentation

pfModule_Create

typedef MODULE_HANDLE(* pfModule_Create) (BROKER_HANDLE broker, const void *configuration)

Creates an instance of a module.

This function must be implemented.

Parameters

broker	The BROKER_HANDLE to which this module will publish messages.
configuration	A pointer to the user-defined configuration structure for this module.

Returns

A non-NULL MODULE_HANDLE upon success, otherwise NULL.

pfModule_Destroy

typedef void(* pfModule_Destroy) (MODULE_HANDLE moduleHandle)

Disposes of the resources managed by this module.

This function must be implemented.

Parameters

moduleHandle

The MODULE_HANDLE of the module to be destroyed.

pfModule_FreeConfiguration

typedef void(* pfModule_FreeConfiguration) (void *configuration)

Frees the configuration object returned by the ParseConfigurationFromJson function.

This function must be implemented by modules that support configuration options.

Parameters

configuration

A void pointer containing a parsed representation of the module's configuration.

pfModule_GetApi

typedef const MODULE_API*(* pfModule_GetApi) (MODULE_API_VERSION gateway_api_version)

This is the only function exported by a module. Using the exported function, the caller learns the functions for the particular module.

Parameters

gateway_api_version

The current API version of the gateway.

Returns

NULL in failure, MODULE_API* pointer on success.

pfModule_ParseConfigurationFromJson

typedef void*(* pfModule_ParseConfigurationFromJson) (const char *configuration)

Translates module configuration from a JSON string to a module specific data structure.

This function must be implemented by modules that support configuration options.

Parameters

configuration

A JSON string which describes any needed configuration to create this module.

Returns

A void pointer containing a parsed representation of the module's configuration.

pfModule_Receive

typedef void(* pfModule_Receive) (MODULE_HANDLE moduleHandle, MESSAGE_HANDLE messageHandle)

Receives a message from the broker.

This function must be implemented.

Parameters

moduleHandle	The MODULE_HANDLE of the module receiving the message.
messageHandle	The MESSAGE_HANDLE of the message being sent to the module.

pfModule_Start

typedef void(* pfModule_Start) (MODULE_HANDLE moduleHandle)

Signals to the module that the broker is ready to send and receive messages.

This function is optional, but recommended. Messaging in the gateway is more predictable when modules delay publishing until after this function is called.

Parameters

moduleHandle

The target module's MODULE_HANDLE.