NAME

EvmItemSet, EvmItemSetVa, EvmItemGet, EvmItemRelease, EvmItemListGet, EvmItemListFree − Create and manipulate event items

SYNOPSIS

#include <evm/evm.h>
EvmStatus_t EvmItemSet(
        EvmEvent_t event,
        EvmItemId_t item_id,
        EvmItemValue_t item_value ); EvmStatus_t EvmItemSetVa(
        EvmEvent_t event,
        [EvmItemId_t  item_id,
        EvmItemValue_t item_value]...,
        EvmITEM_NONE ); EvmStatus_t EvmItemGet(
        EvmEvent_t event,
        EvmItemId_t item_id,
        EvmItemValue_t ∗item_value ); EvmStatus_t EvmItemRelease(
        EvmItemId_t item_id,
        EvmItemValue_t item_value ); EvmStatus_t EvmItemListGet(
        EvmEvent_t event,
        EvmCount_t ∗item_count,
        EvmItemList_t ∗itemList ); void EvmItemListFree(
        EvmItemList_t itemList );

OPERANDS

event
The event containing the item to be manipulated.

item_id
The identifier for the event data item to be set, obtained, or released by the called routine. Possible values for this operand, and the data contained by the data item are identified in the following list. See the EvmEvent(5) reference page for a description of the event data items. 

It is also possible to supply a separate item_id for each of the supported variable types. In these cases, an extra one or two operands (depending on the type) must be supplied in addition to the item_value. See the description below for more information.  The following extended variable item IDs are supported:

item_value
The value to be stored into the item indicated by the associated item_id. For EvmItemGet() this is the location where the value extracted from the event will be stored. 

item_count
This is the return operand. It is the number of entries in item_list, exclusive of the terminating EvmItem_NONE entry. 

DESCRIPTION

Routines in this reference page deal with manipulating data in the standard items in an event. 

The EvmItemSet() routine sets the value of the event data item specified by item_id to the item_value supplied by the caller. 

The EvmItemSetVa() routine sets item values in the event. The list of item_id and item_value operands is terminated by an instance of item_id of EvmITEM_NONE. 

The inclusion of extended variable item-IDs simplifies programming by allowing you to add variable items to an event without first having to set up an EvmVarStruct_t structure, or to release it afterwards.  If you use these extended item-IDs you must follow each with the name of the variable, then a value of the appropriate type. In addition, an EvmITEM_VAR_STRING_I18N value must be followed by an I18N message ID, and an EvmITEM_VAR_OPAQUE value must be followed by a size. 

The EvmItemGet() routine returns, in the item_value reference argument, the value of the event data item specified by item_id.  The caller must use EvmItemRelease() to free any space allocated for the item. 

The EvmItemRelease() routine releases any storage space that was allocated when the data item named by item_id was retrieved from an event using EvmItemGet().

The EvmItemListGet() routine returns, in the itemList reference argument, a list of all of the items, which are currently defined for the event. The last item in the list has an item_id value of EvmITEM_NONE. The number of items in the list, not including the terminating null identifier,  is returned in item_count. The caller is responsible for freeing the memory used by the list by calling EvmItemListFree(). 

The EvmItemListFree() routine frees the memory used by an item list. The itemList operand is a list of items in an event generated by EvmItemListGet(). 

RESTRICTIONS

None

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

Commands: evmshow(1)

Routines: EvmEventCreate(3), EvmEventDestroy(3), EvmEventFormat(3), EvmEventPost(3)

Files: kevm(7)

Event Management: EVM(5)

EVM Events: EvmEvent(5)

Programmer’s Guide