OpenMAMA
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
dictionary.h File Reference
#include "mama/types.h"
#include "mama/fielddesc.h"

Go to the source code of this file.

Data Structures

struct  mamaDictionaryCallbackSet
 A structure containing the callbacks for dictionary creation. More...
 

Typedefs

typedef void(MAMACALLTYPE * mamaDictionary_completeCallback )(mamaDictionary, void *)
 The mamaDictionary class maps field identifiers (FIDs) to human readable strings. More...
 
typedef void(MAMACALLTYPE * mamaDictionary_timeoutCallback )(mamaDictionary, void *)
 
typedef void(MAMACALLTYPE * mamaDictionary_errorCallback )(mamaDictionary, const char *, void *)
 
typedef struct
mamaDictionaryCallbackSet 
mamaDictionaryCallbackSet
 A structure containing the callbacks for dictionary creation. More...
 

Functions

MAMAExpDLL mama_status mama_createDictionary (mamaDictionary *dictionary, mamaQueue queue, mamaDictionaryCallbackSet dictionaryCallbacks, mamaSource source, double timeout, int retries, void *closure)
 Create a data dictionary from a subscription. More...
 
MAMAExpDLL mama_status mamaDictionary_create (mamaDictionary *dictionary)
 Create an empty mamaDictionary so that can be populated at a later stage via a call to buildDictionaryFromMessage () or populated manually via calls to addFieldDescriptor () More...
 
MAMAExpDLL mama_status mamaDictionary_destroy (mamaDictionary dictionary)
 Destroy this mamaDictionary object and free all its resources. More...
 
MAMAExpDLL mama_status mamaDictionary_getFeedName (mamaDictionary dictionary, const char **result)
 Return the dictionary source feed name. More...
 
MAMAExpDLL mama_status mamaDictionary_getFeedHost (mamaDictionary dictionary, const char **result)
 Return the dictionary source feed host. More...
 
MAMAExpDLL mama_status mamaDictionary_getFieldDescriptorByFid (mamaDictionary dictionary, mamaFieldDescriptor *result, mama_fid_t fid)
 Return the mamaFieldDescriptor with the specified field FID. More...
 
MAMAExpDLL mama_status mamaDictionary_getFieldDescriptorByIndex (mamaDictionary dictionary, mamaFieldDescriptor *result, unsigned short index)
 Return the field with the corresponding zero based index. More...
 
MAMAExpDLL mama_status mamaDictionary_getFieldDescriptorByName (mamaDictionary dictionary, mamaFieldDescriptor *result, const char *fname)
 Return the descriptor of the field with the specified name. More...
 
MAMAExpDLL mama_status mamaDictionary_getFieldDescriptorByNameAll (mamaDictionary dictionary, const char *fname, mamaFieldDescriptor *descList, size_t *size)
 Return an array of mamaFieldDescriptor which includes every field in the dictionary with the specified name. More...
 
MAMAExpDLL mama_status mamaDictionary_getMaxFid (mamaDictionary dictionary, mama_fid_t *value)
 Return the highest field identifier. More...
 
MAMAExpDLL mama_status mamaDictionary_getSize (mamaDictionary dictionary, size_t *value)
 Return the number of fields in the dictionary. More...
 
MAMAExpDLL mama_status mamaDictionary_hasDuplicates (mamaDictionary dictionary, int *value)
 Return true if there are multiple fields with the same name. More...
 
MAMAExpDLL mama_status mamaDictionary_buildDictionaryFromMessage (mamaDictionary dictionary, const mamaMsg msg)
 Build a data dictionary from the specified message. More...
 
MAMAExpDLL mama_status mamaDictionary_getDictionaryMessage (mamaDictionary dictionary, mamaMsg *msg)
 Get the underlying message for the data dictionary. More...
 
MAMAExpDLL mama_status mamaDictionary_createFieldDescriptor (mamaDictionary dictionary, mama_fid_t fid, const char *name, mamaFieldType type, mamaFieldDescriptor *descriptor)
 Create a new field descriptor and add it to the dictionary. More...
 
MAMAExpDLL mama_status mamaDictionary_setMaxFid (mamaDictionary dictionary, mama_size_t maxFid)
 Tell the dictionary what the probable maximum fid in the data dictionary may be. More...
 
