QsoStartRecv()--Start Asynchronous Receive Operation

 #include <qsoasync.h>

 int QsoStartRecv (int socketDescriptor,int IOCompletionPort,
 Qso_OverlappedIO_t * communicationsArea)

        

The QsoStartRecv function is used to initiate an asynchronous receive operation. The supplied buffer cannot be reused by the calling application until the receive is complete or the I/O completion port specified on the QsoStartRecv has been destroyed. This API only supports sockets with an address family of AF_INET or AF_INET6 and type SOCK_STREAM.

Parameters

int socketDescriptor (Input)

The socket descriptor that should be used to receive data into the specified buffer.

int IOCompletionPort (Input)

The I/O completion port that should be posted when the operation completes.

Qso_OverlappedIO_t * communicationsArea (Input/Output)

A pointer to a structure that contains the following information:

descriptorHandle	(Input) - The descriptor handle is application specific and is never used by the system. This field is intended to make it easier for the application to keep track of information regarding a given socket connection.
buffer	(Input) - A pointer to a buffer into which data should be read.
bufferLength	(Input) - The length of the buffer into which data should be read. Also represents the amount of data requested.
postFlag	(Input) - The postFlag indicates if this operation should be posted to the I/O completion port even if it completes immediately. A 0 value indicates that if the operation is already complete upon return to the application, then do not post to the I/O completion port. A 1 value indicates that even if the operation completes immediately upon return to the application, the result should still be posted to the I/O completion port.
postFlagResult	(Output) - This field is valid if QsoStartRecv() returns with 1 and postFlag was set to 1. In this scenario, postFlagResult set to 1 denotes the operation completed and been posted to the I/O completion port specified. A value of 0 denotes the operation could not be completed immediately, but will be handled asynchronously.
fillBuffer	(Input) - The fillBuffer flag indicates when this operation should complete. If the fillBuffer flag is 0, then the operation will complete as soon as any data is available to be received. If the fillBuffer flag is non-zero, this operation will not complete until enough data has been received to fill the buffer, an end-of-file condition occurs on the socket, or an error occurs on a socket.
returnValue	(Output) - When QsoStartRecv() completes synchronously (function return value equals 0), then this field indicates the number of bytes that were actually received. When the recv operation completes asynchronously, this field contains indication of success or failure. Zero returned denotes end-of-file state.
errnoValue	(Output) - When the operation completes asynchronously and returnValue is negative, this field contains an errno to indicate the error with which the operation eventually failed.
operationCompleted	(Output) - If the operation is posted to the I/O completion port, this field is updated to indicate that the operation was a QsoStartRecv().
secureDataTransferSize	Not used.
bytesAvailable	Not used.
operationWaitTime	(Input) - A timeval structure which specifies the maximum time allowed for this operation to complete asynchronously. struct timeval { long tv_sec; /* second */ long tv_usec; /* microseconds */ }; If this timer expires, the operation will be posted to the I/O completion port with errnoValue set to EAGAIN. If this field is set to zero, the operation's asynchronous completion will not be timed. If socketDescriptor is closed before the operation completes or times out, the operation will be posted to the I/O completion port with errnoValue set to ECLOSED. The minimum operationWaitTime is 1 second. The microseconds field (tv_usec) in the timeval is not used and must be set to zero.
postedDescriptor	Not used - Must be set to zero.
operationId	(Input) - An identifier to uniquely identify this operation or a group of operations. It can be set with the return value from QsoGenerateOperationId() or with an application-defined value. This value is preserved but ignored by all APIs except QsoCancelOperation() and QsoIsOperationPending().
reserved1	(Input) - Must be set to hex zeroes.
reserved2	(Input) - Must be set to hex zeroes.

Authorities

No authorization is required.

Return Values

QsoStartRecv() returns an integer. Possible values are:

• -1 - The function was not started because an error occurred. Inspect the errno to determine the cause of the failure.
• 0 - The function has already completed. The Qso_OverlappedIO_t communications structure has been updated but nothing has or will be posted to the I/O completion port for this operation. Inspect the returnValue in the Qso_OverlappedIO_t communications structure to determine the number of bytes received.
• 1 - The function has been started. When the function completes (or times out if operationWaitTime was specified), the Qso_OverlappedIO_t communications structure will be updated with the results and the I/O completion port will be posted.

Errno Conditions

When QsoStartRecv() fails, errno can be set to one of the following:

Note: The rest of the errno values from recv() also apply to QsoStartRecv().

Error Messages

Usage Notes

1. If QsoStartRecv() partially fills a buffer and then encounters an EFAULT condition, the QsoStartRecv() will complete with the ETRUNC error value to indicate that some data has been lost.
   
   
2. A buffer that is given to QsoStartRecv() must not be used by the application again until either it is returned by QsoWaitForIOCompletion() or is reclaimed by issuing a close() on the socket descriptor or issuing a QsoDestroyIOCompletionPort() on the I/O completion port. If a buffer is given to QsoStartRecv() to be filled, and it is later detected during QsoStartRecv processing that the buffer has been freed, it may produce an unrecoverable condition on the socket for which the QsoStartRecv() was issued. If this occurs, an ECONNABORTED error value will be returned.
   
   
3. It is not recommended to intermix QsoStartRecv() and blocking I/O (that is, recv()) on the same socket. If this condition occurs, then pending asynchronous send I/O will be serviced first before the blocking I/O.
   
   
4. Socket option SO_RCVLOWAT is not supported by this API. Semantics similar to SO_RCVLOWAT can be obtained using the fillBuffer field in the Qso_OverLappedIO_t structure.
   
   
5. Socket option SO_RCVTIMEO is not supported by this API. Semantics similar to SO_RCVTIMEO can be obtained using the operationWaitTime field in the Qso_OverLappedIO_t structure.

Related Information

• QsoCancelOperation()--Cancel an I/O Operation
  
  
• QsoCreateIOCompletionPort()--Create I/O Completion Port
  
  
• QsoDestroyIOCompletionPort()--Create I/O Completion Port
  
  
• QsoPostIOCompletionPort()--Post Request on I/O Completion Port
  
  
• QsoStartSend--Start Asynchronous Send Operation
  
  
• QsoWaitForIOCompletion()--Wait for I/O Completion Operation
  
  
• recv()--Receive Data

[ Back to top | UNIX-Type APIs | APIs by category ]