sub.h File Reference

Subscribers express interest to receive inbound messages. More...

Macros
#define	TIB_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK   "com.tibco.ftl.client.subscriber.explicitack"
	Explicit acknowledgement property; boolean. More...
#define	TIB_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK   "com.tibco.ftl.client.subscriber.release"
	Ownership of inbound messages; boolean. More...
#define	TIB_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION   "com.tibco.ftl.client.subscriber.persistence.retry.duration"
	Retry duration which persistent subscriber operations; double. More...
#define	TIB_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME   "com.tibco.ftl.client.durable.name"
	Durable name property; string. More...
#define	TIB_SUBSCRIBER_PROPERTY_STRING_KEY_FIELD_NAME   "com.tibco.ftl.client.subscriber.keyfieldname"
	Key field name for a dynamic last-value durable; string. More...
#define	TIB_SUBSCRIBER_PROPERTY_STRING_LABEL   "com.tibco.ftl.client.subscriber.label"
	Property name for a subscriber label; string. More...
#define	TIB_SUBSCRIBER_PROPERTY_STRING_NAME   "com.tibco.ftl.client.subscriber.name"
	Static durable subscriber name property; string. More...

Typedefs
typedef void(*	tibDirectCallback )(tibEx e, tibint64_t count, tibint64_t totalSize, tibint64_t *sizeArray, tibint8_t *data, void *closure)
typedef struct __tibDirectSubscriberId *	tibDirectSubscriber
typedef struct __tibSubscriberId *	tibSubscriber
	A subscriber object realizes the message-receiving functionality of an endpoint within a program. More...

Functions
TIB_API void	tibDirectSubscriber_Close (tibEx e, tibDirectSubscriber subscriber)
	Close a direct subscriber. More...
TIB_API tibDirectSubscriber	tibDirectSubscriber_Create (tibEx e, tibRealm realm, const char *endpointName, tibProperties props)
	Create a direct subscriber. More...
TIB_API void	tibDirectSubscriber_Dispatch (tibEx e, tibDirectSubscriber subscriber, double timeout, tibDirectCallback callback, void *closure)
	Dispatch inbound data for a direct subscriber. More...
TIB_API tibbool_t	tibDirectSubscriber_HasData (tibEx e, tibDirectSubscriber id)
	Test a direct subscriber for inbound data. More...
TIB_API void	tibSubscriber_AcknowledgeMessages (tibEx e, tibSubscriber subscriber, tibint32_t msgNum, tibMessage *msgs)
	Explicitly acknowledge a batch of messages. More...
TIB_API void	tibSubscriber_Close (tibEx e, tibSubscriber subscriber)
	Close a subscriber. More...
TIB_API tibSubscriber	tibSubscriber_Create (tibEx e, tibRealm realm, const char *endpointName, tibContentMatcher matcher, tibProperties props)
	Create a subscriber. More...
TIB_API tibSubscriber	tibSubscriber_CreateOnInbox (tibEx e, tibRealm realm, const char *endpointName, tibProperties props)
	Create an inbox subscriber. More...
TIB_API tibInbox	tibSubscriber_GetInbox (tibEx e, tibSubscriber subscriber)
	Get the inbox object from an inbox subscriber. More...

Detailed Description

Subscribers express interest to receive inbound messages.

This file defines subscriber objects and calls that manipulate them.

Macro Definition Documentation

#define TIB_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK   "com.tibco.ftl.client.subscriber.explicitack"

Explicit acknowledgement property; boolean.

A durable subscriber can acknowledge message receipt to its durable (in the persistence store) in either of two ways:

• With automatic acknowledgement, the FTL library automatically acknowledges the message when the application callback returns.

• With explicit acknowledgement, the application program must call tibMessage_Acknowledge to explicitly acknowledge each message.

To enable explicit acknowledgement mode, pass this property to tibSubscriber_Create with value tibtrue. Otherwise, the default behavior is automatic acknowledgement.

#define TIB_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK   "com.tibco.ftl.client.subscriber.release"

Ownership of inbound messages; boolean.

When tibfalse or absent, the FTL library retains ownership of inbound messages that arrive through this subscriber. The library automatically destroys each message after the callback returns.

When tibtrue, client program code accepts ownership of inbound messages that arrive through this subscriber. The FTL library releases the message object when it dispatches the message to the client's callback. The callback can pass this message to another program thread. Client program code must explicitly destroy the message object.

#define TIB_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION   "com.tibco.ftl.client.subscriber.persistence.retry.duration"

Retry duration which persistent subscriber operations; double.

When tibSubscriber_Create or tibMessage_Acknowledge cannot access the persistence server (usually because of network failure or quorum unavailability), they can automatically retry the interaction. The value of this property overrides the retry behavior of the server. Supply it to the subscriber create call.

Values:

