QsoWaitForIOCompletion()--Wait for I/O Operation

 #include <gskssl.h>
 #include <qsoasync.h

 int QsoWaitForIOCompletion (int IOCompletionPort,
 Qso_OverlappedIO_t * completionStatus,
 struct timeval * timeToWait)

        

The QsoWaitForIOCompletion() is used to wait for a completed overlapped I/O operation. The wait point is represented by the I/O completion port that was created using the QsoCreateIOCompletionPort() function.

Parameters

int IOCompletionPort

(Input) The I/O completion port on which to wait.

Qso_OverlappedIO_t * completionStatus

(Input/Output) A pointer to a qso_overlappedIO_t structure that will be updated with the status defined below. If a field has no relevance to operation completed, then either a null or zero will be returned for that field.

descriptorHandle	(Output) The descriptor handle that was supplied by the application when the operation was started.
buffer	(Output) A pointer to the buffer that was supplied when the operation was started. Null is returned when operationCompleted is QSOSTARTACCEPT or GSKSECURESOCSTARTINIT .
bufferLength	(Output) The length of the buffer that was supplied when the operation was started. Zero is returned when operationCompleted is QSOSTARTACCEPT or GSKSECURESOCSTARTINIT.
postFlag	(Output) The value of the postFlag when the operation was started. Zero is returned when operationCompleted is QSOSTARTACCEPT or GSKSECURESOCSTARTINIT .
fillBuffer	(Output) The value of the fillBuffer when the operation was started. Zero is returned when operationCompleted is QSOSTARTACCEPT or GSKSECURESOCSTARTINIT .
returnValue	(Output) Possible values if operation completed is QSOPOSTIOCOMPLETION, QSOSTARTRECV, QSOSTARTSEND, or QSOSTARTACCEPT: -1 The operation failed and errnoValue field should be checked for further explanation of the error. >= 0 For both QSOSTARTRECV and QSOSTARTSEND, indicates the number of bytes sent or received respectively. A return value of 0 on a receive indicates an end-of-file condition. For QSOSTARTACCEPT, this field is the socket connection descriptor. For QSOPOSTIOCOMPLETION, a return value of 0 indicates the operation was not timed (operationWaitTime was zero on input). QSOPOSTIOCOMPLETION will not return > 0. Possible values if operation completed is GSKSECURESOCSTARTSEND or GSKSECURESOCSTARTRECV: GSK_OK Operation was successful. Field secureDataTransferSize indicates the number of bytes sent or received respectively. Failure Possible values common to GSKSECURESOCSTARTSEND and GSKSECURESOCSTARTRECV: [GSK_AS400_ERROR_INVALID_POINTER] The buffer pointer located in the Qso_OverLappedIO_t is not valid. [GSK_INTERNAL_ERROR] An unexpected error occurred during SSL processing. [GSK_AS400_ERROR_CLOSED] Secure session was closed by a thread during SSL processing. [GSK_ERROR_IO] An error occurred in SSL processing; check the errno value. [GSK_ERROR_SOCKET_CLOSED] A close() was done on the socket descriptor for this secure session. Values unique to GSKSECURESOCSTARTRECV: [GSK_INVALID_HANDLE] The handle specified was not valid. [GSK_INVALID_STATE] The handle is not in the correct state for this operation. [GSK_ERROR_BAD_MESSAGE] SSL received a badly formatted message. [GSK_ERROR_BAD_MAC] A bad message authentication code was received.
	Possible values if operationCompleted is GSKSECURESOCSTARTINIT: [GSK_OK] Operation was successful, a secure session established. [GSK_ERROR_BAD_MESSAGE] SSL received a badly formatted message. [GSK_ERROR_BAD_MAC] A bad message authentication code was received. [GSK_KEYRING_OPEN_ERROR] Certificate store file could not be opened. [GSK_ERROR_BAD_KEYFILE_LABEL] The specified certificate store label is not valid. [GSK_ERROR_BAD_V3_CIPHER] An SSLV3 or TLSV1 cipher suite was specified that is not valid. [GSK_ERROR_BAD_V2_CIPHER] An SSLV2 cipher suite was specified that is not valid. [GSK_ERROR_NO_CIPHERS] No ciphers available or no ciphers were specified. [GSK_ERROR_NO_CERTIFICATE] No certificate is available for SSL processing. [GSK_ERROR_BAD_CERTIFICATE] The certificate is bad. [SSL_ERROR_NOT_TRUSTED_ROOT] The certificate is not signed by a trusted certificate authority. [GSK_KEYFILE_CERT_EXPIRED] The validity time period of the certificate has expired. [GSK_ERROR_BAD_MESSAGE] A badly formatted message was received. [GSK_ERROR_UNSUPPORTED] Operation is not supported by SSL. [GSK_ERROR_BAD_PEER] The peer system is not recognized. [GSK_ERROR_CLOSED] The SSL session ended. [GSK_AS400_ERROR_TIMED_OUT] The value specified for the handshake timeout expired before the handshake completed. [GSK_INSUFFICIENT_STORAGE] Unable to allocate storage for the requested operation.

errnoValue

(Output) If operationCompleted is QSOPOSTIOCOMPLETION, QSOSTARTSEND, QSOSTARTRECV or QSOSTARTACCEPT and returnValue is negative, this field will contain an errno value further defining the error. This is also true if operationCompleted is GSKSECURESOCSTARTINIT, GSKSECURESOCSTARTSEND or GSKSECURESOCSTARTRECV and returnValue is GSK_ERROR_IO.

Possible values are:

[ECANCELED]

The operation was cancelled by QsoCancelOperation().

If operationCompleted is QSOPOSTIOCOMPLETION:

