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

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

◆ TIB_REALM_HTTPS_CONNECTION_TRUST_EVERYONE

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

◆ TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE

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

◆ TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING

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

◆ TIB_REALM_PROPERTY_DOUBLE_CONNECT_INTERVAL

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

◆ TIB_REALM_PROPERTY_LONG_CONNECT_RETRIES

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

◆ TIB_REALM_PROPERTY_LONG_TRUST_TYPE

#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

◆ TIB_REALM_PROPERTY_STRING_APPINSTANCE_IDENTIFIER

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

◆ TIB_REALM_PROPERTY_STRING_CLIENT_LABEL

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

◆ TIB_REALM_PROPERTY_STRING_SECONDARY_SERVER

#define TIB_REALM_PROPERTY_STRING_SECONDARY_SERVER "com.tibco.ftl.client.secondary"

Deprecated. Revise client code to use the core servers list instead.

◆ TIB_REALM_PROPERTY_STRING_TRUST_FILE

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

◆ TIB_REALM_PROPERTY_STRING_TRUST_PEM_STRING

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

◆ TIB_REALM_PROPERTY_STRING_USERNAME

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

◆ TIB_REALM_PROPERTY_STRING_USERPASSWORD

#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

◆ tibRealmNotificationHandler

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

◆ tibRealmNotificationType

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

◆ tibRealm_Close()

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

◆ tibRealm_Connect()

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

◆ tibRealm_CreateLock()

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	Reserved for future use. To ensure forward compatibility, programmers must supply `NULL`.

Returns: A new lock object.

◆ tibRealm_CreateMap()

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

Returns: A new map object.

◆ tibRealm_GetProperties()

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

◆ tibRealm_GetServerUrl()

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

◆ tibRealm_RemoveMap()

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

◆ tibRealm_SetNotificationHandler()

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

◆ tibRealm_Unsubscribe()

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

◆ TIB_REALM_HTTPS_CONNECTION_TRUST_EVERYONE

◆ TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE

◆ TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING

◆ TIB_REALM_PROPERTY_DOUBLE_CONNECT_INTERVAL

◆ TIB_REALM_PROPERTY_LONG_CONNECT_RETRIES

◆ TIB_REALM_PROPERTY_LONG_TRUST_TYPE

◆ TIB_REALM_PROPERTY_STRING_APPINSTANCE_IDENTIFIER

◆ TIB_REALM_PROPERTY_STRING_CLIENT_LABEL

◆ TIB_REALM_PROPERTY_STRING_SECONDARY_SERVER

◆ TIB_REALM_PROPERTY_STRING_TRUST_FILE

◆ TIB_REALM_PROPERTY_STRING_TRUST_PEM_STRING

◆ TIB_REALM_PROPERTY_STRING_USERNAME

◆ TIB_REALM_PROPERTY_STRING_USERPASSWORD

Typedef Documentation

◆ tibRealmNotificationHandler

Enumeration Type Documentation

◆ tibRealmNotificationType

Function Documentation

◆ tibRealm_Close()

◆ tibRealm_Connect()

◆ tibRealm_CreateLock()

◆ tibRealm_CreateMap()

◆ tibRealm_GetProperties()

◆ tibRealm_GetServerUrl()

◆ tibRealm_RemoveMap()

◆ tibRealm_SetNotificationHandler()

◆ tibRealm_Unsubscribe()