Realm objects contain definitions of message formats, endpoints and transport maps.
More...
Realm objects contain definitions of message formats, endpoints and transport maps.
This file defines realm objects and calls that manipulate them.
#define TIB_REALM_PROPERTY_DOUBLE_CONNECT_INTERVAL "com.tibco.ftl.client.interval" |
Property name for the interval between connection attempts; double.
Supply this property to tibRealm_Connect.
The connect call waits this interval (in seconds) between connection attempts.
The default value is 1.0 seconds.
This property applies only to tibRealm_Connect and does not affect reconnects if the client loses connection to the FTL server.
#define TIB_REALM_PROPERTY_LONG_CONNECT_RETRIES "com.tibco.ftl.client.retries" |
Property name for number of connection attempts; long.
Supply this property to tibRealm_Connect.
If the connect call cannot connect to the FTL server after this maximum number of connection attempts, it fails with an exception.
The default value is retry forever (0).
#define TIB_REALM_PROPERTY_STRING_APPINSTANCE_IDENTIFIER "com.tibco.ftl.client.appinstance.identifier" |
Property name for application instance identifier; string.
It is good practice to include this property in the realm connect call of every application program. It gives administrators flexible control over application deployment and over the transports that carry message traffic.
For example, the program obtains the application identifier as a command line argument (or through another configuration mechanism). If an application identifier is present, then the program passes it to tibRealm_Connect as the value of this property.
Within the realm, administrators can define one or more application instances, which tailor the connections between endpoints and transports. The value of this property selects from among those instances.
#define TIB_REALM_PROPERTY_STRING_CLIENT_LABEL "com.tibco.ftl.client.label" |
Property name for client label; string.
It is good practice to include this property in the realm connect call of every application program. Administrators can use client labels in monitoring and management to recognize and distinguish among processes.
For example, the program obtains the client label as a command line argument (or through another configuration mechanism). If a client label is present, then the program passes it to tibRealm_Connect as the value of this property.
Notification handler callback.
In some situations, FTL must notify programs of conditions that preclude the use of event queues (as the communications medium). Instead of sending an advisory, FTL notifies the program through an out-of-band mechanism.
Programs define a notification handler callback (of this type) to process these out-of-band notifications. Programs register the callback using tibRealm_SetNotificationHandler.
- Parameters
-
e | FTL supplies callbacks with a clear exception object; your callback code may use it in its FTL API calls.
When the completion callback returns, FTL does not examine the exception object for errors, nor does FTL return that exception to your program code. |
type | A notification code, which indicates the type of condition. |
reason | A string describing the reason for the notification. |
closure | The closure associated with the handler. |
- Returns
- void
Close a realm object.
Closing a realm object frees all the resources associated with the realm, and invalidates all objects created using the realm (including messages, publishers, subscribers and content matchers).
However, closing a local realm object does not change or destroy any definitions on the FTL server.
Programs must not call tibRealm_Close within a callback.
Programs must close realm objects before closing FTL.
- Parameters
-
e | The exception object captures information about failures. |
realm | The call closes this realm. |
- Returns
- void
Get a copy of the FTL server URL.
This call copies the URL string that your program supplied to tibRealm_Connect.
If a program passes NULL
as the buffer argument, this call returns the length of the URL string (including a NULL
terminating character), without actually writing it.
If the non-null buffer is too short for the entire URL string, the call writes to the end of the buffer, truncating the string, and returns the actual number of bytes in the buffer.
- Parameters
-
e | The exception object captures information about failures. |
realm | The call gets a copy of the server URL from this realm. |
buffer | The call copies the URL into this string buffer. |
size | The program supplies the length of buffer (in bytes). |
- Returns
- This call returns the length of the FTL server URL string (including the
NULL
terminating character).
- See also
- tibRealm_Connect
TIB_API void tibRealm_SetLogLevel |
( |
tibEx |
e, |
|
|
tibRealm |
realm, |
|
|
const char * |
level |
|
) |
| |
Set the log trace level for low-level FTL internal calls for a specified realm.
Set one log level for all logging elements, e.g., tibRealm_SetLogLevel(tibEx e, realm, TIB_LOG_LEVEL_WARN)
Or, set log levels per element tag, e.g., tibRealm_SetLogLevel(tibEx e, realm, "transports:warn;api:debug")
Valid levels:
Valid element tags:
- all - applies to all elements.
- application - logging for the application, e.g., API calls, message formats, and content matchers.
- transports - logging for transports, including peer connections, subscriber interest, message sends, protocols.
- msg - logging related to messages. For debug, print a representation of each inbound/outbound message.
- api - logging related to API calls.
For more information, see the topic Log Levels in the book TIBCO FTL Development.
- Parameters
-
e | The exception object captures information about failures. |
realm | The call sets the level for this realm. |
level | The call sets the level to this value. |
- Returns
- void
TIB_API void tibRealm_Unsubscribe |
( |
tibEx |
e, |
|
|
tibRealm |
realm, |
|
|
const char * |
endpointName, |
|
|
const char * |
dynamicDurableName |
|
) |
| |
Destroy a dynamic durable.
Destroying a dynamic durable removes it from the store.
If one client destroys a dynamic durable while other clients have subscribers to it, subsequent behavior is undefined.
It is an error to use this call to unsubscribe from a static durable.
- Parameters
-
e | The exception object captures information about failures. |
realm | The call destroys a dynamic durable in this realm. |
endpointName | The call destroys a dynamic durable in the store associated with this endpoint. |
dynamicDurableName | The call destroys the dynamic durable with this name. |
- Returns
- void
TIB_API void tibRealm_UnsubscribeEx |
( |
tibEx |
e, |
|
|
tibRealm |
realm, |
|
|
const char * |
endpointName, |
|
|
const char * |
dynamicDurableName, |
|
|
tibProperties |
props |
|
) |
| |
Destroy a dynamic durable.
Destroying a dynamic durable removes it from the store.
If one client destroys a dynamic durable while other clients have subscribers to it, subsequent behavior is undefined.
TIB_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION can be specified in 'props' to specify a duration for persistence call. The call will be retried for the specified time, after which it fails.
It is an error to use this call to unsubscribe from a static durable.
- Parameters
-
e | The exception object captures information about failures. |
realm | The call destroys a dynamic durable in this realm. |
endpointName | The call destroys a dynamic durable in the store associated with this endpoint. |
dynamicDurableName | The call destroys the dynamic durable with this name. |
props | Optional. NULL to omit.
Properties:
|
- Returns
- void