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 tibint32_t	tibMessage_GetFieldCount (tibEx e, tibMessage message)
	Get the number of fields from message's format. 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 tibuint64_t	tibMessage_GetStoreLocalMessageId (tibEx e, tibMessage message)
	Get the store local message id as assigned by the persistence service. 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...

Detailed Description

Message objects contain fields with values.

This file defines message objects, message fields, message iterators, and calls that manipulate them.

Accessors by Name and Field Reference

tibFieldRef

Message Iterators

tibMessageIterator

Macro Definition Documentation

◆ TIB_BUILTIN_MSG_FMT_KEY_FIELDNAME

#define TIB_BUILTIN_MSG_FMT_KEY_FIELDNAME "_key"

Built-in field name of the key field in a keyed opaque message.

◆ TIB_BUILTIN_MSG_FMT_KEY_MAXLEN

#define TIB_BUILTIN_MSG_FMT_KEY_MAXLEN (255)

Maximum length (in bytes) of the key field of a keyed opaque message.

◆ TIB_BUILTIN_MSG_FMT_KEYED_OPAQUE

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

◆ TIB_BUILTIN_MSG_FMT_OPAQUE

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

◆ TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME

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

◆ TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE

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

◆ TIB_MSG_FIELDS_FINGERPRINT_SIZE

#define TIB_MSG_FIELDS_FINGERPRINT_SIZE 20

Size in bytes of a message field fingerprint.

See also: tibMessage_GetFieldsFingerprint

Typedef Documentation

◆ tibMessage

typedef struct __tibMessage* tibMessage

Message object type.

Message objects are not thread-safe. Programs must not access a message from several threads simultaneously.

◆ tibMessageIterator

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.

Enumeration Type Documentation

◆ tibFieldType

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 `TIB_FIELD_TYPE_UNKNOWN` to indicate that the field's type is not defined. For example, getting the field type for a NULL message returns this value. It is not legal for programs to supply `TIB_FIELD_TYPE_UNKNOWN` to any API call except tibFieldType_GetAsString.

Function Documentation

◆ tibFieldType_GetAsString()

TIB_API const char * tibFieldType_GetAsString	(	tibEx	e,
		tibFieldType	fieldType
	)

Return a string that represents a field type.

Parameters

e	The exception object captures information about failures.
fieldType	The call converts this type to a string.

Returns: a string corresponding the fieldType argument

See also: tibFieldType

◆ tibMessage_Acknowledge()

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

Parameters

e	The exception object captures information about failures.
message	The call acknowledges receiving this message.

Returns: void

See also: TIB_SUBSCRIBER_PROPERTY_BOOL_EXPLICIT_ACK

◆ tibMessage_ClearAllFields()

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.

Parameters

e	The exception object captures information about failures.
message	The call clears all fields in this message.

Returns: void

◆ tibMessage_ClearField()

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.

Parameters

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.

Returns: void

See also: tibMessage_ClearFieldByRef

◆ tibMessage_ClearFieldByRef()

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.

Parameters

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.

Returns: void

See also: tibMessage_ClearField

◆ tibMessage_Create()

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.

Parameters

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

Returns: a new message object

See also: TIB_BUILTIN_MSG_FMT_OPAQUE (as formatName argument)

◆ tibMessage_Destroy()

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.

Parameters

e	The exception object captures information about failures.
message	The call destroys this message object.

Returns: void

◆ tibMessage_GetArray()

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*

Parameters

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.

Returns: void*
The program must cast this return value to the appropriate pointer type (see the table above).

See also: tibMessage_GetArrayByRef

◆ tibMessage_GetArrayByRef()

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*

Parameters

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.

Returns: void* The program must cast this return value to the appropriate pointer type (see the table above).

See also: tibMessage_GetArray

◆ tibMessage_GetDateTime()

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.

Parameters

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.

Returns: tibDateTime

See also: tibMessage_GetDateTimeByRef

◆ tibMessage_GetDateTimeByRef()

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.

Parameters

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.

Returns: tibDateTime

See also: tibMessage_GetDateTime

◆ tibMessage_GetDeliveryCount()

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 service has delivered the message from a standard or 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.

Parameters

e	The exception object captures information about failures.
message	The call gets the delivery count for this message.

Returns: the delivery count

◆ tibMessage_GetDouble()

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.

Parameters

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.

Returns: a double floating-point value

See also: tibMessage_GetDoubleByRef

◆ tibMessage_GetDoubleByRef()

