op_pk_nfd_set_ptr()
Abstract
Assigns the value of a structure field in the specified packet; the field-of-interest is specified by name.
Syntax
op_pk_nfd_set_ptr (pkptr, fd_name, value, 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_fmt(), op_pk_copy(), op_pk_get(), op_subq_pk_access(), and op_subq_pk_remove().] |
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* |
value to be assigned to the 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 copy_proc[This can indicate actual size (in bytes) of the specified data structure.] |
Return Type
Compcode
OPC_COMPCODE_SUCCESS if the value of the field could be set; OPC_COMPCODE_FAILURE otherwise.
Example
{
/* declarations */
Packet *f_pkptr; struct Custom_DS *ds_ptr;
/* create a formatted packet */
f_pkptr = op_pk_create_fmt ("struct_pkt");
/* 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_nfd_set_ptr (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, OUTSTRM);
}
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 determined from the packet's format and added to the total size of the packet.
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 way to set the value of a structure field within a packet. Because the packet is formatted, only the values of the field and allocation information need to be specified; the type and size of the field are automatically obtained from the format. This KP should only be applied to formatted packets; otherwise an error will occur
Errors
- Same as
op_pk_nfd_set(). (structure field version)
Reference
- Same as
op_pk_nfd_set(). (structure field version)