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

Macros
#define	TIB_REALM_HTTPS_CONNECTION_TRUST_EVERYONE 0
	Deprecated. Trust any FTL server; property value constant. More...

#define	TIB_REALM_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE 1
	Deprecated. 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
	Deprecated. Trust an FTL server if its certificate is in a trust string; property value constant. More...

#define	TIB_REALM_PROPERTY_BOOL_TRUST_EVERYONE "com.tibco.ftl.trust.everyone"
	Property name for skipping TLS certificate validation; bool. 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_SECURITY_LEVEL "com.tibco.ftl.security.level"
	Property name for TLS security level; long. More...

#define	TIB_REALM_PROPERTY_LONG_TRUST_TYPE "com.tibco.ftl.trust.type"
	Deprecated. 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_CERT "com.tibco.ftl.client.cert"
	Property name for client identity certificate; 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_CLIENT_PRIVATE_KEY "com.tibco.ftl.client.private.key"
	Property name for client certificate's private key; string. More...

#define	TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD "com.tibco.ftl.client.private.key.password"
	Property name for client certificate's private key password; string. More...

#define	TIB_REALM_PROPERTY_STRING_OAUTH2_ACCESS_TOKEN "com.tibco.ftl.oauth2.access.token"
	Property name to specify OAuth 2.0 access token. More...

#define	TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_ID "com.tibco.ftl.oauth2.client.id"
	, Property name for OAuth 2.0 client id, this client id is required to get the OAuth 2.0 access token; string More...

#define	TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_SECRET "com.tibco.ftl.oauth2.client.secret"
	, Property name for OAuth 2.0 client secret, this client secret is required to get the OAuth 2.0 access token; string More...

#define	TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_TRUST_FILE "com.tibco.ftl.oauth2.server.trust.file"
	, Property name for OAuth 2.0 server specific trust file. More...

#define	TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_URL "com.tibco.ftl.oauth2.server.url"
	, Property name for OAuth 2.0 server URL. 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_RewindSubscription (tibEx e, tibRealm realm, const char endpointName, const char durableName, tibProperties props)
	Rewind a durable. More...

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

TIB_API void	tibRealm_UnsubscribeEx (tibEx e, tibRealm realm, const char endpointName, const char dynamicDurableName, tibProperties props)
	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

Deprecated. Trust any FTL server; property value constant.

This constant is deprecated. There is no need to use TIB_REALM_PROPERTY_LONG_TRUST_TYPE. Use TIB_REALM_PROPERTY_BOOL_TRUST_EVERYONE instead.

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

Deprecated. Trust an FTL server if its certificate is in a trust file; property value constant.

This constant is deprecated. There is no need to use TIB_REALM_PROPERTY_LONG_TRUST_TYPE.

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

Deprecated. Trust an FTL server if its certificate is in a trust string; property value constant.

This constant is deprecated. There is no need to use TIB_REALM_PROPERTY_LONG_TRUST_TYPE.

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_BOOL_TRUST_EVERYONE

#define TIB_REALM_PROPERTY_BOOL_TRUST_EVERYONE "com.tibco.ftl.trust.everyone"

Property name for skipping TLS certificate validation; bool.

Supply this property to tibRealm_Connect.

The client trusts any FTL server without verifying trust in the server's certificate. Do not use this property except for convenience in development and testing. It is not secure.

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

This property applies only to tibRealm_Connect and does not affect reconnects if the client loses connection to the FTL server.

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

#define TIB_REALM_PROPERTY_LONG_SECURITY_LEVEL "com.tibco.ftl.security.level"

Property name for TLS security level; long.

Supply this property to tibRealm_Connect.

The value of this property must be an integer between 0 and 5, inclusive.

If the administrator has configured a user-defined certificate at FTL server, the given security level is applied to all TLS connections to FTL server. In general, increasing the security level enforces stricter requirements for certificate keys, signatures, and ciphers. In particular, if the user-provided certificate does not meet the key requirements, the TLS connection will fail. The default security level is 2. FTL will enforce a minimum TLS version of 1.2 regardless of the actual security level.

If the administrator instead uses FTL-issued certificates for TLS, the given security level cannot be greater than 4. FTL will enforce a minimum TLS version of 1.3 when using FTL-issued certificates.

