op_pk_nfd_strip()
Abstract
Removes a field from the specified packet; the field-of-interest is specified by name.
Syntax
op_pk_nfd_strip (pkptr, fd_name)
| 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.] |
Return Type
Compcode
Completion code indicating if the specified field was successfully changed to an “unassigned” condition. The constant OPC_COMPCODE_FAILURE will be returned if a recoverable error occurs.
Example
/* obtain an arriving packet */
pkptr = op_pk_get (0);
/* obtain the source node of the packet from an integer field */
op_pk_nfd_get (pkptr, "fd_source", &src_node);
/* write the source node out as a statistic */
op_stat_write (0, (double) src_node);
/* strip off the source node field */
op_pk_nfd_strip (pkptr, "fd_source");
/* send the modified packet out */
op_pk_send (pkptr, 0);
Details
This KP supports the stripping of all five types of packet fields: integer, double, packet, information, and structure. Simple packet fields (that is, integer, double, and information fields) are modified by this KP to unset status, and their contribution to the total packet size is subtracted out. Packet and structure fields of a packet are also modified by this KP to unset status, and they also have their contributions to total packet size subtracted out. However, the packets and data structures pointed to by the contents of these fields are deallocated, in order to strictly enforce the concept of encapsulation within the stripped field.
Packet fields can encapsulate packets that in turn also have packet fields; arbitrary levels of this type of recursion are supported by op_pk_fd_strip(). The deallocation of data structures encapsulated within structure fields is performed using the deallocation procedure specified by the dealloc_proc argument of the KPs op_pk_fd_set() or op_pk_nfd_set().
Purpose
Provides a mechanism to remove a field from a packet, thus subtracting out its contribution to the total size of the packet. This is typically useful under the following conditions:
- A packet is being routed through a series of processors or queues.
- Some of the packet’s fields are needed to communicate information to an intermediate processor or queue.
- The fields in (2) are not accessed by any other processes along the route of the packet.
Given these conditions, the relevant fields can be stripped out by the intermediate processor. This KP should only be applied to formatted packets; otherwise an error will occur.
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer or
fd_nameargument) - 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 KP
op_pk_fd_strip()to strip a field from a packet, specifying the field by numeric index - Use one of the formats of the KP
op_pk_nfd_set()to assign the value of a packet field - Use the KP
op_pk_nfd_get()to access the value of a packet field - Use the KP
op_pk_destroy()to deallocate a packet