cmiras.h

基于h323协议的软phone

/*

NOTICE:
This document contains information that is proprietary to RADVISION LTD..
No part of this publication may be reproduced in any form whatsoever without
written prior approval by RADVISION LTD..

RADVISION LTD. reserves the right to revise this publication and make changes
without obligation to notify any person of such revisions or changes.

*/

#ifndef _CMIRAS_H
#define _CMIRAS_H

#include "rvinternal.h"
#include "cat.h"
#include "cmCrossReference.h"
#include "cmras.h"

#ifdef __cplusplus
extern "C" {
#endif



/* Application's handle of a RAS message */
RV_DECLARE_HANDLE(HAPPRASMSG);




/************************************************************************
 * rasChanType enumeration
 * rasChanUnicast   - Unicast channel the RAS is listening on
 * rasChanMulticast - Multicast channel the RAS is listening on
 ************************************************************************/
typedef enum
{
    rasChanUnicast,
    rasChanMulticast
} rasChanType;






/************************************************************************
 * cmiRASInitialize
 * purpose: Initialize a RAS instance for use by the CM
 * input  : hApp            - Stack's instance handle
 *          hCat            - CAT instance handle
 *          hVal            - Value "forest" to use for ASN.1 messages
 *          rasConfNode     - RAS configuration node id
 *          maxIncomingTx   - Maximum number of incoming RAS transactions
 *          maxOutgoingTx   - Maximum number of outgoing RAS transactions
 *          maxBufSize      - Maximum buffer size for encoded messages
 *          isGatekeeper    - Indication if we should act as a GK
 * output : none
 * return : RAS module handle on success
 *          NULL on failure
 ************************************************************************/
HRASMGR RVCALLCONV cmiRASInitialize(
    IN  HAPP        hApp,
    IN  RVHCAT      hCat,
    IN  HPVT        hVal,
    IN  int         rasConfNode,
    IN  RvUint32    maxIncomingTx,
    IN  RvUint32    maxOutgoingTx,
    IN  RvUint32    maxBufSize,
    IN  RvBool      isGatekeeper);


/************************************************************************
 * cmiRASStart
 * purpose: Start a RAS instance for use by the CM
 *          Should be called after cmiRASInitialize() and before any
 *          other function.
 * input  : hRasMgr         - RAS instance handle
 *          rasAddressNode  - RAS listening address node id
 *          startingSeqNum  - Starting sequence number to use
 * output : none
 * return : Non negative value on success
 *          Negative value on failure
 ************************************************************************/
int RVCALLCONV cmiRASStart(
    IN  HRASMGR     hRasMgr,
    IN  int         rasAddressNode,
    IN  RvUint32    startingSeqNum);


/************************************************************************
 * cmiRASStop
 * purpose: Stop a RAS instance from running
 * input  : hRasMgr - RAS instance handle
 * output : none
 * return : Non negative value on success
 *          Negative value on failure
 ************************************************************************/
int RVCALLCONV cmiRASStop(
    IN  HRASMGR hRasMgr);


/************************************************************************
 * cmiRASEnd
 * purpose: Free any resources taken by a RAS instance and stop its
 *          activities.
 * input  : hRasMgr - RAS instance handle
 * output : none
 * return : Non negative value on success
 *          Negative value on failure
 ************************************************************************/
int RVCALLCONV cmiRASEnd(
    IN  HRASMGR hRasMgr);


/************************************************************************
 * cmiRASGetEndpointID
 * purpose: Retrieves the EndpointID stored in the ras
 *
 * input  : hRasMgr             - RAS instance handle
 *          eId                 - pointer to the buffer for endpoint ID
 *                                buffer should be big enough for longest EID
 *                                possible (256 byte)
 * output : none
 * return : The length of EID in bytes on success
 *          Negative value on failure
 ************************************************************************/
int RVCALLCONV cmiRASGetEndpointID(
    IN  HRASMGR hRasMgr,
    IN  void*   eId);


/************************************************************************
 * cmiRASUpdateRegInfo
 * purpose: Update the registration information inside the default RAS
 *          messages. This function should be called whenever the
 *          registration status changes.
 *          It takes most of the information from the RAS configuration
 *          message in the PVT database.
 * input  : hRasMgr             - RAS instance handle
 *          beforeRegistration  - RV_TRUE if called before cmRegister()
 *                                RV_FALSE if called after RCF received
 * output : none
 * return : Non negative value on success
 *          Negative value on failure
 ************************************************************************/
int RVCALLCONV cmiRASUpdateRegInfo(
    IN  HRASMGR hRasMgr,
    IN  RvBool  beforeRegistration);


/************************************************************************
 * cmiRASUpdateCallSignalingAddress
 * purpose: Update the CallSignalling address inside the default RAS
 *          messages. This function should be called whenever this
 *          adress changes.
 *          It takes most of the information from the given nodeId
 * input  : hRasMgr     - RAS instance handle
 *          addressId   - nodeId of the address to set
 *          annexEId    - nodeId of the annexE address to set
 * output : none
 * return : Non negative value on success
 *          Negative value on failure
 ************************************************************************/
int RVCALLCONV cmiRASUpdateCallSignalingAddress(
    IN  HRASMGR hRasMgr,
    IN  int     addressId,
    IN  int     annexEId);


/************************************************************************
 * cmiRASGetHAPP
 * purpose: Get the application's handle of a RAS instance for a
 *          specific stack's RAS transaction handle
 * input  : hsRas       - Stack's handle for the RAS transaction
 * output : none
 * return : The application's handle of the RAS instance on success
 *          NULL on failure
 ************************************************************************/
RVAPI
HAPP RVCALLCONV cmiRASGetHAPP(
    IN  HRAS hsRas);




/************************************************************************
 * cmiRASGetRequest
 * purpose: Gets the pvt node of the current RAS request
 * input  : hsRas       - Stack's handle for the RAS transaction
 * output : none
 * return : pvt node of the current RAS request
 *          or negative value on error
 ************************************************************************/
RvPvtNodeId RVCALLCONV cmiRASGetRequest(
    IN  HRAS         hsRas);


/************************************************************************
 * cmiRASGetResponse
 * purpose: Gets the pvt node of the current RAS response
 * input  : hsRas       - Stack's handle for the RAS transaction
 * output : none
 * return : pvt node of the current RAS response
 *          or negative value on error
 ************************************************************************/
RvPvtNodeId RVCALLCONV cmiRASGetResponse(
    IN  HRAS         hsRas);


/************************************************************************
 * cmiRASReceiveMessage
 * purpose: Notify the RAS instance that a message was received from the
 *          network and should be handled.
 * input  : hRasMgr         - RAS instance that needs to handle the message
 *          chanType        - Type of channel to send through
 *          srcAddress      - Address of the sender
 *          message         - The message received
 * output : none
 * return : If an error occurs, the function returns a negative value.
 *          If no error occurs, the function returns a non-negative value.
 ************************************************************************/
int RVCALLCONV cmiRASReceiveMessage(
    IN HRASMGR          hRasMgr,
    IN rasChanType      chanType,
    IN cmRASTransport*  srcAddress,
    IN RvUint8*         messageBuf,
    IN RvSize_t         messageLength);







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


/************************************************************************
 * cmiEvRasMessageToSend
 * purpose: Callback function that the RAS calls when it wants to send
 *          out a RAS message through the network.
 * input  : hApp            - Stack's instance handle
 *          chanType        - Type of channel to send through
 *                            (for now, always through unicast)
 *          destAddress     - Address to send the message to
 *          message         - The message to send
 * 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 RvStatus (RVCALLCONV *cmiEvRasMessageToSend)(
    IN HAPP             hApp,
    IN rasChanType      chanType,
    IN cmRASTransport*  destAddress,
    IN RvUint8*         messageBuf,
    IN RvSize_t         messageLength);