This file defines the eFTL API. More...

Data Structures
struct	tibeftlOptions
	eFTL options. More...

struct	tibeftlSubscriptionOptions
	Subscription options. More...

Macros
#define	TIBEFTL_FIELD_NAME_DESTINATION "_dest"
	Message field name identifying the EMS destination of a message. More...

#define	tibeftlOptionsDefault { 2, NULL, NULL, NULL, NULL, false, 10000, 5, 30000, NULL, NULL, 0 }

#define	tibeftlSubscriptionOptionsDefault { TIBEFTL_ACKNOWLEDGE_MODE_AUTO, NULL, NULL }

Error Codes
Error codes returned by eFTL.
#define	TIBEFTL_ERR_OK (0)
	No error has been reported. More...

#define	TIBEFTL_ERR_INVALID_ARG (1)
	Invalid argument. More...

#define	TIBEFTL_ERR_NO_MEMORY (2)
	Memory allocation failed. More...

#define	TIBEFTL_ERR_TIMEOUT (3)
	Request timeout. More...

#define	TIBEFTL_ERR_NOT_FOUND (4)
	Item not found. More...

#define	TIBEFTL_ERR_INVALID_TYPE (5)
	Item of wrong type. More...

#define	TIBEFTL_ERR_NOT_SUPPORTED (6)
	Not supported. More...

#define	TIBEFTL_ERR_NOT_CONNECTED (8)
	Not connected. More...

#define	TIBEFTL_ERR_CONNECTION_LOST (9)
	Connection lost. More...

#define	TIBEFTL_ERR_CONNECT_FAILED (10)
	Connect failed. More...

#define	TIBEFTL_ERR_PUBLISH_FAILED (11)
	Publish failed. More...

#define	TIBEFTL_ERR_PUBLISH_NOT_AUTHORIZED (12)
	Publish failed, not authorized. More...

#define	TIBEFTL_ERR_SUBSCRIPTION_NOT_AUTHORIZED (13)
	Subscription failed, not authorized. More...

#define	TIBEFTL_ERR_SUBSCRIPTION_FAILED (21)
	Subscription failed. More...

#define	TIBEFTL_ERR_SUBSCRIPTION_INVALID (22)
	Subscription failed, invalid matcher or durable. More...

#define	TIBEFTL_ERR_MAP_REQUEST_NOT_AUTHORIZED (14)
	Map request failed, not authorized. More...

#define	TIBEFTL_ERR_MAP_REQUEST_FAILED (30)
	Map request failed. More...

#define	TIBEFTL_ERR_REQUEST_NOT_AUTHORIZED (40)
	Request not authorized. More...

#define	TIBEFTL_ERR_REQUEST_FAILED (41)
	Request failed. More...

#define	TIBEFTL_ERR_GOING_AWAY (1001)
	Server is shutting down. More...

#define	TIBEFTL_ERR_MESSAGE_TOO_BIG (1009)
	Published message is too big. More...

#define	TIBEFTL_ERR_SERVICE_RESTART (1012)
	Server is restarting. More...

#define	TIBEFTL_ERR_FORCE_CLOSE (4000)
	Server closed the connection. More...

#define	TIBEFTL_ERR_UNAVAILABLE (4001)
	Server is temporarily unavailable. More...

#define	TIBEFTL_ERR_AUTHENTICATION (4002)
	Authentication failed. More...

Durable Types
Durable types.
#define	TIBEFTL_DURABLE_TYPE_SHARED "shared"
	Shared durable. More...

#define	TIBEFTL_DURABLE_TYPE_LAST_VALUE "last-value"
	Last-value durable. More...

Typedefs
typedef struct tibeftlConnectionStruct *	tibeftlConnection
	eFTL connection. More...

typedef struct tibeftlErrStruct *	tibeftlErr
	eFTL error. More...

typedef void(*	tibeftlErrorCallback )(tibeftlConnection conn, tibeftlErr err, void *arg)
	Connection error callback. More...

typedef struct tibeftlKVMapStruct *	tibeftlKVMap
	eFTL key-value map. More...

typedef struct tibeftlMessageStruct *	tibeftlMessage
	eFTL message. More...

typedef void(*	tibeftlMessageCallback )(tibeftlConnection conn, tibeftlSubscription sub, int cnt, tibeftlMessage msg, void arg)
	Message callback. More...

typedef void(*	tibeftlStateCallback )(tibeftlConnection conn, tibeftlConnectionState state, void *arg)
	Connection state callback. More...

typedef struct tibeftlSubscriptionStruct *	tibeftlSubscription
	eFTL subscription. More...