TIB_API tibdouble_t tibMessage_GetDoubleByRef	(	tibEx	e,
		tibMessage	message,
		tibFieldRef	fieldRef
	)

Get the value of a double floating-point field from a message.

Parameters

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.

Returns: a double floating-point value

See also: tibMessage_GetDouble

◆ tibMessage_GetFieldCount()

TIB_API tibint32_t tibMessage_GetFieldCount	(	tibEx	e,
		tibMessage	message
	)

Get the number of fields from message's format.

This returns the number of fields from the message's format.

Parameters

e	The exception object captures information about failures.
message	The call gets the number of fields from the messages's format.

Returns: the number of fields from the message's format.

◆ tibMessage_GetFieldsFingerprint()

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.

Parameters

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.

See also: TIB_MSG_FIELDS_FINGERPRINT_SIZE

◆ tibMessage_GetFieldType()

TIB_API tibFieldType tibMessage_GetFieldType	(	tibEx	e,
		tibMessage	message,
		const char *	name
	)

Get the type of a field within a message.

Parameters

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.

Returns: the type of the field

◆ tibMessage_GetFieldTypeByRef()

TIB_API tibFieldType tibMessage_GetFieldTypeByRef	(	tibEx	e,
		tibMessage	message,
		tibFieldRef	fieldRef
	)

Get the type of a field within a message.

Parameters

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.

Returns: the type of the field

◆ tibMessage_GetInbox()

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.

Parameters

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.

Returns: tibInbox

See also: tibMessage_GetInboxByRef

◆ tibMessage_GetInboxByRef()

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.

Parameters

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.

Returns: tibInbox

See also: tibMessage_GetInbox

◆ tibMessage_GetLong()

TIB_API tibint64_t tibMessage_GetLong	(	tibEx	e,
		tibMessage	message,
		const char *	name
	)

Get the value of a long field from a message.

Parameters

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.

Returns: a 64-bit integer value

See also: tibMessage_GetLongByRef

◆ tibMessage_GetLongByRef()

TIB_API tibint64_t tibMessage_GetLongByRef	(	tibEx	e,
		tibMessage	message,
		tibFieldRef	fieldRef
	)

Get the value of a long field from a message.

Parameters

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.

Returns: a 64-bit integer value

See also: tibMessage_GetLong

◆ tibMessage_GetMessage()

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.

Parameters

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.

Returns: tibMessage

See also: tibMessage_GetMessageByRef

◆ tibMessage_GetMessageByRef()

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.

Parameters

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.

Returns: tibMessage

See also: tibMessage_GetMessage

◆ tibMessage_GetOpaque()

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.

Parameters

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.

Returns: a read-only pointer to opaque data

See also: tibMessage_GetOpaqueByRef

◆ tibMessage_GetOpaqueByRef()

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.

Parameters

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.

Returns: a read-only pointer to opaque data

See also: tibMessage_GetOpaque

◆ tibMessage_GetStoreLocalMessageId()

TIB_API tibuint64_t tibMessage_GetStoreLocalMessageId	(	tibEx	e,
		tibMessage	message
	)

Get the store local message id as assigned by the persistence service.

This message id is local to a persistence service cluster and also different depending on the store being replicated or non replicated.

Parameters

e	The exception object captures information about failures.
message	The call gets the store local message id for this message.

Returns: the store local message id.

◆ tibMessage_GetString()

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.

Parameters

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.

Returns: a pointer to the string field

See also: tibMessage_GetStringByRef

◆ tibMessage_GetStringByRef()

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.

Parameters

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.

Returns: a pointer to the string field

See also: tibMessage_GetString

◆ tibMessage_IsFieldSet()

TIB_API tibbool_t tibMessage_IsFieldSet	(	tibEx	e,
		tibMessage	message,
		const char *	name
	)

Determine whether a field is set in a message.

Parameters

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.

Returns: tibbool_t

See also: tibMessage_IsFieldSetByRef

◆ tibMessage_IsFieldSetByRef()

TIB_API tibbool_t tibMessage_IsFieldSetByRef	(	tibEx	e,
		tibMessage	message,
		tibFieldRef	fieldRef
	)

Determine whether a field is set in a message.

Parameters

e	The exception object captures information about failures.
message	The call checks in this message.
fieldRef	The call checks for this field.

Returns: tibbool_t

See also: tibMessage_IsFieldSet

◆ tibMessage_MutableCopy()

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.

Parameters

e	The exception object captures information about failures.
message	The call copies this source message.

Returns: a mutable message object

