QsoStartAccept()--Start Asynchronous Accept Operation

 #include <sys/socket.h>
 #include <qsoasync.h>

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

        

The QsoStartAccept() function is used to wait asynchronously for connection requests. If connection requests are queued, then QsoStartAccept() takes the first connection request on the queue and creates a new socket to service the connection request. If no connection requests are queued, then an asynchronous QsoStartAccept() request is pended onto the socket and will be transition to the specified I/O completion port once a connection arrives. This API only supports sockets with an address family of AF_INET or AF_INET6 and type SOCK_STREAM.

Parameters

socketDescriptor (Input)

The descriptor of the socket on which to wait.

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	Not used.
bufferLength	Not used.
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	Not used.
fillBuffer	Not used.
returnValue	When QsoStartAccept() completes synchronously (function return value equals 0), then this field identifies the socket descriptor associated with the accepted connection. When the accept operation completes asynchronously, this field contains indication of success or failure.
errnoValue	(Output) - When the operation completes asynchronously and returnValue is negative, this field will contain 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 QSOSTARTACCEPT.
secureDataTransferSize	Not used.
bytesAvailable	(Output) - Number of bytes available to be read from connection. Only valid if returnValue is >=0.
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	(Output) - Must be set to hex zeroes.
reserved2	(Input) - Must be set to hex zeroes.

Authorities

No authorization is required.

Return Values

QsoStartAccept() 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 obtain connection descriptor and bytesAvailable.
• 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 QsoStartAccept() fails, errno can be set to one of the following:

[EFAULT]	Bad address
[EINVAL]	A I/O completion port or reserved field specified was not valid or postedDescriptor was not zero or operationWaitTime.tv_sec was negative or operationWaitTime.tv_usec was not zero, or a Listen() has not been issued against the socket referenced by the SocketDescriptor parameter.
[EACCES]	Permission denied. A connection indication request was received on the socket referenced by the socket_descriptor parameter, but the process that issued the QsoStartAccept() did not have the appropriate privileges required to handle the request. The connection indication request is reset by the system.
[EBADF]	Descriptor not valid.
[ECONNABORTED]	Connection ended abnormally. An QsoStartAccept() was issued on a socket for which receives have been disallowed (due to a shutdown() call).
[EIO]	Input/output.
[EMFILE]	Too many descriptors for this process.
[ENFILE]	Too many descriptors in system.
[ENOBUFS]	There is not enough buffer space for the requested operation.
[ENOTSOCK]	The specified descriptor does not reference a socket.
[EOPNOTSUPP]	Operation not supported. The socket_descriptor parameter references a socket that does not support the QsoStartAccept(). The QsoStartAccept() is only valid on sockets with an address family of AF_INET or AF_INET6 and type SOCK_STREAM. The socket_descriptor parameter references a socket that has undergone an Rbind(). The QsoStartAccept() operation is not valid on sockets in this state.
[EPERM]	The operation is not permitted. A user exit program registered for the exit point, QIBM_QSO_ACCEPT, has rejected the incoming connection being accepted.
[EUNATCH]	The protocol required to support the specified address family is not available at this time.
[EUNKNOWN]	Unknown system state.

Error Messages

Usage Notes

1. It is not recommended to intermix QsoStartAccept() and accept(). If this condition occurs, the order the requests will be serviced is undefined.
   
   
2. The following are inherited by the descriptor returned by the accept() call:
   • All socket options with a level of SOL_SOCKET.
   • The status flags:
     • Blocking flag (set/reset either by the iocltl() call with the FIONBIO request or by the fcntl() call with the F_SETFL command and the status flag set to O_NONBLOCK).
     • Asynchronous flag (set/reset either by the ioctl() call with the FIOASYNC request or by the fcntl() call with the F_SETFL command and the status flag set to FASYNC).
   • The process ID or process group ID that is to receive SIGIO or SIGURG signals (set/reset by either the ioctl() call with the FIOSETOWN or the SIOCSPGRP request, or by the fcntl() call with the F_SETOWN command).
   
   
   
3. Closing a socket causes any queued but unaccepted connection requests to be reset.

4. A user exit point, QIBM_QSO_ACCEPT, exists to optionally accept or reject incoming connections being accepted based on the return code from the registered user exit program. For more information refer to Sockets accept() API Exit Program.

Related Information

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

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