TIBCO FTL®

Typedefs | Functions
fldref.h File Reference

Field references enable efficiency gains when accessing message fields. More...

## Typedefs
typedef struct __tibFieldRef * | tibFieldRef
| Field reference object type. More...

## Functions
TIB_API tibFieldRef | tibFieldRef_Create (tibEx e, const char *fieldName)
| Create a field reference object. More...
TIB_API void | tibFieldRef_Destroy (tibEx e, tibFieldRef f)
| Destroy a field reference object. More...
TIB_API const char * | tibFieldRef_GetFieldName (tibEx e, tibFieldRef f)
| Get the field name from a field reference object. More...

## Detailed Description

Field references enable efficiency gains when accessing message fields.

This file defines field reference objects and the calls that manipulate them.

## Typedef Documentation

## ◆ tibFieldRef

typedef struct __tibFieldRef* tibFieldRef

Field reference object type.

The API provides two versions of each message field accessor call – one accepts a field name, while the other accepts a field reference object (tibFieldRef). Access by field reference is more efficient than access by name alone.

Field reference objects contain a field name, along with internal information that enables efficient access.

Programs can repeatedly use a field reference object to efficiently access a field – even across messages of different formats.

For example, if formats `A` and `B` both have a field named `foo`, then a field reference object with field name `foo` accesses the correct field in messages of either format.

Field reference objects are thread-safe. (However, the field reference that tibMessageIterator_GetNext returns is an exception to this rule.)

## Function Documentation

## ◆ tibFieldRef_Create()

TIB_API tibFieldRef tibFieldRef_Create | ( | tibEx | e,
|  | const char * | fieldName
| ) |  |

Create a field reference object.

This call uses its field name argument to look up internal information that enables efficient access, and caches that information in the new field reference object.

Parameters

  e | The exception object captures information about failures.
  fieldName | The call embeds this field name in the new field reference object.

Returns
  a new tibFieldRef object

## ◆ tibFieldRef_Destroy()

TIB_API void tibFieldRef_Destroy | ( | tibEx | e,
|  | tibFieldRef | f
| ) |  |

Destroy a field reference object.

Destroying a field reference object frees all resources associated with the field reference.

It is illegal to destroy a field reference object obtained from tibMessageIterator_GetNext.

Parameters

  e | The exception object captures information about failures.
  f | The call destroys this field reference object.

Returns
  void

## ◆ tibFieldRef_GetFieldName()

TIB_API const char * tibFieldRef_GetFieldName | ( | tibEx | e,
|  | tibFieldRef | f
| ) |  |

Get the field name from a field reference object.

The name that this call returns becomes invalid when the field reference object becomes invalid.

Parameters

  e | The exception object captures information about failures.
  f | The call returns the name from this field reference object.

Returns
  the field name of the reference