Share this page

# lrs_length_receive

Sockets Functions

Receives data of a specified length.

    int lrs_length_receive( char *socket_descriptor, char *buffer, int location_option, [char* locators], [char* additional_params], LrsLastArg );

socket_descriptor | A descriptor identifying the socket.
buffer | A descriptor identifying the buffer to receive. For details on editing the Windows Sockets Buffers, see the Windows Sockets protocol in the VuGen User Guide.
location_option | The method with which to locate the field within the buffer that determines the length. NoOption - 0 (also called RecieveOption_None) OffsetSize - 1 LeftRightBoundaries - 2 LeftBoundarySize - 3
locator | The values to enable location of the length field within the buffer. You can use parameterization for these values. For option 1, OffsetSize, use "Offset=xxx" (default=0) and "Size=xxx". For option 2, LeftRightBoundaries, specify "LB=xxx", "RB=xxx", and the optional "Ordinal=" and "Offset=xxx". For option 3, LeftBoundarySize, specify "Size=xxx", "LB=xxx", and the optional "Ordinal=" and "Offset=xxx".
additional_params | How the length value within the buffer is formatted and further calculations of the length: "Encoding=" - 0 for decimal (default), 1 for HEX" Order=" - 0 for by host (default), 1 by network order scheme" SubtractSize=" - 0 do not include the size of the data in its length (default), or 1, include the size of the data in its length. "Flags=" - Receive and Send Flags that specify various ways which the call can be made.
LrsLastArg | A marker indicating the end of the parameter list.

The lrs_length_receive function reads data of a specified length from sock_descriptor into buffer . The length is located within the received buffer itself. The user must be aware where the length value is placed within the buffer (unless the RecieveOption_None option is chosen) and its location is specified by the parameters location_option and locators. lrs_length_receive first obtains the value of length (hereafter called length) and afterwards reads length number of bytes from the socket_descriptor into buffer.

The socket_descriptor and buffer parameters are identical to the first two parameters of lrs_receive.

The location_option parameters:

RecieveOption_None - lrs_length_receive will behave identically to lrs_receive. That is, the amount of data to be read will not be limited to a specified length but by the socket buffer size. Note, however, that the function lrs_set_receive_option does not affect lrs_length_receive.

OffsetSize - length takes up sizebytes and is placed offset bytes from the beginning of the buffer. The values for the offset and size are passed as locator parameters with the "Offset" and Size" identifiers (e.g., "Offset=6", "Size=4"). After locating the length field. lrs_length_receive will read length number of bytes that directly follow it.The default value of "Offset" is zero.

LeftRightBoundaries - length is found between a left and right boundary. The values for both boundaries are passed as locator parameters using "LB" and "RB". The amount of data to be read will be length number of bytes immediately following the right boundary. The locator parameters "Offset" and "Ordinal" may also be used. If the left or right boundary is a binary value, specify this by appending /BIN to the option indicator e.g., "RB/BIN=\\x00\\x00\\x01\\x00\\x00\\x00"

LeftBoundarySize - length is located after a left boundary and takes up size bytes. The values for the left boundary and size are passed as locator parameters "LB" and "Size", respectively. The locator parameters "Offset" and "Ordinal" may also be used as well as the /BIN indicator option.

The locator parameters:

Locator parameters may be used in conjunction by passing them as separate string parameters to lrs_length_receive e.g., "LB=LeftLeft ", "Size=1", "Offset=18".

Use the "Offset" locator (e.g., "Offset=4") with the OffsetSize location_option where Offset specifies how many bytes from the beginning of the buffer lies the length field .Use "Offset" with the LeftRightBoundaries or LeftBoundarySize location_option where, to locate length, Offset number of bytes will be added to the left boundary. This is useful when there is always a specific number of bytes of unknown content following a known left boundary. For example, consider three characters, "ABC", that define the left boundary - if there are always 2 bytes of unknown content between "ABC" and length then pass "LB=ABC" and "Offset=2".

The "Ordinal" locator can be used with the LeftRightBoundaries or LeftBoundarySize location_option. It indicates that the length field begins after the ordinal instance of the left boundary. For example, if the left boundary, the string "ABC", appears many times in the buffer, then "Ordinal=2" specifies that you use the second instance of "ABC" to locating length. Note that "Ordinal" can be used in conjunction with "Offset". length lies Offset bytes following the Ordinal instance of the left boundary.