Enumerations
enum	tibeftlAcknowledgeMode { TIBEFTL_ACKNOWLEDGE_MODE_AUTO, TIBEFTL_ACKNOWLEDGE_MODE_CLIENT, TIBEFTL_ACKNOWLEDGE_MODE_NONE }
	Acknowledge mode. More...

enum	tibeftlConnectionState { STATE_INITIAL, STATE_DISCONNECTED, STATE_CONNECTING, STATE_CONNECTED, STATE_DISCONNECTING, STATE_RECONNECTING }
	Connection states. More...

enum	tibeftlFieldType { TIBEFTL_FIELD_TYPE_UNKNOWN, TIBEFTL_FIELD_TYPE_STRING, TIBEFTL_FIELD_TYPE_STRING_ARRAY, TIBEFTL_FIELD_TYPE_LONG, TIBEFTL_FIELD_TYPE_LONG_ARRAY, TIBEFTL_FIELD_TYPE_DOUBLE, TIBEFTL_FIELD_TYPE_DOUBLE_ARRAY, TIBEFTL_FIELD_TYPE_TIME, TIBEFTL_FIELD_TYPE_TIME_ARRAY, TIBEFTL_FIELD_TYPE_MESSAGE, TIBEFTL_FIELD_TYPE_MESSAGE_ARRAY, TIBEFTL_FIELD_TYPE_OPAQUE }
	eFTL message field types. More...

Functions
DLL_EXPORT void	tibeftl_Acknowledge (tibeftlErr err, tibeftlConnection conn, tibeftlMessage msg)
	Acknowledge this message. More...

DLL_EXPORT void	tibeftl_AcknowledgeAll (tibeftlErr err, tibeftlConnection conn, tibeftlMessage msg)
	Acknowledge all messages up to and including this message. More...

DLL_EXPORT tibeftlConnection	tibeftl_Connect (tibeftlErr err, const char url, tibeftlOptions opts, tibeftlErrorCallback errCb, void *errCbArg)
	Connect to the server. More...

DLL_EXPORT tibeftlKVMap	tibeftl_CreateKVMap (tibeftlErr err, tibeftlConnection conn, const char *name)
	Create a key-value map. More...

DLL_EXPORT void	tibeftl_Disconnect (tibeftlErr err, tibeftlConnection conn)
	Disconnect from the server and free all resources associated with the connection, including the connection object itself. More...

DLL_EXPORT bool	tibeftl_IsConnected (tibeftlErr err, tibeftlConnection conn)
	Check whether or not there is a connection to the server. More...

DLL_EXPORT void	tibeftl_Publish (tibeftlErr err, tibeftlConnection conn, tibeftlMessage msg)
	Publish a message to all subscribing clients. More...

DLL_EXPORT void	tibeftl_Reconnect (tibeftlErr err, tibeftlConnection conn)
	Reconnect to the server. More...

DLL_EXPORT void	tibeftl_RemoveKVMap (tibeftlErr err, tibeftlConnection conn, const char *name)
	Remove a key-value map. More...

DLL_EXPORT void	tibeftl_SendReply (tibeftlErr err, tibeftlConnection conn, tibeftlMessage reply, tibeftlMessage request)
	Send a reply message in response to a request message. More...

DLL_EXPORT tibeftlMessage	tibeftl_SendRequest (tibeftlErr err, tibeftlConnection conn, tibeftlMessage request, int64_t timeout)
	Publish a request message and wait for a reply. More...

DLL_EXPORT tibeftlSubscription	tibeftl_Subscribe (tibeftlErr err, tibeftlConnection conn, const char matcher, const char durable, tibeftlMessageCallback msgCb, void *msgCbArg)
	Subscribe to messages. More...

DLL_EXPORT tibeftlSubscription	tibeftl_SubscribeWithOptions (tibeftlErr err, tibeftlConnection conn, const char matcher, const char durable, tibeftlSubscriptionOptions opts, tibeftlMessageCallback msgCb, void msgCbArg)
	Subscribe to messages. More...

DLL_EXPORT void	tibeftl_Unsubscribe (tibeftlErr err, tibeftlConnection conn, tibeftlSubscription sub)
	Unsubscribe from messages and free all resources associated with the subscription. More...

DLL_EXPORT void	tibeftl_UnsubscribeAll (tibeftlErr err, tibeftlConnection conn)
	Unsubscribe from all messages and free all resources associated with all subscriptions. More...

DLL_EXPORT const char *	tibeftl_Version (void)
	Version string of the eFTL library. More...

DLL_EXPORT const char *	tibeftlConnectionState_ToString (tibeftlConnectionState state)
	Get a printable string that describes the connection state. More...

