* return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
RVAPI
int RVCALLCONV cmRASGetTransaction(
    IN  HRAS                hsRas,
    OUT cmRASTransaction*   transaction);


/************************************************************************
 * cmRASGetLastError
 * purpose: This function does absolutly nothing.
 *          It is only here for backward compatibility.
 * input  : hsRas       - Stack's handle for the RAS transaction
 * output : none
 * return : 0
 ************************************************************************/
RVAPI
cmRASError RVCALLCONV cmRASGetLastError(
    IN  HRAS             hsRas);









/************************************************************************
 *
 *                           CALLBACK functions
 *
 ************************************************************************/

/************************************************************************
 * cmEvRASRequestT
 * purpose: Callback function that the RAS calls when a new incoming
 *          RAS request has to be handled
 * input  : hsRas       - Stack's handle for the RAS transaction
 *          hsCall      - Stack's call handle
 *                        Set to NULL if not applicable for this type
 *                        of transaction
 *          transaction - The type of transaction that arrived
 *          srcAddress  - Address of the source
 *          haCall      - Application's call handle (if applicable)
 * output : lphsRas     - The application's RAS transaction handle
 *                        This should be set by the application to find
 *                        this transaction in future callbacks.
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
typedef int (RVCALLCONV *cmEvRASRequestT)(
    IN  HRAS                hsRas,
    IN  HCALL               hsCall,
    OUT LPHAPPRAS           lphaRas,
    IN  cmRASTransaction    transaction,
    IN  cmTransportAddress* srcAddress,
    IN  HAPPCALL            haCall);


/************************************************************************
 * cmEvRASConfirmT
 * purpose: Callback function that the RAS calls when a confirm on a
 *          RAS request is received
 * input  : haRas       - The application's RAS transaction handle
 *          hsRas       - Stack's handle for the RAS transaction
 * output : none
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
typedef int (RVCALLCONV *cmEvRASConfirmT)(
    IN  HAPPRAS          haRas,
    IN  HRAS             hsRas);


/************************************************************************
 * cmEvRASRejectT
 * purpose: Callback function that the RAS calls when a reject on a
 *          RAS request is received
 * input  : haRas       - The application's RAS transaction handle
 *          hsRas       - Stack's handle for the RAS transaction
 *          reason      - Reject reason
 * output : none
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
typedef int (RVCALLCONV *cmEvRASRejectT)(
    IN  HAPPRAS          haRas,
    IN  HRAS             hsRas,
    IN  cmRASReason      reason);


/************************************************************************
 * cmEvRASTimeoutT
 * purpose: Callback function that the RAS calls when a timeout on a
 *          RAS request occured.
 *          This will be the case when no reply arrives or when an
 *          outgoing multicast transaction is being handled (even if
 *          replies arrived).
 * input  : haRas       - The application's RAS transaction handle
 *          hsRas       - Stack's handle for the RAS transaction
 * output : none
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
typedef int (RVCALLCONV *cmEvRASTimeoutT)(
    IN  HAPPRAS          haRas,
    IN  HRAS             hsRas);



/************************************************************************
 * CMRASEVENT struct
 * This struct holds the event handlers of the RAS.
 * There are 4 callback functions in this struct:
 * cmEvRASRequest   - Notifies the application of a new incoming
 *                    transaction
 * cmEvRASConfirm   - Notifies the application of a confirm reply on an
 *                    application's request
 * cmEvRASReject    - Notifies the application of a reject reply on an
 *                    application's request
 * cmEvRASTimeout   - Notifies the application of a timed-out request
 ************************************************************************/
typedef struct
{
    cmEvRASRequestT cmEvRASRequest;
    cmEvRASConfirmT cmEvRASConfirm;
    cmEvRASRejectT  cmEvRASReject;
    cmEvRASTimeoutT cmEvRASTimeout;
} SCMRASEVENT,*CMRASEVENT;


/************************************************************************
 * cmRASSetEventHandler
 * purpose: Sets the callbacks the application wishes to use
 *          This callback is used to set the manual RAS events.
 * input  : hApp        - Application's handle for a stack instance
 *          cmRASEvent  - RAS callbacks to set
 *          size        - Size of callbacks struct (*CMRASEVENT)
 * output : none
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
RVAPI
int RVCALLCONV cmRASSetEventHandler(
    IN  HAPP        hApp,
    IN  CMRASEVENT  cmRASEvent,
    IN  int         size);





/************************************************************************
 *
 *                    Automatic RAS CALLBACK functions
 *
 ************************************************************************/