Refer to the openssl documentation for a precise definition of the openssl security level.

◆ TIB_REALM_PROPERTY_LONG_TRUST_TYPE

#define TIB_REALM_PROPERTY_LONG_TRUST_TYPE "com.tibco.ftl.trust.type"

Deprecated. Property name for secure FTL server trust type; long.

This property is deprecated. Omit this property; instead, use TIB_REALM_PROPERTY_STRING_TRUST_FILE, TIB_REALM_PROPERTY_STRING_TRUST_PEM_STRING, or TIB_REALM_PROPERTY_BOOL_TRUST_EVERYONE. To use the system trust store, omit all of these properties.

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_CERT

#define TIB_REALM_PROPERTY_STRING_CLIENT_CERT "com.tibco.ftl.client.cert"

Property name for client identity certificate; string.

Supply this property to tibRealm_Connect.

As an alternative to user/password, client applications may use a TLS certificate to authenticate to FTL server. A TLS connection is required. Applications must also specify the private key alongside the certificate.

The value of this property must be a PEM file containing the certificate. The PEM file may also include intermediate certificates.

Administrators are responsible for distributing client certificates to applications. The client's auth roles should be encoded as a comma- separated list in the common name (CN) field of the client certificate.

See also: TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY; TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD

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

#define TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY "com.tibco.ftl.client.private.key"

Property name for client certificate's private key; string.

Supply this property to tibRealm_Connect.

When using a TLS certificate to authenticate to FTL server, the corresponding private key and passphrase must be specified as well.

The value of this property must be a PEM file containing the private key.

See also: TIB_REALM_PROPERTY_STRING_CLIENT_CERT; TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD

◆ TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD

#define TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD "com.tibco.ftl.client.private.key.password"

Property name for client certificate's private key password; string.

Supply this property to tibRealm_Connect.

When using a TLS certificate to authenticate to FTL server, the corresponding private key and passphrase must be specified as well.

The value of this property must be a passphrase used to decrypt the private key.

See also: TIB_REALM_PROPERTY_STRING_CLIENT_CERT; TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY

◆ TIB_REALM_PROPERTY_STRING_OAUTH2_ACCESS_TOKEN

#define TIB_REALM_PROPERTY_STRING_OAUTH2_ACCESS_TOKEN "com.tibco.ftl.oauth2.access.token"

Property name to specify OAuth 2.0 access token.

When this parameter is specified, the FTL client library will use this access token to connect to FTL server.

If this property is specified then FTL client library will not attempt to fetch an access token from the OAuth 2.0 server.

Use this property during tibRealm_Connect.

◆ TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_ID

#define TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_ID "com.tibco.ftl.oauth2.client.id"

, Property name for OAuth 2.0 client id, this client id is required to get the OAuth 2.0 access token; string

When this parameter is specified along with TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_URL and TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_SECRET, FTL client library will connect to the OAuth 2.0 server specified to get the OAuth 2.0 access token prior to connecting to the FTL Server.

Use this property during tibRealm_Connect.

◆ TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_SECRET

#define TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_SECRET "com.tibco.ftl.oauth2.client.secret"

, Property name for OAuth 2.0 client secret, this client secret is required to get the OAuth 2.0 access token; string

When this parameter is specified along with TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_URL and TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_ID, FTL client library will connect to the OAuth 2.0 server specified to get the OAuth 2.0 access token prior to connecting to the FTL Server

Use this property during tibRealm_Connect.

◆ TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_TRUST_FILE

#define TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_TRUST_FILE "com.tibco.ftl.oauth2.server.trust.file"

, Property name for OAuth 2.0 server specific trust file.

When the connection to the OAuth 2.0 server is secure, specify this trust file, so the client knows who to trust.

Use this property during tibRealm_Connect.

◆ TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_URL

#define TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_URL "com.tibco.ftl.oauth2.server.url"

, Property name for OAuth 2.0 server URL.

When this parameter is specified along with TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_SECRET and TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_ID, FTL client library will connect to the OAuth 2.0 server specified to get the OAuth 2.0 access token prior to connecting to the FTL Server.

If this url scheme starts with https:// then specify TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_TRUST_FILE ;string

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

Use this property to indicate the location of the trust file for TLS connections to FTL server. The file must contain one or more certificiates in PEM format.