The additional_params parameters:

These parameters indicate in what format the length field will be found. They can be used together. They are passed as separate string parameters to lrs_length_receive e.g., "Order=1", "Encoding=1".

Some length fields in a buffer include their own length in the total value. "SubtractSize" enables you to subtract the length of the field from the total to enable lrs_length_receive to correctly read only the length of data.

## Return Values

If this function fails, it returns NULL. If it succeeds, it returns a pointer to the converted buffer. You can also retrieve the converted buffer using lrs_get_user_buffer.

## Parameterization

You cannot use standard parameterization for any arguments in this function.

## Example 1

In the following example, data (buffer1) is sent on a socket (socket0). Then the same data is received on the same socket with lrs_length_receive using the OffsetSize location_option. buffer1 consists of a length value of 2 bytes (in bold) and data. After obtaining the length value of 51, lrs_length_receive goes on to read 51 bytes of data from socket0 into buffer2. Note that there is no need to pass the locator parameter"Offset=0" as this is the default setting.

buffer1`
51aaabbcc dddeeeeeeeeeeeeeeffffffffffffgggggghhhhhhhi"`

    lrs_create_socket("socket0", "TCP", "RemoteHost=bona.abc.com:7", LrsLastArg);

    lrs_send("socket0", "buffer1", LrsLastArg);

    lrs_length_receive("socket0", "buffer2", OffsetSize, "Size=2", LrsLastArg);

## Example 2

In this example, data (buffer3) is sent on a socket (socket0). The same data is received on the socket with lrs_length_receive. The LeftRightBoundaries location_option is used with the left boundary being the string "LLLL" and the right boundary "RRRR". The lrs_length_receive first locates the second instance of the left boundary string (in bold) because the Ordinal locator is set to 2. The function is then told to jump a further 27 bytes (Offset=27) to finally locate the length value. This value is 9 (in bold) and is bounded by the right boundary of "RRRR". The 9 bytes after the right boundary are the characters "Requested" which lrs_length_receive reads from socket0 and writes to buffer4.
The subsequent call to lrs_receive reads the rest of the data into another buffer.

buffer3
`"12LLLL34LLLLOOOOOfffffsssssseeeeeTTTTTT9RRRRRequestedZZZZZZZZZZZZZZZZZZZZ2LLLLAAAAAAAAAAAAAAAAAAAAAAEnd Buf"`

    lrs_create_socket("socket0", "TCP", "RemoteHost=bona.abc.com:7", LrsLastArg);

    lrs_send("socket0", "buffer3", LrsLastArg);

    lrs_length_receive("socket0", "buffer4", 2, "LB=LLLL", "RB=RRRR", "Offset=27", "Ordinal=1", LrsLastArg);

    // Now receive the rest of received data

    lrs_receive("socket0", "buffer5", LrsLastArg);

## Example 3

In this example, data (buffer6) is sent on a socket (socket0). The same data is received on the socket with lrs_length_receive using the LeftBoundarySize location_option, the left boundary being the binary values \\x00\\x00\\x00\\x07. lrs_length_receive first locates these values (in bold) and then is told to jump a further 7 bytes (Offset=7) to finally locate the length value which takes up 2 bytes (Size=2). This value is 16 (also in bold). However, because the additional_param SubtractSize is set to zero, the size of the length field itself, 2, is subtracted from the total, making 14. The 14 byte string following the length field, "Requested Data", is read from socket0 and written to buffer7.
The subsequent call to lrs_receive reads the rest of the data into another buffer.

buffer6
`"12LLLL34\\x00\\x00\\x00\\x07eTTTTTT16Requested Data ZZZZZZZZZZZZZZZZZZZZ2LLLLAAAAAAAAAAAAAAAAAEnd Buf"`

    lrs_create_socket("socket0", "TCP", "RemoteHost=bona.abc.com:7",

    lrs_send("socket0", "buffer6", LrsLastArg);

    lrs_length_receive("socket0", "buffer7", 3, "LB/BIN=\\x00\\x00\\x00\\x07", "size=2", "Offset=7", "SubtractSize=0", LrsLastArg);

    // Now receive the rest of received data

    lrs_receive("socket0", "buffer8", LrsLastArg);

Tips to improve your search results... VuGen Function Reference Version 26.1 Function Reference 26.1 All View Local Help Center View Online Help Center Version: