op_pk_nfd_is_set()
Abstract
Determines if a field in the specified packet is set; the field-of-interest is specified by name.
Syntax
op_pk_nfd_is_set (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 should be a defined field within the packet's format; if it isn't, this KP will return OPC_FALSE, indicating that the nonexistent field is not set.] |
Return Type
Boolean
Boolean value indicating whether the specified field currently has an assignment.
This value is OPC_TRUE if the specified field is set, and OPC_FALSE if the field is not set, or if an error occurs.
Example
Excerpt from: example model (models/std/tcp_ip); process model (session_mux); state (TO_APPL); enter execs.
/* send this last packet also */
if (op_pk_nfd_is_set (pkptr, "app data");
{
/* get the encapsulated packet */
op_pk_nfd_get (pkptr, "app data", &appl_interface_pkt);
/* get its size */
data_size = op_pk_total_size_get (appl_interface_pkt) / 8;
/* ... */
}
Details
Packet fields are stored in a list within the packet. They are always numerically indexed, and in formatted packets they have associated field names. Unformatted packets that are created via the KP op_pk_create() initially have no defined fields (their field list is empty). Formatted packets that are created via the KP op_pk_create_fmt() initially have all of the fields from the associated packet format defined; some of these fields may be set automatically upon creation (i.e., they have default values).
If a field that is set is stripped from a packet using the KPs op_pk_fd_strip() or op_pk_nfd_strip(), the stripped field is changed to the unset status. If the KP op_pk_nfd_is_set() is applied to a stripped field or to a field that has never been set, the value OPC_FALSE will be returned.
Purpose
Provides a mechanism to determine if a packet field is set. This can be used to test a field before trying to obtain its value, thus preventing an error from occurring if the field is unset. Such a situation can arise if a packet format is flexibly defined such that certain fields might or might not be set depending on the history of the packet before it entered the surrounding module. This KP should only be applied to formatted packets; applying it to unformatted packets will always result in OPC_FALSE being returned, regardless of what string is passed as the field name (however, no error will occur).
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.
- Recoverable Error: No field named (
<fd_name>) in packet (<pk_id>).
Reference
- Use the KP op_pk_fd_is_set() to determine if a field is set in a unformatted (or formatted) packet, utilizing a numeric index to specify the field-of-interest
- Use the KP op_pk_nfd_size() to determine the size of a packet field
- Use the KP op_pk_nfd_type() to determine the type of a packet field
- Use the KP op_pk_fd_max_index() to determine the highest field index in a packet