op_pk_encap_pk_get()
Abstract
Retrieves a copy of an encapsulated packet from a specified encapsulating packet.
Syntax
op_pk_encap_pk_get (pkptr, format, encap_pk_pptr)
| 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(), op_pk_create_fmt(), op_pk_copy(), op_pk_get(), op_subq_pk_access(), and op_subq_pk_remove().] |
format |
const char |
string containing either the name of a packet format or one of the symbolic constants described in the Details section |
encap_pk_pptr |
Packet** |
pointer to a packet pointer [The pointer specified here will be filled in with a pointer to a newly created packet that is a copy of an encapsulated packet.] |
Return Type
Compcode
Completion code indicating if decapsulation was successful.
If successful, this KP returns the value OPC_COMPCODE_SUCCESS; OPC_COMPCODE_FAILURE otherwise.
Example
Excerpt from oms_bgutil.ex.c in models/std/utilities/oms.
if (op_pk_encap_flag_is_set (pkptr, OMSC_BGUTIL_ENCAP_FLAG_INDEX))
{
/* Drill to get a copy of the actual bgutil packet. */
op_pk_encap_pk_get (pkptr, "bgutil_tracer", &bgutil_pkptr);
if (bgutil_pkptr == OPC_NIL)
{
return_routed_bgutil = 0.0;
*routed_packets_per_sec_ptr = 0.0;
FRET (return_routed_bgutil);
}
/* Get the src and dest objids. */
op_pk_nfd_get (bgutil_pkptr, "src_objid", &src_objid);
op_pk_nfd_get (bgutil_pkptr, "dest_objid", &dest_objid);
...
}
Details
This function searches a specified packet for any other packets encapsulated within it of a given format. It fills in encap_pk_pptr with a pointer to a new packet that is a copy of the encapsulated packet. As with any other packet, this packet must later be destroyed to avoid memory errors.
This function retrieves the first encapsulated packet with the specified format. In addition to a format name, format can be one of the constants described in the following table.
| If the constant is… | The function retrieves the first… |
|---|---|
NONE |
unformatted or value vector packet |
OPC_PK_FORMAT_ANY |
packet, regardless of format |
OPC_PK_FORMAT_ANY_FORMATTED |
formatted packet |
OPC_PK_FORMAT_ANY_UNFORMATTED |
unformatted packet |
OPC_PK_FORMAT_ANY_VVEC |
value vector packet |
If there is no packet of the specified format inside the encapsulating packet, the function returns OPC_FAILURE.
If the packet retrieved is a SAR segment, the function recursively looks for a packet of the specified format in the segment’s source packet.
Purpose
Provides a mechanism for quickly retrieving copies of encapsulated packets.
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer or malformed packet)
Reference
- Use the KP op_pk_encap_pk_access() to get a reference to an encapsulated packet
- Use the KP op_pk_encap_flag_set() to set a flag on a packet to be encapsulated
- Use the KP op_pk_encap_flag_is_set() to see if a flag has been set on an encapsulated packet
- Use the KP op_pk_format() to obtain the name of a packet’s format