◆ tibMessage_ReadFromByteArray()

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.

Parameters

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

Returns: tibMessage a new message, equivalent to the byte-array representation

See also: tibMessage_WriteToByteArray; tibMessage_WriteToPortableByteArray

◆ tibMessage_SetArray()

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*

Parameters

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.

Returns: void

See also: tibMessage_SetArrayByRef

◆ tibMessage_SetArrayByRef()

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*

Parameters

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.

Returns: void

See also: tibMessage_SetArray

◆ tibMessage_SetDateTime()

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.

Parameters

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.

Returns: void

See also: tibMessage_SetDateTimeByRef

◆ tibMessage_SetDateTimeByRef()

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.

Parameters

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.

Returns: void

See also: tibMessage_SetDateTime

◆ tibMessage_SetDouble()

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.

Parameters

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.

Returns: void

See also: tibMessage_SetDoubleByRef

◆ tibMessage_SetDoubleByRef()

TIB_API void tibMessage_SetDoubleByRef	(	tibEx	e,
		tibMessage	message,
		tibFieldRef	fieldRef,
		tibdouble_t	value
	)

Set a double floating-point field in a mutable message.

Parameters

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.

Returns: void

See also: tibMessage_SetDouble

◆ tibMessage_SetInbox()

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

Parameters

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.

Returns: void

See also: tibSubscriber_CreateOnInbox; tibSubscriber_GetInbox; tibMessage_SetInboxByRef

◆ tibMessage_SetInboxByRef()

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

Parameters

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.

Returns: void

See also: tibSubscriber_CreateOnInbox; tibSubscriber_GetInbox; tibMessage_SetInbox

◆ tibMessage_SetLong()

TIB_API void tibMessage_SetLong	(	tibEx	e,
		tibMessage	message,
		const char *	name,
		tibint64_t	value
	)

Set a long integer field in a mutable message.

Parameters

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.

Returns: void

See also: tibMessage_SetLongByRef

◆ tibMessage_SetLongByRef()

TIB_API void tibMessage_SetLongByRef	(	tibEx	e,
		tibMessage	message,
		tibFieldRef	fieldRef,
		tibint64_t	value
	)

Set a long integer field in a mutable message.

Parameters

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.

Returns: void

See also: tibMessage_SetLong

◆ tibMessage_SetMessage()

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.

Parameters

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.

Returns: void

See also: tibMessage_SetMessageByRef

◆ tibMessage_SetMessageByRef()

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.

Parameters

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.

Returns: void

See also: tibMessage_SetMessage

◆ tibMessage_SetOpaque()

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.

Parameters

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.

Returns: void

See also: tibMessage_SetOpaqueByRef

◆ tibMessage_SetOpaqueByRef()

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.

Parameters

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.

Returns: void

See also: tibMessage_SetOpaque

◆ tibMessage_SetOpaqueDirect()

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

Parameters

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.

Returns: void

See also: tibMessage_SetOpaqueDirectByRef

◆ tibMessage_SetOpaqueDirectByRef()

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

Parameters

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.

Returns: void

See also: tibMessage_SetOpaqueDirect

◆ tibMessage_SetString()

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.

Parameters

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.

Returns: void

See also: tibMessage_SetStringByRef

◆ tibMessage_SetStringByRef()

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.

Parameters

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.

Returns: void

See also: tibMessage_SetString

◆ tibMessage_ToString()

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.

Parameters

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

Returns: the actual length of the description string, including terminating NULL character (in btyes)

◆ tibMessage_WriteToByteArray()

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:

Create an array you think is big enough.
Call tibMessage_WriteToByteArray.
If the returned size is bigger than your array, then call tibMessage_WriteToByteArray again with a larger array (at least the returned size).

Parameters

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

Returns: the actual size of the serialized representation (in bytes)

See also: tibMessage_WriteToPortableByteArray; tibMessage_ReadFromByteArray

◆ tibMessage_WriteToPortableByteArray()

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:

Create an array you think is big enough.
Call tibMessage_WriteToPortableByteArray.
If the returned size is bigger than your array, then call tibMessage_WriteToPortableByteArray again with a larger array (at least the returned size).

Parameters

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

Returns: the actual size of the serialized representation (in bytes)

See also: tibMessage_WriteToByteArray; tibMessage_ReadFromByteArray

◆ tibMessageIterator_Create()

TIB_API tibMessageIterator tibMessageIterator_Create	(	tibEx	e,
		tibMessage	message
	)

Create a message iterator object.

Parameters

