Reads bytes from the specified socket and returns the number of bytes received.
[ lReturn = ] WsReceive ( socket, lTimeout [, enMode ], pDst [, lBytes] [, plRemotePort] [, pvRemoteHost] [, sEos] )
The WsReceive procedure syntax has the following parts:
Name |
Type |
Description |
lReturn |
Long |
If no error occurs, WsReceive returns the number of bytes received. Returns -1 if failed. |
socket |
Val ASocket |
A descriptor identifying a (possibly connected) socket. |
lTimeout |
Val Long |
The maximum length of time in milliseconds attempting to receive the data. |
enMode |
Val enumAIoMode |
Input receive mode. The default value is 0 (aioDefault) and aioDisableWsReceiveEarlyReturn can be combined with aioDisableBstrConvert. |
pDst |
Var Any |
The destination buffer for the bytes received. |
lBytes |
Val Long |
Maximum number of bytes to receive. If the default value is used (-1) the byte length of the pDst is used as the maximum of bytes to receive. |
plRemotePort |
Var Long |
Returned port number from which to receive the data. This parameter should be used only for socket that used the UDP protocol. |
pvRemoteHost
|
Var Variant |
Returned host address of the port. The port from which to receive the data. This parameter should be used only for socket that used the UDP protocol. See comments for more information. |
sEOS |
Val BString |
End of String (terminator) - the input will be terminated when the EOS string is received. The default value is an Empty string. |
enumAIoMode can have one of the following values:
Name |
Value |
Description |
aioDefault |
0 |
Receive data available |
aioWaitGpibSrqVxiDor |
1 |
Receive on Srq (gpib) or on Dor (vxi) |
aioGpibImmediateOrSrq |
2 |
Receive on Immediate or Srq (gpib) |
aioDisableBstrConvert |
4 |
Disable conversion of BString to String |
aioDisableComReceiveEarlyReturn (v 6.0) |
8 |
Disable early return from ComReceive |
aioDisableWsReceiveEarlyReturn (v.6.0) |
0x10 |
Disable early return from WsReceive |
Receives data with a remote host using the WsReceive function.
If enMode, input receive mode includes aioDisableWsReceiveEarlyReturn, it prevents WsReceive from an "early return" when there is a momentary interruption in the data being received.
The usage of the WsReceive function is slightly different when utilizing the TCP protocol than when using the UDP protocol.
When using a TCP connection-oriented stream, once client and server sockets are connected, you can use the WsSend and WsReceive functions to exchange data. Omit the lRemotePort and lRemoteHost parameters for the functions.
The WsSend function writes outgoing data on a connected socket. The WsReceive function reads incoming data on connection-oriented sockets.
The UDP datagram socket application calls WsReceive with the plRemotePort and pvRemoteHost parameters to prepare to receive data from a remote host. The WsReceive function reads incoming data on unconnected sockets and captures the address from which the data was sent. To do this, the local address of the socket must be known. pvRemoteHost was defined as Long prior to ATEasy 2024 (v13) and is now variant a long number (vtI4) for IPv4 and an array of 16 bytes (vtArray or vtU1) for IPv6 addresses.
The WsSend function is used on a connectionless socket to send a datagram to a specific peer socket identified by the lRemotePort and lRemoteHost parameters.
The function will return if any of the following conditions is met: 1) if the number of bytes received is equal to lBytes or 2) if the timeout time (lTimeout) is expired or 3) if the terminator is received.
If sEos parameter is an empty string and aioDisableWsReceiveEarlyReturn mode flag is not used (default case), the function will return immediately if characters are found in the input buffer, and the timeout will be ignored. Using the aioDisableWsReceiveEarlyReturn flag will ensure that the function will return only if the timeout is reached or all lBytes characters were received.
The function will return -1 if sEOS was specified (not empty string) but was not received. If no terminator (sEOS was specified and no data was received (timeout) the function will return 0.
The following two examples will attempt to receive data until data is received, in both the TCP and UDP protocols.
while True
! Attempt to Receive data from the remote host:
if WsReceive(lSocket, 1000, , sData, ,lRemotePort, vRemoteHost)>0
exitloop
endif
endwhile
while True
! Attempt to Receive data from the remote host:
if WsReceive(lSocket, 1000, , sData)>0
exitloop
endif
endwhile