MAMAExpDLL mama_status mamaDictionary_writeToFile (mamaDictionary dictionary, const char *fileName)
 Write the data dictionary to a file. More...
 
MAMAExpDLL mama_status mamaDictionary_populateFromFile (mamaDictionary dictionary, const char *fileName)
 Populate a dictionary from the contents of a file. More...
 

Typedef Documentation

typedef void(MAMACALLTYPE * mamaDictionary_completeCallback)(mamaDictionary, void *)

The mamaDictionary class maps field identifiers (FIDs) to human readable strings.

Any incoming mamaMsg might contain FIDs but no field names. The dictionary allows applications to determine the name associated with a given FID. Typedefs for the dictionary callbacks.

  • mamaDictionary_setErrorCallback ()
  • mamaDictionary_setCompleteCallback ()
  • mamaDictionary_setTimeoutCallback ()
typedef void(MAMACALLTYPE * mamaDictionary_timeoutCallback)(mamaDictionary, void *)
typedef void(MAMACALLTYPE * mamaDictionary_errorCallback)(mamaDictionary, const char *, void *)

A structure containing the callbacks for dictionary creation.

Function Documentation

MAMAExpDLL mama_status mama_createDictionary ( mamaDictionary dictionary,
mamaQueue  queue,
mamaDictionaryCallbackSet  dictionaryCallbacks,
mamaSource  source,
double  timeout,
int  retries,
void closure 
)

Create a data dictionary from a subscription.

Parameters
dictionaryA pointer for the dictionary being created.
queueThe mama queue.
dictionaryCallbacksA mamaDictionaryCallbackSet with the callbacks for completion, errors and timeouts.
sourceThe mamaSource identifying the source of the dictionary.
timeoutthe timeout
retriesnumber of retries
closureA user supplied value passed to the callbacks.
MAMAExpDLL mama_status mamaDictionary_create ( mamaDictionary dictionary)

Create an empty mamaDictionary so that can be populated at a later stage via a call to buildDictionaryFromMessage () or populated manually via calls to addFieldDescriptor ()

Parameters
dictionaryThe address to where the dictionary will be written
MAMAExpDLL mama_status mamaDictionary_destroy ( mamaDictionary  dictionary)

Destroy this mamaDictionary object and free all its resources.

Parameters
dictionaryThe dictionary.
MAMAExpDLL mama_status mamaDictionary_getFeedName ( mamaDictionary  dictionary,
const char **  result 
)

Return the dictionary source feed name.

Parameters
dictionaryThe dictionary.
result(out) points to the feed name
MAMAExpDLL mama_status mamaDictionary_getFeedHost ( mamaDictionary  dictionary,
const char **  result 
)

Return the dictionary source feed host.

Parameters
dictionaryThe dictionary.
result(out) points to the feed host
MAMAExpDLL mama_status mamaDictionary_getFieldDescriptorByFid ( mamaDictionary  dictionary,
mamaFieldDescriptor result,
mama_fid_t  fid 
)

Return the mamaFieldDescriptor with the specified field FID.

This method is very efficient (constant time).

Parameters
dictionaryThe dictionary.
fidThe field id.
result(out) points to the mamaFieldDescriptor (not a copy)
MAMAExpDLL mama_status mamaDictionary_getFieldDescriptorByIndex ( mamaDictionary  dictionary,
mamaFieldDescriptor result,
unsigned short  index 
)

Return the field with the corresponding zero based index.

This method is O (N) with respect to the size of the dictionary.

Parameters
dictionaryThe dictionary.
indexThe zero-based index.
resultThe result.
MAMAExpDLL mama_status mamaDictionary_getFieldDescriptorByName ( mamaDictionary  dictionary,
mamaFieldDescriptor result,
const char *  fname 
)

Return the descriptor of the field with the specified name.

If there is more than one field with the same name, the one with the lowest field id is returned.

Parameters
dictionaryThe dictionary.
resultthe result * or NULL if no such field
fnameThe name of the field to search for.
MAMAExpDLL mama_status mamaDictionary_getFieldDescriptorByNameAll ( mamaDictionary  dictionary,
const char *  fname,
mamaFieldDescriptor descList,
size_t *  size 
)

