op_pk_fd_get()
Abstract
Obtains the value of a field in the specified packet; the field-of-interest is specified by a numeric index.
Syntax
op_pk_fd_get (pkptr, field_index, value_ptr)
| Argument | Type | Description |
|---|---|---|
pkptr |
Packet* |
pointer to the packet of interest. [A pointer to a packet can be obtained from many KPs, including op_pk_create(), op_pk_create_fmt(), op_pk_copy(), op_pk_get(), op_subq_pk_access(), and op_subq_pk_remove().] |
field_index |
int |
numeric index of the field-of-interest [This value must be non-negative.] |
value_ptr |
void* |
pointer to a variable to be filled in with the specified field’s value [This argument can accept a pointer to an integer, a double, a packet pointer, or any other data structure pointer. The data type of the argument pointer must match the data type of the specified field.] |
Return Type
Compcode
OPC_COMPCODE_FAILURE if the field is not obtained; OPC_COMPCODE_SUCCESS otherwise.
Example
{
/* variable declarations */
int i; double d; Packet *pkptr, *enc_pkptr; struct Custom_DS *ds_ptr;
/* obtain an arriving packet */
pkptr = op_pk_get (0);
/* obtain the simple field types */
op_pk_fd_get (pkptr, 0, &i);
op_pk_fd_get (pkptr, 1, &d);
printf ("packet contents: integer (%d), double (%g)\n", i, d);
/* decapsulate a higher-level packet from the arriving packet */
op_pk_fd_get (pkptr, 2, &enc_pkptr);
op_pk_print (enc_pkptr);
/* extract a data structure from a packet field */
op_pk_fd_get (pkptr, 3, &ds_ptr);
op_pk_destroy (pkptr);
}
Details
This KP supports value access for all five types of packet fields: integer, double, packet, information, and structure. However, the behavior differs depending on the type, as follows.
Integer and double fields
Simple packet fields (integer and double) have their values copied into the passed variable, but are otherwise unaffected by this KP (i.e., these types of fields remain set and accessible, and continue to contribute the same amount of bits to the packet’s total size).
Packet and structure fields
Packet and structure fields of a packet also have their values (i.e., pointers to packets or data structures) copied into the passed variable.
Note: As a side-effect of accessing packet and structure values, the fields are effectively stripped from the packet: their status changes to unset, their contents become inaccessible to successive op_pk_fd_get() calls, and their contribution to the packet’s total size is subtracted. These side effects are intended to enforce strict ownership rules for the encapsulated field contents. Accessing the contents of these fields conceptually decapsulates the packet or data structure from within the packet.
Information fields
Accessing the value of an information field does not have a valid purpose since the field does not have a defined value; but instead of causing an error, the string “unspecified” is copied into the passed value pointer (the passed address must point to an array of characters of adequate length to contain this string).
Purpose
Provides a mechanism to obtain the value of a packet’s field. This operation is fundamental to the goal of using packets as containers of data for inter-process communications. Usually, this KP will be called when a packet has arrived on an input stream of a processor or queue, and the packet must be processed, stored, or it requires a response message.
Errors
- Program Abort: Segmentation violation. (due to invalid
pkptrorvalue_ptrarguments) - Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet.
- Program Abort: Packet pointer references unowned packet (
<pk_id>). - Recoverable Error: Field index (
<field_index>) is out-of-range for packet (<pk_id>).
Reference
- Use one of the variants of the KP op_pk_fd_set() to assign a value to a packet field
- Use the KP op_pk_fd_get_dbl() to obtain the value of a double field from a packet, using a numeric index to specify the field
- Use the KP op_pk_fd_get_int32() to obtain the value of a 32-bit integer field from a packet, using a numeric index to specify the field
- Use the KP op_pk_fd_get_int64() to obtain the value of a 64-bit integer field from a packet, using a numeric index to specify the field
- Use the KP op_pk_fd_get_objid() to obtain the value of an object ID field from a packet, using a numeric index to specify the field
- Use the KP op_pk_fd_get_pkt() to obtain the value of a packet field from a packet, using a numeric index to specify the field
- Use the KP op_pk_fd_get_pkid() to obtain the value of a packet ID field from a packet, using a numeric index to specify the field
- Use the KP op_pk_fd_get_ptr() to obtain the value of a structure field from a packet, using a numeric index to specify the field
- Use one of the variants the KP op_pk_nfd_get() to obtain the value of a field from a formatted packet, using a name to specify the field to be accessed
- Use the KP op_pk_fd_type() to determine the type of a packet field
- Use the KP op_pk_fd_size() to determine the size of a packet field
- Use the KP op_pk_fd_is_set() to determine if a packet field is set