472 lines
13 KiB
HTML
472 lines
13 KiB
HTML
|
<!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>qtoq_connect()--Make QoS Sockets Connection API</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. -->
|
||
|
|
<!-- Created by John Hall and Dale LeFevre for V5R2 -->
|
||
|
|
<!-- File tagging cleanup completed Mar 2002 by v2cdijab -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>qtoq_connect()--Make QoS Sockets Connection API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 80%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <qtoqsapi.h>
|
||
|
|
|
||
|
|
int qtoq_connect(
|
||
|
|
int socket_descriptor,
|
||
|
|
struct sockaddr *address,
|
||
|
|
int address_length,
|
||
|
|
int req_type,
|
||
|
|
qos_conn_req *qos_data,
|
||
|
|
unsigned int *qos_session,
|
||
|
|
int *qos_descriptor,
|
||
|
|
)
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
Service Program Name: QSYS/QTOQSAPI<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *EXCLUDE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <strong>qtoq_connect()</strong> API provides simplified Quality of
|
||
|
|
Service functionality for connection-oriented sockets communications between
|
||
|
|
RSVP aware applications on a client and server. The standard <strong>
|
||
|
|
connect()</strong> sockets call can be replaced with this API.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong><em>socket_descriptor</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Required
|
||
|
|
|
||
|
|
<p>An opened socket descriptor that has been bound to the IP address and port
|
||
|
|
from which the application will accept connection requests.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>destination_address</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Required
|
||
|
|
|
||
|
|
<p>A pointer to a <samp>sockaddr</samp> structure containing the IP address and
|
||
|
|
port of the server to connect to.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>address_length</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Required
|
||
|
|
|
||
|
|
<p>Integer containing the length of the destination address structure.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>req_type</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Required
|
||
|
|
|
||
|
|
<p>The type of QoS service being requested. The possible values are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="30 70" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>REQ_SIGNAL_RET_EVENTS(1)</em></td>
|
||
|
|
<td align="left" valign="top">Use normal RSVP signaling and return RSVP events
|
||
|
|
to the calling program.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" nowrap><em>REQ_SIGNAL_NORET_EVENTS(2)</em></td>
|
||
|
|
<td align="left" valign="top">Use normal RSVP signaling without returning
|
||
|
|
events to the calling program.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>qos_data</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Required
|
||
|
|
|
||
|
|
<p>Pointer to a <samp>qos_conn_req</samp> data structure that defines the type
|
||
|
|
of service being requested and the source and destination addresses of the
|
||
|
|
request.</p>
|
||
|
|
|
||
|
|
<p>The <samp>qos_conn_req</samp> data structure is defined below:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
typedef struct
|
||
|
|
{
|
||
|
|
int service; ; /* Values can be GUARANTEED_SERV (2)
|
||
|
|
or CONTROLLED_LOAD_SERV (5) */
|
||
|
|
union
|
||
|
|
{
|
||
|
|
struct CL_spec /* Controlled-Load service */
|
||
|
|
{
|
||
|
|
float TB_Tspec_r; /* token bucket rate in bytes/sec */
|
||
|
|
float TB_Tspec_b; /* token bucket depth in bytes */
|
||
|
|
float TB_Tspec_p; /* token bucket peak in bytes/sec */
|
||
|
|
unsigned long TB_Tspec_m; /* min policed unit in bytes */
|
||
|
|
unsigned long TB_Tspec_M; /* max packet size in bytes */
|
||
|
|
} CL_spec;
|
||
|
|
struct Guar_spec /* Guaranteed service */
|
||
|
|
{
|
||
|
|
float Guar_R; /* guaranteed rate in bytes/sec */
|
||
|
|
unsigned long Guar_S; /* slack term in microsecs */
|
||
|
|
} Guar_spec;
|
||
|
|
} spec_u;
|
||
|
|
} qos_spec_t;
|
||
|
|
|
||
|
|
typedef struct
|
||
|
|
{
|
||
|
|
struct sockaddr source; /* Source address/port */
|
||
|
|
int s_length; /* Source address length */
|
||
|
|
int style; /* Style of Reservation. */
|
||
|
|
qos_spec_t Spec; /* Flow info */
|
||
|
|
unsigned char result; /* API status */
|
||
|
|
} qos_conn_req; /* End of QoS connection request structure */
|
||
|
|
</pre>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>qos_session</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Output) Required
|
||
|
|
|
||
|
|
<p>Pointer to an integer value where the unique QoS session ID can be stored.
|
||
|
|
This ID is required for all future QoS API calls.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>qos_descriptor</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Output) Optional
|
||
|
|
|
||
|
|
<p>Pointer to an integer where the value of the descriptor that the application
|
||
|
|
can wait on for RSVP events is stored. This value is set to NULL if it is not
|
||
|
|
used.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<p>None.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Values</h3>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top">if successful.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>-1</em></td>
|
||
|
|
<td align="left" valign="top">if function failed. Errno indicates error
|
||
|
|
reason.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>When this function call fails, the errno value is set to one of the
|
||
|
|
following:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>[EACCES]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Permission denied. This error code indicates one of the following:</p>
|
||
|
|
<ul>
|
||
|
|
<li>The process does not have the appropriate privileges to connect to the
|
||
|
|
address pointed to by the destination_address parameter.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The socket pointed to by socket_descriptor is using a connection-oriented
|
||
|
|
transport service, and the destination_address parameter specifies a TCP/IP
|
||
|
|
limited broadcast address (internet address of all ones).</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EADDRINUSE]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Address already in use. This error code indicates one of the following:</p>
|
||
|
|
<ul>
|
||
|
|
<li>The socket_descriptor parameter points to a connection-oriented socket that
|
||
|
|
has been bound to a local address that contained no wildcard values, and the
|
||
|
|
destination_address parameter specified an address that matched the bound
|
||
|
|
address.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The socket_descriptor parameter points to a socket that has been bound to a
|
||
|
|
local address that contained no wildcard values, and the <strong><em>
|
||
|
|
destination_address</em></strong> parameter (also containing no wildcard
|
||
|
|
values) specified an address that would have resulted in a connection with an
|
||
|
|
association that is not unique.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EADDRNOTAVAIL]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Address not available. This error code indicates one of the following:</p>
|
||
|
|
<ul>
|
||
|
|
<li>The socket_descriptor parameter points to a socket with an address family
|
||
|
|
of AF_INET and either a port was not available or a route to the address
|
||
|
|
specified by the destination_address parameter could not be found.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EAFNOSUPPORT]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>The type of socket is not supported in this protocol family. The address
|
||
|
|
family specified in the address structure pointed to by the <strong><em>
|
||
|
|
destination_address</em></strong> parameter cannot be used with the socket
|
||
|
|
pointed to by the socket_descriptor parameter. This error also will be reported
|
||
|
|
if the API is called with a socket type that is not AF_INET and SOCK_DGRAM or
|
||
|
|
SOCK_STREAM.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EALREADY]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Operation already in progress. A previous connect() function had already
|
||
|
|
been issued for the socket pointed to by the socket_descriptor parameter, and
|
||
|
|
has yet to be completed. This error code is returned only on sockets that use a
|
||
|
|
connection-oriented transport service.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EBADF]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Descriptor not valid.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ECONNREFUSED]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>The destination socket refused an attempted connect operation. This error
|
||
|
|
occurs when there is no application that is bound to the address specified by
|
||
|
|
the destination_address parameter.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EFAULT]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Bad address. The system detected an address that was not valid while
|
||
|
|
attempting to access the destination_address parameter.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EHOSTUNREACH]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>A route to the remote host is not available.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EINPROGRESS]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Operation in progress. The socket_descriptor parameter points to a socket
|
||
|
|
that is marked as non blocking and the connection could not be completed
|
||
|
|
immediately. This error code is returned only on sockets that use a
|
||
|
|
connection-oriented transport service.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EINTR]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Interrupted function call.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EINVAL]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Parameter not valid. This error code indicates one of the following:</p>
|
||
|
|
<ul>
|
||
|
|
<li>The address_length parameter specifies a length that is negative or not
|
||
|
|
valid for the address family.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The AF_INET socket is of type SOCK_STREAM, and a previous connect() has
|
||
|
|
already completed unsuccessfully. Only one connection attempt is allowed on a
|
||
|
|
connection-oriented socket.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EIO]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Input/output error.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EISCONN]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>A connection has already been established. This error code is returned only
|
||
|
|
on sockets that use a connection-oriented transport service.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ENETUNREACH]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Cannot reach the destination network. This error code indicates the
|
||
|
|
following:</p>
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>For sockets that use the AF_INET address family, the address specified by
|
||
|
|
the destination_address parameter requires the use of a router, and the socket
|
||
|
|
option SO_DONTROUTE is currently set on.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ENOBUFS]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>There is not enough buffer space for the requested operation.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ENOTDIR]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Not a directory.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EOPNOTSUPP]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Operation not supported.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[ETIMEDOUT]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>A remote host did not respond within the timeout period. This error code is
|
||
|
|
returned when connection establishment times out. No connection is established.
|
||
|
|
A possible cause may be that the partner application is bound to the address
|
||
|
|
specified by the destination_address parameter, but the partner application has
|
||
|
|
not yet issued a listen().</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EUNKNOWN]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>Unknown system state.</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>
|
||
|
|
|
||
|
|
<dt><em>[EPROTO]</em></dt>
|
||
|
|
|
||
|
|
<dd><p>An underlying protocol error has occurred.</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top" nowrap>Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPE3418 E</td>
|
||
|
|
<td align="left" 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 &1 in library
|
||
|
|
&2 ended. Reason code &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>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>The qtoq_connect() API can be used to replace the normal connect() sockets
|
||
|
|
call in an application using connection oriented sockets.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The application program can choose to be signaled when RSVP events occur or
|
||
|
|
allow the QoS server to handle the events. If the server handles the events,
|
||
|
|
the application program will not be informed if the RSVP signaling fails or if
|
||
|
|
the requested reservations have been changed by the network.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<p>For a description of the RSVP protocol, see RFC 2205 on the RFC Pages for <a
|
||
|
|
href="http://www.ietf.org/rfc.html">The Internet Engineering Task
|
||
|
|
Force</a>.<img src="www.gif" alt="Link outside Information Center"></p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
API introduced: V5R2
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|