op_pk_fd_set_ptr()
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.
Syntax
op_pk_fd_set_ptr (pkptr, field_index, value, field_size, copy_proc, dealloc_proc, alloc_size)
| Argument | Type | Description |
|---|---|---|
pkptr |
Packet* |
pointer to the packet-of-interest |
field_index |
int |
numeric index of the field-of-interest [This value must be non-negative, or an error will occur.] |
value |
void* |
value to be assigned to the field |
field_size |
OpT_Int64 |
modeled size (in bits) of the field contents, or OPC_FIELD_SIZE_UNCHANGED (see Details) |
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_ptr (uf_pkptr, 0, 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
If field_size is different from the previous size of the field, the total size of the packet will change accordingly. If field_size is specified as OPC_FIELD_SIZE_UNCHANGED, the size of the field will remain as defined in the packet.
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).
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 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()).
Errors
- Same as
op_pk_fd_set()(structure field version).
Reference
- Same as
op_pk_fd_set()(structure field version).