TIBCO FTL®
|
Message objects contain fields with values. More...
Macros | |
#define | TIB_BUILTIN_MSG_FMT_KEY_FIELDNAME "_key" |
Built-in field name of the key field in a keyed opaque message. More... | |
#define | TIB_BUILTIN_MSG_FMT_KEY_MAXLEN (255) |
Maximum length (in bytes) of the key field of a keyed opaque message. More... | |
#define | TIB_BUILTIN_MSG_FMT_KEYED_OPAQUE "_keyed_opaque" |
Built-in format name for keyed opaque messages. More... | |
#define | TIB_BUILTIN_MSG_FMT_OPAQUE "_default_opaque" |
Built-in format name for opaque messages. More... | |
#define | TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME "_data" |
Built-in field name of the data field in an opaque message or a keyed opaque message. More... | |
#define | TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE (12000) |
Maximum efficient length (in bytes) of a built-in opaque message. More... | |
#define | TIB_MSG_FIELDS_FINGERPRINT_SIZE 20 |
Size in bytes of a message field fingerprint. More... | |
Typedefs | |
typedef struct __tibMessage * | tibMessage |
Message object type. More... | |
typedef struct __tibMessageIterator * | tibMessageIterator |
Message iterator object type. More... | |
Enumerations | |
enum | tibFieldType { TIB_FIELD_TYPE_OPAQUE = 0, TIB_FIELD_TYPE_LONG = 1, TIB_FIELD_TYPE_LONG_ARRAY = 2, TIB_FIELD_TYPE_DOUBLE = 3, TIB_FIELD_TYPE_DOUBLE_ARRAY = 4, TIB_FIELD_TYPE_STRING = 5, TIB_FIELD_TYPE_STRING_ARRAY = 6, TIB_FIELD_TYPE_MESSAGE = 7, TIB_FIELD_TYPE_MESSAGE_ARRAY = 8, TIB_FIELD_TYPE_INBOX = 9, TIB_FIELD_TYPE_DATETIME = 10, TIB_FIELD_TYPE_DATETIME_ARRAY = 11, TIB_FIELD_TYPE_UNKNOWN = 2048 } |
Datatypes of FTL message fields. More... | |
Functions | |
TIB_API const char * | tibFieldType_GetAsString (tibEx e, tibFieldType fieldType) |
Return a string that represents a field type. More... | |
TIB_API void | tibMessage_Acknowledge (tibEx e, tibMessage message) |
Explicitly acknowledge a message. More... | |
TIB_API void | tibMessage_ClearAllFields (tibEx e, tibMessage message) |
Clear all fields in a mutable message. More... | |
TIB_API void | tibMessage_ClearField (tibEx e, tibMessage message, const char *name) |
Clear a field in a mutable message. More... | |
TIB_API void | tibMessage_ClearFieldByRef (tibEx e, tibMessage message, tibFieldRef fieldRef) |
Clear a field in a mutable message. More... | |
TIB_API tibMessage | tibMessage_Create (tibEx e, tibRealm realm, const char *formatName) |
Create a mutable message object. More... | |
TIB_API void | tibMessage_Destroy (tibEx e, tibMessage message) |
Destroy a message object. More... | |
TIB_API void * | tibMessage_GetArray (tibEx e, tibMessage message, tibFieldType arrayType, const char *name, tibint32_t *arraySize) |
Get the value of an array field from a message. More... | |
TIB_API void * | tibMessage_GetArrayByRef (tibEx e, tibMessage message, tibFieldType arrayType, tibFieldRef fieldRef, tibint32_t *arraySize) |
Get the value of an array field from a message. More... | |
TIB_API tibDateTime * | tibMessage_GetDateTime (tibEx e, tibMessage message, const char *name) |
Get the value of a DateTime field from a message. More... | |
TIB_API tibDateTime * | tibMessage_GetDateTimeByRef (tibEx e, tibMessage message, tibFieldRef fieldRef) |
Get the value of a DateTime field from a message. More... | |
TIB_API tibint32_t | tibMessage_GetDeliveryCount (tibEx e, tibMessage message) |
Get the delivery count of a message. More... | |
TIB_API tibdouble_t | tibMessage_GetDouble (tibEx e, tibMessage message, const char *name) |
Get the value of a double floating-point field from a message. More... | |
TIB_API tibdouble_t | tibMessage_GetDoubleByRef (tibEx e, tibMessage message, tibFieldRef fieldRef) |
Get the value of a double floating-point field from a message. More... | |
TIB_API void | tibMessage_GetFieldsFingerprint (tibEx e, tibMessage message, tibuint8_t *fingerprintBuffer, tibint32_t fingerprintBufferSize) |
Return a fingerprint representing a message's set fields. More... | |
TIB_API tibFieldType | tibMessage_GetFieldType (tibEx e, tibMessage message, const char *name) |
Get the type of a field within a message. More... | |
TIB_API tibFieldType | tibMessage_GetFieldTypeByRef (tibEx e, tibMessage message, tibFieldRef fieldRef) |
Get the type of a field within a message. More... | |
TIB_API tibInbox | tibMessage_GetInbox (tibEx e, tibMessage message, const char *name) |
Get the value of an inbox field from a message. More... | |
TIB_API tibInbox | tibMessage_GetInboxByRef (tibEx e, tibMessage message, tibFieldRef fieldRef) |
Get the value of an inbox field from a message. More... | |
TIB_API tibint64_t | tibMessage_GetLong (tibEx e, tibMessage message, const char *name) |
Get the value of a long field from a message. More... | |
TIB_API tibint64_t | tibMessage_GetLongByRef (tibEx e, tibMessage message, tibFieldRef fieldRef) |
Get the value of a long field from a message. More... | |
TIB_API tibMessage | tibMessage_GetMessage (tibEx e, tibMessage message, const char *name) |
Get the value of a message field from a message. More... | |
TIB_API tibMessage | tibMessage_GetMessageByRef (tibEx e, tibMessage message, tibFieldRef fieldRef) |
Get the value of a message field from a message. More... | |
TIB_API const void * | tibMessage_GetOpaque (tibEx e, tibMessage message, const char *name, tibint32_t *size) |
Get the content of an opaque field from a message. More... | |
TIB_API const void * | tibMessage_GetOpaqueByRef (tibEx e, tibMessage message, tibFieldRef fieldRef, tibint32_t *size) |
Get the content of an opaque field from a message. More... | |
TIB_API const char * | tibMessage_GetString (tibEx e, tibMessage message, const char *name) |
Get the value of a string field from a message. More... | |
TIB_API const char * | tibMessage_GetStringByRef (tibEx e, tibMessage message, tibFieldRef fieldRef) |
Get the value of a string field from a message. More... | |
TIB_API tibbool_t | tibMessage_IsFieldSet (tibEx e, tibMessage message, const char *name) |
Determine whether a field is set in a message. More... | |
TIB_API tibbool_t | tibMessage_IsFieldSetByRef (tibEx e, tibMessage message, tibFieldRef fieldRef) |
Determine whether a field is set in a message. More... | |
TIB_API tibMessage | tibMessage_MutableCopy (tibEx e, tibMessage message) |
Create a mutable copy of a message. More... | |
TIB_API tibMessage | tibMessage_ReadFromByteArray (tibEx e, tibRealm realm, const tibuint8_t *byteArray, tibint32_t byteArraySize) |
Create a message from a byte-array representation. More... | |
TIB_API void | tibMessage_SetArray (tibEx e, tibMessage message, tibFieldType arrayType, const char *name, const void *const values, tibint32_t arraySize) |
Set an array field in a mutable message. More... | |
TIB_API void | tibMessage_SetArrayByRef (tibEx e, tibMessage message, tibFieldType arrayType, tibFieldRef fieldRef, const void *const values, tibint32_t arraySize) |
Set an array field in a mutable message. More... | |
TIB_API void | tibMessage_SetDateTime (tibEx e, tibMessage message, const char *name, const tibDateTime *dateTime) |
Set a DateTime field in a mutable message. More... | |
TIB_API void | tibMessage_SetDateTimeByRef (tibEx e, tibMessage message, tibFieldRef fieldRef, const tibDateTime *dateTime) |
Set a DateTime field in a mutable message. More... | |
TIB_API void | tibMessage_SetDouble (tibEx e, tibMessage message, const char *name, tibdouble_t value) |
Set a double floating-point field in a mutable message. More... | |
TIB_API void | tibMessage_SetDoubleByRef (tibEx e, tibMessage message, tibFieldRef fieldRef, tibdouble_t value) |
Set a double floating-point field in a mutable message. More... | |
TIB_API void | tibMessage_SetInbox (tibEx e, tibMessage message, const char *name, tibInbox inbox) |
Set an inbox field in a mutable message. More... | |
TIB_API void | tibMessage_SetInboxByRef (tibEx e, tibMessage message, tibFieldRef fieldRef, tibInbox inbox) |
Set an inbox field in a mutable message. More... | |
TIB_API void | tibMessage_SetLong (tibEx e, tibMessage message, const char *name, tibint64_t value) |
Set a long integer field in a mutable message. More... | |
TIB_API void | tibMessage_SetLongByRef (tibEx e, tibMessage message, tibFieldRef fieldRef, tibint64_t value) |
Set a long integer field in a mutable message. More... | |
TIB_API void | tibMessage_SetMessage (tibEx e, tibMessage message, const char *name, tibMessage value) |
Set a sub-message field in a mutable message. More... | |
TIB_API void | tibMessage_SetMessageByRef (tibEx e, tibMessage message, tibFieldRef fieldRef, tibMessage value) |
Set a sub-message field in a mutable message. More... | |
TIB_API void | tibMessage_SetOpaque (tibEx e, tibMessage message, const char *name, const void *value, tibint32_t size) |
Set an opaque (byte-string) field in a mutable message. More... | |
TIB_API void | tibMessage_SetOpaqueByRef (tibEx e, tibMessage message, tibFieldRef fieldRef, const void *value, tibint32_t size) |
Set an opaque (byte-string) field in a mutable message. More... | |
TIB_API void | tibMessage_SetOpaqueDirect (tibEx e, tibMessage message, const char *name, const void *value, tibint32_t size) |
Set an opaque (byte-string) field in a mutable message. More... | |
TIB_API void | tibMessage_SetOpaqueDirectByRef (tibEx e, tibMessage message, tibFieldRef fieldRef, const void *value, tibint32_t size) |
Set an opaque (byte-string) field by reference in a mutable message. More... | |
TIB_API void | tibMessage_SetString (tibEx e, tibMessage message, const char *name, const char *value) |
Set a string field in a mutable message. More... | |
TIB_API void | tibMessage_SetStringByRef (tibEx e, tibMessage message, tibFieldRef fieldRef, const char *value) |
Set a string field in a mutable message. More... | |
TIB_API tibint32_t | tibMessage_ToString (tibEx e, tibMessage message, char *buffer, tibint32_t size) |
Get a printable string that describes the contents of a message. More... | |
TIB_API tibint32_t | tibMessage_WriteToByteArray (tibEx e, tibMessage message, tibuint8_t *byteArray, tibint32_t byteArraySize) |
Write a serialized representation of a message to a byte-array. More... | |
TIB_API tibint32_t | tibMessage_WriteToPortableByteArray (tibEx e, tibMessage message, tibuint8_t *byteArray, tibint32_t byteArraySize) |
Write a self-describing serialized representation of a message to a byte-array. More... | |
TIB_API tibMessageIterator | tibMessageIterator_Create (tibEx e, tibMessage message) |
Create a message iterator object. More... | |
TIB_API void | tibMessageIterator_Destroy (tibEx e, tibMessageIterator messageIterator) |
Destroy a message iterator object. More... | |
TIB_API tibFieldRef | tibMessageIterator_GetNext (tibEx e, tibMessageIterator messageIterator) |
Get the next field of a message iterator object. More... | |
TIB_API tibbool_t | tibMessageIterator_HasNext (tibEx e, tibMessageIterator messageIterator) |
Determine whether a message iterator object can present another field. More... | |
TIB_API void | tibMessageIterator_Reset (tibEx e, tibMessageIterator messageIterator) |
Reset a message iterator object. More... | |
Message objects contain fields with values.
This file defines message objects, message fields, message iterators, and calls that manipulate them.
#define TIB_BUILTIN_MSG_FMT_KEY_FIELDNAME "_key" |
Built-in field name of the key field in a keyed opaque message.
#define TIB_BUILTIN_MSG_FMT_KEY_MAXLEN (255) |
Maximum length (in bytes) of the key field of a keyed opaque message.
#define TIB_BUILTIN_MSG_FMT_KEYED_OPAQUE "_keyed_opaque" |
Built-in format name for keyed opaque messages.
Keyed opaque messages contain only a character string and a byte-string. Content matchers can match against the key field (character string).
This format name is valid as an argument to tibMessage_Create.
#define TIB_BUILTIN_MSG_FMT_OPAQUE "_default_opaque" |
Built-in format name for opaque messages.
Opaque messages contain only a byte-string.
This format name is valid as an argument to tibMessage_Create.
#define TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME "_data" |
Built-in field name of the data field in an opaque message or a keyed opaque message.
#define TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE (12000) |
Maximum efficient length (in bytes) of a built-in opaque message.
Larger payloads are less efficient.
This threshold also applies to the total payload of a keyed opaque message (including the key string, its null terminator, and the opaque data).
#define TIB_MSG_FIELDS_FINGERPRINT_SIZE 20 |
Size in bytes of a message field fingerprint.
typedef struct __tibMessage* tibMessage |
Message object type.
Message objects are not thread-safe. Programs must not access a message from several threads simultaneously.
typedef struct __tibMessageIterator* tibMessageIterator |
Message iterator object type.
When you do not know the format of a message at the time you design a program, your program can use a message iterator to traverse the fields of a message. For example, you can use this technique to output the complete content of an erroneous or unexpected message to a log file. (However, when you do know the format of an inbound message, then you can code the program to get each field in the most efficient manner.)
A message iterator presents all the fields that are actually set in a message object. The message format determines the order in which an iterator presents the fields of a message.
Message iterator objects are not thread-safe. Programs must not access a message iterator from several threads simultaneously.
An iterator becomes invalid when its message becomes invalid.
enum tibFieldType |
Datatypes of FTL message fields.
Enumerator | |
---|---|
TIB_FIELD_TYPE_OPAQUE | Opaque byte-string. |
TIB_FIELD_TYPE_LONG | Long integer. |
TIB_FIELD_TYPE_LONG_ARRAY | Array of long integers. |
TIB_FIELD_TYPE_DOUBLE | Double floating-point number. |
TIB_FIELD_TYPE_DOUBLE_ARRAY | Array of double floating-point numbers. |
TIB_FIELD_TYPE_STRING | Character string. |
TIB_FIELD_TYPE_STRING_ARRAY | Array of character strings. |
TIB_FIELD_TYPE_MESSAGE | Sub-message (that is, a nested message). |
TIB_FIELD_TYPE_MESSAGE_ARRAY | Array of sub-messages. |
TIB_FIELD_TYPE_INBOX | Inbox. |
TIB_FIELD_TYPE_DATETIME | DateTime. |
TIB_FIELD_TYPE_DATETIME_ARRAY | Array of DateTimes. |
TIB_FIELD_TYPE_UNKNOWN | Unrecognized type. tibMessage_GetFieldType and tibMessage_GetFieldTypeByRef return For example, getting the field type for a NULL message returns this value. It is not legal for programs to supply |
TIB_API const char* tibFieldType_GetAsString | ( | tibEx | e, |
tibFieldType | fieldType | ||
) |
Return a string that represents a field type.
e | The exception object captures information about failures. |
fieldType | The call converts this type to a string. |
TIB_API void tibMessage_Acknowledge | ( | tibEx | e, |
tibMessage | message | ||
) |
Explicitly acknowledge a message.
When a durable subscriber object specifies explicit acknowledgement, the application program must acknowledge each message to the durable by calling this method.
When a durable subscriber object does not specify explicit acknowledgement, the FTL library automatically acknowledges the message when the application callback method returns.
For any message that arrives through a non-durable subscriber, this call returns without error (and without action).
e | The exception object captures information about failures. |
message | The call acknowledges receiving this message. |
TIB_API void tibMessage_ClearAllFields | ( | tibEx | e, |
tibMessage | message | ||
) |
Clear all fields in a mutable message.
After clearing all fields, you can re-use the message. The message format does not change.
This call is more efficient than creating a new empty message of the same format.
e | The exception object captures information about failures. |
message | The call clears all fields in this message. |
TIB_API void tibMessage_ClearField | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name | ||
) |
Clear a field in a mutable message.
Clearing a field clears the data from a field in the message object, and flags the field so a subsequent send call does not transmit it.
e | The exception object captures information about failures. |
message | The call clears the field in this message. |
name | The call clears the field with this name. |
TIB_API void tibMessage_ClearFieldByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef | ||
) |
Clear a field in a mutable message.
Clearing a field clears the data from a field in the message object, and flags the field so a subsequent send call does not transmit it.
e | The exception object captures information about failures. |
message | The call clears the field in this message. |
fieldRef | The call clears the value of this field. |
TIB_API tibMessage tibMessage_Create | ( | tibEx | e, |
tibRealm | realm, | ||
const char * | formatName | ||
) |
Create a mutable message object.
Programs can use this call to create messages for sending.
Message objects are not thread-safe. Programs must not access a message from several threads simultaneously.
e | The exception object captures information about failures. |
realm | The call searches this realm for the format definition. |
formatName | The call creates a message with this format.NULL is a special value, indicating an unnamed dynamic format (for use only in one specific message). |
TIB_API void tibMessage_Destroy | ( | tibEx | e, |
tibMessage | message | ||
) |
Destroy a message object.
A program that creates a mutable message must explicitly destroy it to reclaim its resources. (However, it is often more efficient to reuse a mutable message. For further details, see the book TIBCO FTL Development.)
If a subscriber has set the release to callback property, then the program must explicitly destroy all messages it receives through dispatch from that subscriber. Otherwise, the program must not destroy messages received through dispatch.
Inbound messages (and sub-messages) in callbacks belong to the FTL library; programs must not destroy them.
Do not destroy a message if the program needs a reference into that message – for example, a string pointer (from tibMessage_GetString) or an opaque pointer (from tibMessage_GetOpaque).
Destroying a message frees all resources associated with it.
e | The exception object captures information about failures. |
message | The call destroys this message object. |
TIB_API void* tibMessage_GetArray | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldType | arrayType, | ||
const char * | name, | ||
tibint32_t * | arraySize | ||
) |
Get the value of an array field from a message.
The program must cast the return value appropriately. The values array is valid only for the lifetime of the message. Programs must not modify or free the array.
This table lists the valid array types.
Array Type Constant | Values Array Pointer Type |
---|---|
TIB_FIELD_TYPE_LONG_ARRAY | tibint64_t* |
TIB_FIELD_TYPE_DOUBLE_ARRAY | double* |
TIB_FIELD_TYPE_STRING_ARRAY | char** |
TIB_FIELD_TYPE_MESSAGE_ARRAY | tibMessage* |
TIB_FIELD_TYPE_DATETIME_ARRAY | tibDateTime* |
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
arrayType | The program supplies the array type of the field. |
name | The call gets the value of the field with this name. |
arraySize | The call stores the number of array elements in this location. |
TIB_API void* tibMessage_GetArrayByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldType | arrayType, | ||
tibFieldRef | fieldRef, | ||
tibint32_t * | arraySize | ||
) |
Get the value of an array field from a message.
The program must cast the return value appropriately. The values array is valid only for the lifetime of the message. Programs must not modify or free the array.
This table lists the valid array types.
Array Type Constant | Values Array Pointer Type |
---|---|
TIB_FIELD_TYPE_LONG_ARRAY | tibint64_t* |
TIB_FIELD_TYPE_DOUBLE_ARRAY | double* |
TIB_FIELD_TYPE_STRING_ARRAY | char** |
TIB_FIELD_TYPE_MESSAGE_ARRAY | tibMessage* |
TIB_FIELD_TYPE_DATETIME_ARRAY | tibDateTime* |
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
arrayType | The program supplies the array type of the field. |
fieldRef | The call gets the value of this field. |
arraySize | The call stores the number of array elements in this location. |
TIB_API tibDateTime* tibMessage_GetDateTime | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name | ||
) |
Get the value of a DateTime field from a message.
The program must not destroy the tibDateTime
struct because the message owns it.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
name | The call gets the value of the field with this name. |
TIB_API tibDateTime* tibMessage_GetDateTimeByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef | ||
) |
Get the value of a DateTime field from a message.
The program must not destroy the tibDateTime
struct because the message owns it.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
fieldRef | The call gets the value of this field. |
TIB_API tibint32_t tibMessage_GetDeliveryCount | ( | tibEx | e, |
tibMessage | message | ||
) |
Get the delivery count of a message.
This value represents the number of times that a persistence server has delivered the message from a shared durable to any subscriber. The value 1 indicates the application is the first to receive the message.
The special value -1 indicates that delivery count does not apply. For example, the message is not in a shared durable, or did not arrive from a persistence server that tracks delivery count.
e | The exception object captures information about failures. |
message | The call gets the delivery count for this message. |
TIB_API tibdouble_t tibMessage_GetDouble | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name | ||
) |
Get the value of a double floating-point field from a message.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
name | The call gets the value of the field with this name. |
TIB_API tibdouble_t tibMessage_GetDoubleByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef | ||
) |
Get the value of a double floating-point field from a message.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
fieldRef | The call gets the value of this field. |
TIB_API void tibMessage_GetFieldsFingerprint | ( | tibEx | e, |
tibMessage | message, | ||
tibuint8_t * | fingerprintBuffer, | ||
tibint32_t | fingerprintBufferSize | ||
) |
Return a fingerprint representing a message's set fields.
A message's fields fingerprint is calculated based on the message's set fields, taking into account each field's position, type, and name, but not value.
e | The exception object captures information about failures. |
message | The message to retrieve a fields fingerprint for. |
fingerprintBuffer | A user-allocated buffer to hold the returned fingerprint. |
fingerprintBufferSize | The size in bytes of fingerprintBuffer; must be at least TIB_MSG_FIELDS_FINGERPRINT_SIZE. |
TIB_API tibFieldType tibMessage_GetFieldType | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name | ||
) |
Get the type of a field within a message.
e | The exception object captures information about failures. |
message | The call finds the field within this message. |
name | The call gets the type of the field with this name. |
TIB_API tibFieldType tibMessage_GetFieldTypeByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef | ||
) |
Get the type of a field within a message.
e | The exception object captures information about failures. |
message | The call finds the field within this message. |
fieldRef | The call gets the type of this field. |
TIB_API tibInbox tibMessage_GetInbox | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name | ||
) |
Get the value of an inbox field from a message.
This call deserializes the inbox value, caches the result with the message object, and returns that cached inbox object. The inbox object is valid only for the lifetime of the message (though programs may copy it). Your program must not modify nor destroy the inbox object.
Calling this method repeatedly returns the same cached inbox; it does not repeat the deserialization.
Programs can send messages to the inbox using tibPublisher_SendToInbox.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
name | The call gets the value of the field with this name. |
TIB_API tibInbox tibMessage_GetInboxByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef | ||
) |
Get the value of an inbox field from a message.
This call deserializes the inbox value, caches the result with the message object, and returns that cached inbox object. The inbox object is valid only for the lifetime of the message (though programs may copy it). Your program must not modify nor destroy the inbox object.
Calling this method repeatedly returns the same cached inbox; it does not repeat the deserialization.
Programs can send messages to the inbox using tibPublisher_SendToInbox.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
fieldRef | The call gets the value of this field. |
TIB_API tibint64_t tibMessage_GetLong | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name | ||
) |
Get the value of a long field from a message.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
name | The call gets the value of the field with this name. |
TIB_API tibint64_t tibMessage_GetLongByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef | ||
) |
Get the value of a long field from a message.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
fieldRef | The call gets the value of this field. |
TIB_API tibMessage tibMessage_GetMessage | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name | ||
) |
Get the value of a message field from a message.
This call deserializes the sub-message value, caches the result with the message object, and returns a pointer to that sub-message. The sub-message is valid only for the lifetime of the parent message.
The program must not modify nor destroy the sub-message. The FTL library destroys the sub-message when it destroys the parent message (usually when the callback returns).
Calling this method repeatedly returns the same cached sub-message; it does not repeat the deserialization.
e | The exception object captures information about failures. |
message | The call gets the field in this message. |
name | The call gets the value of the field with this name. |
TIB_API tibMessage tibMessage_GetMessageByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef | ||
) |
Get the value of a message field from a message.
This call deserializes the sub-message value, caches the result with the message object, and returns a pointer to that sub-message. The sub-message is valid only for the lifetime of the parent message. The program must not modify nor destroy the sub-message. The FTL library destroys the sub-message when it destroys the parent message (usually when the callback returns).
Calling this method repeatedly returns the same cached sub-message; it does not repeat the deserialization.
e | The exception object captures information about failures. |
message | The call gets the field in this message. |
fieldRef | The call gets the value of this field. |
TIB_API const void* tibMessage_GetOpaque | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name, | ||
tibint32_t * | size | ||
) |
Get the content of an opaque field from a message.
The data pointer is valid only for the lifetime of the message. The data bytes are part of the message object; the program must neither modify nor free them.
The data pointer is not necessarily aligned to a word boundary. Before casting the opaque data to a struct, you must either verify that it is properly aligned (that is, the data pointer is divisible by 8), or copy the data to an aligned location.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
name | The call gets the content of the field with this name. |
size | The call returns the length (in bytes) of the opaque field. |
TIB_API const void* tibMessage_GetOpaqueByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef, | ||
tibint32_t * | size | ||
) |
Get the content of an opaque field from a message.
The data pointer is valid only for the lifetime of the message. The data bytes are part of the message object; the program must neither modify nor free them.
The data pointer is not necessarily aligned to a word boundary. Before casting the opaque data to a struct, you must either verify that it is properly aligned (that is, the data pointer is divisible by 8), or copy the data to an aligned location.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
fieldRef | The call gets the content of this field. |
size | The call returns the length (in bytes) of the opaque field. |
TIB_API const char* tibMessage_GetString | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name | ||
) |
Get the value of a string field from a message.
A NULL
character terminates the string. The string pointer is valid only for the lifetime of the message. The string is part of the message object; the program must neither modify nor free it.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
name | The call gets the value of the field with this name. |
TIB_API const char* tibMessage_GetStringByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef | ||
) |
Get the value of a string field from a message.
A NULL
character terminates the string. The string pointer is valid only for the lifetime of the message. The string is part of the message object; the program must neither modify nor free it.
e | The exception object captures information about failures. |
message | The call gets the field from this message. |
fieldRef | The call gets the value of this field. |
TIB_API tibbool_t tibMessage_IsFieldSet | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name | ||
) |
Determine whether a field is set in a message.
e | The exception object captures information about failures. |
message | The call checks in this message. |
name | The call checks for a field with this name. |
TIB_API tibbool_t tibMessage_IsFieldSetByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef | ||
) |
Determine whether a field is set in a message.
e | The exception object captures information about failures. |
message | The call checks in this message. |
fieldRef | The call checks for this field. |
TIB_API tibMessage tibMessage_MutableCopy | ( | tibEx | e, |
tibMessage | message | ||
) |
Create a mutable copy of a message.
Programs cannot modify inbound messages that subscribers receive. However, programs can use this call to create mutable copies (which they may modify).
Programs must destroy mutable copies to reclaim resources.
e | The exception object captures information about failures. |
message | The call copies this source message. |
TIB_API tibMessage tibMessage_ReadFromByteArray | ( | tibEx | e, |
tibRealm | realm, | ||
const tibuint8_t * | byteArray, | ||
tibint32_t | byteArraySize | ||
) |
Create a message from a byte-array representation.
This call reconstitutes a message object from its serialized byte-array representation.
After this call returns, you may re-use or destroy the byte-array.
e | The exception object captures information about failures. |
realm | The call gets format information from this realm. |
byteArray | The call reads this byte-array representation of the message. |
byteArraySize | The program supplies the size of the byte-array (in bytes). |
TIB_API void tibMessage_SetArray | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldType | arrayType, | ||
const char * | name, | ||
const void *const | values, | ||
tibint32_t | arraySize | ||
) |
Set an array field in a mutable message.
When the values array contains strings or message objects, this call copies the data into the message field. After this call returns, the program may modify (or free) the original values array and the strings or messages in it.
This table lists the valid array types.
Array Type Constant | Values Array Pointer Type |
---|---|
TIB_FIELD_TYPE_LONG_ARRAY | tibint64_t* |
TIB_FIELD_TYPE_DOUBLE_ARRAY | double* |
TIB_FIELD_TYPE_STRING_ARRAY | char** |
TIB_FIELD_TYPE_MESSAGE_ARRAY | tibMessage* |
TIB_FIELD_TYPE_DATETIME_ARRAY | tibDateTime* |
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
arrayType | The program supplies a values array of this type. |
name | The call sets the value of the field with this name. |
values | The call sets the field value to the array at this location. (Null is not a legal value within a string array.) |
arraySize | The program supplies the number of elements in the array. |
TIB_API void tibMessage_SetArrayByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldType | arrayType, | ||
tibFieldRef | fieldRef, | ||
const void *const | values, | ||
tibint32_t | arraySize | ||
) |
Set an array field in a mutable message.
When the values array contains strings or message objects, this call copies the data into the message field. After this call returns, the program may modify (or free) the original values array and the strings or messages in it.
This table lists the valid array types.
Array Type Constant | Values Array Pointer Type |
---|---|
TIB_FIELD_TYPE_LONG_ARRAY | tibint64_t* |
TIB_FIELD_TYPE_DOUBLE_ARRAY | double* |
TIB_FIELD_TYPE_STRING_ARRAY | char** |
TIB_FIELD_TYPE_MESSAGE_ARRAY | tibMessage* |
TIB_FIELD_TYPE_DATETIME_ARRAY | tibDateTime* |
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
arrayType | The program supplies a values array of this type. |
fieldRef | The call sets the value of this field. |
values | The call sets the field value to the array at this location. (Null is not a legal value within a string array.) |
arraySize | The program supplies the number of elements in the array. |
TIB_API void tibMessage_SetDateTime | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name, | ||
const tibDateTime * | dateTime | ||
) |
Set a DateTime field in a mutable message.
This call copies a DateTime value into a message field of type TIB_FIELD_TYPE_DATETIME
.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
name | The call sets the value of the field with this name. |
dateTime | The call sets this DateTime as the field value. |
TIB_API void tibMessage_SetDateTimeByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef, | ||
const tibDateTime * | dateTime | ||
) |
Set a DateTime field in a mutable message.
This call copies a DateTime value into a message field of type TIB_FIELD_TYPE_DATETIME
.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
fieldRef | The call sets the value of this field. |
dateTime | The call sets this DateTime as the field value. |
TIB_API void tibMessage_SetDouble | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name, | ||
tibdouble_t | value | ||
) |
Set a double floating-point field in a mutable message.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
name | The call sets the value of the field with this name. |
value | The call sets this double as the field value. |
TIB_API void tibMessage_SetDoubleByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef, | ||
tibdouble_t | value | ||
) |
Set a double floating-point field in a mutable message.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
fieldRef | The call sets the value of this field. |
value | The call sets this double as the field value. |
TIB_API void tibMessage_SetInbox | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name, | ||
tibInbox | inbox | ||
) |
Set an inbox field in a mutable message.
This call copies an inbox into a message field. Programs that receive the message can get the inbox, and send messages to it (using tibPublisher_SendToInbox).
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
name | The call sets the value of the field with this name. |
inbox | The call sets this inbox as the field value. |
TIB_API void tibMessage_SetInboxByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef, | ||
tibInbox | inbox | ||
) |
Set an inbox field in a mutable message.
This call copies an inbox into a message field. Programs that receive the message can copy the inbox, and send messages to it (using tibPublisher_SendToInbox).
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
fieldRef | The call sets the value of this field. |
inbox | The call sets this inbox as the field value. |
TIB_API void tibMessage_SetLong | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name, | ||
tibint64_t | value | ||
) |
Set a long integer field in a mutable message.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
name | The call sets the value of the field with this name. |
value | The call sets this long integer as the field value. |
TIB_API void tibMessage_SetLongByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef, | ||
tibint64_t | value | ||
) |
Set a long integer field in a mutable message.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
fieldRef | The call sets the value of this field. |
value | The call sets this long integer as the field value. |
TIB_API void tibMessage_SetMessage | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name, | ||
tibMessage | value | ||
) |
Set a sub-message field in a mutable message.
This call copies the sub-message into the enclosing message field.
Do not set a message as a sub-message of itself (at any level of nesting).
This call copies the data into the message field. After this call returns, the program may modify (or free) the original sub-message and the strings or messages in it.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
name | The call sets the value of the field with this name. |
value | The call sets this sub-message as the field value. |
TIB_API void tibMessage_SetMessageByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef, | ||
tibMessage | value | ||
) |
Set a sub-message field in a mutable message.
This call copies the sub-message into the enclosing message field.
Do not set a message as a sub-message of itself (at any level of nesting).
This call copies the data into the message field. After this call returns, the program may modify (or free) the original sub-message and the strings or messages in it.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
fieldRef | The call sets the value of this field. |
value | The call sets this sub-message as the field value. |
TIB_API void tibMessage_SetOpaque | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name, | ||
const void * | value, | ||
tibint32_t | size | ||
) |
Set an opaque (byte-string) field in a mutable message.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
name | The call sets the value of the field with this name. |
value | The call copies this byte-string into the message field. |
size | Supply the length (in bytes) of the opaque value. |
TIB_API void tibMessage_SetOpaqueByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef, | ||
const void * | value, | ||
tibint32_t | size | ||
) |
Set an opaque (byte-string) field in a mutable message.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
fieldRef | The call sets the value of this field. |
value | The call copies this byte-string into the message field. |
size | Supply the length (in bytes) of the opaque value. |
TIB_API void tibMessage_SetOpaqueDirect | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name, | ||
const void * | value, | ||
tibint32_t | size | ||
) |
Set an opaque (byte-string) field in a mutable message.
For efficiency, programs can set an opaque field without the expense of copying the byte-string.
tibMessage_SetOpaque copies the opaque value from your buffer into the mutable message object. The program may then modify the buffer without affecting the message.
In contrast, tibMessage_SetOpaqueDirect stores only a pointer to the data in the message object. The send call serializes the opaque data. If you change the data in the buffer before the send call, you must call tibMessage_SetOpaqueDirect again to ensure correct serialization. You must not deallocate the buffer until after destroying the message (that is, until after tibMessage_Destroy returns).
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
name | The call sets the value of the field with this name. |
value | The call sets the field value in the message to be a pointer to this byte-string. |
size | Supply the length (in bytes) of the opaque value. |
TIB_API void tibMessage_SetOpaqueDirectByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef, | ||
const void * | value, | ||
tibint32_t | size | ||
) |
Set an opaque (byte-string) field by reference in a mutable message.
For efficiency, programs can set an opaque field without the expense of copying the byte-string.
tibMessage_SetOpaque copies the opaque value from your buffer into the mutable message object. The program may then modify the buffer without affecting the message.
In contrast, tibMessage_SetOpaqueDirect stores only a pointer to the data in the message object. The send call serializes the opaque data. If you change the data in the buffer before the send call, you must call tibMessage_SetOpaqueDirect again to ensure correct serialization. You must not deallocate the buffer until after destroying the message (that is, until after tibMessage_Destroy returns).
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
fieldRef | The call sets the value of this field. |
value | The call sets the field value in the message to be a pointer to this byte-string. |
size | Supply the length (in bytes) of the opaque value. |
TIB_API void tibMessage_SetString | ( | tibEx | e, |
tibMessage | message, | ||
const char * | name, | ||
const char * | value | ||
) |
Set a string field in a mutable message.
This call copies the string value into the message.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
name | The call sets the value of the field with this name. |
value | The call sets this string as the field value. |
TIB_API void tibMessage_SetStringByRef | ( | tibEx | e, |
tibMessage | message, | ||
tibFieldRef | fieldRef, | ||
const char * | value | ||
) |
Set a string field in a mutable message.
This call copies the string value into the message.
e | The exception object captures information about failures. |
message | The call sets the field in this message. |
fieldRef | The call sets the value of this field. |
value | The call sets this string as the field value. |
TIB_API tibint32_t tibMessage_ToString | ( | tibEx | e, |
tibMessage | message, | ||
char * | buffer, | ||
tibint32_t | size | ||
) |
Get a printable string that describes the contents of a message.
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.
e | The exception object captures information about failures. |
message | The call produces a string description of this message. |
buffer | The call stores the description in this string buffer. |
size | The program supplies the length of buffer (in bytes). |
NULL
character (in btyes) TIB_API tibint32_t tibMessage_WriteToByteArray | ( | tibEx | e, |
tibMessage | message, | ||
tibuint8_t * | byteArray, | ||
tibint32_t | byteArraySize | ||
) |
Write a serialized representation of a message to a byte-array.
Programmers estimate the required size of the byte-array buffer. If the buffer is too small, 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.
Programming Strategy:
e | The exception object captures information about failures. |
message | The call serializes this message. |
byteArray | The call writes the serialized representation into this byte-array buffer. |
byteArraySize | The program supplies the size of the buffer (in bytes). |
TIB_API tibint32_t tibMessage_WriteToPortableByteArray | ( | tibEx | e, |
tibMessage | message, | ||
tibuint8_t * | byteArray, | ||
tibint32_t | byteArraySize | ||
) |
Write a self-describing serialized representation of a message to a byte-array.
This call writes a portable form of the message, which you can use outside the originating realm. The portable form is larger than optimized forms, because it includes all format metadata (as with a dynamic format).
Programmers estimate the required size of the byte-array buffer. If the buffer is too small, 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.
Programming Strategy:
e | The exception object captures information about failures. |
message | The call serializes this message. |
byteArray | The call writes the serialized representation into this byte-array buffer. |
byteArraySize | The program supplies the size of the buffer (in bytes). |
TIB_API tibMessageIterator tibMessageIterator_Create | ( | tibEx | e, |
tibMessage | message | ||
) |
Create a message iterator object.
e | The exception object captures information about failures. |
message | The call initializes an iterator for the fields of this message. |
TIB_API void tibMessageIterator_Destroy | ( | tibEx | e, |
tibMessageIterator | messageIterator | ||
) |
Destroy a message iterator object.
Destroying a message iterator object frees all the resources associated with it, but does not affect the message object.
e | The exception object captures information about failures. |
messageIterator | The call destroys this message iterator object. |
TIB_API tibFieldRef tibMessageIterator_GetNext | ( | tibEx | e, |
tibMessageIterator | messageIterator | ||
) |
Get the next field of a message iterator object.
This call advances the iterator to the next field of its message, and returns a field reference object, which refers to that next field. Programs can use that field reference object to get the field's name, type and value.
Warning: For efficiency, an iterator object reuses a single field reference object. Iterator calls overwrite that field reference object. Programs can use the field reference object with correct results only until the next call that changes the state of the iterator. That is, when you get the next field, reset the iterator, or destroy the iterator, then the field reference object changes too (which also invalidates any field name string you might have previously extracted from the field reference). Although field reference objects are usually thread-safe, this one is not thread-safe. Your program must not destroy this field reference object.
If the iterator has already presented the last field of the message, then this call throws the exception TIB_NOT_FOUND.
e | The exception object captures information about failures. |
messageIterator | The call advances this iterator to the next field. |
TIB_API tibbool_t tibMessageIterator_HasNext | ( | tibEx | e, |
tibMessageIterator | messageIterator | ||
) |
Determine whether a message iterator object can present another field.
true
if a message iterator is ready to present another field. false
if the iterator has presented the last field (and has not been reset).e | The exception object captures information about failures. |
messageIterator | The call checks this iterator. |
TIB_API void tibMessageIterator_Reset | ( | tibEx | e, |
tibMessageIterator | messageIterator | ||
) |
Reset a message iterator object.
This call resets a message iterator to the beginning of its message (that is, the first field of the message).
e | The exception object captures information about failures. |
messageIterator | The call resets this message iterator. |