op_sar_rsmbuf_pk_remove()
Abstract
Removes a complete source packet from the specified reassembly buffer. A pointer to the removed packet is returned.
Syntax
op_sar_rsmbuf_pk_remove (sb_hndl)
| Argument | Type | Description |
|---|---|---|
sb_hndl |
Sbhandle |
handle identifying the reassembly buffer-of-interest [This value must identify a Sar reassembly buffer. A Sar buffer handle is obtained when a buffer is created via the KP op_sar_buf_create().] |
Return Type
Packet*
Pointer to the complete source packet removed from the specified reassembly buffer. [If there are no complete packets within the specified reassembly buffer, the value OPC_NIL is returned by this KP.]
Example
/* Receive an incoming packet. */
pkptr = op_pk_get (INSTRM_1);
/* Determine if the received packet is a segment, or normal packet. */
if (op_sar_pk_is_segment (pkptr) == OPC_TRUE)
{
/* Received a segment; add to reassembly buffer. */
op_sar_rsmbuf_seg_insert (rsm_sbh, pkptr);
/* See if any packets are ready to be removed from reassembly buffer. */
while ((pkptr = op_sar_rsmbuf_pk_remove (rsm_sbh)) != OPC_NIL)
op_pk_send (pkptr, OUTSTRM_1);
}
else
{
/* Received a normal packet; forward on to output stream. */
op_pk_send (pkptr, OUTSTRM_1);
}
Details
Only a completely reassembled source packet is removed by this KP; source packets in the buffer that are incomplete (missing one or more bits) are not affected by this KP’s invocation.
Unlike segmentation or resegmentation buffers, reassembly buffers do not simply have packets removed from the “head” of the buffer (the head being the departure end of an ordered list of buffer packets). The internal structure of reassembly buffers is more complex than the other buffer types, and actually includes two separate ordered lists of source packets: an incomplete list and a complete list.
- The incomplete list holds incomplete source packets, and absorbs arriving Sar segments as they are inserted into the reassembly buffer. The order of incomplete source packets in this list is based on the arrival sequence of the first segment of each packet.
- The complete list holds complete source packets, and has packets transferred to it from the incomplete list as they are completed. The order of complete source packets in this list is based on the completion sequence of source packets. Packets removed from the reassembly buffer are taken from this list’s head.
The source packet removed from the complete list will be the packet in the buffer that has been completed for the longest duration. Note that other complete packets that follow the removed packet in the complete list may have been waiting for completion for a longer duration than the removed packet.
Purpose
Provides a mechanism to extract a complete source packet from a reassembly buffer. This is the final stage of a source packet’s interaction with the Sar package, in which it reemerges, fully reconstructed. This KP is typically invoked to obtain reassembled packets for further processing and eventual hand-off to higher-level protocols. Appropriate times to check for the presence of complete source packets occur after Sar segments (or source packets) are inserted into a reassembly buffer, since source packets can only be completed at these times (see the Example section).
Errors
- Standard Sar errors (see Table 15)
- Program Abort: Buffer handle references destroyed buffer.
- Program Abort: Buffer type (
<type>) is invalid for this KP, should be (reassembly).
Reference
- Use the KP op_sar_rsmbuf_pk_count() to determine the number of complete source packets in a reassembly buffer
- Use the KP op_sar_buf_size() to determine the number of bits stored in a Sar buffer
- Use the KP op_sar_rsmbuf_seg_insert() to insert a Sar segment into a reassembly buffer
- Use the KP op_sar_rsmbuf_pk_flush() to flush old, incomplete source packets from a reassembly buffer