If the trust file contains only an FTL-issued root certificate (ftl-trust.pem), the library will also try to verify FTL server's certificate against the system trust store.

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

Use this property to supply a trust string for TLS connections to FTL server. The string must contain one or more certificates in PEM format.

If the trust string contains only an FTL-issued root certificate, the library will also try to verify FTL server's certificate against the system trust store.

◆ 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. This can be a masked password, which would be unmasked before being sent to the realm service.

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 or for authentication. Otherwise optional; to omit, supply `NULL`. For TLS connections to FTL server, omit all trust properties to use the system trust store. The library will also try the system trust store when an FTL-issued trust file (ftl-trust.pem) is specified. TLS Connection Properties TIB_REALM_PROPERTY_STRING_TRUST_FILE TIB_REALM_PROPERTY_STRING_TRUST_PEM_STRING TIB_REALM_PROPERTY_BOOL_TRUST_EVERYONE TIB_REALM_PROPERTY_LONG_SECURITY_LEVEL Authenication Properties TIB_REALM_PROPERTY_STRING_USERNAME TIB_REALM_PROPERTY_STRING_USERPASSWORD TIB_REALM_PROPERTY_STRING_CLIENT_CERT TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD 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.

◆ 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. Note that the lock is actually acquired by map calls for objects associated with a lock. See:

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.

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

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_GetServerVersion()

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

◆ 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	Optional. `NULL` to omit. Properties: TIB_MAP_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION TIB_MAP_PROPERTY_STRING_LABEL

Returns: void

◆ tibRealm_RewindSubscription()

TIB_API void tibRealm_RewindSubscription	(	tibEx	e,
		tibRealm	realm,
		const char *	endpointName,
		const char *	durableName,
		tibProperties	props
	)

Rewind a durable.

Rewinding a durable returns the durable to an earlier state. Messages that were acknowledged and are still retained by the server will be delivered again when the next subscriber is created on the durable.

For this call to succeed, message retention must be enabled for the durable. Message retention causes successfully acknowledged messages to be preserved for some amount of time, as specified in the realm configuration.

If one client rewinds a 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 the persistence call. The call will be retried for the specified time, after which it fails.

Parameters

e	The exception object captures information about failures.
realm	The call rewinds a durable in this realm.
endpointName	The call rewinds a durable in the store associated with this endpoint.
durableName	The call rewinds the durable with this name.
props	Optional. `NULL` to omit. Properties: TIB_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

Returns: void

◆ tibRealm_SetLogCallback()

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

◆ tibRealm_SetLogFiles()

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

◆ tibRealm_SetLogLevel()

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

◆ 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

◆ tibRealm_UnsubscribeEx()

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 the 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: TIB_SUBSCRIBER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

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_BOOL_TRUST_EVERYONE

◆ TIB_REALM_PROPERTY_DOUBLE_CONNECT_INTERVAL

◆ TIB_REALM_PROPERTY_LONG_CONNECT_RETRIES

◆ TIB_REALM_PROPERTY_LONG_SECURITY_LEVEL

◆ TIB_REALM_PROPERTY_LONG_TRUST_TYPE

◆ TIB_REALM_PROPERTY_STRING_APPINSTANCE_IDENTIFIER

◆ TIB_REALM_PROPERTY_STRING_CLIENT_CERT

◆ TIB_REALM_PROPERTY_STRING_CLIENT_LABEL

◆ TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY

◆ TIB_REALM_PROPERTY_STRING_CLIENT_PRIVATE_KEY_PASSWORD

◆ TIB_REALM_PROPERTY_STRING_OAUTH2_ACCESS_TOKEN

◆ TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_ID

◆ TIB_REALM_PROPERTY_STRING_OAUTH2_CLIENT_SECRET

◆ TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_TRUST_FILE

◆ TIB_REALM_PROPERTY_STRING_OAUTH2_SERVER_URL

◆ 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_GetServerVersion()

◆ tibRealm_RemoveMap()

◆ tibRealm_RewindSubscription()

◆ tibRealm_SetLogCallback()

◆ tibRealm_SetLogFiles()

◆ tibRealm_SetLogLevel()

◆ tibRealm_SetNotificationHandler()

◆ tibRealm_Unsubscribe()

◆ tibRealm_UnsubscribeEx()