TIBCO FTL®
|
Realm objects contain definitions of message formats, endpoints and transport maps. More...
Macros | |
#define | TIB_REALM_HTTPS_CONNECTION_TRUST_EVERYONE 0 |
Trust any FTL server; property value constant. More... | |
#define | TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE 1 |
Trust an FTL server if its certificate is in a trust file; property value constant. More... | |
#define | TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING 2 |
Trust an FTL server if its certificate is in a trust string; property value constant. More... | |
#define | TIB_REALM_PROPERTY_DOUBLE_CONNECT_INTERVAL "com.tibco.ftl.client.interval" |
Property name for the interval between connection attempts; double. More... | |
#define | TIB_REALM_PROPERTY_LONG_CONNECT_RETRIES "com.tibco.ftl.client.retries" |
Property name for number of connection attempts; long. More... | |
#define | TIB_REALM_PROPERTY_LONG_TRUST_TYPE "com.tibco.ftl.trust.type" |
Property name for secure FTL server trust type; long. More... | |
#define | TIB_REALM_PROPERTY_STRING_APPINSTANCE_IDENTIFIER "com.tibco.ftl.client.appinstance.identifier" |
Property name for application instance identifier; string. More... | |
#define | TIB_REALM_PROPERTY_STRING_CLIENT_LABEL "com.tibco.ftl.client.label" |
Property name for client label; string. More... | |
#define | TIB_REALM_PROPERTY_STRING_SECONDARY_SERVER "com.tibco.ftl.client.secondary" |
Deprecated. Revise client code to use the core servers list instead. More... | |
#define | TIB_REALM_PROPERTY_STRING_TRUST_FILE "com.tibco.ftl.trust.file" |
Property name for secure FTL server trust file; string. More... | |
#define | TIB_REALM_PROPERTY_STRING_TRUST_PEM_STRING "com.tibco.ftl.trust.pem.string" |
Property name for secure FTL server trust data; string. More... | |
#define | TIB_REALM_PROPERTY_STRING_USERNAME "com.tibco.ftl.client.username" |
Property name for FTL server username; string. More... | |
#define | TIB_REALM_PROPERTY_STRING_USERPASSWORD "com.tibco.ftl.client.userpassword" |
Property name for FTL server password; string. More... | |
Typedefs | |
typedef void(* | tibRealmNotificationHandler) (tibEx e, tibRealmNotificationType type, const char *reason, void *closure) |
Notification handler callback. More... | |
Enumerations | |
enum | tibRealmNotificationType { TIB_CLIENT_DISABLED = 0 } |
Conditions in notifications. More... | |
Functions | |
TIB_API void | tibRealm_Close (tibEx e, tibRealm realm) |
Close a realm object. More... | |
TIB_API tibRealm | tibRealm_Connect (tibEx e, const char *serverUrl, const char *appName, tibProperties props) |
Connect to an FTL server, and create a realm object. More... | |
TIB_API tibLock | tibRealm_CreateLock (tibEx e, tibRealm realm, const char *lockName, tibProperties props) |
Create a lock object. More... | |
TIB_API tibMap | tibRealm_CreateMap (tibEx e, tibRealm realm, const char *endpointName, const char *mapName, tibProperties props) |
TIB_API tibProperties | tibRealm_GetProperties (tibEx e, tibRealm realm) |
Get a copy of the realm connection properties. More... | |
TIB_API tibint32_t | tibRealm_GetServerUrl (tibEx e, tibRealm realm, char *buffer, tibint32_t size) |
Get a copy of the FTL server URL. More... | |
TIB_API void | tibRealm_RemoveMap (tibEx e, tibRealm realm, const char *endpointName, const char *mapName, tibProperties props) |
TIB_API void | tibRealm_SetNotificationHandler (tibEx e, tibRealm realm, tibRealmNotificationHandler handler, void *closure) |
Register the notification handler callback. More... | |
TIB_API void | tibRealm_Unsubscribe (tibEx e, tibRealm realm, const char *endpointName, const char *dynamicDurableName) |
Destroy a dynamic durable. 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_HTTPS_CONNECTION_TRUST_EVERYONE 0 |
Trust any FTL server; property value constant.
This constant is one possible value of the property TIB_REALM_PROPERTY_LONG_TRUST_TYPE in the method tibRealm_Connect.
The client trusts any FTL server without verifying trust in the server's certificate. Do not use this value except for convenience in development and testing. It is not secure.
#define TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE 1 |
Trust an FTL server if its certificate is in a trust file; property value constant.
This constant is one possible value of the property TIB_REALM_PROPERTY_LONG_TRUST_TYPE in the method tibRealm_Connect.
The client trusts the FTL server based on the trust file created by the FTL server and distributed by the administrator.
Specify the file path of the trust file in the property TIB_REALM_PROPERTY_STRING_TRUST_FILE.
#define TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING 2 |
Trust an FTL server if its certificate is in a trust string; property value constant.
This constant is one possible value of the property TIB_REALM_PROPERTY_LONG_TRUST_TYPE in the method tibRealm_Connect.
The client trusts the FTL server based on a trust string.
Specify the trust string in the property TIB_REALM_PROPERTY_STRING_TRUST_PEM_STRING.
#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.
#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_LONG_TRUST_TYPE "com.tibco.ftl.trust.type" |
Property name for secure FTL server trust type; long.
Supply this property to tibRealm_Connect. Its value determines trust in the FTL server's certificate.
#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.
#define TIB_REALM_PROPERTY_STRING_SECONDARY_SERVER "com.tibco.ftl.client.secondary" |
Deprecated. Revise client code to use the core servers list instead.
#define TIB_REALM_PROPERTY_STRING_TRUST_FILE "com.tibco.ftl.trust.file" |
Property name for secure FTL server trust file; string.
Supply this property to tibRealm_Connect.
If the realm connect call specifies the trust type as TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE, use this property to indicate the location of the trust file.
#define TIB_REALM_PROPERTY_STRING_TRUST_PEM_STRING "com.tibco.ftl.trust.pem.string" |
Property name for secure FTL server trust data; string.
Supply this property to tibRealm_Connect.
If the realm connect call specifies the trust type as TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING, use this property to supply the trust string in PEM format.
#define TIB_REALM_PROPERTY_STRING_USERNAME "com.tibco.ftl.client.username" |
Property name for FTL server username; string.
Supply this property to tibRealm_Connect, which identifies your program to the FTL server with the username value you supply.
#define TIB_REALM_PROPERTY_STRING_USERPASSWORD "com.tibco.ftl.client.userpassword" |
Property name for FTL server password; string.
Supply this property to tibRealm_Connect, which authenticates your program to the FTL server with the password value you supply.
typedef void(* tibRealmNotificationHandler) (tibEx e, tibRealmNotificationType type, const char *reason, void *closure) |
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.
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. |
Conditions in notifications.
Enumerator | |
---|---|
TIB_CLIENT_DISABLED | The FTL server administratively disabled this client. The current realm object no longer supports FTL functionality. Nonetheless, the program can still call close or destroy functions on FTL objects in the realm. To resume FTL functionality, some programs may first call tibRealm_Close on the disabled realm object, and then create a new realm object by calling tibRealm_Connect. Other programs may restart or exit. |
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.
e | The exception object captures information about failures. |
realm | The call closes this realm. |
TIB_API tibRealm tibRealm_Connect | ( | tibEx | e, |
const char * | serverUrl, | ||
const char * | appName, | ||
tibProperties | props | ||
) |
Connect to an FTL server, and create a realm object.
The FTL server defines information about endpoints, transports and formats, which lets applications communicate within a realm. The realm object is a local copy (within your program) of the subset of the realm information that pertains to your application.
e | The exception object captures information about failures. |
serverUrl | The call contacts the FTL server at this URL list. |
appName | The program supplies a NULL-terminated string. The call sends this application name to the FTL server. The server responds with an application-specific subset of the realm information. To use the default application, supply NULL . |
props | Properties configure interaction with the FTL server. Required for connecting to a secure FTL server, for authentication, and for fault tolerance. Otherwise optional; to omit, supply NULL .
|
TIB_API tibLock tibRealm_CreateLock | ( | tibEx | e, |
tibRealm | realm, | ||
const char * | lockName, | ||
tibProperties | props | ||
) |
Create a lock object.
Cooperating application programs can use locks to implement exclusive access to a map within a persistence store.
Lock objects with the same lock name represent the same lock within the persistence store.
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. |
lockName | The lock object represents the lock with this name in the store. |
props | Reserved for future use. To ensure forward compatibility, programmers must supply NULL . |
TIB_API tibMap tibRealm_CreateMap | ( | tibEx | e, |
tibRealm | realm, | ||
const char * | endpointName, | ||
const char * | mapName, | ||
tibProperties | props | ||
) |
Create a map object.
Map objects with the same map name represent the same map within the persistence store.
If the store does not already contain the named map, this call creates the map as a dynamic durable.
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 map object represents a map within the store associated with this endpoint. |
mapName | The map object represents the map with this name. |
props | Optional. NULL to omit.Properties: |
TIB_API tibProperties tibRealm_GetProperties | ( | tibEx | e, |
tibRealm | realm | ||
) |
Get a copy of the realm connection properties.
This call returns a copy of the properties object that your program supplied to tibRealm_Connect. Your program must destroy this properties object to reclaim its resources (see tibProperties_Destroy).
If your program did not supply any properties to the realm connect call, then this call returns NULL
.
e | The exception object captures information about failures. |
realm | The call returns a copy of the connect properties from this realm. |
TIB_API tibint32_t tibRealm_GetServerUrl | ( | tibEx | e, |
tibRealm | realm, | ||
char * | buffer, | ||
tibint32_t | size | ||
) |
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.
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). |
TIB_API void tibRealm_RemoveMap | ( | tibEx | e, |
tibRealm | realm, | ||
const char * | endpointName, | ||
const char * | mapName, | ||
tibProperties | props | ||
) |
Delete a map from a persistence store.
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 call removes a map from the store associated with this endpoint. |
mapName | The call removes the map with this name from the store. |
props | Reserved for future use. To ensure forward compatibility, programmers must supply NULL . |
TIB_API void tibRealm_SetNotificationHandler | ( | tibEx | e, |
tibRealm | realm, | ||
tibRealmNotificationHandler | handler, | ||
void * | closure | ||
) |
Register the notification handler callback.
Programs may register at most one notification handler per realm. It is good practice for all programs to do so. For background information, see tibRealmNotificationHandler.
e | The exception object captures information about failures. |
realm | The call sets the notification handler for this realm. |
handler | The call sets this callback function to handle notifications. |
closure | Notification passes this closure to the callback. |
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.
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. |