#include <stdbool.h>
#include <stdlib.h>

Macros
#define	MADS_EXPORT

Typedefs
typedef void *	agent_t

Enumerations
enum	message_type_t { mads_none = 0 , mads_json = 1 , mads_blob , mads_error }

enum	event_type_t { mads_marker = 0 , mads_marker_in , mads_marker_out , mads_startup , mads_shutdown , mads_message }

Functions
MADS_EXPORT const char *	mads_version ()
	Returns the MADS library version string.

MADS_EXPORT const char *	mads_default_settings_uri ()
	Returns the default settings URI compiled into the library.

MADS_EXPORT void	mads_free (void *ptr)
	Releases memory allocated by the MADS C API.

MADS_EXPORT agent_t	agent_create (const char name, const char settings_uri)
	Creates a new agent instance.

MADS_EXPORT int	agent_init (agent_t agent, bool crypto)
	Initializes an agent before connecting it.

MADS_EXPORT void	agent_destroy (agent_t agent)
	Destroys an agent instance.

MADS_EXPORT void	agent_set_id (agent_t agent, const char *id)
	Sets the agent identifier.

MADS_EXPORT const char *	agent_id (agent_t agent)
	Returns the current agent identifier.

MADS_EXPORT void	agent_install_loop_watchdog (agent_t agent)
	Installs the internal loop watchdog for the agent.

MADS_EXPORT void	agent_set_key_dir (agent_t agent, const char *key_dir)
	Sets the directory containing authentication keys.

MADS_EXPORT void	agent_set_client_key_name (agent_t agent, const char *client_key_name)
	Sets the client key filename.

MADS_EXPORT void	agent_set_server_key_name (agent_t agent, const char *server_key_name)
	Sets the server key filename.

MADS_EXPORT void	agent_set_auth_verbose (agent_t agent, bool verbose)
	Enables or disables verbose authentication logging.

MADS_EXPORT int	agent_set_client_public_key (agent_t agent, const char *key)
	Sets the client public key.

MADS_EXPORT int	agent_set_client_secret_key (agent_t agent, const char *key)
	Sets the client secret key.

MADS_EXPORT int	agent_set_server_public_key (agent_t agent, const char *key)
	Sets the server public key.

MADS_EXPORT int	agent_setup_crypto (agent_t agent, bool verbose)
	Enables CURVE encryption and sets up authentication.

MADS_EXPORT int	agent_connect (agent_t agent, int delay_ms)
	Connects the agent to the MADS infrastructure.

MADS_EXPORT int	agent_register_event (agent_t agent, event_type_t event, const char *info_json)
	Registers an event for the connected agent.

MADS_EXPORT int	agent_disconnect (agent_t agent)
	Disconnects the agent if it is connected.

MADS_EXPORT int	agent_stop (agent_t agent)
	Requests this agent's loops to stop.

MADS_EXPORT bool	agent_running (agent_t agent)
	Whether this agent's loops should keep going.

MADS_EXPORT void	mads_stop_process (void)
	Requests a process-wide stop.

MADS_EXPORT bool	mads_process_running (void)
	Whether a process-wide stop has been requested.

MADS_EXPORT void	agent_set_receive_timeout (agent_t agent, int timeout)
	Sets the receive timeout in milliseconds.

MADS_EXPORT int	agent_receive_timeout (agent_t agent)
	Returns the current receive timeout.

MADS_EXPORT const char *	agent_last_error ()
	Returns the last error message produced by the wrapper.

MADS_EXPORT const char *	agent_get_settings (agent_t agent, int n)
	Serializes the current settings to JSON.

MADS_EXPORT int	agent_set_settings_timeout (agent_t agent, int to_ms)
	Sets the timeout used when fetching settings.

MADS_EXPORT void	agent_set_pub_topic (agent_t agent, const char *topic)
	Sets the publish topic for the agent.

MADS_EXPORT void	agent_set_sub_topics (agent_t agent, const char **topics, int n_topics)
	Sets the subscribe topics for the agent.