DLL_EXPORT void	tibeftlErr_Clear (tibeftlErr err)
	Clear an error. More...

DLL_EXPORT tibeftlErr	tibeftlErr_Create (void)
	Create an error object. More...

DLL_EXPORT void	tibeftlErr_Destroy (tibeftlErr err)
	Destroy an error object. More...

DLL_EXPORT int	tibeftlErr_GetCode (tibeftlErr err)
	Get the error code. More...

DLL_EXPORT const char *	tibeftlErr_GetDescription (tibeftlErr err)
	Get the error description. More...

DLL_EXPORT bool	tibeftlErr_IsSet (tibeftlErr err)
	Check if an error has been set. More...

DLL_EXPORT void	tibeftlErr_Set (tibeftlErr err, int code, const char *desc)
	Set an error. More...

DLL_EXPORT void	tibeftlKVMap_Destroy (tibeftlErr err, tibeftlKVMap map)
	Destroy a key-value map. More...

DLL_EXPORT tibeftlMessage	tibeftlKVMap_Get (tibeftlErr err, tibeftlKVMap map, const char *key)
	Get a key-value pair from a map. More...

DLL_EXPORT void	tibeftlKVMap_Remove (tibeftlErr err, tibeftlKVMap map, const char *key)
	Remove a key-value pair from a map. More...

DLL_EXPORT void	tibeftlKVMap_Set (tibeftlErr err, tibeftlKVMap map, const char *key, tibeftlMessage msg)
	Set a key-value pair in a map. More...

DLL_EXPORT void	tibeftlMessage_ClearAllFields (tibeftlErr err, tibeftlMessage msg)
	Clear all fields from a message. More...

DLL_EXPORT void	tibeftlMessage_ClearField (tibeftlErr err, tibeftlMessage msg, const char *field)
	Clear a field from a message. More...

DLL_EXPORT tibeftlMessage	tibeftlMessage_Create (tibeftlErr err)
	Create a message object. More...

DLL_EXPORT void	tibeftlMessage_Destroy (tibeftlErr err, tibeftlMessage msg)
	Destroy a message object. More...

DLL_EXPORT void *	tibeftlMessage_GetArray (tibeftlErr err, tibeftlMessage msg, tibeftlFieldType type, const char field, int size)
	Get an array field from a message. More...

DLL_EXPORT double	tibeftlMessage_GetDouble (tibeftlErr err, tibeftlMessage msg, const char *field)
	Get a double field from a message. More...

DLL_EXPORT tibeftlFieldType	tibeftlMessage_GetFieldType (tibeftlErr err, tibeftlMessage msg, const char *field)
	Get the type of a field in a message. More...

DLL_EXPORT int64_t	tibeftlMessage_GetLong (tibeftlErr err, tibeftlMessage msg, const char *field)
	Get a long field from a message. More...

DLL_EXPORT tibeftlMessage	tibeftlMessage_GetMessage (tibeftlErr err, tibeftlMessage msg, const char *field)
	Get a message field from a message. More...

DLL_EXPORT void *	tibeftlMessage_GetOpaque (tibeftlErr err, tibeftlMessage msg, const char field, size_t size)
	Get an opaque field from a message. More...

DLL_EXPORT int64_t	tibeftlMessage_GetStoreMessageId (tibeftlErr err, tibeftlMessage msg)
	Get the message's unique store identifier assigned by the persistence service. More...

DLL_EXPORT const char *	tibeftlMessage_GetString (tibeftlErr err, tibeftlMessage msg, const char *field)
	Get a string field from a message. More...

DLL_EXPORT int64_t	tibeftlMessage_GetTime (tibeftlErr err, tibeftlMessage msg, const char *field)
	Get a time field from a message. More...

DLL_EXPORT bool	tibeftlMessage_IsFieldSet (tibeftlErr err, tibeftlMessage msg, const char *field)
	Check whether a field is set in a message. More...

DLL_EXPORT bool	tibeftlMessage_NextField (tibeftlErr err, tibeftlMessage msg, const char *field, tibeftlFieldType type)
	Get the next field in a message. More...

DLL_EXPORT void	tibeftlMessage_SetArray (tibeftlErr err, tibeftlMessage msg, tibeftlFieldType type, const char field, const void const value, int size)
	Set an array field in a message. More...

DLL_EXPORT void	tibeftlMessage_SetDouble (tibeftlErr err, tibeftlMessage msg, const char *field, double value)
	Set a double field in a message. More...

DLL_EXPORT void	tibeftlMessage_SetLong (tibeftlErr err, tibeftlMessage msg, const char *field, int64_t value)
	Set a long field in a message. More...

