NAME

rapi_reserve - make, modify, or delete a reservation

SYNOPSIS

#include <rapi.h>

int rapi_reserve(
    rapi_sid_t       Sid,             /* Session ID             */
    unsigned int     Flags,           /* Flags                  */
    rapi_addr_t     *RHost,           /* Receive host addr      */
    rapi_styleid_t   StyleId,         /* Style ID               */
    rapi_stylex_t   *Style_Ext,       /* Style extension        */
    rapi_policy_t   *Rcvr_Policy,     /* Receiver policy        */
    int              FilterSpecNo,    /* Number of filter specs */
    rapi_filter_t   *FilterSpec_list, /* List of filter specs   */
    int              FlowspecNo,      /* Number of flowspecs    */
    rapi_flowspec_t *Flowspec_list    /* List of flowspecs      */
)

DESCRIPTION

The rapi_reserve() function is called to make, modify, or delete a resource reservation for a session. The call may be repeated with different parameters, allowing the application to modify or remove the reservation; the latest call will take precedence.

PARAMETERS

Sid

This parameter must be a session ID returned by a successful rapi_session() call.

Flags

Setting the RAPI_REQ_CONFIRM flag requests confirmation of the reservation, by means of a confirmation upcall (type RAPI_RESV_CONFIRM).

RHost

This parameter may be used to define the interface address on which data will be received for multicast flows. It is useful for a multi-homed host. If it is NULL or the host address is INADDR_ANY, an implementation-defined interface will be chosen. The format of a rapi_addr_t is implementation-dependent, see Header File .

StyleId

This parameter specifies the reservation style id (values defined below).

Style_Ext

This parameter is a pointer to a style-dependent extension to the parameter list, or NULL.

Rcvr_Policy

This parameter is a pointer to a policy data structure, or it is NULL.

FilterSpec_list, FilterSpecNo

The FilterSpec_list parameter is a pointer to an area containing a sequential vector of RAPI filter spec objects. The number of objects in this vector is specified in FilterSpecNo. If FilterSpecNo is zero, the FilterSpec_list parameter is ignored and can be NULL.

Flowspec_list, FlowspecNo

The Flowspec_list parameter is a pointer to an area containing a sequential vector of RAPI flow spec objects. The number of objects in this vector is specified in FlowspecNo. If FlowspecNo is zero, the Flowspec_list parameter is ignored and can be NULL.

If FlowspecNo is zero, the rapi_reserve() call will remove the current reservation(s) for the specified session, and FilterSpec_list and Flowspec_list will be ignored. Otherwise, the parameters depend upon the style, as follows:

Wildcard Filter (WF)

Use StyleId = RAPI_RSTYLE_WILDCARD. The Flowspec_list parameter may be NULL (to delete the reservation) or else point to a single flowspec. The FilterSpec_list parameter may be empty or it may point to a single filter spec containing appropriate wildcard(s).

Fixed Filter (FF)

Use StyleId = RAPI_RSTYLE_FIXED. FilterSpecNo must equal FlowspecNo. Entries in Flowspec_list and FilterSpec_list parameters will correspond in pairs.

Shared Explicit (SE)

Use StyleId = RAPI_RSTYLE_SE. The Flowspec_list parameter should point to a single flowspec. The FilterSpec_list parameter may point to a list of any length.

RESULT

Depending upon the parameters, each call may or may not result in new admission control calls, which could fail asynchronously.

If there is a synchronous error in this call, rapi_reserve() returns a RAPI error code; otherwise, it returns zero.

Applications that make use of the RAPI_RESV_CONFIRM flag will normally receive positive acknowledgement that the QoS request succeeded. Otherwise, applications measure success in the form of errors returned when making QoS requests. No final positive acknowledgement will occur.

An admission control failure (for example, refusal of the QoS request) is reported asynchronously by an upcall of type RAPI_RESV_ERROR. A RSVP_Err_NO_PATH error code indicates that RSVP state from one or more of the senders specified in FilterSpec_list has not (yet) propagated all the way to the receiver; it may also indicate that one or more of the specified senders has closed its API session and that its RSVP state has been deleted from the routers.