qtoq_connect_ex()--Make QoS Sockets Connection API
Syntax
#include <qtoqsapi.h> int qtoq_connect_ex( int socket_descriptor, struct sockaddr *address, int address_length, int req_type, qos_conn_req_ex *qos_data, unsigned int *qos_session, int *qos_descriptor, )Service Program Name: QSYS/QTOQSAPI
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The qtoq_connect_ex() API provides simplified Quality of Service functionality for IPv4 and IPv6 connection-oriented sockets communications between RSVP aware applications on a client and server. The standard connect() sockets call can be replaced with this API.
Parameters
- socket_descriptor
- (Input) Required
An opened socket descriptor that has been bound to the IP address and port from which the application will accept connection requests.
- destination_address
- (Input) Required
A pointer to a sockaddr structure containing the IP address and port of the server to connect to.
- address_length
- (Input) Required
Integer containing the length of the destination address structure.
- req_type
- (Input) Required
The type of QoS service being requested. The possible values are:
REQ_SIGNAL_RET_EVENTS(1) Use normal RSVP signaling and return RSVP events to the calling program. REQ_SIGNAL_NORET_EVENTS(2) Use normal RSVP signaling without returning events to the calling program.
- qos_data
- (Input) Required
Pointer to a qos_conn_req_ex data structure that defines the type of service being requested and the source and destination addresses of the request.
The qos_conn_req_ex data structure is defined below:
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_afinetx 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_ex; /* End of QoS connection request structure */
- qos_session
- (Output) Required
Pointer to an integer value where the unique QoS session ID can be stored. This ID is required for all future QoS API calls.
- qos_descriptor
- (Output) Optional
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.
Authorities
None.
Return Values
0 | if successful. |
-1 | if function failed. Errno indicates error reason. |
Error Conditions
When this function call fails, the errno value is set to one of the following:
- [EACCES]
Permission denied. This error code indicates one of the following:
- The process does not have the appropriate privileges to connect to the
address pointed to by the destination_address parameter.
- 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).
- The process does not have the appropriate privileges to connect to the
address pointed to by the destination_address parameter.
- [EADDRINUSE]
Address already in use. This error code indicates one of the following:
- 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.
- The socket_descriptor parameter points to a socket that has been bound to a local address that contained no wildcard values, and the destination_address parameter (also containing no wildcard values) specified an address that would have resulted in a connection with an association that is not unique.
- 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.
- [EADDRNOTAVAIL]
Address not available. This error code indicates one of the following:
- The socket_descriptor parameter points to a socket with an address family of AF_INET or AF_INET6 and either a port was not available or a route to the address specified by the destination_address parameter could not be found.
- [EAFNOSUPPORT]
The type of socket is not supported in this protocol family. The address family specified in the address structure pointed to by the destination_address 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 or AF_INET6 and SOCK_DGRAM or SOCK_STREAM.
- [EALREADY]
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.
- [EBADF]
Descriptor not valid.
- [ECONNREFUSED]
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.
- [EFAULT]
Bad address. The system detected an address that was not valid while attempting to access the destination_address parameter.
- [EHOSTUNREACH]
A route to the remote host is not available.
- [EINPROGRESS]
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.
- [EINTR]
Interrupted function call.
- [EINVAL]
Parameter not valid. This error code indicates one of the following:
- The address_length parameter specifies a length that is negative or not
valid for the address family.
- The AF_INET or AF_INET6 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.
- The address_length parameter specifies a length that is negative or not
valid for the address family.
- [EIO]
Input/output error.
- [EISCONN]
A connection has already been established. This error code is returned only on sockets that use a connection-oriented transport service.
- [ENETUNREACH]
Cannot reach the destination network. This error code indicates the following:
- For sockets that use the AF_INET or AF_INET6 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.
- [ENOBUFS]
There is not enough buffer space for the requested operation.
- [ENOTDIR]
Not a directory.
- [EOPNOTSUPP]
Operation not supported.
- [ETIMEDOUT]
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().
- [EUNKNOWN]
Unknown system state.
- [EUNATCH]
The protocol required to support the specified address family is not available at this time.
- [EPROTO]
An underlying protocol error has occurred.
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
- The qtoq_connect_ex() API can be used to replace the normal connect() sockets
call in an application using connection oriented sockets.
- 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.
Related Information
For a description of the RSVP protocol, see RFC 2205 on the RFC Pages.
API introduced: V5R2