qtoq_connect()--Make QoS Sockets Connection API

 #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,
                 )

The qtoq_connect() API provides simplified Quality of Service functionality for 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 data structure that defines the type of service being requested and the source and destination addresses of the request.

The qos_conn_req 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        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 */

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

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).

[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.

[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 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 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 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.

[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 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

Usage Notes

1. The qtoq_connect() API can be used to replace the normal connect() sockets call in an application using connection oriented sockets.
   
   
2. 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 for The Internet Engineering Task Force.