• 0 No retry. The call raises an exception.
• -1 Synchronously retry the interaction until it succeeds. The call returns only upon success.
• n (Any positive double value) Retry the interaction for n seconds. Return upon success or raise an exception after timeout.

Closing the subscriber or the realm supersedes and cancels retry behavior.

#define TIB_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME   "com.tibco.ftl.client.durable.name"

Durable name property; string.

To request messages from a persistence store, supply a durable name as the value of this property in a tibSubscriber_Create call.

If a static or dynamic durable with this name already exists, the new subscriber draws messages from that durable.

Otherwise, the store creates a new dynamic durable with this name.

If this property is present, it overrides the TIB_SUBSCRIBER_PROPERTY_STRING_NAME property.

#define TIB_SUBSCRIBER_PROPERTY_STRING_KEY_FIELD_NAME   "com.tibco.ftl.client.subscriber.keyfieldname"

Key field name for a dynamic last-value durable; string.

When creating or subscribing to a dynamic last-value durable, this property is required. Supply the name of the last-value durable's key field as the value of this property.

The subscriber's content matcher must match the key field against a specific value.

#define TIB_SUBSCRIBER_PROPERTY_STRING_LABEL   "com.tibco.ftl.client.subscriber.label"

Property name for a subscriber label; string.

It is good practice to include this property in every subscriber create call. Monitoring data incorporates these labels so administrators can identify and distinguish among subscribers. Use labels that reveal the unique role and identity of each subscriber within the application program.

The library does not use labels internally.

tibSubscriber_Create

#define TIB_SUBSCRIBER_PROPERTY_STRING_NAME   "com.tibco.ftl.client.subscriber.name"

Static durable subscriber name property; string.

To request messages from static durable in a persistence store, programs may supply a subscriber name as the value of this property in a tibSubscriber_Create call.

If TIB_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME is present, it overrides this property.

If neither this property nor TIB_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME is present, then the create call uses the default durable subscriber name (_default).

Setting this value is required for only static durables where administrative configuration maps the subscriber name to a durable name.

Typedef Documentation

typedef void(* tibDirectCallback)(tibEx e, tibint64_t count, tibint64_t totalSize, tibint64_t *sizeArray, tibint8_t *data, void *closure)

Direct subscriber callback.

Programs define callbacks of this type to process data buffers inbound to direct subscribers. tibDirectSubscriber_Dispatch invokes the callback.

The callback must unpack the data buffer. When the callback returns, the direct subscriber automatically acknowledges that it has received the buffer.

The data buffer and the size array belong to the library. Applications must not write into these objects, nor free them.

Note

The buffer, its data, and the size array are valid only until the callback returns. To extend the lifetime of the data, copy it to application memory.

Parameters

e	The exception object captures information about failures.
count	The number of data items in the data buffer.
totalSize	The size of the data buffer (in bytes).
sizeArray	An array of sizes corresponding to the count data items in the buffer.
data	The data buffer.
closure	A closure object. The direct subscriber receives this object in the dispatch call, and passes it unchanged to the callback. The callback may modify it.

typedef struct __tibDirectSubscriberId* tibDirectSubscriber

typedef struct __tibSubscriberId* tibSubscriber

A subscriber object realizes the message-receiving functionality of an endpoint within a program.

A subscriber object encapsulates all the information that a program needs to subscribe to a stream of messages. Subscriber objects use the transport and format resources associated with an endpoint (as defined in the realm).

A subscriber does not receive messages until you add it to an event queue.

• A subscriber can also use an optional content matcher to filter the message stream.
• An inbox subscriber receives messages sent to a specific inbox.

Function Documentation

TIB_API void tibDirectSubscriber_Close	(	tibEx	e,
		tibDirectSubscriber	subscriber
	)

Close a direct subscriber.

Closing a direct subscriber invalidates all subsequent method calls, and forces any blocked dispatch calls to return.

However, closing a direct subscriber does not free its memory. For more information, see "Programming with Direct Subscribers" in TIBCO FTL Development.

Parameters

e	The exception object captures information about failures.
subscriber	The call closes this direct subscriber.

Returns

void

TIB_API tibDirectSubscriber tibDirectSubscriber_Create	(	tibEx	e,
		tibRealm	realm,
		const char *	endpointName,
		tibProperties	props
	)

Create a direct subscriber.

Applications use direct subscriber objects to receive data buffers with low latency.

For a complete explanation, including best practices, see "Direct Publishers and Subscribers" in TIBCO FTL Development.

Parameters

e	The exception object captures information about failures.
realm	The realm object is the source of configuration information about the application, endpoints, and transports.
endpointName	The endpoint identifies the subscriber's data stream within the realm.
props	Reserved for future use. To ensure forward compatibility, programmers must supply NULL.

Returns

On success, this call returns a new direct subscriber object.
On failure, this call returns NULL.

TIB_API void tibDirectSubscriber_Dispatch	(	tibEx	e,
		tibDirectSubscriber	subscriber,
		double	timeout,
		tibDirectCallback	callback,
		void *	closure
	)

