op_pk_ici_get()
Abstract
Obtains the pointer to the ICI that has been previously associated with the packet via the KP op_pk_ici_set().
Syntax
op_pk_ici_get (pkptr)
| 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().] |
Return Type
Ici*
Pointer to the ICI that is associated with the packet.
The constant OPC_NIL is returned when there is no ICI associated with the packet.
Example
/* Obtain a completed packet. */
pkptr = op_subq_pk_remove (0, OPC_QPOS_HEAD);
/* Obtain the Ici associated with the packet. */
iciptr = op_pk_ici_get (pkptr);
/* Determine on which stream to send the packet. */
op_ici_attr_get (iciptr, "dst_strm", &strm_index);
/* Destroy the ici. */
op_ici_destroy (iciptr);
/* Send the packet out. */
op_pk_send (pkptr, strm_index);
Details
An ICI pointer can only be set in a packet via the KP op_pk_ici_set(). The ICI pointer remains in the packet until over-written by another call to the KP op_pk_ici_set(). The ICI is not destroyed when the packet is destroyed, since other packets or process models may still have references to the ICI and intend to use its contents.
The initial ICI pointer associated with a newly created packet is the constant OPC_NIL.
Purpose
Provides a mechanism to obtain the ICI pointer that has been set in the packet via the KP op_pk_ici_set(). Since ICIs are frequently used to carry parameters associated with a packet (e.g., to specify requested services, priority, protocol type, etc.), it is convenient to use op_pk_ici_set() to create an association between the ICI and the packet so that these parameters will be readily available when they are needed by packet handling logic. Without this capability, parameters must be obtained immediately from an ICI that accompanies a packet in a stream interrupt, and stored individually either within the packet or in user-defined state variables.
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer or malformed packet)
- Program Abort: Packet pointer is NIL
- Program Abort: Packet pointer references destroyed packet.
- Program Abort: Packet pointer references unowned packet (
<pk_id>).
Reference
- Use the KP op_ici_create() to create an ICI
- Use the KP op_ici_install() to install an ICI for outgoing interrupts
- Use the KP op_ici_destroy() to deallocate an ICI that has been processed
- Use the KP op_pk_ici_set() to set the ICI pointer in the packet