[EAGAIN]	The specified timer value expired.
[ECLOSED]	The socket descriptor was closed before the timer expired.

If operationCompleted is QSOSTARTRECV or GSKSECURESOCSTARTRECV:

[EAGAIN]	The operation did not complete in the specified time.
[EIO]	Input/output error.
[ECONNABORTED]	Connection ended abnormally. This error code indicates that the transport provider ended the connection abnormally because of one of the following: The retransmission limit has been reached for the data that was being sent on the socket. A protocol error was detected.
[ECONNRESET]	A connection with a remote socket was reset by that socket.
[ECLOSED]	Connection was closed. Only valid for QSOSTARTRECV.
[EFAULT]	Read buffer pointer not valid.

If operationCompleted is QSOSTARTSEND or GSKSECURESOCSTARTSEND:

[EAGAIN]	The operation did not complete in the specified time.
[EIO]	Input/output error.
[EPIPE]	Broken pipe.
[ECLOSED]	Connection was closed. Only valid for QSOSTARTSEND
[EFAULT]	Send buffer pointer not valid.

If operationCompleted is QSOSTARTACCEPT:

[EAGAIN]	The operation did not complete in the specified time.
[ECONNABORTED]	Connection ended abnormally.
[ECLOSED]	Listening socket closed.
[EIO]	Input/output error.
[EMFILE]	Too many descriptors for this process.
[ENFILE]	Too many descriptors in system.
[ENOBUFS]	There is not enough buffer space for the requested operation.
[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.
[EUNKNOWN]	Unknown system state.

If operationCompleted is GSKSECURESOCSTARTINIT:

[ECONNABORTED]	Connection ended abnormally.
[EDEADLK]	Resource deadlock avoided.
[EINTR]	Interrupted function call.
[EIO]	Input/output error.
[ETERM]	Operation terminated.
[EUNATCH]	The protocol required to support the specified address family is not available at this time.

Any errno that can be returned by send() or recv() can be returned by this API if operationCompleted is GSKSECURESOCSTARTINIT. See Sockets APIs for a description of the errno values they return.

If an errno is returned that is not in this list, see Errno Values for UNIX^®-Type Functions for a description of the errno.

operationCompleted	(Output) The operation that was started and has now completed. 1 (QSOSTARTSEND) 2 (QSOSTARTRECV) 3 (QSOPOSTIOCOMPLETION) 4 (GSKSECURESOCSTARTSEND) 5 (GSKSECURESOCSTARTRECV) 6 (QSOSTARTACCEPT) 7 (GSKSECURESOCSTARTINIT)
secureDataTransferSize	(Output) Number of bytes received or sent if operationCompleted is GSKSECURESOCSTARTRECV or GSKSECURESOCSTARTSEND respectively and returnValue equals GSK_OK.
bytesAvailable	(Output) Number of bytes available to be read from connection. This parameter is valid only if operationCompleted is QSOSTARTACCEPT and returnValue is >= 0.
operationWaitTime	(Output) The value of the operationWaitTime when the operation was started.
postedDescriptor	(Output) Always set to negative one. This field is only used on input for QsoPostIOCompletion(). When the operation is retrieved with QsoWaitForIOCompletion(), the descriptorHandle should be used to identify the socket connection and not this field.
operationId	(Output) - An identifier to uniquely identify this operation or a group of operations. This value is preserved from the start operation and returned by QsoWaitForIOCompletion(). It is ignored unless QsoCancelOperation() or QsoIsOperationPending() is used.

struct timeval * timeToWait

(Input) A pointer to a timeval structure that contains the time in seconds and microseconds for which the QsoWaitForIOCompletion() call should block if there is no completion status to receive.

If this parameter is null, QsoWaitForIOCompletion() waits indefinitely. If this value is specified, and 0 seconds 0 microseconds are specified, QsoWaitForIOCompletion() returns immediately.

Authorities

Authorization of *R (allow access to the object) to the certificate store file and its associated files is required. Authorization of *X (allow use of the object) to each directory of the path name of the certificate store file and its associated files is required.

Return Values

QsoWaitForIOCompletion returns an integer. Possible value are:

Errno Conditions

When QsoWaitForIOCompletion fails, errno can be set to one of the following:

Error Messages

Usage Notes

1. An errno of EDESTROYED indicates that the thread was waiting on the I/O completion port at the time that it was destroyed by another thread. When an I/O completion port is destroyed, all buffers that are associated with outstanding overlapped I/O operations are immediately available for use by the application program.
   
   
2. The application should first check the return value of the QsoWaitForIOCompletion() call to determine if the Qso_OverlappedIO_t structure specified by the completionStatus parameter has been updated. This structure is updated ONLY if the return value of the QsoWaitForIOCompletion() call is one (1).

Related Information

• QsoCancelOperation()--Cancel an I/O Operation
  
  
• QsoIsOperationPending()--Check if an I/O Operation is Pending
  
  
• QsoCreateIOCompletionPort()--Create I/O Completion Port
  
  
• QsoDestroyIOCompletionPort()--Destroy I/O Completion Port
  
  
• QsoPostIOCompletionPort()--Post Request on I/O Completion Port
  
  
• QsoStartAccept()--Start asynchronous accept operation
  
  
• QsoStartRecv()--Start Asynchronous Recv Operation
  
  
• QsoStartSend()--Start Asynchronous Send Operation
  
  
• gsk_secure_soc_startRecv()--Start Asynchronous Receive Operation on a secure session
  
  
• gsk_secure_soc_startSend()--Start Asynchronous Send Operation on a secure session
  
  
• gsk_secure_soc_startInit()--Start Asynchronous Operation to negotiate a secure session

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