Return an array of mamaFieldDescriptor which includes every field in the dictionary with the specified name.

The caller is responsible for allocating descList with room enough for all possible duplicate fields (use mamaDictionary_getSize () to be safe).

Parameters
dictionaryThe dictionary.
fname(in) The name to search dictionary for.
descList(out) An array of mamaFieldDescriptor objects, which are not copies and should not be destroyed by the caller.
size(out) The final number of entries in descList. The value should be intialised to the size allocated to decList. This will be modified to the actual number found on return, or will return once this value has been found.
MAMAExpDLL mama_status mamaDictionary_getMaxFid ( mamaDictionary  dictionary,
mama_fid_t value 
)

Return the highest field identifier.

Parameters
dictionaryThe dictionary.
valueA pointer that will contain highest FID.
MAMAExpDLL mama_status mamaDictionary_getSize ( mamaDictionary  dictionary,
size_t *  value 
)

Return the number of fields in the dictionary.

Parameters
dictionaryThe dictionary.
valueThe number of entries in the dictionary.
MAMAExpDLL mama_status mamaDictionary_hasDuplicates ( mamaDictionary  dictionary,
int *  value 
)

Return true if there are multiple fields with the same name.

Parameters
dictionaryThe dictionary.
value1 if there are duplicates, 0 otherwise.
MAMAExpDLL mama_status mamaDictionary_buildDictionaryFromMessage ( mamaDictionary  dictionary,
const mamaMsg  msg 
)

Build a data dictionary from the specified message.

Parameters
dictionaryThe dictionary
msgA mamaMsg representing the contents of a data dictionary.
MAMAExpDLL mama_status mamaDictionary_getDictionaryMessage ( mamaDictionary  dictionary,
mamaMsg msg 
)

Get the underlying message for the data dictionary.

A new message instance is created each time this function is called. It is the responsibility for the caller to destroy the message when no longer required.

Parameters
dictionaryThe Dictionary
msgThe address of the mamaMsg where the result is to be written
MAMAExpDLL mama_status mamaDictionary_createFieldDescriptor ( mamaDictionary  dictionary,
mama_fid_t  fid,
const char *  name,
mamaFieldType  type,
mamaFieldDescriptor descriptor 
)

Create a new field descriptor and add it to the dictionary.

New fields can be added to an existing dictionary obtained from the MAMA infrastructure. This function can also be used to manually populate a new data dictionary.

Parameters
dictionaryThe dictionary to which the field is to be added.
fidThe fid for the new field descriptor.
nameThe name for the new field descriptor.
typeThe type for the new field descriptor.
descriptorThe newly created fieldDescriptor. NULL can be specified.
MAMAExpDLL mama_status mamaDictionary_setMaxFid ( mamaDictionary  dictionary,
mama_size_t  maxFid 
)

Tell the dictionary what the probable maximum fid in the data dictionary may be.

This is not necessary but will aid performance for manually creating a new dictionary or adding new fields to an existing dictionary.

Calling this function ensures that there is capacity in the dictionary for field descriptors with fids up to the max specified.

Fields with fids greater than specified can be added to the dictionary but this will incur the overhead of allocating more memory and copying dictionary elements.

Parameters
dictionaryThe mamaDictionary.
maxFidThe probable maximum fid being added to the dictionary.
MAMAExpDLL mama_status mamaDictionary_writeToFile ( mamaDictionary  dictionary,
const char *  fileName 
)

Write the data dictionary to a file.

The dictionary will be written in the form: fid|fieldName|fieldType

Parameters
dictionaryThe dictionary to serialize.
fileNameThe name of the file to serialize the dictionary to. This can be a fully qualified name, relative or a file on the $WOMBAT_PATH
MAMAExpDLL mama_status mamaDictionary_populateFromFile ( mamaDictionary  dictionary,
const char *  fileName 
)

Populate a dictionary from the contents of a file.

Can be used to add additional fields to an existing dictionary or to populate a new dictionary.

Parameters
dictionaryThe dictionary to populate.
fileNameThe file from which to populate the dictionary. This can be a fully qualified name, relative or a file on the $WOMBAT_PATH


© 2012 Linux Foundation