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 tibint32_t	tibRealm_GetServerVersion (tibEx e, tibRealm id, char *buf, tibint32_t size)
	Returns the FTLserver version. More...

TIB_API void	tibRealm_RemoveMap (tibEx e, tibRealm realm, const char endpointName, const char mapName, tibProperties props)

TIB_API void	tibRealm_SetLogCallback (tibEx e, tibRealm realm, tibLogCallback logCallback, tibProperties properties, void *closure)
	Register a log callback for a specified realm. More...

TIB_API void	tibRealm_SetLogFiles (tibEx e, tibRealm realm, const char *filePrefix, tibint64_t maxFileSize, tibint32_t maxFiles, tibProperties properties)
	Arrange rotating log files for a specified realm. More...

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. More...

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...

Detailed Description

Realm objects contain definitions of message formats, endpoints and transport maps.

This file defines realm objects and calls that manipulate them.

Macro Definition Documentation

#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.

See Also: TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE; TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING; TIB_REALM_HTTPS_CONNECTION_TRUST_EVERYONE

#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 Documentation

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.

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

Enumeration Type Documentation

enum tibRealmNotificationType

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.

Function Documentation

TIB_API void tibRealm_Close	(	tibEx	e,
		tibRealm	realm
	)

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

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.

Note: It is good practice that each application process maintain only one connection to each relevant FTL server. Realm objects are thread-safe; you can safely use the same realm object in all the threads of an application program. Do not duplicate connections to the same FTL server in several threads, which would duplicate the realm object.

Parameters

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`. TLS Secure FTL Server Properties TIB_REALM_PROPERTY_LONG_TRUST_TYPE TIB_REALM_PROPERTY_STRING_TRUST_FILE TIB_REALM_PROPERTY_STRING_TRUST_PEM_STRING Authenication Properties TIB_REALM_PROPERTY_STRING_USERNAME TIB_REALM_PROPERTY_STRING_USERPASSWORD Note: If USERPASSWORD is specified, but USERNAME is not, the call will fail. Application Instance Property TIB_REALM_PROPERTY_STRING_APPINSTANCE_IDENTIFIER Connection Attempts Properties TIB_REALM_PROPERTY_LONG_CONNECT_RETRIES TIB_REALM_PROPERTY_DOUBLE_CONNECT_INTERVAL

Returns: This call returns a realm object.

See Also: TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE; TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING; TIB_REALM_HTTPS_CONNECTION_TRUST_EVERYONE

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.

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.
lockName	The lock object represents the lock with this name in the store.
props	Optional. `NULL` to omit. Properties: TIBLOCK_PROPERTY_DOUBLE_LOCK_ACQUIRE_RETRY_DURATION

Returns: A new lock object.

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.

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 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_MAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION TIB_MAP_PROPERTY_STRING_LABEL

Returns: A new map object.

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.

Parameters

e	The exception object captures information about failures.
realm	The call returns a copy of the connect properties from this realm.

Returns: This call returns a properties object.

See Also: tibRealm_Connect

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.

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 tibint32_t tibRealm_GetServerVersion	(	tibEx	e,
		tibRealm	id,
		char *	buf,
		tibint32_t	size
	)

Returns the FTLserver version.

Programmers estimate the required size of the string buffer. If the buffer is too small (or NULL), the call fails, but returns the actual required size. The program can use this information to supply a buffer of the required size in the second call.

Parameters

e	The exception object captures information about failures.
realm	The call returns the version of the FTLserver that this client is connected to, if the buffer is smaller, it returns the size required.
buf	The call stores the version string in 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.

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 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`.

Returns: void

TIB_API void tibRealm_SetLogCallback	(	tibEx	e,
		tibRealm	realm,
		tibLogCallback	logCallback,
		tibProperties	properties,
		void *	closure
	)

Register a log callback for a specified realm.

If you register a log callback (one per realm), then FTL directs all log statements associated with that realm to that callback.

Parameters

e	The exception object captures information about failures.
realm	The call sets the callback for this realm.
logCallback	FTL invokes this callback to process all log statements.
properties	Reserved for future use. To ensure forward compatibility, programmers must supply `NULL`.
closure	FTL supplies this closure object to the callback with each log statement.

Returns: void

TIB_API void tibRealm_SetLogFiles	(	tibEx	e,
		tibRealm	realm,
		const char *	filePrefix,
		tibint64_t	maxFileSize,
		tibint32_t	maxFiles,
		tibProperties	properties
	)

Arrange rotating log files for a specified realm.

The filename extension .0 indicates the current log file. Rotation shifts each file by incrementing its numeric extension. If the number of files would exceed the maximum, rotation deletes the oldest file.

Parameters

e	The exception object captures information about failures.
realm	The call sets the log file parameters for this realm.
filePrefix	All log files begin with this filename prefix.
maxFileSize	FTL rotates the log files when the current log file exceeds this limit (in bytes). This value must be greater than 102400 (100 kilobytes).
maxFiles	FTL limits the number of log files to this maximum.
properties	Reserved for future use. To ensure forward compatibility, programmers must supply `NULL`.

Returns: void

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_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.

Parameters

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.

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

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation