op_pk_nfd_set()
DEPRECATED—Use explicitly typed op_pk_nfd_set_<type>()
Abstract
Assigns the value of a structure field in the specified packet, in addition to structure copying and deallocation procedures; the field-of-interest is specified by name.
Note: This format is used for structure fields only. For other field types, use an alternate format (see the Purpose section for details).
Syntax
op_pk_nfd_set (pkptr, fd_name, value, copy_proc, dealloc_proc, alloc_size)
| Argument | Type | Description |
|---|---|---|
pkptr |
Packet* |
pointer to the packet-of-interest (see the preceding KP entry for details). |
fd_name |
const char* |
name of the field-of-interest [This name must be a defined field within the packet's format, or an error will occur.] |
value |
void* |
data structure pointer to be assigned to the specified field |
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 |
argument passed to the copy_proc[This may indicate actual size (in bytes) of the specified data structure.] |
Return Type
Compcode
Completion code indicating if the specified field was successfully assigned a new value. OPC_COMPCODE_FAILURE is returned if a recoverable error occurs.
Example
{
typedef struct {
int int_value;
char name[100];
} custom_DS;
/* declarations */
Packet *f_pkptr; Custom_DS *ds_ptr;
/* create a formatted packet */
f_pkptr = op_pk_create_fmt ("struct_pkt");
/* allocate a new data structure */
ds_ptr = (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_nfd_set (f_pkptr, "ds_field", ds_ptr, op_prg_mem_copy_create,
op_prg_mem_free, sizeof (Custom_DS));
/* send the defined packet out of the processor */
op_pk_send (f_pkptr, 0);
}
Details
The value argument can accept a pointer to any type of data structure. If the specified field has not been set before, the size of the new field is also determined from the packet's format, and added to the total size of the packet.
For the structure field type, the value of the field must be specified. Structures assigned to fields are “encapsulated” within the packet being operated on by this KP, and the invoking process should typically not continue to reference the assigned structure pointer (this is occasionally useful as a means of remote inter-process communication, but structure memory must be handled very carefully).
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 structure field within a packet. Because the packet is formatted, only the value of the field and allocation information needs to be specified; the type and size of the field (which would need to be specified to the unformatted version of this KP, op_pk_fd_set()), are automatically obtained from the format.
Note: This KP should be applied only to formatted packets; otherwise an error will occur.
This format of op_pk_nfd_set() supports only structure field types. Alternate formats of this KP support integer, double, or packet field types (op_pk_nfd_set()) and information field types (op_pk_nfd_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_nfd_set_ptr().
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer or fd_name argument)
- Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet.
- Program Abort: Packet pointer references unowned packet (
<pk_id>). - Recoverable Error: No field named (
<fd_name>) in 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_fd_set() to assign the value of a field in an unformatted (or formatted) packet, utilizing a numeric index to specify the field to be assigned
- Use one of the variants of the KP op_pk_nfd_get() to obtain the value of a field in a packet
- Use the KP op_pk_nfd_strip() to unset a field within a packet, subtracting out its contribution to total packet size