gsk_secure_soc_startSend()--Start asynchronous send operation on a secure session
Syntax
#include <gskssl.h> #include <qsoasync.h> int gsk_secure_soc_startSend (gsk_handle my_session_handle, int IOCompletionPort, Qso_OverlappedIO_t * communicationsArea)Service Program Name: QSYS/QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
The gsk_secure_soc_startSend() function is used to initiate an asynchronous send operation on a secure session. The supplied send buffer cannot be reused by the calling application until the send is complete or the I/O completion port specified on the gsk_secure_soc_startSend() 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
written.
- 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 of data that should be sent over the socket.
bufferLength (Input) - The length of the data to be sent.
postFlag (Input) - The postFlag indicates if this operation should be posted to the I/O completion port even if it completes immediately. - A value of 0 indicates that if the operation is already complete upon return to the application, then do not post to the I/O completion port.
- A value of 1 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_startSend() 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) - Only used on gsk_secure_soc_startRecv() or QsoStartRecv(). Ignored on gsk_secure_soc_startSend().
returnValue (Output) - If gsk_secure_soc_startSend() completes synchronously (return value equals GSK_OK), then this field is set to GSK_OK and field secureDataTransferSize indicates number of bytes sent.
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 GSKSECURESOCSTARTSEND.
secureDataTransferSize (Output) - Number of bytes sent when gsk_secure_soc_startSend() completes synchronously (function 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. 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
gsk_secure_soc_startSend() 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 sent.
-
GSK_IBMI_ASYNCHRONOUS_SEND - 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_SOCKET_CLOSED]
-
A close() was done on the socket descriptor for this secure session.
- [GSK_ IBMI_ERROR_INVALID_POINTER]
-
The buffer pointer located in Qso_OverlappedIO_t communications area is not valid.
- [GSK_INTERNAL_ERROR]
An unexpected error occurred during SSL processing.
- [GSK_IBMI_ERROR_INVALID_OVERLAPPEDIO_T]
The Qso_OverLappedIO_t specified was not valid.
- [GSK_IBMI_ERROR_INVALID_IOCOMPLETIONPORT]
The I/O completion port specified was not valid.
- [GSK_IBMI_ERROR_BAD_SOCKET_DESCRIPTOR]
The socket descriptor specified within the gsk_handle was not valid.
- [GSK_ERROR_SSL_CLOSED]
A gsk_secure_soc_misc(GSK_CLOSE_NOTIFY) was previously performed on this secure session.
- [GSK_ERROR_SEQNUM_EXHAUSTED]
A secure connection using TLSv1.1 or higher protocol has sent or received more than 264-1 SSL records. To prevent this error perform a gsk_secure_soc_misc(GSK_RESET_CIPHER) operation before the record limit is reached. A general guideline would be once a day for long lived secure connections.
- GSK_ERROR_IO]
An error occured in SSL processing; check the errno value.
Error Conditions
When gsk_secure_soc_startSend() API fails with return code [GSK_ERROR_IO], errno can be set to:
- [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.
- [ENOTSOCK]
-
The specified descriptor does not reference a socket.
- [EPIPE]
-
Broken pipe.
- [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
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
CPFA081 E | Unable to set return value or error code. |
Usage Notes
-
Since gsk_secure_soc_startSend() is asynchronous, care should
be used to control how many of these functions are outstanding. When a TCP
socket becomes flow control blocked such that the gsk_secure_soc_startSend()
is not able to pass the data to the TCP socket immediately, the return value
will be GSK_IBMI_ASYNCHRONOUS_SEND. Applications that send large amounts of
data should have the postFlag set to 0. This allows the application to use a
return value of GSK_IBMI_ASYNCHRONOUS_SEND as an indication that the socket has
become flow control blocked. The application should then wait for the
outstanding operation to complete before issuing another gsk_secure_soc_startSend().
This will ensure that the application does not exhaust system buffer resources.
-
A buffer that is given to gsk_secure_soc_startSend() 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 QsoDestroyForIOCompletionPort()
on the I/O completion port. If a buffer is given to
gsk_secure_soc_startSend() to be sent, and it is
later detected during gsk_secure_soc_startSend()
processing that the buffer has been freed, it may produce an
unrecoverable condition on the socket for which the
gsk_secure_soc_startSend() was issued. If this
occurs, an ECONNABORTED error value will be returned.
-
There is no maximum length of data that can be written.
-
It is not recommended to intermix gsk_secure_soc_startSend()
and blocking I/O (ie, send() or gsk_secure_soc_write()) on the
same socket. If one does, then pending asynchronous send I/O will be
serviced before blocking I/O once data can be sent.
-
It is strongly suggested that you do not mix the gsk_secure_soc_write() nor
gsk_secure_soc_startSend() APIs with any of the
sockets write 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_write() and
gsk_secure_soc_startSend()APIs.
-
Socket option SO_SNDTIMEO is not supported by this API. Semantics similar to
SO_SNDTIMEO can be obtained using the operationWaitTime field in the
Qso_OverLappedIO_t structure.
Related Information
-
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_read()--Receive data on a
secure session
-
gsk_secure_soc_startInit()--Start Asynchronous
Operation to negotiate a secure session
-
gsk_secure_soc_startRecv()--Start Asynchronous
Receive Operation on a secure session
-
QsoCancelOperation()--Cancel
an I/O Operation
-
QsoPostIOCompletionPort()--Post Request on I/O
Completion Port
-
QsoCreateIOCompletionPort()--Create I/O
Completion Port
-
QsoDestroyIOCompletionPort()--Destroy
I/O Completion Port
-
QsoStartRecv--Start Asynchronous Recv Operation
-
QsoStartSend--Start Asynchronous Send Operation
-
QsoWaitForIOCompletion()--Wait for I/O
Completion Operation
- send()--Send Data
API introduced: V5R1
Top | UNIX-Type APIs | APIs by category |