MADS_EXPORT const char *	agent_pub_topic (agent_t agent)
	Return publishing topic for the agent.

MADS_EXPORT int	agent_sub_topics (agent_t agent, char *topics, size_t n_topics)
	Return subscription topics for the agent.

MADS_EXPORT char *	agent_topics (agent_t agent, int tab)

MADS_EXPORT int	agent_settings_timeout (agent_t agent)
	Returns the current settings timeout.

MADS_EXPORT int	discover_broker_settings (const char room, char *url, size_t url_size)
	Discovers the broker settings URI advertised in a service room.

MADS_EXPORT bool	agent_setting_bool (agent_t agent, const char *key)
	Reads a boolean setting.

MADS_EXPORT int	agent_setting_int (agent_t agent, const char *key)
	Reads an integer setting.

MADS_EXPORT double	agent_setting_dbl (agent_t agent, const char *key)
	Reads a floating-point setting.

MADS_EXPORT const char *	agent_setting_str (agent_t agent, const char *key)
	Reads a string setting.

MADS_EXPORT void	agent_print_settings (agent_t agent, int tab)
	Prints the current settings JSON to standard output.

MADS_EXPORT const char *	agent_settings_uri (agent_t agent)
	Returns the current settings URI.

MADS_EXPORT int	agent_set_high_watermark (agent_t agent, int n)
	Sets the outgoing message high watermark.

MADS_EXPORT int	agent_high_watermark (agent_t agent)
	Returns the outgoing message high watermark.

MADS_EXPORT int	agent_set_wire_format (agent_t agent, int format)
	Sets the outgoing wire format.

MADS_EXPORT int	agent_wire_format (agent_t agent)
	Returns the outgoing wire format.

MADS_EXPORT int	agent_set_compression (agent_t agent, int compression)
	Sets the outgoing compression policy.

MADS_EXPORT int	agent_compression (agent_t agent)
	Returns the outgoing compression policy.

MADS_EXPORT int	agent_publish (agent_t agent, const char message, const char topic)
	Publishes a JSON message on a topic.

MADS_EXPORT message_type_t	agent_receive (agent_t agent, bool dont_block)
	Receives the next incoming message.

MADS_EXPORT void	agent_last_message (agent_t agent, char topic, char message)
	Returns the topic and payload of the last received message.

Macro Definition Documentation

◆ MADS_EXPORT

#define MADS_EXPORT

Definition at line 29 of file agent_c.h.

Typedef Documentation

◆ agent_t

typedef void* agent_t

Definition at line 73 of file agent_c.h.

Enumeration Type Documentation

◆ event_type_t

enum event_type_t

Enumerator
mads_marker
mads_marker_in
mads_marker_out
mads_startup
mads_shutdown
mads_message

Definition at line 82 of file agent_c.h.

◆ message_type_t

enum message_type_t

Enumerator
mads_none
mads_json
mads_blob
mads_error

Definition at line 75 of file agent_c.h.

Function Documentation

◆ agent_compression()

MADS_EXPORT int agent_compression ( agent_t agent )

Returns the outgoing compression policy.

Parameters

agent Agent handle.

Returns: 0 = None, 1 = Snappy, 2 = Auto.

◆ agent_connect()

MADS_EXPORT int agent_connect	(	agent_t	agent,
		int	delay_ms
	)

Connects the agent to the MADS infrastructure.

Parameters

agent	Agent handle.
delay_ms	Delay in milliseconds applied by the underlying connect call.

Returns: 0 on success, -1 on error.

On failure, call agent_last_error() for details.

◆ agent_create()

MADS_EXPORT agent_t agent_create	(	const char *	name,
		const char *	settings_uri
	)

Creates a new agent instance.

Parameters

name	Agent name.
settings_uri	URI or path used to load the agent settings.

Returns: Opaque handle to the created agent. Destroy it with agent_destroy().

◆ agent_destroy()

MADS_EXPORT void agent_destroy ( agent_t agent )

Destroys an agent instance.

The agent is shut down before being deleted.

Parameters

agent Agent handle.

