ReceiveAsynchronous (Socket function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Template:Socket:ReceiveAsynchronous subtitle}}
{{Template:Socket:ReceiveAsynchronous subtitle}}
Unlike the <var>[[Receive (Socket function)|Receive]]</var> and     
<var>[[ReceiveAndParse (Socket function)|ReceiveAndParse]]</var> methods, if <var>ReceiveAsynchronous</var> receives fewer than the requested number of bytes, it will return, either immediately or after a timeout, according to your specification.             


==Syntax==
==Syntax==
Line 6: Line 9:
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%BytesReceived</th><td>number</td></tr>
<tr><th>%BytesReceived</th>
<td>A numeric string to contain the count of the number of bytes received, or to contain 0, if the operation cannot be performed.</td></tr>
 
<tr><th>socket</th>
<tr><th>socket</th>
<td>Socket object</td></tr>
<td>A variable or an expression that is a reference to a <var>Socket</var> object.</td></tr>
 
<tr><th><var>Target</var></th>
<tr><th><var>Target</var></th>
<td>string</td></tr>
<td>This [[Notation conventions for methods#Named parameters|name allowed]] parameter is a %variable or an <var>IMAGE</var> 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 <var class="term">%BytesReceived</var> value.
</td></tr>
 
<tr><th><var>MaxBytes</var></th>
<tr><th><var>MaxBytes</var></th>
<td>number</td></tr>
<td>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.
<p>If the <var>MaxBytes</var> argument value is 0, and the <var>Target</var> argument is a <var>Longstring</var>, the received data is limited to 2,147,483,647 bytes. The <var>MaxBytes</var> argument value must not exceed 2,147,483,647.
<var>MaxBytes</var> may have the special value <code>-1</code> to indicate there is no limit to the number of bytes received.
</p></td></tr>
 
<tr><th><var>Options</var></th>
<tr><th><var>Options</var></th>
<td>string</td></tr>
<td>This optional, name allowed, parameter is an option string, which can contain either of the following:
<table class="syntaxTable">
<tr><th><var>BINARY</var></th>
<td>Regardless of the socket's <var>[[BINARY (JANUS DEFINE parameter)|BINARY]]</var> or <var>[[CHAR (JANUS DEFINE parameter)|CHAR]]</var> port parameter, data '''is not translated''' when saved in the receive target. The received string can be translated later in the program using the <var>[[TranIn (Socket function)|TranIn]]</var> method. </td></tr>  
<tr><th><var>CHAR</var> </th><td>Regardless of the socket's <var>BINARY</var> or <var>CHAR</var> parameter, data '''is translated''' when saved in the receive target. The translation is specified by the input table defined by the socket's <var>[[XTAB (JANUS DEFINE parameter)|XTAB]]</var> port parameter.
</td></tr>
<tr><th nowrap><var>PRSTOK [AMBIG|]</var>hexstr<var>[|</var>hexstr<var>]...</var>
</th><td>A set of parse tokens that override the current parse tokens on the socket.
 
Whether it is set on the port definition or by the <var>[[Set (Socket function)|Set]]</var> or <var>ReceiveAndParse</var> methods, <var>PRSTOK</var> must '''not''' be <code>NONE</code>, or <var>ReceiveAndParse</var> will fail.
</td></tr></table>
 
<tr><th><var>Wait</var></th>
<tr><th><var>Wait</var></th>
<td><var>Boolean</var> value</td></tr>
<td>This name allowed, optional, <var>[[Boolean enumeration|Boolean]]</var> value indicates whether the method should wait until the timeout time before returning, if <var>MaxBytes</var> bytes are not immediately available.
<p>
If <code>Wait=True</code> and the request for <var>MaxBytes</var> times out, the conection is not closed, and some number of bytes between 0 and <code>MaxBytes-1</code> is returned. If <code>Wait=False</code>, <var>ReceiveAsynchronous</var> returns  immediately with whatever number of input bytes are available. </p></td></tr>
</table>
</table>
==Usage notes==
==Usage notes==
==Examples==
<ul>
<li>If <var>ReceiveAsynchronous</var> returns a 0 indicating 
that no bytes were returned, it means either of these:
<ul>
<li>No bytes were available at the instant
the method was called or after the timeout time.
<li>No data will ever be returned on the socket, because we a FIN was returned from the other side.
</ul>
 
A returned 0 is not ambiguous with the <var>Receive</var> and     
<var>ReceiveAndParse</var> methods, because they only return a 0 when a FIN was received. But if a 0 is returned from <var>ReceiveAsynchronous</var>, you must determine if it is 
caused by a FIN or not: If <var>ReceiveAsynchronous</var> returns a 0 because a FIN was received, and you call it   
(or <var>Receive</var>) again, you will get a request cancellation. So when <var>ReceiveAsynchronous</var>   
returns a 0, call the <var>[[ReceivedFin_(Socket_function)|ReceivedFin]]</var> method to check if a FIN has been received &mdash; 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.                 
</ul>


==See also==
==See also==
 
<ul>
<li><var>[[Receive (Socket function)|Receive]]</var>
<li><var>[[ReceiveAndParse (Socket function)|ReceiveAndParse]]</var>
</ul>
{{Template:Socket:ReceiveAsynchronous footer}}
{{Template:Socket:ReceiveAsynchronous footer}}

Latest revision as of 16:14, 11 June 2012

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.

Syntax

%bytesReceived = socket:ReceiveAsynchronous( [Target=] string, - [[MaxBytes=] number], - [[Options=] string], - [Wait= boolean])

Syntax terms

%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 -1 to indicate there is no limit to the number of bytes received.

Options This optional, name allowed, parameter is an option string, which can contain either of the following:
BINARY Regardless of the socket's BINARY or CHAR port parameter, data is not translated when saved in the receive target. The received string can be translated later in the program using the TranIn method.
CHAR Regardless of the socket's BINARY or CHAR parameter, data is translated when saved in the receive target. The translation is specified by the input table defined by the socket's XTAB port parameter.
PRSTOK [AMBIG|]hexstr[|hexstr]... A set of parse tokens that override the current parse tokens on the socket.

Whether it is set on the port definition or by the Set or ReceiveAndParse methods, PRSTOK must not be NONE, or ReceiveAndParse will fail.

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 Wait=True and the request for MaxBytes times out, the conection is not closed, and some number of bytes between 0 and MaxBytes-1 is returned. If Wait=False, ReceiveAsynchronous returns immediately with whatever number of input bytes are available.

Usage notes

  • 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.

See also