TIBCO FTL®

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