◆ agent_disconnect()

MADS_EXPORT int agent_disconnect ( agent_t agent )

Disconnects the agent if it is connected.

Parameters

agent Agent handle.

Returns: 0 on success, -1 on error.

Returns 0 if the agent is already disconnected.

◆ agent_get_settings()

MADS_EXPORT const char * agent_get_settings	(	agent_t	agent,
		int	n
	)

Serializes the current settings to JSON.

Parameters

agent	Agent handle.
n	Indentation passed to JSON dump formatting.

Returns: Pointer to an internal null-terminated JSON string.

◆ agent_high_watermark()

MADS_EXPORT int agent_high_watermark ( agent_t agent )

Returns the outgoing message high watermark.

Parameters

agent Agent handle.

Returns: High watermark value.

◆ agent_id()

MADS_EXPORT const char * agent_id ( agent_t agent )

Returns the current agent identifier.

Parameters

agent Agent handle.

Returns: Pointer to an internal null-terminated string.

◆ agent_init()

MADS_EXPORT int agent_init	(	agent_t	agent,
		bool	crypto
	)

Initializes an agent before connecting it.

A note about cryptpographic setup: it is possible to enable cryptographic communication in two ways: by reading keys from files, or by setting them directly from strings:

For file-based setup, call agent_set_key_dir() to set the directory containing the authentication keys, agent_set_client_key_name() and agent_set_server_key_name() to set the client and server key filenames, and then call agent_init() with crypto set to true.
For direct string setup, call agent_setup_crypto() to enable
cryptography, then call agent_set_client_public_key(), agent_set_client_secret_key(), and agent_set_server_public_key() to set the keys, and finally call agent_init() with crypto set to true.

In the second form, it is an error to call agent_init() with crypto set to true before setting the keys, or to set the keys before calling agent_setup_crypto().

Parameters

agent	Agent handle.
crypto	Enables cryptographic setup when true.

Returns: 0 on success, -1 on error.

On failure, call agent_last_error() for details.

◆ agent_install_loop_watchdog()

MADS_EXPORT void agent_install_loop_watchdog ( agent_t agent )

Installs the internal loop watchdog for the agent.

Parameters

agent Agent handle.

◆ agent_last_error()

MADS_EXPORT const char * agent_last_error ( )

Returns the last error message produced by the wrapper.

Returns: Pointer to an internal null-terminated string.

◆ agent_last_message()

MADS_EXPORT void agent_last_message	(	agent_t	agent,
		char **	topic,
		char **	message
	)

Returns the topic and payload of the last received message.

Parameters

agent	Agent handle.
topic	Output pointer receiving the topic string.
message	Output pointer receiving the message payload string.

The returned pointers refer to internal storage that is overwritten by the next call to this function.

◆ agent_print_settings()

MADS_EXPORT void agent_print_settings	(	agent_t	agent,
		int	tab
	)

Prints the current settings JSON to standard output.

Parameters

agent	Agent handle.
tab	Indentation passed to JSON dump formatting.

◆ agent_pub_topic()

MADS_EXPORT const char * agent_pub_topic ( agent_t agent )

Return publishing topic for the agent.

Parameters

agent

Returns: MADS_EXPORT const*

◆ agent_publish()

MADS_EXPORT int agent_publish	(	agent_t	agent,
		const char *	message,
		const char *	topic
	)

Publishes a JSON message on a topic.

Parameters

agent	Agent handle.
message	Null-terminated JSON string.
topic	Topic name.

Returns: 0 on success, -1 on error.

On failure, call agent_last_error() for details.

◆ agent_receive()

MADS_EXPORT message_type_t agent_receive	(	agent_t	agent,
		bool	dont_block
	)

Receives the next incoming message.

Parameters

agent	Agent handle.
dont_block	When true, performs a non-blocking receive.

Returns: Received message type, mads_none if no message is available, or mads_error on failure.

◆ agent_receive_timeout()

MADS_EXPORT int agent_receive_timeout ( agent_t agent )

Returns the current receive timeout.

Parameters

agent Agent handle.

