NAME

rapi_event_rtn_t - event upcall function template

SYNOPSIS

#include <rapi.h>

typedef void    rapi_event_rtn_t(
    rapi_sid_t        Sid,              /* Session ID            */
    rapi_eventinfo_t  EventType,        /* Event type            */
    rapi_styleid_t    Style,            /* Reservation style     */
    int               ErrorCode,        /* Error event: code     */
    int               ErrorValue,       /* Error event: value    */
    rapi_addr_t       *ErrorNode,       /* Node detecting error  */
    unsigned int      ErrorFlags,       /* Error flags           */
    int               FilterSpecNo,     /* number of filterSpecs */
    rapi_filter_t     *FilterSpec_list,
    int               FlowspecNo,       /* number of flowspecs   */
    rapi_flowspec_t   *Flowspec_list,
    int               AdspecNo,         /* number of adspecs     */
    rapi_adspec_t     *Adspec_list,
    void              *Event_arg        /* application argument  */
);

DESCRIPTION

This is the template for the function the address of which each application must supply as an argument to rapi_session() and which the implementation will call when asynchronous RAPI events occur. The event upcall function is invoked from the implementation's asynchronous RSVP event mechanism when an event occurs. See rapi_session() for more details.

PARAMETERS

Sid

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

EventType

Upcall event type.

Style

This parameter contains the style of the reservation; it is non-zero only for a RAPI_RESV_EVENT or RAPI_RESV_ERROR event.

ErrorCode, ErrorValue

These values encode the error cause, and they are set only for a RAPI_PATH_ERROR or RAPI_RESV_ERROR event. See rapi_strerror() and Error Handling (Error Handling) for interpretation of these values.

ErrorNode

This is the IP (V4 or V6) address of the node that detected the error, and it is set only for a RAPI_PATH_ERROR or RAPI_RESV_ERROR event. The format of a rapi_addr_t is implementation-dependent. See Header File .

ErrorFlags

These error flags are set only for a RAPI_PATH_ERROR or RAPI_RESV_ERROR event.

RAPI_ERRF_InPlace

The reservation failed, but another (presumably smaller) reservation is still in place on the same interface.

RAPI_ERRF_NotGuilty

The reservation failed, but the request from this client was merged with a larger reservation upstream, so this client's reservation might not have caused the failure.

FilterSpec_list, FilterSpecNo

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

Flowspec_list, FlowspecNo

The Flowspec_list parameter is a pointer to an area containing a sequential vector of RAPI flowspec or Tspec objects. The number of objects in this vector is specified in FlowspecNo. If FlowspecNo is zero, the Flowspec_list parameter will be NULL.

Adspec_list, AdspecNo

The Adspec_list parameter is a pointer to an area containing a sequential vector of RAPI adspec objects. The number of objects in this vector is specified in AdspecNo. If AdspecNo is zero, the Adspec_list parameter will be NULL.

Event_arg

This is the value supplied in the rapi_session() call.

RESULT

When the application's upcall function returns, any areas pointed to by Flowspec_list, FilterSpec_list or Adspec_list become invalid for further reference. The upcall function must copy any values it wants to save.

The specific parameters depend upon EventType, which may have one of the following values:

RAPI_PATH_EVENT

A path event indicates that RSVP sender ("Path") state from a remote node has arrived or changed at the local node. A RAPI_PATH_EVENT event containing the complete current list of senders (or possibly no senders, after a path teardown) in the path state for the specified session will be triggered whenever the path state changes.

FilterSpec_list, Flowspec_list, and Adspec_list will be of equal length, and corresponding entries will contain sender templates, sender Tspecs, and Adspecs, respectively, for all senders known at this node. In general, a missing object will be indicated by an empty RAPI object.

RAPI_PATH_EVENT events are enabled by the initial rapi_session() call.

RAPI_RESV_EVENT

A reservation event indicates that reservation state has arrived or changed at the node, implying (but not assuring) that reservations have been established or deleted along the entire data path to one or more receivers. RAPI_RESV_EVENT events containing the current reservation state for the API session will be triggered whenever the reservation state changes.

Flowspec_list will either contain one flowspec object or be empty (if the state has been torn down), and FilterSpec_list will contain zero or more corresponding filter spec objects. Adspec_list will be empty.

RAPI_RESV_EVENT events are enabled by a rapi_sender() call; the sender template from the latter call will match the filter spec returned in the upcall triggered by a reservation event.

RAPI_PATH_ERROR

A path error event indicates that an asynchronous error has been found in the sender information specified in a rapi_sender() call.

The ErrorCode and ErrorValue parameters will specify the error. FilterSpec_list and Flowspec_list will each contain one object, the sender template and corresponding sender Tspec (if any) in error, while Adspec_list will be empty. If there is no sender Tspec, the object in Flowspec_list will be an empty RAPI object. The Adspec_list will be empty.

RAPI_PATH_ERROR events are enabled by a rapi_sender() call, and the sender Tspec in that call will match the sender Tspec returned in a subsequent upcall triggered by a RAPI_PATH_ERROR event.

RAPI_RESV_ERROR

A reservation error event indicates that an asynchronous reservation error has occurred.

The ErrorCode and ErrorValue parameters will specify the error. Flowspec_list will contain one flowspec, while FilterSpec_list may contain zero or more corresponding filter specs. Adspec_list will be empty.

RAPI_RESV_ERROR events are enabled by a call to rapi_reserve().

RAPI_RESV_CONFIRM

A RAPI_RESV_CONFIRM event indicates that a reservation has been made at least up to an intermediate merge point, and probably (but not necessarily) all the way to at least one sender. A RAPI_RESV_CONFIRM event is enabled by a rapi_reserve() call with the RAPI_REQ_CONFIRM flag set, and at most one confirmation event will result from each such call.

The parameters of a RAPI_RESV_CONFIRM event upcall are the same as those for a RAPI_RESV_EVENT event upcall.

The accompanying table summarizes the events. Here, "n" is a non-negative integer.

Event	Enabled by	FilterSpecNo	FlowspecNo	AdspecNo
RAPI_PATH_EVENT	rapi_session	n	n	n
RAPI_PATH_ERROR	rapi_sender	1	1	0
RAPI_RESV_EVENT	rapi_sender	n	1 or 0	0
RAPI_RESV_ERROR	rapi_reserve	n	1	0
RAPI_RESV_CONFIRM	rapi_reserve	1	1	0