ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/gskstartsend.htm

553 lines
16 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>gsk_secure_soc_startSend()--Start asynchronous send operation on a
secure session</title>
<!-- Begin Header Records -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- Created for V5R1 -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- End Header Records -->
<!--Java sync-link-->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<h2>gsk_secure_soc_startSend()--Start asynchronous send operation on a secure
session</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Syntax
<pre>
#include &lt;gskssl.h&gt;
#include &lt;qsoasync.h&gt;
int gsk_secure_soc_startSend (gsk_handle my_session_handle,
int IOCompletionPort,
Qso_OverlappedIO_t * communicationsArea)
</pre>
&nbsp;&nbsp;Service Program Name: QSYS/QSOSSLSR<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>gsk_secure_soc_startSend()</strong> 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
<strong>gsk_secure_soc_startSend()</strong> has been destroyed. This API
supports sockets with an address family of AF_INET or AF_INET6 and type SOCK_STREAM only.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><em><strong>my_session_handle</strong></em>&nbsp;(Input)</dt>
<dd>The handle, returned from <strong>gsk_secure_soc_open()</strong> and used
on the <strong>gsk_secure_soc_init()</strong> API call that initialized the
secure session over which data is to be written.<br>
<br>
</dd>
<dt><em><strong>int IOCompletionPort</strong></em>&nbsp;(Input)</dt>
<dd>The I/O completion port that should be posted when the operation
completes.<br>
<br>
</dd>
<dt><em><strong>Qso_OverlappedIO_t</strong> *
communicationsArea</em>&nbsp;(Input/Output)</dt>
<dd>A pointer to a structure that contains the following information:<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><strong><em>descriptorHandle</em></strong> </td>
<td align="left" valign="top">(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.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>buffer</em></strong> </td>
<td align="left" valign="top">(Input) - A pointer to a buffer of data that
should be sent over the socket.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>bufferLength</em></strong> </td>
<td align="left" valign="top">(Input) - The length of the data to be sent.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>postFlag</em></strong> </td>
<td align="left" valign="top">(Input) - The postFlag indicates if this
operation should be posted to the I/O completion port even if it completes
immediately.
<ul>
<li>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.</li>
<li>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.</li>
</ul>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>postFlagResult</em></strong> </td>
<td align="left" valign="top">(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.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>fillBuffer</em></strong> </td>
<td align="left" valign="top">(Input) - Only used on
<strong>gsk_secure_soc_startRecv()</strong> or <strong>QsoStartRecv()</strong>.
Ignored on <strong>gsk_secure_soc_startSend()</strong>.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>returnValue</em></strong> </td>
<td align="left" valign="top">(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.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em><strong>errnoValue</strong></em> </td>
<td align="left" valign="top">(Output) - When the operation has completed
asynchronously and returnValue is GSK_ERROR_IO, this field will contain an
errno further defining the failure.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>operationCompleted</em></strong>
</td>
<td align="left" valign="top">(Output) - If the operation is posted to the I/O
completion port, this field is updated to indicate that the operation was a
GSKSECURESOCSTARTSEND.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>secureDataTransferSize</em></strong>
</td>
<td align="left" valign="top">(Ouput) - Number of bytes sent when
<strong>gsk_secure_soc_startSend()</strong> completes synchronously (function
return value equals GSK_OK).<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>bytesAvailable</em></strong> </td>
<td align="left" valign="top">Not used. </td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>operationWaitTime</em></strong> </td>
<td align="left" valign="top">(Input) - A timeval structure which specifies the
maximum time allowed for this operation to complete asynchronously.
<pre>
struct timeval {
long tv_sec; /* second */
long tv_usec; /* microseconds */
};
</pre>
If this timer expires, the operation will be posted to the I/O completion port
with <em>errnoValue</em> set to EAGAIN.<br>
<br>
If this field is set to zero, the operation's asynchronous completion will not
be timed.<br>
<br>
If socketDescriptor is closed before the operation completes or times out, the
operation will be posted to the I/O completion port with <em>errnoValue</em>
set to ECLOSED.<br>
<br>
The minimum operationWaitTime is 1 second. The microseconds field (tv_usec) in
the timeval is not used and must be set to zero. </td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>postedDescriptor</em></strong> </td>
<td align="left" valign="top">Not used - Must be set to zero. </td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>reserved1</em></strong> </td>
<td align="left" valign="top">(Input) - Must be set to hex zeroes.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong><em>reserved2</em></strong> </td>
<td align="left" valign="top">(Input) - Must be set to hex zeroes. </td>
</tr>
</table>
</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>No authorization is required.</p>
<br>
<h3>Return Values</h3>
<p><strong>gsk_secure_soc_startSend()</strong> returns an integer. Possible
values are:</p>
<ul>
<li>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.<br>
<br>
</li>
<li>GSK_AS400_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.<br>
<br>
</li>
<li>If the function fails, possible values are:<br>
<br>
<dl>
<dt>[GSK_INVALID_HANDLE]</dt>
<dd>
<p>The handle specified was not valid.</p>
</dd>
<dt>[GSK_INVALID_STATE]</dt>
<dd>
<p>The handle is not in the correct state for this operation.</p>
</dd>
<dt>[GSK_INVALID_BUFFER SIZE]</dt>
<dd>
<p>The bufferLength field located in the Qso_OverLappedIO_t communications area
is less than 1.</p>
</dd>
<dt>[GSK_ERROR_SOCKET_CLOSED]</dt>
<dd>
<p>A <strong>close()</strong> was done on the socket descriptor for this secure
session.</p>
</dd>
<dt>[GSK_ AS400_ERROR_INVALID_POINTER]</dt>
<dd>
<p>The buffer pointer located in Qso_OverlappedIO_t communications area is not
valid.</p>
</dd>
<dt>[GSK_INTERNAL_ERROR]</dt>
<dd>
<p>An unexpected error occurred during SSL processing.</p>
</dd>
<dt>[GSK_AS400_ERROR_INVALID_ OVERLAPPEDIO_T]</dt>
<dd>
<p>The Qso_OverLappedIO_t specified was not valid.</p>
</dd>
<dt>[GSK_AS400_ERROR_INVALID_ IOCOMPLETIONPORT]</dt>
<dd>
<p>The I/O completion port specified was not valid.</p>
</dd>
<dt>[GSK_AS400_ERROR_BAD_SOCKET_DESCRIPTOR]</dt>
<dd>
<p>The socket descriptor specified within the gsk_handle was not valid.</p>
</dd>
<dt>GSK_ERROR_IO]</dt>
<dd>
<p>An error occured in SSL processing; check the <strong>errno</strong>
value.</p>
</dd>
</dl>
</li>
</ul>
<br>
<h3>Error Conditions</h3>
<p>When <strong>gsk_secure_soc_startSend()</strong> API fails with return code
[GSK_ERROR_IO], <em>errno</em> can be set to:</p>
<dl>
<dt><em>[EINVAL]</em></dt>
<dd>
<p>The field operationWaitTime.tv_sec was negative or operationWaitTime.tv_usec
was not zero or postedDescriptor was not zero.</p>
</dd>
<dt><em>[EIO]</em></dt>
<dd>
<p>Input/output error.</p>
</dd>
<dt><em>[ENOTCONN]</em></dt>
<dd>
<p>Requested operation requires a connection.</p>
</dd>
<dt><em>[ENOTSOCK]</em></dt>
<dd>
<p>The specified descriptor does not reference a socket.</p>
</dd>
<dt><em>[EPIPE]</em></dt>
<dd>
<p>Broken pipe.</p>
</dd>
<dt><em>[EUNATCH]</em></dt>
<dd>
<p>The protocol required to support the specified address family is not
available at this time.</p>
</dd>
</dl>
<p>If an <em>errno</em> is returned that is not in this list, see <a href=
"unix14.htm">Errno Values for UNIX-Type Functions</a> for a description of the
<em>errno</em>.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPE3418 E</td>
<td width="85%" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA081 E</td>
<td align="left" valign="top">Unable to set return value or error code.</td>
</tr>
</table>
<br>
<h3>Usage Notes</h3>
<ol>
<li>Since <strong>gsk_secure_soc_startSend()</strong> 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
<strong>gsk_secure_soc_startSend()</strong> is not able to pass the data to the
TCP socket immediately, the return value will be GSK_AS400_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_AS400_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 <strong>gsk_secure_soc_startSend()</strong>.
This will ensure that the application does not exhaust system buffer
resources.<br>
<br>
</li>
<li>A buffer that is given to <strong>gsk_secure_soc_startSend()</strong> 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 <strong>gsk_secure_soc_startSend()</strong> to be
sent, and it is later detected during
<strong>gsk_secure_soc_startSend()</strong> processing that the buffer has been
freed, it may produce an unrecoverable condition on the socket for which the
<strong>gsk_secure_soc_startSend()</strong> was issued. If this occurs, an
ECONNABORTED error value will be returned.<br>
<br>
</li>
<li>There is no maximum length of data that can be written.<br>
<br>
</li>
<li>It is not recommended to intermix
<strong>gsk_secure_soc_startSend()</strong> and blocking I/O (ie, send() or
gsk_secure_soc_send()) 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.<br>
<br>
</li>
<li>It is strongly suggested that you do not mix the
<strong>gsk_secure_soc_write()</strong> nor
<strong>gsk_secure_soc_startSend()</strong> 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 <strong>gsk_secure_soc_write()</strong> and
<strong>gsk_secure_soc_startSend()</strong>APIs.</li>
<li>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.<br>
<br>
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li><a href="gsk_secure_soc_init.htm">gsk_secure_soc_init()</a>--Negotiate a secure
session<br><br></li>
<li><a href="gsk_secure_soc_misc.htm">gsk_secure_soc_misc()</a>--Perform
miscellaneous functions for a secure session<br><br></li>
<li><a href="gsk_secure_soc_open.htm">gsk_secure_soc_open()</a>--Get a handle for a
secure session<br><br></li>
<li><a href="gsk_secure_soc_read.htm">gsk_secure_soc_read()</a>--Receive data on a
secure session<br><br></li>
<li><a href="gskstartinit.htm">gsk_secure_soc_startInit()</a>--Start asynchronous
operation to negotiate a secure session<br>
<br>
</li>
<li><a href="gskstartrecv.htm">gsk_secure_soc_startRecv()</a>--Start Asynchronous
Receive Operation on a Secure Session<br><br></li>
<li><a href="postiocompletion.htm">QsoPostIOCompletionPort()</a>--Post Request on
I/O Completion Port<br><br></li>
<li><a href="createiocompletionport.htm">QsoCreateIOCompletionPort()</a>--Create
I/O Completion Port<br><br></li>
<li><a href="destroyiocompletionport.htm">QsoDestroyIOCompletionPort()</a>--Destroy
I/O Completion Port<br><br></li>
<li><a href="startrecv.htm">QsoStartRecv</a>--Start Asynchronous Recv
Operation<br><br></li>
<li><a href="startsend.htm">QsoStartSend</a>--Start Asynchronous Send
Operation<br><br></li>
<li><a href="waitforiocompletion.htm">QsoWaitForIOCompletion()</a>--Wait for I/O
Completion Operation<br><br></li>
<li><a href="send.htm">send()</a>--Send Data</li>
</ul>
<br>
<hr>
API introduced: V5R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a> </td>
</tr>
</table></center>
</body>
</html>