op_pk_fd_set()
Abstract
Assigns the value of a structure field in the specified packet, as well as the type, size, and procedures for structure copying and deallocation; the field-of-interest is specified by a numeric index.
Note: This KP format is used for structure fields only. For other field types, use an alternate format (see the Purpose section for details).
Syntax
op_pk_fd_set (pkptr, fd_index, type, value, size, copy_proc, dealloc_proc, alloc_size)
| 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().] |
fd_index |
int |
numeric index of the field-of-interest |
type |
int |
type to be assigned to the field [This is an integer code which specifies the field type (see Table 55 “Field Type Symbolic Constants“ on page 14); the only acceptable value for this KP format is OPC_FIELD_TYPE_STRUCT.] |
value |
void* |
data structure pointer to be assigned to the field |
size |
int, double, or OpT_Int64 |
modeled size (in bits) of the field contents, or OPC_FIELD_SIZE_UNCHANGED [If this argument is of type double or OpT_Int64, you must augment the type argument. See the Details section for more information.] |
copy_proc |
SimT_Pk_Fd_Struct_Copy_Proc |
copy procedure for the specified data structure, typically the KP op_prg_mem_copy_create() (see Details) |
dealloc_proc |
SimT_Pk_Fd_Struct_Dealloc_Proc |
deallocation procedure for the specified data structure, typically the KP op_prg_mem_free() (see Details) |
alloc_size |
size_t |
actual size (in bytes) of the specified data structure |
Return Type
Compcode
OPC_COMPCODE_SUCCESS if the field could be set; OPC_COMPCODE_FAILURE otherwise.
Example
{
/* declarations */
Packet *uf_pkptr; struct Custom_DS *ds_ptr;
/* create an unformatted packet */
uf_pkptr = op_pk_create (64);
/* allocate a new data structure */
ds_ptr = (struct Custom_DS *) op_prg_mem_alloc (sizeof (Custom_DS));
/* fill in certain data structure values */
ds_ptr->int_value = 455;
sprintf (ds_ptr->name, "Custom Data Structure #1");
/* assign the data structure to a field in the packet */
op_pk_fd_set (uf_pkptr, 0, OPC_FIELD_TYPE_STRUCT, ds_ptr, 256,
op_prg_mem_copy_create, op_prg_mem_free, sizeof (Custom_DS));
/* send the defined packet out of the processor */
op_pk_send (uf_pkptr, OUTSTRM);
}
Details
The value argument can accept a pointer to any type of data structure. The value of the fd_index argument must be non-negative, or an error will occur. If the specified size of the field is different from its previous size, the total size of the packet will change proportionally.
For the structure field type, both the value and size of the field must be specified. Structures assigned to fields are “encapsulated” within the packet, and the invoking process typically should not continue to use the structure pointer (this is occasionally useful as a means of remote inter-process communication, but structure memory must be handled very carefully).
If size is of type double, you must augment the type argument by adding an OR operator (|) and the flag OPC_FIELD_SIZE_IS_DOUBLE; otherwise the underlying code will interpret the size argument as an integer value. If the size argument is of type OpT_Int64, you must augment the type argument by adding an OR operator (|) and the OPC_FIELD_SIZE_IS_INT64 flag. For example,
op_pk_fd_set (pkptr, 0, OPC_FIELD_TYPE_STRUCT, val_ptr, 16, copy,free, alloc_size) |
uses a size argument of type integer (the value 16 as an integer (four-byte) argument) |
op_pk_fd_set (pkptr, 0,OPC_FIELD_TYPE_STRUCT|OPC_FIELD_SIZE_IS_DOUBLE, val_ptr,16.0, copy, free, alloc_size) |
uses a size argument of type double (the value 16.0 as a double (eight-byte) argument) |
OpT_Int64 the_size = 16;op_pk_fd_set (pkptr, 0,OPC_FIELD_TYPE_STRUCT|OPC_FIELD_SIZE_IS_INT64, val_ptr,the_size, copy, free, alloc_size) |
uses a size argument of type 64-bit integer (the value 16 as a 64-bit integer (eight-byte) argument) |
If size is different from the previous size of the field, the total size of the packet will change accordingly. If size is OPC_FIELD_SIZE_UNCHANGED, the size of the field will remain as defined in the packet.
Note: OPC_FIELD_SIZE_UNCHANGED is a 64-bit value. When it is used, the type argument must be augmented for an OpT_Int64 argument, as follows:
op_pk_fd_set (pkptr, field_index,
OPC_FIELD_TYPE_STRUCT|OPC_FIELD_SIZE_IS_INT64, val_ptr,
OPC_FIELD_SIZE_UNCHANGED, copy_proc, dealloc_proc,
alloc_size)
The specified copy and deallocation procedures are invoked when the specified packet is copied or destroyed, respectively. The copy procedure is used to allocate memory for and copy the structure contained in the field. The prototype for copy_proc is:
typedef void * (*SimT_Pk_Fd_Struct_Copy_Proc)(void * org_ptr, size_t size)
When op_prg_mem_copy_create() is the specified copy procedure, alloc_size specifies the size in bytes necessary to reserve the correct amount of memory during allocation of structure copies. copy_proc must not be null; at the very least, it must be a stub function that simply returns org_ptr.
The deallocation procedure is used to deallocate the memory occupied by the structure contained in the field. The prototype for dealloc_proc is:
typedef void (*SimT_Pk_Fd_Struct_Dealloc_Proc)(void * ptr)
dealloc_proc can be null, in which case the memory is not freed.
Note: Because fields are not copied automatically when a packet is copied, the copy and deallocation procedures might not be invoked when expected. The copy procedure is invoked only when a structure field changes, not when a packet is copied. The deallocation procedure is invoked only when the structure field being destroyed is unique to the packet (that is, not referenced by a copy of the packet). See the description of op_pk_copy() for more details.
Purpose
Provides a mechanism to set the value of a field within a packet. This KP is usually applied to unformatted packets, but it can be applied to formatted packets as well (formatted packet field names can be converted into numeric indices using the KPs op_pk_name_to_index() and op_pk_nfd_name_to_index()).
This format of op_pk_fd_set() only supports structure field types. Alternate formats of this KP support integer, double, or packet field types (op_pk_fd_set()) and information field types (op_pk_fd_set())
A data-type-specific version of this KP exists. The alternate KP is more efficient than this variable argument version. In addition, it allows the compiler to catch argument errors that are missed with this KP. For details, refer to op_pk_fd_set_ptr().
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer or malformed packet)
- Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet.
- Program Abort: Packet pointer references unowned packet (
<pk_id>). - Program Abort: Allocation of memory failed.
- Recoverable Error: Field type (
<type>) is unrecognized. - Recoverable Error: Field size (
<size>) is out-of-range. - Recoverable Error: Field index (
<fd_index>) is out-of-range for packet (<pk_id>).
Reference
- Use the alternate formats of this KP to assign values to integer, double, packet, or information fields of a packet
- Use one of the variants of the KP op_pk_nfd_set() to assign the value of a field in a formatted packet, utilizing a name to specify the field to be assigned
- Use one of the variants of the KP op_pk_fd_get() to obtain the value of a field in a packet
- Use the KP op_pk_fd_strip() to unset a packet field, subtracting out its contribution to total packet size