Returns: Receive timeout in milliseconds.

◆ agent_register_event()

MADS_EXPORT int agent_register_event	(	agent_t	agent,
		event_type_t	event,
		const char *	info_json
	)

Registers an event for the connected agent.

Parameters

agent	Agent handle.
event	Event type to register.
info_json	Optional JSON payload string. Pass `NULL` for no payload.

Returns: 0 on success, -1 on error.

On failure, call agent_last_error() for details.

◆ agent_running()

MADS_EXPORT bool agent_running ( agent_t agent )

Whether this agent's loops should keep going.

False after agent_stop(), agent_disconnect(), a remote shutdown/restart command, or a process-wide stop (mads_stop_process(), SIGINT/SIGTERM). Reconnecting with agent_connect() re-arms a stop raised by agent_disconnect().

Parameters

agent Agent handle.

Returns: true while the agent should keep running; false otherwise (including for a NULL handle).

◆ agent_set_auth_verbose()

MADS_EXPORT void agent_set_auth_verbose	(	agent_t	agent,
		bool	verbose
	)

Enables or disables verbose authentication logging.

Parameters

agent	Agent handle.
verbose	Set to true to enable verbose output.

◆ agent_set_client_key_name()

MADS_EXPORT void agent_set_client_key_name	(	agent_t	agent,
		const char *	client_key_name
	)

Sets the client key filename.

Parameters

agent	Agent handle.
client_key_name	Client key filename.

◆ agent_set_client_public_key()

MADS_EXPORT int agent_set_client_public_key	(	agent_t	agent,
		const char *	key
	)

Sets the client public key.

Note that this functiuon must be called after agent_setup_crypto() and before agent_connect()

Parameters

agent	Agent handle.
key	Public key string.

Returns: 0 on success, -1 on error.

◆ agent_set_client_secret_key()

MADS_EXPORT int agent_set_client_secret_key	(	agent_t	agent,
		const char *	key
	)

Sets the client secret key.

Note that this functiuon must be called after agent_setup_crypto() and before agent_connect()

Parameters

agent	Agent handle.
key	Secret key string.

Returns: 0 on success, -1 on error.

◆ agent_set_compression()

MADS_EXPORT int agent_set_compression	(	agent_t	agent,
		int	compression
	)

Sets the outgoing compression policy.

Parameters

agent	Agent handle.
compression	`0` = None, `1` = Snappy, `2` = Auto (default).

Returns: 0 on success, -1 on error.

◆ agent_set_high_watermark()

MADS_EXPORT int agent_set_high_watermark	(	agent_t	agent,
		int	n
	)

Sets the outgoing message high watermark.

Parameters

agent	Agent handle.
n	High watermark value.

Returns: 0 on success, -1 on error.

◆ agent_set_id()

MADS_EXPORT void agent_set_id	(	agent_t	agent,
		const char *	id
	)

Sets the agent identifier.

Parameters

agent	Agent handle.
id	Null-terminated identifier string.

◆ agent_set_key_dir()

MADS_EXPORT void agent_set_key_dir	(	agent_t	agent,
		const char *	key_dir
	)

Sets the directory containing authentication keys.

Parameters

agent	Agent handle.
key_dir	Filesystem path to the key directory.

◆ agent_set_pub_topic()

MADS_EXPORT void agent_set_pub_topic	(	agent_t	agent,
		const char *	topic
	)

Sets the publish topic for the agent.

Parameters

agent	Agent handle.
topic	Publish topic.

Returns: MADS_export

◆ agent_set_receive_timeout()

MADS_EXPORT void agent_set_receive_timeout	(	agent_t	agent,
		int	timeout
	)

Sets the receive timeout in milliseconds.

Parameters

agent	Agent handle.
timeout	Timeout in milliseconds.

◆ agent_set_server_key_name()

MADS_EXPORT void agent_set_server_key_name	(	agent_t	agent,
		const char *	server_key_name
	)

Sets the server key filename.

Parameters

agent	Agent handle.
server_key_name	Server key filename.

