op_sar_rsgbuf_seg_insert()
Abstract
Inserts the specified segment at the tail of the specified resegmentation buffer. The user-defined label and absolute index arguments respectively “tag” the segment’s bit-range for later reference.
Syntax
op_sar_rsgbuf_seg_insert (sb_hndl, seg_pkptr, seg_label, bit_index_abs)
| Argument | Type | Description |
|---|---|---|
sb_hndl |
Sbhandle |
handle identifying the resegmentation buffer-of-interest [This value must identify a Sar resegmentation buffer. A Sar buffer handle is obtained when a buffer is created via the KP op_sar_buf_create().] |
seg_pkptr |
Packet* |
pointer to the segment to be inserted into the buffer [Sar segments are represented as standard packets, and can be handled by all Pk package KPs; however, their internal data contents is typically only accessed by Sar package KPs to perform reassembly or resegmentation tasks. A pointer to a packet representing a Sar segment is usually first obtained from the KP op_sar_srcbuf_seg_remove().] |
seg_label |
OpT_Int64 |
label for the specified segment within the buffer [A segment label is a user-defined numeric value that “tags” the specified segment; the label is thus associated with the contents of the specified segment within a Sar resegmentation buffer.] |
bit_index_abs |
OpT_Sar_Size |
absolute index for the first bit of the specified segment [An absolute index is a user-defined numeric value that identifies the first bit of a range within a Sar resegmentation buffer.] |
Return Type
void
No return value.
Example
/* Obtain an arriving frame. */
frame_pkptr = op_pk_get (REF_INSTRM);
/* Remove the frame’s data segment and destroy the frame */
op_pk_nfd_get (frame_pkptr, "data_seg", &inseg_pkptr);
op_pk_destroy (frame_pkptr);
/* The segments must be divided into smaller segments before entering */
/* the destination sub-network, so they are inserted into a reseg. buffer. */
op_sar_rsgbuf_seg_insert (rsg_sbh, inseg_pkptr, 0, 0);
/* Loop through all resulting small segments, forwarding them on. */
while ((remseg_pkptr = op_sar_srcbuf_seg_remove (rsg_sbh, STD_SEG_LEN)) != OPC_NIL)
{
/* Create a frame for the current small segment, and insert the segment. */
frame_pkptr = create_frame ();
op_pk_nfd_set (frame_pkptr, "data_seg", remseg_pktr);
/* Forward the frame. */
op_pk_send (frame_pkptr, REF_OUTSTRM);
}
Details
The seg_label argument is used to identify the range of bits associated with the inserted segment. Every bit from the inserted segment is associated with the same segment label, so if the segment is split due to removal of smaller segments from the buffer, the bits remaining in the buffer will still be identifiable through their segment label. The label of a segment can later be used to identify the segment for flushing from the resegmentation buffer via the KPs op_sar_rsgbuf_lbl_seg_range_get() and op_sar_srcbuf_bits_flush(). Segment labels are user-defined numeric values to support the use of process-model specific sequence numbers as labels. Typically, segments are either labeled with a segment sequence number, or with a sequence number based on the first (or last) byte (or bit) that they contain.
The bit_index_abs argument is also used to identify the range of bits associated with the inserted segment. The absolute bit index actually identifies the first bit of the segment, and the Sar package assumes that the absolute bit index of each remaining bit of the segment is a successively higher value (incremented by one). For instance, if a segment has five bits and the first bit has an absolute index of 20, than the Sar package assumes that the absolute index of the last bit in the segment is 24. The absolute bit index of a segment can later be used to identify the segment (or portions of it) for flushing from the resegmentation buffer via the KP op_sar_rsgbuf_bits_flush_abs(). Absolute bit indices are user-defined numeric values to support the use of process-model specific sequence numbers as bit-range identifiers, but the Sar assumptions typically restrict the provided indices to be bit-oriented. The bit_index_abs argument is a 64-bit integer number to accommodate large sequences of bits.
Purpose
Provides a mechanism for inserting a Sar segment into a resegmentation buffer (there is no other mechanism for placing packets into a Sar resegmentation buffer). Resegmentation buffers only accept the insertion of Sar segments, and they typically are used for two applications:
- as a retransmission buffer for storing transmitted data until the data is acknowledged or “times out” and must be retransmitted
- as a buffer for compressing or expanding the length of an incoming stream of data segments
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 (resegmentation). - Program Abort: Packet pointer references unowned packet (
<pkid>) - Program Abort: Packet pointer references static packet (
<pkid>) - Program Abort: Packet (
<pkid>) must be a segment of another packet - Recoverable Error: Index (
<bit_index_abs>) is invalid. / Value must be >= 0.
Reference
- Use the KP op_sar_srcbuf_seg_remove() to remove and obtain a Sar segment from the head of a (re)segmentation buffer
- Use the KP op_sar_srcbuf_seg_access() to copy a Sar segment from the head of a (re)seg. buffer
- Use the KP op_sar_srcbuf_bits_flush() to flush a bit-range, identified by local bit index and length, from a (re)segmentation buffer
- Use the KP op_sar_rsgbuf_bits_flush_abs() to flush a bit-range, identified by absolute bit index and length, from a resegmentation buffer