Dispatch inbound data for a direct subscriber.

If the timeout elapses before an event arrives in the queue, then the dispatch call returns normally. The call does not indicate whether or not it actually dispatched an event.

Parameters

e	The exception object captures information about failures (during dispatch) and conveys it back to its caller. The exception does not carry information from the callback.
subscriber	Dispatch a data buffer for this direct subscriber.
timeout	If a data buffer is not available, the call waits for inbound data. If a data buffer does not arrive before this timeout (in seconds) elapses, the call returns. The constants TIB_TIMEOUT_WAIT_FOREVER and TIB_TIMEOUT_NO_WAIT are special values.
callback	Process inbound data using this callback method.
closure	The callback method receives this data object as an argument.

TIB_API tibbool_t tibDirectSubscriber_HasData	(	tibEx	e,
		tibDirectSubscriber	id
	)

Test a direct subscriber for inbound data.

If the subscriber has data ready to dispatch, this call returns tibtrue. Otherwise it returns tibfalse.

When data is not ready to dispatch, this call is faster than calling tibDirectSubscriber_Dispatch with a timeout value of TIB_TIMEOUT_NO_WAIT.

TIB_API void tibSubscriber_AcknowledgeMessages	(	tibEx	e,
		tibSubscriber	subscriber,
		tibint32_t	msgNum,
		tibMessage *	msgs
	)

Explicitly acknowledge a batch of messages.

When a durable subscriber object specifies explicit acknowledgement, the application program must acknowledge each message to the durable, the application can acknowledge each message individually by calling msg.acknowledge() or by calling this method with a batch of messages.

When a durable subscriber object does not specify explicit acknowledgement, the FTL library automatically acknowledges the message when the application callback method returns.

For any message that arrives through a non-durable subscriber, this call returns without error (and without action).

Parameters

e	The exception object captures information about failures.
subscriber	The subscriber for which we want to explicitly acknowledge messages.
msgNum	The number of messages to acknowledge
msgs	The array of messages to acknowledge

Returns

void

See Also

TIB_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK

TIB_API void tibSubscriber_Close	(	tibEx	e,
		tibSubscriber	subscriber
	)

Close a subscriber.

Closing a subscriber frees all the resources associated with it (for example, inbox objects; transport resources that are not used in other endpoints).

Parameters

e	The exception object captures information about failures.
subscriber	The call closes this subscriber.

Returns

void

TIB_API tibSubscriber tibSubscriber_Create	(	tibEx	e,
		tibRealm	realm,
		const char *	endpointName,
		tibContentMatcher	matcher,
		tibProperties	props
	)

Create a subscriber.

Applications use subscriber objects to register interest in a stream of messages (sent with one-to-many send calls).

A subscriber does not receive messages until you add it to an event queue.

Parameters

e	The exception object captures information about failures.
realm	The realm object is the source of configuration information about the application, endpoints, transports and formats.
endpointName	The endpoint identifies the subscriber's data stream within the realm. To use the default endpoint, supply NULL.
matcher	Optional. NULL to omit. The matcher filters messages based on their content.
props	Optional. NULL to omit. Persistence properties: TIB_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME TIB_SUBSCRIBER_PROPERTY_STRING_NAME TIB_SUBSCRIBER_PROPERTY_STRING_KEY_FIELD_NAME TIB_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK TIB_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION Message ownership property: TIB_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK Other properties: TIB_SUBSCRIBER_PROPERTY_STRING_LABEL

Returns

a new subscriber object

TIB_API tibSubscriber tibSubscriber_CreateOnInbox	(	tibEx	e,
		tibRealm	realm,
		const char *	endpointName,
		tibProperties	props
	)

Create an inbox subscriber.

Applications use inbox subscriber objects to register interest in a stream of inbox messages.

A subscriber does not receive messages until you add it to an event queue.

Because inbox messages do not trigger the content matchers of other subscribers on the endpoint, they are an efficient way to target a message to a specific destination. For example, you might use an inbox message to query a specific data source, or to reply to a query.

Parameters

e	The exception object captures information about failures.
realm	The realm object is the source of configuration information about the application, endpoints, transports and formats.
endpointName	The endpoint identifies the subscriber's data stream within the realm. To use the default endpoint, supply NULL.
props	Optional. NULL to omit. Message ownership property: TIB_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK

Returns

a new subscriber object

TIB_API tibInbox tibSubscriber_GetInbox	(	tibEx	e,
		tibSubscriber	subscriber
	)

Get the inbox object from an inbox subscriber.

Messages can carry this inbox object to other programs. Programs that receive that inbox can send a stream of one-to-one messages to the inbox subscriber. See tibMessage_SetInbox.

Your program must not destroy the inbox because the subscriber owns it.

Parameters

e	The exception object captures information about failures.
subscriber	The call copies the inbox from this inbox subscriber.

Returns

an inbox object