TIBCO FTL®

Macros | Typedefs | Functions
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_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_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_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_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

## ◆ TIB_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK

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

## ◆ TIB_SUBSCRIBER_PROPERTY_BOOL_NOLOCAL_MESSAGE_DELIVERY

#define TIB_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 subscribers on an endpoint that have a 'store' associated.

When `tibfalse` or absent, FTL delivers messages to the 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 subscriber.

## ◆ TIB_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK

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

## ◆ TIB_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

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

## ◆ TIB_SUBSCRIBER_PROPERTY_LONG_PREFETCH_SIZE

#define TIB_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_SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME

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

## ◆ TIB_SUBSCRIBER_PROPERTY_STRING_KEY_FIELD_NAME

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

## ◆ TIB_SUBSCRIBER_PROPERTY_STRING_LABEL

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

See tibSubscriber_Create

## ◆ TIB_SUBSCRIBER_PROPERTY_STRING_NAME

#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

## ◆ tibDirectCallback

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.

## ◆ tibDirectSubscriber

typedef struct __tibDirectSubscriberId* tibDirectSubscriber

## ◆ tibSubscriber

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

## ◆ tibDirectSubscriber_Close()

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

## ◆ tibDirectSubscriber_Create()

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`.

## ◆ tibDirectSubscriber_Dispatch()

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.

## ◆ tibDirectSubscriber_HasData()

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.

## ◆ tibSubscriber_AcknowledgeMessages()

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

## ◆ tibSubscriber_Close()

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

## ◆ tibSubscriber_Create()

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

## ◆ tibSubscriber_CreateOnInbox()

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

## ◆ tibSubscriber_GetInbox()

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