EvmVarGet(3)

NAME

EvmVarGet(), EvmVarGetOpaque(), EvmVarGetString(), EvmVarGetType(), EvmVarGetXxx(), EvmVarListFree(), EvmVarListGet(), EvmVarRelease(), EvmVarSet(), EvmVarSetOpaque(), EvmVarSetStringI18N(), EvmVarSetXxx() — manipulate event variables

SYNOPSIS

#include

EvmStatus_t   

EvmStatus_t    

EvmStatus_t    

EvmStatus_t   

EvmStatus_t   

EvmStatus_t 

EvmStatus_t   

EvmStatus_t 

EvmStatus_t      

EvmStatus_t    

EvmStatus_t    

EvmStatus_t   

<evm/evm.h> EvmVarGet( EvmEvent_t event, EvmVarName_t v_name, EvmVarStruct_t *var ); EvmVarGetOpaque( EvmEvent_t event, EvmVarName_t v_name, EvmOpaque_t *item_value, EvmSize_t *size ); EvmVarGetString( EvmEvent_t event, EvmVarName_t v_name, EvmString_t *item_value, EvmI18NMsgId_t *msg_id ); EvmVarGetType( EvmEvent_t event, EvmVarName_t v_name, EvmVarType_t *type ); EvmVarGetXxx( EvmEvent_t event, EvmVarName_t v_name, evm_type *item_value ); EvmVarListFree( EvmVarList_t varlist ); EvmVarListGet( EvmEvent_t event, EvmCount_t *var_count, EvmVarList_t *varList ); EvmVarRelease( EvmVarStruct_t *var ); EvmVarSet( EvmEvent_t event, EvmVarName_t v_name, EvmVarType_t type, EvmVarValue_t item_value, EvmI18NMsgId_t msg_id, EvmSize_t size ); EvmVarSetOpaque( EvmEvent_t event, EvmVarName_t v_name, const EvmOpaque_t item_value, EvmSize_t size ); EvmVarSetStringI18N( EvmEvent_t event, EvmVarName_t v_name, const EvmString_t item_value, EvmI18NMsgId_t msg_id ); EvmVarSetXxx( EvmEvent_t event, EvmVarName_t v_name, const evm_type item_value );

Library

EVM Support Library (libevm.so).

Parameters

event

The event to be processed.

v_name

The name of a variable in the event for which data is to be set or obtained.

For EvmVarSet(), if the named variable exists, the associated data is modified. If the variable does not exist, it is created and added to the event. The value to be stored is passed in item_value.

type

The enumeration constant for the type of the item_value to be stored in the variable indicated by v_name. Possible values for this field are:

EvmTYPE_BOOLEAN
EvmTYPE_CHAR
EvmTYPE_INT16
EvmTYPE_INT32
EvmTYPE_INT64
EvmTYPE_UINT8
EvmTYPE_UINT16
EvmTYPE_UINT32
EvmTYPE_UINT64
EvmTYPE_FLOAT
EvmTYPE_DOUBLE
EvmTYPE_STRING
EvmTYPE_OPAQUE

For EvmVarGetType(), the type operand is a returned value.

item_value

The value to be stored in the variable indicated by v_name.

msg_id

For a string variable being set in an internationalized event, msg_id may contain an I18N (internationalization) message identifier corresponding to the value of the variable. The identifier must refer to a message in the catalog and message set associated with the event (see the EvmItemSet(3) manpage).

The msg_id operand is ignored for variables whose type is not EvmTYPE_STRING.

size

The size of the associated item_value in bytes. The caller must specify the correct size when setting a variable of type EvmTYPE_OPAQUE. For all other variable types, the size is ignored.

var

For the EvmVarGet() routine, this is a pointer to the location where the output data is to be stored.

For the EvmVarRelease() routine, this is a pointer to the storage space to be released.

var_count

This is the number of names in the var_list obtained by EvmVarListGet(), not including the terminating NULL pointer.

varlist

On return from the EvmVarListGet() routine, this is a list of pointers to the names of the variables associated with the event. The last item in the list is a NULL pointer.

For the EvmVarListFree() routine, this is a list of names of variables for which memory should be freed. The list must be terminated by a NULL pointer.

DESCRIPTION

The EvmVarSet() routine sets the value of a variable data item, indicated by v_name, in an event. This routine is used both for adding a variable and for altering its value. If the v_name variable is not already present in the event, it is added.

The EvmVarSetXxx(), EvmVarSetStringI18N(), and EvmVarSetOpaque() routines offer a simpler means of setting a variable than the generic EvmVarSet() routine. Using these routines, a single call can set a variable of any type. To use these routines, replace the Xxx() in the routine name with the required type name, and supply a value of the corresponding type as the item_value operand. The following types are supported:

Boolean, Char, Int16, Int32, Int64, Uint8, Uint16, Uint32, Uint64, Float, Double, String.

Use EvmVarSetStringI18N() to set a string variable with a non-zero I18N message-ID. Use EvmVarSetOpaque() to set an opaque variable. Each of these routines requires one more operand than the others in this group.

The EvmVarGet() routine returns the event variable indicated by v_name in the var variable. The caller must free any space used by the variable by calling EvmVarRelease().

The EvmVarGetType() routine returns the type of the named variable.

The EvmVarGetXxx(), EvmVarGetString(), and EvmVarGetOpaque() routines offer a simpler means of retrieving a variable value than the generic EvmVarGet() routine. These routines can retrieve a variable of a specific type with a single call. To use these routines, replace the Xxx() in the routine name with the required type name, and supply a pointer to a location of the corresponding type as the item_value pointer. Refer to the description of EvmVarSetXxx() above for details of the supported types.

Use EvmVarGetString() to retrieve a string variable, specifying NULL for the msg_id operand if you do not want to receive an I18N message-ID. Use EvmVarGetOpaque() to retrieve an opaque variable. Each of these routines requires one more operand than the others in this group.

Note that EvmVarGetString() and EvmVarGetOpaque() return their variable values in heap memory. Use free() to free this space when it is no longer needed.

The EvmVarRelease() routine releases any storage space allocated when the specified var was retrieved from an event using EvmVarGet(). It is important that this routine is called when the variable is no longer needed to ensure that all memory associated with the variable is released. Do not use this routine to release variables retrieved with any of the EvmVarGetXxx() routines.

The EvmVarListGet() routine returns, in the varList reference argument, a pointer to an array of pointers to names of all the variables contained in the event. The last entry in the array is a NULL pointer. The var_count argument receives the number of names in the list, not counting the terminating null value. The caller must free the memory used by the list by calling EvmVarListFree().

The EvmVarListFree() routine frees the memory used by a variable list (varList).

Notes

The caller must specify the size when adding an opaque variable to an event.

To avoid memory leakage, memory that is supplied to the caller from API routines must be freed with the appropriate routine.

RETURN VALUE

EvmERROR_NONE: The operation completed without error.
EvmERROR_INVALID_ARGUMENT: One of the arguments to the function is invalid.
EvmERROR_INVALID_VALUE: A value in a structure member is invalid.
EvmERROR_NO_MEMORY: An operation failed because an attempt to acquire heap memory failed.
EvmERROR_NOT_PRESENT: A request specified an item or variable name component in an itemList or a varList that is not part of the event being processed.

ERRORS

The value of errno is not set.

EvmVarGet(3)

Technical documentation

» Table of Contents

» Index