◆ agent_set_server_public_key()

MADS_EXPORT int agent_set_server_public_key	(	agent_t	agent,
		const char *	key
	)

Sets the server public key.

Note that this functiuon must be called after agent_setup_crypto() and before agent_connect()

Parameters

agent	Agent handle.
key	Public key string.

Returns: 0 on success, -1 on error.

◆ agent_set_settings_timeout()

MADS_EXPORT int agent_set_settings_timeout	(	agent_t	agent,
		int	to_ms
	)

Sets the timeout used when fetching settings.

Parameters

agent	Agent handle.
to_ms	Timeout in milliseconds.

Returns: 0 on success, -1 on error.

◆ agent_set_sub_topics()

MADS_EXPORT void agent_set_sub_topics	(	agent_t	agent,
		const char **	topics,
		int	n_topics
	)

Sets the subscribe topics for the agent.

Parameters

agent	Agent handle.
topics	Array of null-terminated topic strings.
n_topics	Number of topics in the array.

Returns: MADS_export

◆ agent_set_wire_format()

MADS_EXPORT int agent_set_wire_format	(	agent_t	agent,
		int	format
	)

Sets the outgoing wire format.

Parameters

agent	Agent handle.
format	`0` = JSON (default), `1` = MessagePack.

Returns: 0 on success, -1 on error.

◆ agent_setting_bool()

MADS_EXPORT bool agent_setting_bool	(	agent_t	agent,
		const char *	key
	)

Reads a boolean setting.

Parameters

agent	Agent handle.
key	Setting key.

Returns: Setting value, or false if the key is missing.

◆ agent_setting_dbl()

MADS_EXPORT double agent_setting_dbl	(	agent_t	agent,
		const char *	key
	)

Reads a floating-point setting.

Parameters

agent	Agent handle.
key	Setting key.

Returns: Setting value, or 0.0 if the key is missing.

◆ agent_setting_int()

MADS_EXPORT int agent_setting_int	(	agent_t	agent,
		const char *	key
	)

Reads an integer setting.

Parameters

agent	Agent handle.
key	Setting key.

Returns: Setting value, or 0 if the key is missing.

◆ agent_setting_str()

MADS_EXPORT const char * agent_setting_str	(	agent_t	agent,
		const char *	key
	)

Reads a string setting.

Parameters

agent	Agent handle.
key	Setting key.

Returns: Pointer to an internal null-terminated string. Returns an empty string if the key is missing.

◆ agent_settings_timeout()

MADS_EXPORT int agent_settings_timeout ( agent_t agent )

Returns the current settings timeout.

Parameters

agent Agent handle.

Returns: Timeout in milliseconds.

◆ agent_settings_uri()

MADS_EXPORT const char * agent_settings_uri ( agent_t agent )

Returns the current settings URI.

Parameters

agent Agent handle.

Returns: Pointer to an internal null-terminated string.

◆ agent_setup_crypto()

MADS_EXPORT int agent_setup_crypto	(	agent_t	agent,
		bool	verbose
	)

Enables CURVE encryption and sets up authentication.

Note that this function must be called before agent_init() and before setting the keys

Parameters

agent	Agent handle.
verbose	Set to true to enable verbose output.

Returns: 0 on success, -1 on error.

On failure, call agent_last_error() for details.

◆ agent_stop()

MADS_EXPORT int agent_stop ( agent_t agent )

Requests this agent's loops to stop.

Stops the agent's Mads::Runtime; other agents in the same process keep running unless they share the same Runtime. Use this to end a receive loop driven by agent_running().

Parameters

agent Agent handle.

Returns: 0 on success, -1 on error (NULL handle).

◆ agent_sub_topics()

MADS_EXPORT int agent_sub_topics	(	agent_t	agent,
		char **	topics,
		size_t *	n_topics
	)

Return subscription topics for the agent.

The topics output parameter receives an array of null-terminated strings containing the subscription topics. Pass the address of a char* initialized to NULL to have the function allocate the array with malloc(); the caller owns it and must release it with mads_free(). The n_topics output parameter receives the number of topics in the array.