e	The exception object captures information about failures.
message	The call initializes an iterator for the fields of this message.

Returns: a new message iterator object

See also: tibMessageIterator

◆ tibMessageIterator_Destroy()

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.

Parameters

e	The exception object captures information about failures.
messageIterator	The call destroys this message iterator object.

Returns: tibMessageIterator

◆ tibMessageIterator_GetNext()

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.

Parameters

e	The exception object captures information about failures.
messageIterator	The call advances this iterator to the next field.

Returns: a field reference to the next field

◆ tibMessageIterator_HasNext()

TIB_API tibbool_t tibMessageIterator_HasNext	(	tibEx	e,
		tibMessageIterator	messageIterator
	)

Determine whether a message iterator object can present another field.

This call returns true if a message iterator is ready to present another field.
This call returns false if the iterator has presented the last field (and has not been reset).

Parameters

e	The exception object captures information about failures.
messageIterator	The call checks this iterator.

Returns: tibbool_t

◆ tibMessageIterator_Reset()

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

Parameters

e	The exception object captures information about failures.
messageIterator	The call resets this message iterator.

Returns: void

Macros

Typedefs

Enumerations

Functions

Detailed Description

Accessors by Name and Field Reference

Message Iterators

Macro Definition Documentation

◆ TIB_BUILTIN_MSG_FMT_KEY_FIELDNAME

◆ TIB_BUILTIN_MSG_FMT_KEY_MAXLEN

◆ TIB_BUILTIN_MSG_FMT_KEYED_OPAQUE

◆ TIB_BUILTIN_MSG_FMT_OPAQUE

◆ TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME

◆ TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE

◆ TIB_MSG_FIELDS_FINGERPRINT_SIZE

Typedef Documentation

◆ tibMessage

◆ tibMessageIterator

Enumeration Type Documentation

◆ tibFieldType

Function Documentation

◆ tibFieldType_GetAsString()

◆ tibMessage_Acknowledge()

◆ tibMessage_ClearAllFields()

◆ tibMessage_ClearField()

◆ tibMessage_ClearFieldByRef()

◆ tibMessage_Create()

◆ tibMessage_Destroy()

◆ tibMessage_GetArray()

◆ tibMessage_GetArrayByRef()

◆ tibMessage_GetDateTime()

◆ tibMessage_GetDateTimeByRef()

◆ tibMessage_GetDeliveryCount()

◆ tibMessage_GetDouble()

◆ tibMessage_GetDoubleByRef()

◆ tibMessage_GetFieldCount()

◆ tibMessage_GetFieldsFingerprint()

◆ tibMessage_GetFieldType()

◆ tibMessage_GetFieldTypeByRef()

◆ tibMessage_GetInbox()

◆ tibMessage_GetInboxByRef()

◆ tibMessage_GetLong()

◆ tibMessage_GetLongByRef()

◆ tibMessage_GetMessage()

◆ tibMessage_GetMessageByRef()

◆ tibMessage_GetOpaque()

◆ tibMessage_GetOpaqueByRef()

◆ tibMessage_GetStoreLocalMessageId()

◆ tibMessage_GetString()

◆ tibMessage_GetStringByRef()

◆ tibMessage_IsFieldSet()

◆ tibMessage_IsFieldSetByRef()

◆ tibMessage_MutableCopy()

◆ tibMessage_ReadFromByteArray()

◆ tibMessage_SetArray()

◆ tibMessage_SetArrayByRef()

◆ tibMessage_SetDateTime()

◆ tibMessage_SetDateTimeByRef()

◆ tibMessage_SetDouble()

◆ tibMessage_SetDoubleByRef()

◆ tibMessage_SetInbox()

◆ tibMessage_SetInboxByRef()

◆ tibMessage_SetLong()

◆ tibMessage_SetLongByRef()

◆ tibMessage_SetMessage()

◆ tibMessage_SetMessageByRef()

◆ tibMessage_SetOpaque()

◆ tibMessage_SetOpaqueByRef()

◆ tibMessage_SetOpaqueDirect()

◆ tibMessage_SetOpaqueDirectByRef()

◆ tibMessage_SetString()

◆ tibMessage_SetStringByRef()

◆ tibMessage_ToString()

◆ tibMessage_WriteToByteArray()

◆ tibMessage_WriteToPortableByteArray()

◆ tibMessageIterator_Create()

◆ tibMessageIterator_Destroy()

◆ tibMessageIterator_GetNext()

◆ tibMessageIterator_HasNext()

◆ tibMessageIterator_Reset()