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