destsub.h File Reference

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

Macros
#define	TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK   "com.tibco.ftl.client.subscriber.explicitack"
	Explicit acknowledgement property; boolean. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_NOLOCAL_MESSAGE_DELIVERY   "com.tibco.ftl.client.subscriber.nolocal.message.delivery"
	No Local property that inhibits delivery of messages published by publishers on the same connection as the subscriber; boolean. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK   "com.tibco.ftl.client.subscriber.release"
	Ownership of inbound messages; boolean. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_DOUBLE_ACK_BATCH_TIME   "com.tibco.ftl.client.subscriber.ack.batch.time"
	Ack batch time. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION   "com.tibco.ftl.client.subscriber.persistence.retry.duration"
	Retry duration which persistent subscriber operations; double. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_INT_ACK_BATCH_SIZE   "com.tibco.ftl.client.subscriber.ack.batch.size"
	Ack batch size. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_INT_ACK_MODE   "com.tibco.ftl.client.subscriber.ack.batch.mode"
	Ack mode. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_INT_DURABLE_TYPE   "com.tibco.ftl.client.subscriber.durable.type"
	Durable type property. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_LONG_PREFETCH_SIZE   "com.tibco.ftl.client.subscriber.prefetch.size"
	Allows a subscriber to override the prefetch set by the administrator for a static durable or dynamic durable template. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME   "com.tibco.ftl.client.durable.name"
	Durable name property; string. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_STRING_LABEL   "com.tibco.ftl.client.subscriber.label"
	Property name for a subscriber label; string. More...
#define	TIB_DEST_SUBSCRIBER_PROPERTY_STRING_MATCH_FILTER   "com.tibco.ftl.client.subscriber.match.filter"
	Property name for a subscriber match filter; string. More...

Typedefs
typedef tibSubscriber	tibDestSubscriber
	A destination subscriber object realizes the message-receiving functionality of a destination in a program. More...

Enumerations
enum	tibDestSubscriberAckMode {   TIB_DEST_SUBSCRIBER_ACK_MODE_SYNC = 1 ,   TIB_DEST_SUBSCRIBER_ACK_MODE_ASYNC = 2 }
enum	tibDestSubscriberDurableType {   TIB_DEST_SUBSCRIBER_DURABLE_TYPE_STANDARD = 1 ,   TIB_DEST_SUBSCRIBER_DURABLE_TYPE_SHARED = 2 ,   TIB_DEST_SUBSCRIBER_DURABLE_TYPE_LASTVALUE = 3 }
	Durable types. More...

Functions
TIB_API void	tibDestSubscriber_Acknowledge (tibEx e, tibDestSubscriber destSubscriber, tibMessage message)
	Explicitly acknowledge a single message. More...
TIB_API void	tibDestSubscriber_AcknowledgeMessages (tibEx e, tibDestSubscriber destSubscriber, tibint32_t count, tibMessage *messages)
	Explicitly acknowledge a batch of messages. More...
TIB_API void	tibDestSubscriber_Close (tibEx e, tibDestSubscriber destSubscriber)
	Close a destination subscriber. More...

Detailed Description

Destination Subscribers express interest to receive inbound messages.

This file defines destination subscriber objects and calls that manipulate them.

Macro Definition Documentation

TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK

#define TIB_DEST_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.

TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_NOLOCAL_MESSAGE_DELIVERY

#define TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_NOLOCAL_MESSAGE_DELIVERY   "com.tibco.ftl.client.subscriber.nolocal.message.delivery"

No Local property that inhibits delivery of messages published by publishers on the same connection as the subscriber; boolean.

This mainly applies only to destination subscribers

When tibfalse or absent, FTL delivers messages to the dest subscriber that are published by a publisher on the same connection This is the default behavior.

When tibtrue, FTL does not deliver messages that are published by publishers on the same connection as the dest subscriber.

TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK

#define TIB_DEST_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.

TIB_DEST_SUBSCRIBER_PROPERTY_DOUBLE_ACK_BATCH_TIME

#define TIB_DEST_SUBSCRIBER_PROPERTY_DOUBLE_ACK_BATCH_TIME   "com.tibco.ftl.client.subscriber.ack.batch.time"

Ack batch time.

This property is optional when creating destination subscribers on topics or queues. Specify the time interval in milliseconds after which the messages should be acknowledged.

TIB_DEST_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

#define TIB_DEST_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.

TIB_DEST_SUBSCRIBER_PROPERTY_INT_ACK_BATCH_SIZE

#define TIB_DEST_SUBSCRIBER_PROPERTY_INT_ACK_BATCH_SIZE   "com.tibco.ftl.client.subscriber.ack.batch.size"

Ack batch size.

This property is optional when creating destination subscribers on topics or queues. Specify the number of messages to be acknowledged in a batch.

