op_sar_rsgbuf_lbl_seg_range_get()
Abstract
Obtains bit-range parameters for a segment, specified by its label, within the specified resegmentation buffer.
Syntax
op_sar_rsgbuf_lbl_seg_range_get (sb_hndl, label, first_bit_ptr, num_bits_ptr)
| 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().] |
label |
OpT_Int64 |
label identifying a segment within the buffer [A segment label is a user-defined numeric value that identifies a particular Sar segment within a Sar buffer. Segments are assigned labels when inserted into Sar resegmentation buffers by op_sar_rsgbuf_seg_insert().] |
first_bit_ptr |
OpT_Sar_Size* |
pointer to a variable that is assigned the local index of the first bit in the buffer associated with the specified segment [A local index is a numeric value that indicates the position in a Sar buffer of the first bit within a specified range of bits (in this case, the range associated with a Sar segment). Local index values vary from 0 (for the first bit in the buffer) to N-1 (where N is the number of bits in the buffer, for the last bit in the buffer).] |
num_bits_ptr |
OpT_Sar_Size* |
pointer to a variable that is assigned the number of bits in the buffer associated with the specified segment |
Return Type
Compcode
Completion code indicating whether the remaining contents of the specified segment is located in the buffer as a single contiguous bit-range, thus resulting in valid values for the bit index and count arguments.
[This value can be compared to the two symbolic constants OPC_COMPCODE_SUCCESS and OPC_COMPCODE_FAILURE.]
Example
/* Receive an acknowledgement from the peer process. */
ack_pkptr = op_pk_get (ACK_INSTRM);
/* Determine the sequence number of the segment being acknowledged. */
op_pk_nfd_get (ack_segptr, "ack_seg_seqnum", &new_ack_seg_seqnum);
/* Check if new acknowledgment progressed past last acknowledgment. */
if (new_ack_seg_seqnum > old_ack_seg_seqnum)
{
/* Determine the buffer-local bit-range of new acknowledgment. */
op_sar_rsgbuf_lbl_seg_range_get (rsg_sbh, new_ack_seg_seqnum,
&new_ack_bit_index, &new_ack_bit_count);
/* Flush the resegmentation buffer of acknowledged bits. */
op_sar_srcbuf_bits_flush (rsg_sbh, new_ack_bit_index, new_ack_bit_count);
/* Reset new acknowledgement as old acknowledgement. */
old_ack_seg_seqnum = new_ack_seg_seqnum;
}
Details
The numeric label used to identify the segment to this KP must match the label assigned to the intended segment when it was inserted into the Sar resegmentation buffer via the KP op_sar_rsgbuf_seg_insert(). The Sar package keeps track of the bit-ranges in the resegmentation buffer associated with the inserted segment and its corresponding label. The segment label is user-defined 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.
Both the first_bit_ptr and num_bits_ptr arguments are pointers to 64-bit integer numbers to accommodate large ranges.
Purpose
Provides a mechanism for obtaining the local bit index and length of the bit-range associated with a specific segment in a resegmentation buffer. The bit-range parameters are necessary for flushing the segment from the resegmentation buffer, via the KP op_sar_srcbuf_bits_flush(). Flushing segments from resegmentation buffers is typically performed when these buffers are being used for retransmission purposes (i.e., to store copies of transmitted data for potential retransmission due to packet loss, excessive delays, etc.). For instance, when a segment has been correctly received, it can be flushed from the resegmentation buffer, since it will no longer be needed as “insurance” against transmission failure (see the Example section for an illustration of this use of a resegmentation buffer).
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).
Reference
- Use the KP op_sar_rsgbuf_lbl_pk_range_get() to determine the local bit index and length of the bit-range associated with a specific source packet in a resegmentation 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