Parameters

agent
topics
n_topics

Returns: MADS_EXPORT

◆ agent_topics()

MADS_EXPORT char * agent_topics	(	agent_t	agent,
		int	tab
	)

◆ agent_wire_format()

MADS_EXPORT int agent_wire_format ( agent_t agent )

Returns the outgoing wire format.

Parameters

agent Agent handle.

Returns: 0 = JSON, 1 = MessagePack.

◆ discover_broker_settings()

MADS_EXPORT int discover_broker_settings	(	const char *	room,
		char **	url,
		size_t	url_size
	)

Discovers the broker settings URI advertised in a service room.

If room is NULL or empty, the compiled default MADS service room is used. The discovered URI is written as tcp://ip:port.

Parameters

room	Service discovery room name, or NULL for the default room.
url	Pointer to the output buffer receiving the null-terminated settings URI. Pass the address of a char* initialized to NULL to have the function allocate a buffer with malloc(); the caller owns it and must release it with mads_free().
url_size	Size of the provided output buffer in bytes. Ignored when the function allocates the buffer.

Returns: 0 on success, -1 on error.

On failure, call agent_last_error() for details.

◆ mads_default_settings_uri()

MADS_EXPORT const char * mads_default_settings_uri ( )

Returns the default settings URI compiled into the library.

Returns: Pointer to an internal null-terminated string.

◆ mads_free()

MADS_EXPORT void mads_free ( void * ptr )

Releases memory allocated by the MADS C API.

Use this for buffers returned by functions that allocate output memory. This keeps allocation and deallocation inside the same runtime on Windows.

Parameters

ptr	Pointer returned by a MADS C API allocation, or NULL.

◆ mads_process_running()

MADS_EXPORT bool mads_process_running ( void )

Whether a process-wide stop has been requested.

Returns: true until mads_stop_process() (or a signal handler) stops the process-wide run flag.

◆ mads_stop_process()

MADS_EXPORT void mads_stop_process ( void )

Requests a process-wide stop.

Every agent's agent_running() becomes false, as with SIGINT/SIGTERM.

◆ mads_version()

MADS_EXPORT const char * mads_version ( )

Returns the MADS library version string.

Returns: Pointer to an internal null-terminated string.

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ MADS_EXPORT

Typedef Documentation

◆ agent_t

Enumeration Type Documentation

◆ event_type_t

◆ message_type_t

Function Documentation

◆ agent_compression()

◆ agent_connect()

◆ agent_create()

◆ agent_destroy()

◆ agent_disconnect()

◆ agent_get_settings()

◆ agent_high_watermark()

◆ agent_id()

◆ agent_init()

◆ agent_install_loop_watchdog()

◆ agent_last_error()

◆ agent_last_message()

◆ agent_print_settings()

◆ agent_pub_topic()

◆ agent_publish()

◆ agent_receive()

◆ agent_receive_timeout()

◆ agent_register_event()

◆ agent_running()

◆ agent_set_auth_verbose()

◆ agent_set_client_key_name()

◆ agent_set_client_public_key()

◆ agent_set_client_secret_key()

◆ agent_set_compression()

◆ agent_set_high_watermark()

◆ agent_set_id()

◆ agent_set_key_dir()

◆ agent_set_pub_topic()

◆ agent_set_receive_timeout()

◆ agent_set_server_key_name()

◆ agent_set_server_public_key()

◆ agent_set_settings_timeout()

◆ agent_set_sub_topics()

◆ agent_set_wire_format()

◆ agent_setting_bool()

◆ agent_setting_dbl()

◆ agent_setting_int()

◆ agent_setting_str()

◆ agent_settings_timeout()

◆ agent_settings_uri()

◆ agent_setup_crypto()

◆ agent_stop()

◆ agent_sub_topics()

◆ agent_topics()

◆ agent_wire_format()

◆ discover_broker_settings()

◆ mads_default_settings_uri()

◆ mads_free()

◆ mads_process_running()

◆ mads_stop_process()

◆ mads_version()