/************************************************************************
 * cmEvAutoRASRequestT
 * purpose: Callback function that the RAS calls when a new incoming
 *          automatic RAS request has to be handled.
 *          No action can be taken by the application - this is only
 *          for notification purposes.
 * input  : hsRas       - Stack's handle for the RAS transaction
 *          hsCall      - Stack's call handle
 *                        Set to NULL if not applicable for this type
 *                        of transaction
 *          transaction - The type of transaction that arrived
 *          srcAddress  - Address of the source
 *          haCall      - Application's call handle (if applicable)
 * output : none
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
typedef int (RVCALLCONV *cmEvAutoRASRequestT)(
    IN  HRAS             hsRas,
    IN  HCALL            hsCall,
    IN  cmRASTransaction transaction,
    IN  cmRASTransport*  srcAddress,
    IN  HAPPCALL         haCall);


/************************************************************************
 * cmEvAutoRASConfirmT
 * purpose: Callback function that the RAS calls when a confirm on an
 *          Automatic RAS request is received
 * input  : hsRas       - Stack's handle for the RAS transaction
 * output : none
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
typedef int (RVCALLCONV *cmEvAutoRASConfirmT)(
    IN  HRAS             hsRas);


/************************************************************************
 * cmEvAutoRASRejectT
 * purpose: Callback function that the RAS calls when a reject on an
 *          Automatic RAS request is received
 * input  : hsRas       - Stack's handle for the RAS transaction
 *          reason      - Reject reason
 * output : none
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
typedef int (RVCALLCONV *cmEvAutoRASRejectT)(
    IN  HRAS             hsRas,
    IN  cmRASReason      reason);


/************************************************************************
 * cmEvAutoRASTimeoutT
 * purpose: Callback function that the RAS calls when a timeout on an
 *          Automatic RAS request occured.
 *          This will be the case when no reply arrives or when an
 *          outgoing multicast transaction is being handled (even if
 *          replies arrived).
 * input  : hsRas       - Stack's handle for the RAS transaction
 * output : none
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
typedef int (RVCALLCONV *cmEvAutoRASTimeoutT)(
    IN  HRAS             hsRas);



/************************************************************************
 * CMAUTORASEVENT struct
 * This struct holds the event handlers of the Automatic RAS.
 * There are 4 callback functions in this struct:
 * cmEvAutoRASRequest   - Notifies the application of a new incoming
 *                        transaction that is handled by the automatic RAS
 * cmEvAutoRASConfirm   - Notifies the application of a confirm reply on an
 *                        automatic RAS request
 * cmEvAutoRASReject    - Notifies the application of a reject reply on an
 *                        automatic RAS s request
 * cmEvAutoRASTimeout   - Notifies the application of a timed-out on an
 *                        automatic RAS request
 ************************************************************************/
typedef struct
{
    cmEvAutoRASRequestT cmEvAutoRASRequest;
    cmEvAutoRASConfirmT cmEvAutoRASConfirm;
    cmEvAutoRASRejectT  cmEvAutoRASReject;
    cmEvAutoRASTimeoutT cmEvAutoRASTimeout;
} SCMAUTORASEVENT,*CMAUTORASEVENT;


/************************************************************************
 * cmAutoRASSetEventHandler
 * purpose: Sets the callbacks the application wishes to use for automatic
 *          RAS. Catching these callbacks allows the application to
 *          know about the messages that the automatic RAS receives.
 *          It doesn't allow the application to act on them - only to
 *          know about them.
 * input  : hApp            - Application's handle for a stack instance
 *          cmAutoRASEvent  - Automatic RAS callbacks to set
 *          size            - Size of callbacks struct (*CMRASEVENT)
 * output : none
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
RVAPI
int RVCALLCONV cmAutoRASSetEventHandler(
    IN  HAPP            hApp,
    IN  CMAUTORASEVENT  cmAutoRASEvent,
    IN  int             size);



#ifdef __cplusplus
}
#endif


#endif  /* CMRAS_H */