NAME

rapi_session - create a session

SYNOPSIS

#include <rapi.h>

rapi_sid_t rapi_session(
    rapi_addr_t      *Dest,       /* Session: (Dst addr, port)  */
    int               Protid,     /* Protocol Id                */
    unsigned int      Flags,      /* Flags                      */
    rapi_event_rtn_t *Event_rtn,  /* Address of upcall routine  */
    void             *Event_arg,  /* App argument to upcall     */
    int              *Errnop      /* Place to return error code */
)

DESCRIPTION

The rapi_session() call creates an API session.

After a successful rapi_session() call has been made, the application may receive upcalls of type RAPI_PATH_EVENT for the API session.

PARAMETERS

The parameters are as follows:

Dest

This parameter points to a rapi_addr_t structure defining the destination IP (V4 or V6) address and a port number to which data will be sent. The Dest and Protid parameters define an RSVP session. If the Protid specifies UDP or TCP transport, as specified in the Assigned Numbers RFC 1700, the port corresponds to the appropriate transport port number. The format of a rapi_addr_t is implementation-dependent, see Header File .

Protid

The IP protocol ID for the session. If it is omitted (that is, zero), 17 (UDP) is assumed.

Flags

RAPI_GPI_SESSION

If set, this flag requests that this API session be defined in the GPI format used by the IPSEC extension of RSVP. If this flag is set, the port number included in Dest is considered "virtual" (see the IPSEC specification, reference RFC 1825 for details), and any sender template and filter specifications must be in GPI format.

RAPI_USE_INTSERV

If set, IntServ formats are used in upcalls; otherwise, the Simplified format is used (see RAPI Objects ).

Event_rtn

This parameter is a pointer to an upcall function that will be invoked to notify the application of RSVP errors and state change events. Pending events cause the invocation of the upcall function - see Use with select() or poll() ). The application must supply an upcall routine for event processing. See Event Upcall .

Event_arg

This parameter is an argument that will be passed to any invocation of the upcall routine. See Event Upcall .

Errnop

The address of an integer into which a RAPI error code will be returned.

RESULT

If it succeeds, the rapi_session() call returns an opaque but non-zero session handle for use in subsequent calls related to this API session.

If the call fails synchronously, it returns zero (RAPI_NULL_SID) and stores a RAPI error code into the integer variable pointed to by the Errnop parameter.

EXTENDED DESCRIPTION

An application can have multiple API sessions registered for the same or different RSVP sessions at the same time. There can be at most one sender associated with each API session; however, an application can announce multiple senders for a given RSVP session by announcing each sender in a separate API session.

Two API sessions for the same RSVP session, if they are receiving data, are assumed to have joined the same multicast group and will receive the same data packets. An implementation should disallow multiple API sessions for the same sender within one RSVP session (see Reservation Model ). The behavior of an implementation that allows multiple API sessions for the same sender is unspecified.