ReceiveAsynchronous (Socket function)
Receive zero or more bytes on this socket (Socket class)
[Introduced in Sirius Mods 7.9]
Unlike the Receive and ReceiveAndParse methods, if ReceiveAsynchronous receives fewer than the requested number of bytes, it will return, either immediately or after a timeout, according to your specification.
%bytesReceived = socket:ReceiveAsynchronous( [Target=] string, - [[MaxBytes=] number], - [[Options=] string], - [Wait= boolean])
|%BytesReceived||A numeric string to contain the count of the number of bytes received, or to contain 0, if the operation cannot be performed.|
|socket||A variable or an expression that is a reference to a Socket object.|
|Target||This name allowed parameter is a %variable or an IMAGE item that is the target of the receive operation. It is referred to as the "receive target." Since you may request that some bytes from the socket stream be discarded, the length of the string stored in this target may be less than the %BytesReceived value.|
|MaxBytes||This optional, name allowed, parameter is the maximum number of bytes of data to receive, less the length of the separator string. This optional argument defaults to 0, which means limit the received data (less separator) to the declared length of the receive target.
If the MaxBytes argument value is 0, and the Target argument is a Longstring, the received data is limited to 2,147,483,647 bytes. The MaxBytes argument value must not exceed 2,147,483,647.
MaxBytes may have the special value
|Options||This optional, name allowed, parameter is an option string, which can contain either of the following:
|Wait||This name allowed, optional, Boolean value indicates whether the method should wait until the timeout time before returning, if MaxBytes bytes are not immediately available.
- If ReceiveAsynchronous returns a 0 indicating
that no bytes were returned, it means either of these:
- No bytes were available at the instant the method was called or after the timeout time.
- No data will ever be returned on the socket, because we a FIN was returned from the other side.
A returned 0 is not ambiguous with the Receive and ReceiveAndParse methods, because they only return a 0 when a FIN was received. But if a 0 is returned from ReceiveAsynchronous, you must determine if it is caused by a FIN or not: If ReceiveAsynchronous returns a 0 because a FIN was received, and you call it (or Receive) again, you will get a request cancellation. So when ReceiveAsynchronous returns a 0, call the ReceivedFin method to check if a FIN has been received — unless you "know" the other side will never close the connection nicely (with a FIN) and that the only way the connection can be closed is with a reset.