DLL_EXPORT void	tibeftlMessage_SetMessage (tibeftlErr err, tibeftlMessage msg, const char *field, tibeftlMessage value)
	Set a message field in a message. More...

DLL_EXPORT void	tibeftlMessage_SetOpaque (tibeftlErr err, tibeftlMessage msg, const char field, void value, size_t size)
	Set an opaque field in a message. More...

DLL_EXPORT void	tibeftlMessage_SetString (tibeftlErr err, tibeftlMessage msg, const char field, const char value)
	Set a string field in a message. More...

DLL_EXPORT void	tibeftlMessage_SetTime (tibeftlErr err, tibeftlMessage msg, const char *field, int64_t value)
	Set a time field in a message. More...

DLL_EXPORT size_t	tibeftlMessage_ToString (tibeftlErr err, tibeftlMessage msg, char *buffer, size_t size)
	Get a printable string that describes the contents of a message. More...

Detailed Description

This file defines the eFTL API.

Macro Definition Documentation

#define TIBEFTL_DURABLE_TYPE_LAST_VALUE "last-value"

Last-value durable.

#define TIBEFTL_DURABLE_TYPE_SHARED "shared"

Shared durable.

#define TIBEFTL_ERR_AUTHENTICATION (4002)

Authentication failed.

#define TIBEFTL_ERR_CONNECT_FAILED (10)

Connect failed.

#define TIBEFTL_ERR_CONNECTION_LOST (9)

Connection lost.

#define TIBEFTL_ERR_FORCE_CLOSE (4000)

Server closed the connection.

#define TIBEFTL_ERR_GOING_AWAY (1001)

Server is shutting down.

#define TIBEFTL_ERR_INVALID_ARG (1)

Invalid argument.

#define TIBEFTL_ERR_INVALID_TYPE (5)

Item of wrong type.

#define TIBEFTL_ERR_MAP_REQUEST_FAILED (30)

Map request failed.

#define TIBEFTL_ERR_MAP_REQUEST_NOT_AUTHORIZED (14)

Map request failed, not authorized.

#define TIBEFTL_ERR_MESSAGE_TOO_BIG (1009)

Published message is too big.

#define TIBEFTL_ERR_NO_MEMORY (2)

Memory allocation failed.

#define TIBEFTL_ERR_NOT_CONNECTED (8)

Not connected.

#define TIBEFTL_ERR_NOT_FOUND (4)

Item not found.

#define TIBEFTL_ERR_NOT_SUPPORTED (6)

Not supported.

#define TIBEFTL_ERR_OK (0)

No error has been reported.

#define TIBEFTL_ERR_PUBLISH_FAILED (11)

Publish failed.

#define TIBEFTL_ERR_PUBLISH_NOT_AUTHORIZED (12)

Publish failed, not authorized.

#define TIBEFTL_ERR_REQUEST_FAILED (41)

Request failed.

#define TIBEFTL_ERR_REQUEST_NOT_AUTHORIZED (40)

Request not authorized.

#define TIBEFTL_ERR_SERVICE_RESTART (1012)

Server is restarting.

#define TIBEFTL_ERR_SUBSCRIPTION_FAILED (21)

Subscription failed.

#define TIBEFTL_ERR_SUBSCRIPTION_INVALID (22)

Subscription failed, invalid matcher or durable.

#define TIBEFTL_ERR_SUBSCRIPTION_NOT_AUTHORIZED (13)

Subscription failed, not authorized.

#define TIBEFTL_ERR_TIMEOUT (3)

Request timeout.

#define TIBEFTL_ERR_UNAVAILABLE (4001)

Server is temporarily unavailable.

#define TIBEFTL_FIELD_NAME_DESTINATION "_dest"

Message field name identifying the EMS destination of a message.

The destination message field is only required when communicating with EMS.

To publish a message on a specific EMS destination include this message field using tibeftlMessage_SetString().

tibeftlMessage_SetString(err, msg, TIBEFTL_FIELD_NAME_DESTINATION, "MyDest");

To subscribe to messages published on a specific EMS destination use a subscription matcher that includes this message field name in tibeftl_Subscribe().

char matcher[64];
snprintf(matcher, sizeof(matcher), "{\"%s\":\"%s\"}",
        TIBEFTL_FIELD_NAME_DESTINATION, "MyDest");
tibeftl_Subscribe(err, conn, matcher, "MyDurable", cb, NULL);

To distinguish between topics and queues the destination name can be prefixed with either "TOPIC:" or "QUEUE:", for example "TOPIC:MyDest" or "QUEUE:MyDest". A destination name with no prefix is a topic.

#define tibeftlOptionsDefault { 2, NULL, NULL, NULL, NULL, false, 10000, 5, 30000, NULL, NULL, 0 }

#define tibeftlSubscriptionOptionsDefault { TIBEFTL_ACKNOWLEDGE_MODE_AUTO, NULL, NULL }

Typedef Documentation

typedef struct tibeftlConnectionStruct* tibeftlConnection

eFTL connection.

A tibeftlConnection object represents the connection to the server.

typedef struct tibeftlErrStruct* tibeftlErr

eFTL error.

A tibeftlErr object is passed to function calls to capture information about failures.

typedef void(* tibeftlErrorCallback)(tibeftlConnection conn, tibeftlErr err, void *arg)

Connection error callback.

A connection error callback is invoked whenever an error occurs on the connection. When the connection to the server is lost, tibeftl_Reconnect() can be called from within this callback to attempt a reconnect to the server.

Parameters

conn	The connection on which the error occurred.
err	The connection error.
arg	The callback-specific argument.

See Also: tibeftl_Connect

typedef struct tibeftlKVMapStruct* tibeftlKVMap

eFTL key-value map.

A tibeftlKVMap object is used to set and get key-value pairs.

typedef struct tibeftlMessageStruct* tibeftlMessage

eFTL message.

A tibeftlMessage object is used to send information between clients.

typedef void(* tibeftlMessageCallback)(tibeftlConnection conn, tibeftlSubscription sub, int cnt, tibeftlMessage *msg, void *arg)

Message callback.

A message callback is invoked whenever messages are received that matche a subscription.

Parameters

conn	The connection on which the message was received.
sub	The subscription associated with the message.
cnt	The number of received messages.
msg	The array of received messages.
arg	The callback-specific argument.

See Also: tibeftl_Subscribe

typedef void(* tibeftlStateCallback)(tibeftlConnection conn, tibeftlConnectionState state, void *arg)

Connection state callback.

A connection state callback is invoked whenever the state of the connection changes.

Parameters

conn	The connection on which the state changed.
state	The current state of the connection.
arg	The callback-specific argument.

See Also: tibeftlOptions

typedef struct tibeftlSubscriptionStruct* tibeftlSubscription

eFTL subscription.

A tibeftlSubscription object represents an interest in receiving messages with particular content.

Enumeration Type Documentation

enum tibeftlAcknowledgeMode

Acknowledge mode.

See Also: tibeftlSubscriptionOptions

Enumerator

TIBEFTL_ACKNOWLEDGE_MODE_AUTO

Auto acknowledgment mode.

Messages consumed from a subscription with this acknowledgment mode are automatically acknowledged.

TIBEFTL_ACKNOWLEDGE_MODE_CLIENT

Client acknowledgment mode.

Messages consumed from a subscription with this acknowledgment mode require explicit acknowledgment by the client.

The eFTL server will stop delivering messages to the client once the server's configured maximum unacknowledged messages is reached.

See Also: tibeftl_Acknowledge; tibeftl_AcknowledgeAll

TIBEFTL_ACKNOWLEDGE_MODE_NONE

None acknowledgment mode.

Messages consumed from a subscription with this acknowledgment mode do not require acknowledgment.

enum tibeftlConnectionState

Connection states.

See Also: tibeftlStateCallback

Enumerator
STATE_INITIAL
STATE_DISCONNECTED
STATE_CONNECTING
STATE_CONNECTED
STATE_DISCONNECTING
STATE_RECONNECTING

enum tibeftlFieldType

eFTL message field types.

Enumerator
TIBEFTL_FIELD_TYPE_UNKNOWN
TIBEFTL_FIELD_TYPE_STRING
TIBEFTL_FIELD_TYPE_STRING_ARRAY
TIBEFTL_FIELD_TYPE_LONG
TIBEFTL_FIELD_TYPE_LONG_ARRAY
TIBEFTL_FIELD_TYPE_DOUBLE
TIBEFTL_FIELD_TYPE_DOUBLE_ARRAY
TIBEFTL_FIELD_TYPE_TIME
TIBEFTL_FIELD_TYPE_TIME_ARRAY
TIBEFTL_FIELD_TYPE_MESSAGE
TIBEFTL_FIELD_TYPE_MESSAGE_ARRAY
TIBEFTL_FIELD_TYPE_OPAQUE

Function Documentation

DLL_EXPORT void tibeftl_Acknowledge	(	tibeftlErr	err,
		tibeftlConnection	conn,
		tibeftlMessage	msg
	)

Acknowledge this message.

Messages consumed from subscriptions with a client acknowledgment mode must be explicitly acknowledged. The eFTL server will stop delivering messages to the client once the server's configured maximum number of unacknowledged messages is reached.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.
msg	The message to acknowledge.

DLL_EXPORT void tibeftl_AcknowledgeAll	(	tibeftlErr	err,
		tibeftlConnection	conn,
		tibeftlMessage	msg
	)

Acknowledge all messages up to and including this message.

Messages consumed from subscriptions with a client acknowledgment mode must be explicitly acknowledged. The eFTL server will stop delivering messages to the client once the server's configured maximum number of unacknowledged messages is reached.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.
msg	The message being acknowledged.

DLL_EXPORT tibeftlConnection tibeftl_Connect	(	tibeftlErr	err,
		const char *	url,
		tibeftlOptions *	opts,
		tibeftlErrorCallback	errCb,
		void *	errCbArg
	)

Connect to the server.

Creates a connection to the server.

When a pipe-separated list of URLs is specified this call will attempt a connection to each in turn, in a random order, until one is connected.

The server URLs have the syntax:

ws://host:port/channel wss://host:port/channel

Optionally, the URLs can contain the username, password, and/or client identifier:

ws://username:password:port/channel?clientId=<identifier> wss://username:password:port/channel?clientId=<identifier>

Parameters

err	An eFTL error to capture information about failures.
url	A single URL, or a pipe ('\|') separated list of URLs, to the server.
opts	(optional) The options to use when creating the connection.
errCb	(optional) The error callback to be invoked when connection errors occur.
errCbArg	(optional) The error callback argument.

Returns: The connection object.

DLL_EXPORT tibeftlKVMap tibeftl_CreateKVMap	(	tibeftlErr	err,
		tibeftlConnection	conn,
		const char *	name
	)

Create a key-value map.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.
name	The key-value map name.

Returns: The key-value map.

DLL_EXPORT void tibeftl_Disconnect	(	tibeftlErr	err,
		tibeftlConnection	conn
	)

Disconnect from the server and free all resources associated with the connection, including the connection object itself.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.

DLL_EXPORT bool tibeftl_IsConnected	(	tibeftlErr	err,
		tibeftlConnection	conn
	)

Check whether or not there is a connection to the server.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.

Returns: true if there is a connection to the server, false otherwise.

DLL_EXPORT void tibeftl_Publish	(	tibeftlErr	err,
		tibeftlConnection	conn,
		tibeftlMessage	msg
	)

Publish a message to all subscribing clients.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.
msg	The message to publish.

See Also: TIBEFTL_FIELD_NAME_DESTINATION

DLL_EXPORT void tibeftl_Reconnect	(	tibeftlErr	err,
		tibeftlConnection	conn
	)

Reconnect to the server.

Can be called from within the tibeftlErrorCallback.

All subscriptions are restored following a successful reconnect.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.

DLL_EXPORT void tibeftl_RemoveKVMap	(	tibeftlErr	err,
		tibeftlConnection	conn,
		const char *	name
	)

Remove a key-value map.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.
name	The key-value map name.

Returns: The key-value map.

DLL_EXPORT void tibeftl_SendReply	(	tibeftlErr	err,
		tibeftlConnection	conn,
		tibeftlMessage	reply,
		tibeftlMessage	request
	)

Send a reply message in response to a request message.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.
reply	The reply message to send.
request	The request message.

See Also: tibeftl_SendRequest

DLL_EXPORT tibeftlMessage tibeftl_SendRequest	(	tibeftlErr	err,
		tibeftlConnection	conn,
		tibeftlMessage	request,
		int64_t	timeout
	)

Publish a request message and wait for a reply.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.
request	The request message to publish.
timeout	Timeout, in milliseconds, to wait for a reply.

Returns: The reply message, or NULL if the request times out.

See Also: tibeftl_SendReply; TIBEFTL_FIELD_NAME_DESTINATION

DLL_EXPORT tibeftlSubscription tibeftl_Subscribe	(	tibeftlErr	err,
		tibeftlConnection	conn,
		const char *	matcher,
		const char *	durable,
		tibeftlMessageCallback	msgCb,
		void *	msgCbArg
	)

Subscribe to messages.

A subscription can be narrowed by using a matcher that matches only those messages whose content is of interest.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.
matcher	(optional) The matcher for selecting which messages to receive.
durable	(optional) The name to use when creating durable subscriptions.
msgCb	The message callback to be invoked when messages are received.
msgCbArg	The message callback argument.

Returns: The subscription.

See Also: TIBEFTL_FIELD_NAME_DESTINATION

DLL_EXPORT tibeftlSubscription tibeftl_SubscribeWithOptions	(	tibeftlErr	err,
		tibeftlConnection	conn,
		const char *	matcher,
		const char *	durable,
		tibeftlSubscriptionOptions *	opts,
		tibeftlMessageCallback	msgCb,
		void *	msgCbArg
	)

Subscribe to messages.

A subscription can be narrowed by using a matcher that matches only those messages whose content is of interest.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.
matcher	(optional) The matcher for selecting which messages to receive.
durable	(optional) The name to use when creating durable subscriptions.
opts	(optional) The options to use when creating the subscription.
msgCb	The message callback to be invoked when messages are received.
msgCbArg	The message callback argument.

Returns: The subscription.

DLL_EXPORT void tibeftl_Unsubscribe	(	tibeftlErr	err,
		tibeftlConnection	conn,
		tibeftlSubscription	sub
	)

Unsubscribe from messages and free all resources associated with the subscription.

For durable subscriptions, calling this function will cause the persistence service to remove the durable subscription as well, along with any persisted messages.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.
sub	The subscription from which to unsubscribe.

DLL_EXPORT void tibeftl_UnsubscribeAll	(	tibeftlErr	err,
		tibeftlConnection	conn
	)

Unsubscribe from all messages and free all resources associated with all subscriptions.

For durable subscriptions, calling this function will cause the persistence service to remove the durable subscription as well, along with any persisted messages.

Parameters

err	An eFTL error to capture information about failures.
conn	The connection object.

DLL_EXPORT const char* tibeftl_Version ( void )

Version string of the eFTL library.

Returns: The version string of the eFTL library.

DLL_EXPORT const char* tibeftlConnectionState_ToString ( tibeftlConnectionState state )

Get a printable string that describes the connection state.

DLL_EXPORT void tibeftlErr_Clear ( tibeftlErr err )

Clear an error.

Parameters

err	The error object.

DLL_EXPORT tibeftlErr tibeftlErr_Create ( void )

Create an error object.

Returns: The error object.

DLL_EXPORT void tibeftlErr_Destroy ( tibeftlErr err )

Destroy an error object.

Parameters

err	The error object.

DLL_EXPORT int tibeftlErr_GetCode ( tibeftlErr err )

Get the error code.

Parameters

err	The error object.

Returns: The error code.

DLL_EXPORT const char* tibeftlErr_GetDescription ( tibeftlErr err )

Get the error description.

Parameters

err	The error object.

Returns: The error description.

DLL_EXPORT bool tibeftlErr_IsSet ( tibeftlErr err )

Check if an error has been set.

Parameters

err	The error object.

Returns: true if the error is set, false otherwise.

DLL_EXPORT void tibeftlErr_Set	(	tibeftlErr	err,
		int	code,
		const char *	desc
	)

Set an error.

Parameters

err	The error object.
code	The error code.
desc	The error description.

DLL_EXPORT void tibeftlKVMap_Destroy	(	tibeftlErr	err,
		tibeftlKVMap	map
	)

Destroy a key-value map.

Parameters

err	An eFTL error to capture information about failures.
map	The key-value map object.

DLL_EXPORT tibeftlMessage tibeftlKVMap_Get	(	tibeftlErr	err,
		tibeftlKVMap	map,
		const char *	key
	)

Get a key-value pair from a map.

Parameters

err	An eFTL error to capture information about failures.
map	The key-value map.
key	The key name.

Returns: The value, or NULL if not set.

DLL_EXPORT void tibeftlKVMap_Remove	(	tibeftlErr	err,
		tibeftlKVMap	map,
		const char *	key
	)

Remove a key-value pair from a map.

Parameters

err	An eFTL error to capture information about failures.
map	The key-value map.
key	The key name.

DLL_EXPORT void tibeftlKVMap_Set	(	tibeftlErr	err,
		tibeftlKVMap	map,
		const char *	key,
		tibeftlMessage	msg
	)

Set a key-value pair in a map.

Parameters

err	An eFTL error to capture information about failures.
map	The key-value map object.
key	The key name.
msg	The value to set.

DLL_EXPORT void tibeftlMessage_ClearAllFields	(	tibeftlErr	err,
		tibeftlMessage	msg
	)

Clear all fields from a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.

DLL_EXPORT void tibeftlMessage_ClearField	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field
	)

Clear a field from a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to clear.

DLL_EXPORT tibeftlMessage tibeftlMessage_Create ( tibeftlErr err )

Create a message object.

Parameters

err	An eFTL error to capture information about failures.

Returns: The message object.

DLL_EXPORT void tibeftlMessage_Destroy	(	tibeftlErr	err,
		tibeftlMessage	msg
	)

