 |
Index for
Section 3 |
|
 |
Alphabetical
listing for E |
|
 |
Bottom of
page |
|
EvmVarSet(3)
NAME
EvmVarSet, EvmVarSetXxx, EvmVarSetStringI18N, EvmVarSetOpaque, EvmVarGet,
EvmVarGetType, EvmVarGetXxx, EvmVarGetString, EvmVarGetOpaque,
EvmVarRelease, EvmVarListGet, EvmVarListFree - Manipulate event variables
SYNOPSIS
#include <evm/evm.h>
EvmStatus_t EvmVarSet(
EvmEvent_t event,
EvmVarName_t v_name,
EvmVarType_t type,
EvmVarValue_t item_value,
EvmI18NMsgId_t msg_id,
EvmSize_t size );
EvmStatus_t EvmVarSetXxx(
EvmEvent_t event,
EvmVarName_t v_name,
const evm_type item_value );
EvmStatus_t EvmVarSetStringI18N(
EvmEvent_t event,
EvmVarName_t v_name,
const EvmString_t item_value,
EvmI18NMsgId_t msg_id );
EvmStatus_t EvmVarSetOpaque(
EvmEvent_t event,
EvmVarName_t v_name,
const EvmOpaque_t item_value,
EvmSize_t size );
EvmStatus_t EvmVarGet(
EvmEvent_t event,
EvmVarName_t v_name,
EvmVarStruct_t *var );
EvmStatus_t EvmVarGetType(
EvmEvent_t event,
EvmVarName_t v_name,
EvmVarType_t *type );
EvmStatus_t EvmVarGetXxx(
EvmEvent_t event,
EvmVarName_t v_name,
evm_type *item_value );
EvmStatus_t EvmVarGetString(
EvmEvent_t event,
EvmVarName_t v_name,
EvmString_t *item_value,
EvmI18NMsgId_t *msg_id );
EvmStatus_t EvmVarGetOpaque(
EvmEvent_t event,
EvmVarName_t v_name,
EvmOpaque_t *item_value,
EvmSize_t *size );
EvmStatus_t EvmVarRelease(
EvmVarStruct_t *var );
EvmStatus_t EvmVarListGet(
EvmEvent_t event,
EvmCount_t *var_count,
EvmVarList_t *varList );
EvmStatus_t EvmVarListFree(
EvmVarList_t varlist );
OPERANDS
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(), this 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, this
argument may contain an I18N 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) reference page). This 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, you can set a variable of any type with a
single call. To use them, 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, and 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. Using these routines, you can retrieve a variable of a specific
type with a single call. To use them, 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. You must use free() to free this space when you have
finished with it.
The EvmVarRelease() routine releases any storage space that was 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.
You must 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.
RESTRICTIONS
To avoid memory leakage, memory that is supplied to the caller from API
routines must be freed with the appropriate routine.
RETURN VALUES
EvmERROR_NONE
The operation was completed without error.
EvmERROR_INVALID_ARGUMENT
One of the arguments to the function was 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
None
LIBRARY
EVM Support Library (libevm.so, libevm.a)
FILES
None
SEE ALSO
Files: kevm(7)
Event Management: EVM(5)
EVM Events: EvmEvent(5)
Programmer's Guide
|
Index for
Section 3 |
|
|
Alphabetical
listing for E |
|
 |
Top of
page |
|