TIBCO FTL®

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

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:

1. Create an array you think is big enough.
2. Call tibMessage_WriteToByteArray.
3. 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:

1. Create an array you think is big enough.
2. Call tibMessage_WriteToPortableByteArray.
3. 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