TIBCO FTL®
|
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_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... | |
Subscribers express interest to receive inbound messages.
This file defines subscriber objects and calls that manipulate them.
#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.
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:
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.
#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
).
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.
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.
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.
e | The exception object captures information about failures. |
subscriber | The call closes this direct subscriber. |
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.
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 . |
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.
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_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).
e | The exception object captures information about failures. |
subscriber | The call closes this subscriber. |
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.
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: Message ownership property: Other properties: |
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.
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_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.
e | The exception object captures information about failures. |
subscriber | The call copies the inbox from this inbox subscriber. |