rapi_event_rtn_t - event upcall function template
#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 */ );
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.
This parameter must be a session ID returned by a successful
Upcall event type.
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.
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
These error flags are set only for a RAPI_PATH_ERROR or RAPI_RESV_ERROR event.
The reservation failed, but another (presumably smaller) reservation is still in place on the same interface.
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.
This is the value supplied in the
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:
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
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.
A path error event indicates that an asynchronous error has been found in the sender information specified in a
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.
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
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