browser.h File Reference

Programs can use browsers to inspect and delete existing messages in shared durables. More...

Macros
#define	TIB_BROWSER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION   "com.tibco.ftl.client.browser.persistence.retry.duration"
	Retry duration for browser operations; double. More...
#define	TIB_BROWSER_PROPERTY_STRING_LABEL   "com.tibco.ftl.client.browser.label"
	Property name for a browser label; string. More...
#define	TIB_BROWSER_PROPERTY_STRING_MATCHER   "com.tibco.ftl.client.browser.matcher"
	Property name for a browser matcher; string. More...

Typedefs
typedef struct __tibBrowserId *	tibBrowser

Functions
TIB_API void	tibBrowser_Close (tibEx e, tibBrowser browser)
	Close a browser. More...
TIB_API tibBrowser	tibBrowser_Create (tibEx e, tibRealm realm, const char *endpointName, const char *durableName, tibProperties props)
	Create a browser. More...
TIB_API void	tibBrowser_DeleteMessage (tibEx e, tibBrowser browser, tibMessage message)
	Delete a browsed message from the durable. More...
TIB_API tibMessage	tibBrowser_Next (tibEx e, tibBrowser browser)
	Retrieve the next message in the durable. More...
TIB_API void	tibBrowser_Reset (tibEx e, tibBrowser browser)
	Return the browser to the first message in the durable. More...

Detailed Description

Programs can use browsers to inspect and delete existing messages in shared durables.

To create a browser object, see tibBrowser_Create.

This file defines browser calls.

Macro Definition Documentation

TIB_BROWSER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

#define TIB_BROWSER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION   "com.tibco.ftl.client.browser.persistence.retry.duration"

Retry duration for browser operations; double.

When tibBrowser_Create or tibBrowser_DeleteMessage 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 browser 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 realm or destroying the browser supersedes and cancels retry behavior.

This property does not apply to tibBrowser_Next.

TIB_BROWSER_PROPERTY_STRING_LABEL

#define TIB_BROWSER_PROPERTY_STRING_LABEL   "com.tibco.ftl.client.browser.label"

Property name for a browser label; string.

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

When the browser label is present in the browser create call, the new browser assigns it as the label of its internal subscribers.

See tibBrowser_Create.

TIB_BROWSER_PROPERTY_STRING_MATCHER

#define TIB_BROWSER_PROPERTY_STRING_MATCHER   "com.tibco.ftl.client.browser.matcher"

Property name for a browser matcher; string.

Limit the browser to messages that match this string.

See tibBrowser_Create.

Typedef Documentation

tibBrowser

typedef struct __tibBrowserId* tibBrowser

Function Documentation

tibBrowser_Close()

TIB_API void tibBrowser_Close	(	tibEx	e,
		tibBrowser	browser
	)

Close a browser.

Closing a browser frees all the resources associated with it. This call allows the server to clean up as well.

Parameters

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

tibBrowser_Create()

TIB_API tibBrowser tibBrowser_Create	(	tibEx	e,
		tibRealm	realm,
		const char *	endpointName,
		const char *	durableName,
		tibProperties	props
	)

Create a browser.

Applications use browser objects to inspect and, optionally, delete the contents of a shared durable.

See tibBrowser_Next and tibBrowser_DeleteMessage.

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 browser's store configuration within the realm. The endpoint must have the same store and durable template as the endpoint used by the durable subscriber.
durableName	The durable to browse.
props	Optional. NULL to omit. Properties: TIB_BROWSER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION TIB_BROWSER_PROPERTY_STRING_LABEL TIB_BROWSER_PROPERTY_STRING_MATCHER

Returns

a new browser object

tibBrowser_DeleteMessage()

TIB_API void tibBrowser_DeleteMessage	(	tibEx	e,
		tibBrowser	browser,
		tibMessage	message
	)

Delete a browsed message from the durable.

This call deletes the specified message from the browser's durable. The message is deleted even if it has since been delivered to a live subscriber.

This call only accepts messages returned from calls to tibBrowser_Next for this browser, or mutable copies of such messages. See tibMessage_MutableCopy.

Parameters

e	The exception object captures information about failures.
browser	The call removes the message from this browser's durable.
message	The call removes this message.

tibBrowser_Next()

TIB_API tibMessage tibBrowser_Next	(	tibEx	e,
		tibBrowser	browser
	)

Retrieve the next message in the durable.

A browser starts at the first available message in the durable. Each call to this function advances the browser to the next available message.

The browser will not return messages that have been delivered to live subscribers. To browse every message it may be necessary to stop all subscribers on the durable.

Messages returned by the browser may be delivered to, and acknowledged by, live subscribers at any time.

If the connection to the persistence service is interrupted, or some other error occurs, the call will fail, regardless of any retry duration. When this happens, calls to this function will continue to fail until tibBrowser_Reset is called, or a new browser is created.

The library owns the message object, and may destroy it after the program calls tibBrowser_Next, tibBrowser_Reset, or tibBrowser_Close. Application code may take a copy of the message via tibMessage_MutableCopy.

Parameters

e	The exception object captures information about failures.
browser	The call retrieves the next message in the browser's durable.

Returns

A message. NULL indicates no more data.

tibBrowser_Reset()

TIB_API void tibBrowser_Reset	(	tibEx	e,
		tibBrowser	browser
	)

Return the browser to the first message in the durable.

Applications may call this function to return to the beginning of the durable. The next call to tibBrowser_Next will return the first available message.

If tibBrowser_Next fails, it is necessary to call this function to continue using the browser.

Parameters

e	The exception object captures information about failures.
browser	The call resets this browser.