TIBCO FTL®

Macros | Typedefs | Enumerations | Functions
realm.h File Reference

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:

- tibMap_CreateIteratorWithLock
- tibMap_GetSizeWithLock
- tibMap_GetWithLock
- tibMap_RemoveAllWithLock
- tibMap_RemoveWithLock
- tibMap_SetMultipleWithLock
- tibMap_SetWithLock

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:

- TIB_LOG_LEVEL_OFF
- TIB_LOG_LEVEL_SEVERE
- TIB_LOG_LEVEL_WARN
- TIB_LOG_LEVEL_INFO
- TIB_LOG_LEVEL_VERBOSE
- TIB_LOG_LEVEL_DEBUG

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