gsk_secure_soc_startRecv()--Start asynchronous receive operation on a secure session

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

 int gsk_secure_soc_startRecv (gsk_handle my_session_handle,
                              int IOCompletionPort,
                              Qso_OverlappedIO_t * communicationsArea)

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

Parameters

my_session_handle (Input)

The handle, returned from gsk_secure_soc_open() and used on the gsk_secure_soc_init() API call that initialized the secure session over which data is to be read.

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 gsk_secure_soc_startRecv() 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) - IF gsk_secure_soc_startRecv() completes synchronously (function return value equals GSK_OK), then this field is set to GSK_OK and field secure data transfer size indicates number of bytes received.
errnoValue	(Output) - When the operation has completed asynchronously and returnValue is GSK_ERROR_IO, this field will contain an errno further defining the failure.
operationCompleted	(Output) - If the operation is posted to the I/O completion port, this field is updated to indicate that the operation was a GSKSECURESOCSTARTRECV.
secureDataTransferSize	(Output) - Number of bytes received when gsk_secure_soc_startRecv() completes synchronously (return value equals GSK_OK).
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.
reserved1	(Output) - Must be set to hexadecimal zeroes.
reserved2	(Input) - Must be set to hexadecimal zeroes.

Authorities

No authorization is required.

Return Values

gsk_secure_soc_startRecv() returns an integer. Possible values are:

• GSK_OK - The function has completed synchronously. The Qso_OverlappedIO_t communications structure has been updated but nothing has nor will be posted to the I/O completion port for this operation. Inspect field secureDataTransferSize in the Qso_OverlappedIO_t communications structure to determine the number of bytes received.
  
  
• GSK_AS400_ASYNCHRONOUS_RECV - 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.
  
  
• If the function fails, possible values are:
  
  

  [GSK_INVALID_HANDLE]

  The handle specified was not valid.

  [GSK_INVALID_STATE]

  The handle is not in the correct state for this operation.

  [GSK_INVALID_BUFFER SIZE]

  The bufferLength field located in the Qso_OverLappedIO_t communications area is less than 1.

  [GSK_ERROR_BAD_MESSAGE]

  SSL received a badly formatted message.

  [GSK_ERROR_BAD_MAC]

  A bad message authentization code was received.

  [GSK_ AS400_ERROR_INVALID_POINTER]

  The buffer pointer located in Qso_OverLappedIO_t communications area is not valid.

  [GSK_ERROR_SOCKET_CLOSED]

  A close() was done on the socket descriptor for this secure session.

  [GSK_INTERNAL_ERROR]

  An unexpected error occurred during SSL processing.

  [GSK_AS400_ERROR_INVALID_ OVERLAPPEDIO_T]

  The Qso_OverLappedIO_t specified was not valid.

  [GSK_AS400_ERROR_INVALID_ IOCOMPLETIONPORT]

  The I/O completion port specified was not valid.

  [GSK_AS400_ERROR_BAD_SOCKET_DESCRIPTOR]

  The socket descriptor specified within the gsk_handle was not valid.

  [GSK_ERROR_IO]

  An error occured in SSL processing; check the errno value.

Error Conditions

When gsk_secure_soc_startRecv() API fails with return code [GSK_ERROR_IO], errno can be set to:

[ECONNRESET]

A connection with a remote socket was reset by that socket.

[EINVAL]

The field operationWaitTime.tv_sec was negative or operationWaitTime.tv_usec was not zero or postedDescriptor was not zero.

[EIO]

Input/output error.

[ENOTCONN]

Requested operation requires a connection.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

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

Error Messages

Usage Notes

1. A buffer that is given to gsk_secure_soc_startRecv() 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 gsk_secure_soc_startRecv() to be filled, and it is later detected during gsk_secure_soc_startRecv() processing that the buffer has been freed, it may produce an unrecoverable condition on the socket for which the gsk_secure_soc_startRecv() was issued. If this occurs, an ECONNABORTED error value will be returned.
   
   
2. It is not recommended to intermix gsk_secure_soc_startRecv() and blocking I/O (ie, recv() or gsk_secure_soc_read()) on the same socket. If this condition occurs, then pending asynchronous recv I/O will be serviced first before the blocking I/O.
   
   
3. The maximum length of data typically returned will not exceed 16 KB. This is due to the fact that SSL is a record level protocol and the largest record allowed is 32 KB minus the necessary SSL record headers.
   
   
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.
   
   
6. It is strongly suggested that you do not mix the gsk_secure_soc_read() nor gsk_secure_soc_startRecv() APIs with any of the sockets read functions. However, SSL and socket reads and writes can be mixed, but they must be performed in matched sets. If a client application writes 100 bytes of data using one or more of the socket send() calls, then the server application must read exactly 100 bytes of data using one or more of the socket recv() calls. This is also true for gsk_secure_soc_read() and gsk_secure_soc_startRecv() APIs.
   
   
7. A FIONREAD ioctl() cannot be used to determine the amount of data available for reading by using gsk_secure_soc_startRecv().
   
   
8. SSL will ignore the out of band (OOB) data indicator. OOB will not affect the SSL application. OOB will only be data to the SSL protocol.
   
9. For an SSL enabled socket, which must use a connection-oriented transport service (that is, TCP), a returned value of zero in the secureDataTransferSize field indicates one of the following:
   • The partner program has issued a close() for the socket.
     
     
   • The partner program has issued a secure close for the secure session. For example, if the partner program was coded using the GSKit APIs, the partner issued gsk_secure_soc_close().
     
     
   • The partner program has issued a shutdown() to disable writing to the socket.
     
     
   • The connection is broken and the error was returned on a previously issued socket function.
     
     
   • A shutdown() to disable reading was previously done on the socket.

Related Information

• gsk_secure_soc_close()--Close a Secure Session
  
  
• gsk_secure_soc_init()--Negotiate a secure session
  
  
• gsk_secure_soc_misc()--Perform miscellaneous functions for a secure session
  
  
• gsk_secure_soc_open()--Get a handle for a secure session
  
  
• gsk_secure_soc_startInit()--Start asynchronous operation to negotiate a secure session
  
  
• gsk_secure_soc_startSend()--Start Asynchronous Send Operation on a Secure Session
  
  
• gsk_secure_soc_write()--Send data on a secure session
  
  
• 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