This section describes a generic interface between an application and an RSVP control process. The details of a real interface may be operating-system dependent; the following can only suggest the basic functions to be performed. Some of these calls cause information to be returned asynchronously.
Call: SESSION( DestAddress , ProtocolId, DstPort [ , SESSION_object ] [ , Upcall_Proc_addr ] ) -> Session-id
This call initiates RSVP processing for a session, defined by DestAddress together with ProtocolId and possibly a port number DstPort. If successful, the SESSION call returns immediately with a local session identifier Session-id, which may be used in subsequent calls.
The Upcall_Proc_addr parameter defines the address of an upcall procedure to receive asynchronous error or event notification; see below. The SESSION_object parameter is included as an escape mechanism to support some more general definition of the session ("generalized destination port"), should that be necessary in the future. Normally SESSION_object will be omitted.
Call: SENDER( Session-id [ , Source_Address ] [ , Source_Port ] [ , Sender_Template ] [ , Sender_Tspec ] [ , Adspec ] [ , Data_TTL ] [ , Policy_data ] )
A sender uses this call to define, or to modify the definition of, the attributes of the data flow. The first SENDER call for the session registered as `Session-id' will cause RSVP to begin sending Path messages for this session; later calls will modify the path information.
The SENDER parameters are interpreted as follows:
This is the address of the interface from which the data will be sent. If it is omitted, a default interface will be used. This parameter is needed only on a multihomed sender host.
This is the UDP/TCP port from which the data will be sent.
This parameter is included as an escape mechanism to support a more general definition of the sender ("generalized source port"). Normally this parameter may be omitted.
This parameter describes the traffic flow to be sent; see [RFC 2210].
This parameter may be specified to initialize the computation of QoS properties along the path; see [RFC 2210].
This is the (non-default) IP Time-To-Live parameter that is being supplied on the data packets. It is needed to ensure that Path messages do not have a scope larger than multicast data packets.
This optional parameter passes policy data for the sender. This data may be supplied by a system service, with the application treating it as opaque.
Call: RESERVE( session-id, [ receiver_address , ] [ CONF_flag, ] [ Policy_data, ] style, style-dependent-parms )
A receiver uses this call to make or to modify a resource reservation for the session registered as `session-id'. The first RESERVE call will initiate the periodic transmission of Resv messages. A later RESERVE call may be given to modify the parameters of the earlier call (but note that changing existing reservations may result in admission control failures).
The optional `receiver_address' parameter may be used by a receiver on a multihomed host (or router); it is the IP address of one of the node's interfaces. The CONF_flag should be set on if a reservation confirmation is desired, off otherwise. The `Policy_data' parameter specifies policy data for the receiver, while the `style' parameter indicates the reservation style. The rest of the parameters depend upon the style; generally these will be appropriate flowspecs and filter specs.
The RESERVE call returns immediately. Following a RESERVE call, an asynchronous ERROR/EVENT upcall may occur at any time.
Call: RELEASE( session-id )
This call removes RSVP state for the session specified by session-id. The node then sends appropriate teardown messages and ceases sending refreshes for this session-id.
The general form of a upcall is as follows:
Upcall: <Upcall_Proc>( ) -> session-id, Info_type, information_parameters
Here "Upcall_Proc" represents the upcall procedure whose address was supplied in the SESSION call. This upcall may occur asynchronously at any time after a SESSION call and before a RELEASE call, to indicate an error or an event.
Currently there are five upcall types, distinguished by the Info_type parameter. The selection of information parameters depends upon the type.
A Path Event upcall results from receipt of the first Path message for this session, indicating to a receiver application that there is at least one active sender, or if the path state changes.
Upcall: <Upcall_Proc>( ) -> session-id, Info_type=PATH_EVENT, Sender_Tspec, Sender_Template [ , Adspec ] [ , Policy_data ]
This upcall presents the Sender_Tspec, the Sender_Template, the Adspec, and any policy data from a Path message.
A Resv Event upcall is triggered by the receipt of the first RESV message, or by modification of a previous reservation state, for this session.
Upcall: <Upcall_Proc>( ) -> session-id, Info_type=RESV_EVENT, Style, Flowspec, Filter_Spec_list [ , Policy_data ]
Here `Flowspec' will be the effective QoS that has been received. Note that an FF-style Resv message may result in multiple RESV_EVENT upcalls, one for each flow descriptor.
An Path Error event indicates an error in sender information that was specified in a SENDER call.
Upcall: <Upcall_Proc>( ) -> session-id, Info_type=PATH_ERROR, Error_code , Error_value , Error_Node , Sender_Template [ , Policy_data_list ]
The Error_code parameter will define the error, and Error_value may supply some additional (perhaps system-specific) data about the error. The Error_Node parameter will specify the IP address of the node that detected the error. The Policy_data_list parameter, if present, will contain any POLICY_DATA objects from the failed Path message.
An Resv Error event indicates an error in a reservation message to which this application contributed.
Upcall: <Upcall_Proc>( ) -> session-id, Info_type=RESV_ERROR, Error_code , Error_value , Error_Node , Error_flags , Flowspec, Filter_spec_list [ , Policy_data_list ]
The Error_code parameter will define the error and Error_value may supply some additional (perhaps system-specific) data. The Error_Node parameter will specify the IP address of the node that detected the event being reported.
There are two Error_flags:
This flag may be on for an Admission Control failure, to indicate that there was, and is, a reservation in place at the failure node. This flag is set at the failure point and forwarded in ResvErr messages.
This flag may be on for an Admission Control failure, to indicate that the flowspec requested by this receiver was strictly less than the flowspec that got the error. This flag is set at the receiver API.
Filter_spec_list and Flowspec will contain the corresponding objects from the error flow descriptor (see Section 3.1.8). List_count will specify the number of FILTER_SPECS in Filter_spec_list. The Policy_data_list parameter will contain any POLICY_DATA objects from the ResvErr message.
A Confirmation event indicates that a ResvConf message was received.
Upcall: <Upcall_Proc>( ) -> session-id, Info_type=RESV_CONFIRM, Style, List_count, Flowspec, Filter_spec_list [ , Policy_data ]
The parameters are interpreted as in the Resv Error upcall.
Although RSVP messages indicating path or resv events may be received periodically, the API should make the corresponding asynchronous upcall to the application only on the first occurrence or when the information to be reported changes. All error and confirmation events should be reported to the application.