3.11.1 Application/RSVP Interface

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.

• Register Session

                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.

• Define Sender

                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:

  • Source_Address

    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.

  • Source_Port

    This is the UDP/TCP port from which the data will be sent.

  • Sender_Template

    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.

  • Sender_Tspec

    This parameter describes the traffic flow to be sent; see [RFC 2210].

  • Adspec

    This parameter may be specified to initialize the computation of QoS properties along the path; see [RFC 2210].

  • Data_TTL

    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.

  • Policy_data

    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.

• Reserve

                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.

• Release

                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.

• Error/Event Upcalls

  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.

  1. Info_type = PATH_EVENT

     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.

  2. Info_type = RESV_EVENT

     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.

  3. Info_type = PATH_ERROR

     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.

  4. Info_type = RESV_ERR

     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:

     • InPlace

       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.

     • NotGuilty

       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.

  5. Info_type = RESV_CONFIRM

     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.