agent.h File Reference

#include "callbacks.h"
#include "channel.h"
#include "common.h"
#include "limits.h"
#include "options.h"
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	yami_agent
	Message broker. More...

Functions
void	yami_init (struct yami_agent *self)
	Initializer. More...
void	yami_init_with_user_array (struct yami_agent *self, struct yami_channel channels_array[], size_t channels_array_size)
	Initializer. More...
void	yami_init_with_options (struct yami_agent *self, const struct yami_options *options)
	Initializer. More...
void	yami_init_with_options_ua (struct yami_agent *self, const struct yami_options *options, struct yami_channel channels_array[], size_t channels_array_size)
	Initializer. More...
enum yami_result	yami_clean (struct yami_agent *self)
	Destructor. More...
void	yami_set_io_error_callback (struct yami_agent *self, yami_io_error_function io_error_callback)
	Sets the error logger callback function. More...
void	yami_set_raw_message_callback (struct yami_agent *self, yami_raw_message_function raw_message_callback)
	Sets the raw message callback. More...
void	yami_set_message_callback (struct yami_agent *self, yami_message_function message_callback)
	Sets the high-level message callback. More...
void	yami_set_connection_callback (struct yami_agent *self, yami_connection_event_function connection_callback)
	Sets the connection event callback. More...
enum yami_result	yami_set_listener (struct yami_agent *self, const char target[])
	Sets the optional listener. More...
enum yami_result	yami_open_connection (struct yami_agent *self, const char target[])
	Creates (opens) outgoing communication channel. More...
enum yami_result	yami_close_connection (struct yami_agent *self, const char target[])
	Closes communication channel. More...
enum yami_result	yami_is_output_channel_busy (const struct yami_agent *self, const char target[], int32_t *out_busy)
	Checks if there is space in the output channel. More...
enum yami_result	yami_post_raw_message (struct yami_agent *self, const char target[], const uint8_t header[], size_t header_size, const uint8_t body[], size_t body_size)
	Posts the raw message. More...
enum yami_result	yami_post_message (struct yami_agent *self, const char target[], const char object_name[], const char message_name[], const uint8_t body[], size_t body_size, int64_t *out_message_id)
	Posts the high-level message. More...
enum yami_result	yami_post_reply (struct yami_agent *self, const char target[], int64_t message_id, const uint8_t body[], size_t body_size)
	Posts the high-level message reply. More...
enum yami_result	yami_post_reject (struct yami_agent *self, const char target[], int64_t message_id, const char reason[])
	Posts the high-level message rejection. More...
enum yami_result	yami_do_some_work (struct yami_agent *self, size_t timeout)
	Performs some unit of network-related activity. More...

Function Documentation

enum yami_result yami_clean

(

struct yami_agent *

self

)

Destructor.

Cleans up the agent's system resources.

Parameters

self	this object

Returns

yami_ok or yami_io_error in case of any system-related errors.

enum yami_result yami_close_connection	(	struct yami_agent *	self,
		const char	target[]
	)

Closes communication channel.

Closes communication channel. This function can be used to close outgoing and incoming communication channels.

Parameters

self	this object
target	endpoint name for the channel that is to be closed

Returns

yami_ok if the oporation was successful or the channel does not exist or yami_io_error in case of system error

enum yami_result yami_do_some_work	(	struct yami_agent *	self,
		size_t	timeout
	)

Performs some unit of network-related activity.

Parameters

self	this object
timeout	maximum blocking time, 0u means indefinite

Returns

yami_ok if the work is performed, yami_timed_out if no work was pending during the given time, yami_io_error in case of system-related error, yami_unexpected_value if the new connection is created but the target cannot be formatted or yami_bad_state if there is no event to wait for

void yami_init

(

struct yami_agent *

self

)

Initializer.

Initializes the agent object to the basic operational state, using the internal static array of channels. No network resources are allocated. All socket-related options have their default values.

This function always succeeds as it does not take into account any previous object state.

Parameters

self	this object

void yami_init_with_options	(	struct yami_agent *	self,
		const struct yami_options *	options
	)

Initializer.

Initializes the agent object to the basic operational state with the given set of options. No network resources are allocated.

This function always succeeds as it does not take into account any previous object state.

Parameters

self	this object
options	user-provided option values

void yami_init_with_options_ua	(	struct yami_agent *	self,
		const struct yami_options *	options,
		struct yami_channel	channels_array[],
		size_t	channels_array_size
	)

Initializer.

Initializes the agent object to the basic operational state with the given set of options and the array of channels allocated by user; channels do not have to be initialized. No network resources are allocated.

This function always succeeds as it does not take into account any previous object state.

Parameters

self	this object
options	options user-provided option values
channels_array	array of channel structures, preallocated by caller
channels_array_size	number of channel structures in the array

void yami_init_with_user_array	(	struct yami_agent *	self,
		struct yami_channel	channels_array[],
		size_t	channels_array_size
	)

Initializer.

Initializes the agent object to the basic operational state, using the array of channels allocated by user; channels do not have to be initialized. No network resources are allocated. All socket-related options have their default values.

This function always succeeds as it does not take into account any previous object state.

Parameters

self	this object
channels_array	array of channel structures, preallocated by caller
channels_array_size	number of channel structures in the array

enum yami_result yami_is_output_channel_busy	(	const struct yami_agent *	self,
		const char	target[],
		int32_t *	out_busy
	)

Checks if there is space in the output channel.

Checks if there is space in the output channel for the new message.

Parameters

self	this object
target	endpoint name for the channel that is to be checked
out_busy	variable to be set to 1 if the channel is busy

Returns

yami_ok if the oporation was successful or yami_no_such_name if there is no such channel

enum yami_result yami_open_connection	(	struct yami_agent *	self,
		const char	target[]
	)

Creates (opens) outgoing communication channel.

Creates (opens) outgoing communication channel if it does not yet exist.

Parameters

self	this object
target	endpoint name for the new connection

Returns

yami_ok if the connection was successful or the channel already exists or yami_not_enough_space if there is no place for the new channels or yami_io_error in case of system error

enum yami_result yami_post_message	(	struct yami_agent *	self,
		const char	target[],
		const char	object_name[],
		const char	message_name[],
		const uint8_t	body[],
		size_t	body_size,
		int64_t *	out_message_id
	)

Posts the high-level message.

Posts the high-level message. Note: the message is placed in the outgoing buffer, but in order to physically send it to the remote recevier the I/O work needs to be done on this agent.

Parameters

self	this object
target	endpoint name for the channel where the message should be sent
object_name	name of logical message destination
message_name	name of message
body	already serialized body buffer
body_size	size of the body buffer
out_message_id	high-level message identifier, allocated by this agent

Returns

yami_ok if the message was posted, yami_no_such_name if the given target does not reference any open channel or yami_not_enough_space if the message is bigger than the buffer space

enum yami_result yami_post_raw_message	(	struct yami_agent *	self,
		const char	target[],
		const uint8_t	header[],
		size_t	header_size,
		const uint8_t	body[],
		size_t	body_size
	)

Posts the raw message.

Posts the raw message that was already serialized by user. The user is supposed to provide his own message header. Note: the message is placed in the outgoing buffer, but in order to physically send it to the remote recevier the I/O work needs to be done on this agent.

Parameters

self	this object
target	endpoint name for the channel where the message should be sent
header	already serialized header buffer
header_size	size of the header buffer
body	already serialized body buffer
body_size	size of the body buffer

Returns

yami_ok if the message was posted, yami_no_such_name if the given target does not reference any open channel or yami_not_enough_space if the message is bigger than the buffer space

enum yami_result yami_post_reject	(	struct yami_agent *	self,
		const char	target[],
		int64_t	message_id,
		const char	reason[]
	)

Posts the high-level message rejection.

Posts the high-level message rejection. Note: the message rejection is placed in the outgoing buffer, but in order to physically send it to the remote recevier the I/O work needs to be done on this agent.

Parameters

self	this object
target	endpoint name for the channel where the rejection should be sent, in typical scenario this should be the originating endpoint
message_id	high-level message identifier, allocated by remote sender
reason	exception message, intended as description of why the original message is rejected

Returns

yami_ok if the message was posted, yami_no_such_name if the given target does not reference any open channel or yami_not_enough_space if the message is bigger than the buffer space

enum yami_result yami_post_reply	(	struct yami_agent *	self,
		const char	target[],
		int64_t	message_id,
		const uint8_t	body[],
		size_t	body_size
	)

Posts the high-level message reply.

Posts the high-level message reply. Note: the message reply is placed in the outgoing buffer, but in order to physically send it to the remote recevier the I/O work needs to be done on this agent.

Parameters

self	this object
target	endpoint name for the channel where the reply should be sent, in typical scenario this should be the originating endpoint
message_id	high-level message identifier, allocated by remote sender
body	already serialized body buffer
body_size	size of the body buffer

Returns

yami_ok if the message was posted, yami_no_such_name if the given target does not reference any open channel or yami_not_enough_space if the message is bigger than the buffer space

void yami_set_connection_callback	(	struct yami_agent *	self,
		yami_connection_event_function	connection_callback
	)

Sets the connection event callback.

Sets the connection event callback function, which will be called whenever new connection is created or existing connection is closed.

Note: It is possible to execute any function from the callback, but depending on the actual action it may lead to further (that is, recursive) callback invocations.

This function always succeeds.

Parameters

self	this object
connection_callback	user-provided connection callback

void yami_set_io_error_callback	(	struct yami_agent *	self,
		yami_io_error_function	io_error_callback
	)

Sets the error logger callback function.

Sets the error logger callback function that will be called in case of I/O or system error.

This function always succeeds.

Parameters

self	this object
io_error_callback	user-provided I/O error logger callback

enum yami_result yami_set_listener	(	struct yami_agent *	self,
		const char	target[]
	)

Sets the optional listener.

Sets the optional listener in the agent. The listener will operate based on the given target.

Parameters

self	this object
target	target defining the protocol and local network endpoint

Returns

yami_ok or yami_io_error in case of system errors or yami_bad_state if this agent already has a listener

void yami_set_message_callback	(	struct yami_agent *	self,
		yami_message_function	message_callback
	)

Sets the high-level message callback.

Sets the high-level message callback function, which will be called when there is a new incoming message, or when there is a reply, rejection or error report for previously sent outgoing message.

Note: It is possible to execute any function from the callback, but depending on the actual action it may lead to further (that is, recursive) callback invocations.

This function always succeeds.

Parameters

self	this object
message_callback	user-provided high-level message callback

void yami_set_raw_message_callback	(	struct yami_agent *	self,
		yami_raw_message_function	raw_message_callback
	)

Sets the raw message callback.

Sets the raw message callback function, which will be called when there is a new incoming message.

Note: It is possible to execute any function from the callback, but depending on the actual action it may lead to further (that is, recursive) callback invocations.

This function always succeeds.

Parameters

self	this object
raw_message_callback	user-provided raw message callback