Destroy a message object.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.

DLL_EXPORT void* tibeftlMessage_GetArray	(	tibeftlErr	err,
		tibeftlMessage	msg,
		tibeftlFieldType	type,
		const char *	field,
		int *	size
	)

Get an array field from a message.

The returned array is valid only for the lifetime of the message. The returned array must not be modified or freed.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
type	The field type to get.
field	The name of the field to get.
size	The number of elements in the array.

Returns: The value of the field.

DLL_EXPORT double tibeftlMessage_GetDouble	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field
	)

Get a double field from a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to get.

Returns: The value of the field.

DLL_EXPORT tibeftlFieldType tibeftlMessage_GetFieldType	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field
	)

Get the type of a field in a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The field name.

Returns: The type of the field.

DLL_EXPORT int64_t tibeftlMessage_GetLong	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field
	)

Get a long field from a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to get.

Returns: The value of the field.

DLL_EXPORT tibeftlMessage tibeftlMessage_GetMessage	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field
	)

Get a message field from a message.

The returned message is valid only for the lifetime of the message. The returned message must not be modified or freed.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to get.

Returns: The value of the field.

DLL_EXPORT void* tibeftlMessage_GetOpaque	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field,
		size_t *	size
	)

Get an opaque field from a message.

The returned opaque is valid only for the lifetime of the message. The returned opaque must not be modified or freed.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to get.
size	The size of the field in bytes.

Returns: The value of the field.

DLL_EXPORT int64_t tibeftlMessage_GetStoreMessageId	(	tibeftlErr	err,
		tibeftlMessage	msg
	)

Get the message's unique store identifier assigned by the persistence service.

Parameters

err	An eFTL error to capture information about failures.
The	message object.

Returns: The message identifier.

DLL_EXPORT const char* tibeftlMessage_GetString	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field
	)

Get a string field from a message.

The returned string is valid only for the lifetime of the message. The returned string must not be modified or freed.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to get.

Returns: The value of the field.

DLL_EXPORT int64_t tibeftlMessage_GetTime	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field
	)

Get a time field from a message.

Time is the number of milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to get.

Returns: The value of the field.

DLL_EXPORT bool tibeftlMessage_IsFieldSet	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field
	)

Check whether a field is set in a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The field name.

Returns: true if the field is set, false otherwise.

DLL_EXPORT bool tibeftlMessage_NextField	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char **	field,
		tibeftlFieldType *	type
	)

Get the next field in a message.

Calling this function repeatedly will iterate over all of the fields in a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the next field.
type	The type of the next field.

Returns: true if there are additional fields, false if the current field is the last field.

DLL_EXPORT void tibeftlMessage_SetArray	(	tibeftlErr	err,
		tibeftlMessage	msg,
		tibeftlFieldType	type,
		const char *	field,
		const void *const	value,
		int	size
	)

Set an array field in a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
type	The type of the field to set.
field	The name of the field to set.
value	The value of the field to set.
size	The number of elements in the array.

DLL_EXPORT void tibeftlMessage_SetDouble	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field,
		double	value
	)

Set a double field in a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to set.
value	The value of the field to set.

DLL_EXPORT void tibeftlMessage_SetLong	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field,
		int64_t	value
	)

Set a long field in a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to set.
value	The value of the field to set.

DLL_EXPORT void tibeftlMessage_SetMessage	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field,
		tibeftlMessage	value
	)

Set a message field in a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to set.
value	The value of the field to set.

DLL_EXPORT void tibeftlMessage_SetOpaque	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field,
		void *	value,
		size_t	size
	)

Set an opaque field in a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to set.
value	The value of the field to set.
size	The size of the field to set in bytes.

DLL_EXPORT void tibeftlMessage_SetString	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field,
		const char *	value
	)

Set a string field in a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to set.
value	The value of the field to set.

DLL_EXPORT void tibeftlMessage_SetTime	(	tibeftlErr	err,
		tibeftlMessage	msg,
		const char *	field,
		int64_t	value
	)

Set a time field in a message.

Time is the number of milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
field	The name of the field to set.
value	The value of the field to set.

DLL_EXPORT size_t tibeftlMessage_ToString	(	tibeftlErr	err,
		tibeftlMessage	msg,
		char *	buffer,
		size_t	size
	)

Get a printable string that describes the contents of a message.

Parameters

err	An eFTL error to capture information about failures.
msg	The message object.
buffer	(optional) The buffer into which the printable string is stored.
size	The size of the buffer in bytes.

Returns: The actual length of the printable string, including the terminating NULL character, in bytes.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation