op_sar_rsgbuf_lbl_pk_range_get()
Abstract
Obtains bit-range parameters for a source packet, specified by its label, within the specified resegmentation buffer.
Syntax
op_sar_rsgbuf_lbl_pk_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 source packet within the buffer [A packet label is a user-defined numeric value that identifies a particular packet within a Sar buffer. Source packets are assigned labels when inserted into Sar segmentation buffers by op_sar_segbuf_pk_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 source packet [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 source packet). 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 packet |
Return Type
Compcode
Completion code indicating whether the remaining contents of the specified source packet 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 source packet being acknowledged. */
op_pk_nfd_get (ack_pkptr, "ack_pk_seqnum", &new_ack_pk_seqnum);
/* Check if new acknowledgment progressed past last acknowledgment. */
if (new_ack_pk_seqnum > old_ack_pk_seqnum)
{
/* Determine the buffer-local bit-range of new acknowledgment. */
op_sar_rsgbuf_lbl_pk_range_get (rsg_sbh, new_ack_pk_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_pk_seqnum = new_ack_pk_seqnum;
}
Details
The numeric label used to identify the source packet to this KP must match the label assigned to the intended source packet when it was inserted into a Sar segmentation buffer via the KP op_sar_segbuf_pk_insert(). Even though the source packet may have been divided into segments by the original segmentation buffer, transmitted between modules and across links, and then partially regrouped within the resegmentation buffer, the Sar package keeps track of the bit-ranges in the resegmentation buffer associated with the source packet and its corresponding label. The source packet label is user-defined to support the use of process-model specific sequence numbers as labels; typically, source packets are either labeled with a packet 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 source packet in a resegmentation buffer. The bit-range parameters are necessary for flushing the source packet from the resegmentation buffer, via the KP op_sar_srcbuf_bits_flush(). Flushing source packets 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 source packet 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_seg_range_get() to determine the local bit index and length of the bit-range associated with a specific Sar segment 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