TIB_DEST_SUBSCRIBER_PROPERTY_INT_ACK_MODE

#define TIB_DEST_SUBSCRIBER_PROPERTY_INT_ACK_MODE   "com.tibco.ftl.client.subscriber.ack.batch.mode"

Ack mode.

This property is optional when creating destination subscribers on topics or queues. Specify one of the values from the enumeration tibDestSubscriberAckMode.

TIB_DEST_SUBSCRIBER_PROPERTY_INT_DURABLE_TYPE

#define TIB_DEST_SUBSCRIBER_PROPERTY_INT_DURABLE_TYPE   "com.tibco.ftl.client.subscriber.durable.type"

Durable type property.

This property is required when creating destination subscribers on topics. Specify one of the values from the enumeration tibDestSubscriberDurableType.

TIB_DEST_SUBSCRIBER_PROPERTY_LONG_PREFETCH_SIZE

#define TIB_DEST_SUBSCRIBER_PROPERTY_LONG_PREFETCH_SIZE   "com.tibco.ftl.client.subscriber.prefetch.size"

Allows a subscriber to override the prefetch set by the administrator for a static durable or dynamic durable template.

When absent, the FTL library will default the prefetch value set by the administrator for a static durable or dynamic durable template.

When present and set to a value greater than zero, a subscriber receives prefetch number of messages in a batch as set by the subscriber. NOTE: This value should be lower than the administrator configured value.

TIB_DEST_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME

#define TIB_DEST_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 tibRealm_CreateDestSubscriber call.

If a durable with this name already exists on a given destination, the new destination subscriber draws messages from that durable. Otherwise, the store creates a new dynamic durable with this name.

TIB_DEST_SUBSCRIBER_PROPERTY_STRING_LABEL

#define TIB_DEST_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 destination 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.

See tibSubscriber_Create

TIB_DEST_SUBSCRIBER_PROPERTY_STRING_MATCH_FILTER

#define TIB_DEST_SUBSCRIBER_PROPERTY_STRING_MATCH_FILTER   "com.tibco.ftl.client.subscriber.match.filter"

Property name for a subscriber match filter; string.

This property is optional when creating destination subscribers on topics or queues. Specify a string that represents a filter expression. The filter expression is used to match messages based on their content.

Typedef Documentation

tibDestSubscriber

typedef tibSubscriber tibDestSubscriber

A destination subscriber object realizes the message-receiving functionality of a destination in a program.

A destination subscriber object encapsulates all the information that a program needs to subscribe to a stream of messages. Subscriber objects receive messages from the peristence service

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

• A destination subscriber can also use an optional content matcher to filter the message stream.

Enumeration Type Documentation

tibDestSubscriberAckMode

enum tibDestSubscriberAckMode

Enumerator
TIB_DEST_SUBSCRIBER_ACK_MODE_SYNC
TIB_DEST_SUBSCRIBER_ACK_MODE_ASYNC

tibDestSubscriberDurableType

enum tibDestSubscriberDurableType

Durable types.

Enumerator
TIB_DEST_SUBSCRIBER_DURABLE_TYPE_STANDARD
TIB_DEST_SUBSCRIBER_DURABLE_TYPE_SHARED
TIB_DEST_SUBSCRIBER_DURABLE_TYPE_LASTVALUE

Function Documentation

tibDestSubscriber_Acknowledge()

TIB_API void tibDestSubscriber_Acknowledge	(	tibEx	e,
		tibDestSubscriber	destSubscriber,
		tibMessage	message
	)

Explicitly acknowledge a single message.

When a destination subscriber object specifies explicit acknowledgement, the application program must acknowledge each message to the durable, the application can acknowledge each message individually by calling tibDestSubscriber_Acknowledge or by calling tibDestSubscriber_AcknowledgeMessages with a batch of messages.

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

Parameters

e	The exception object captures information about failures.
destSubscriber	The dest subscriber for which we want to explicitly acknowledge messages.
message	The message to acknowledge

See also

TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK

tibDestSubscriber_AcknowledgeMessages()

TIB_API void tibDestSubscriber_AcknowledgeMessages	(	tibEx	e,
		tibDestSubscriber	destSubscriber,
		tibint32_t	count,
		tibMessage *	messages
	)

Explicitly acknowledge a batch of messages.

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

When a describe 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.
destSubscriber	The dest subscriber for which we want to explicitly acknowledge messages.
count	The number of messages to acknowledge
messages	The array of messages to acknowledge

See also

TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK

tibDestSubscriber_Close()

TIB_API void tibDestSubscriber_Close	(	tibEx	e,
		tibDestSubscriber	destSubscriber
	)

Close a destination subscriber.

Closing a destination subscriber frees all the resources associated with it additionally any messages that are not acknowledged by the subscriber will be released to other subscribers.

Parameters

e	The exception object captures information about failures.
destSubscriber	The destSubscriber object.