transport.h

基于h323协议的软phone

/***********************************************************************
        Copyright (c) 2002 RADVISION Ltd.
************************************************************************
NOTICE:
This document contains information that is confidential and proprietary
to RADVISION Ltd.. No part of this document may be reproduced in any
form whatsoever without written prior approval by RADVISION Ltd..

RADVISION Ltd. reserve the right to revise this publication and make
changes without obligation to notify any person of such revisions or
changes.
***********************************************************************/

#ifndef _TRANSPORT_H
#define _TRANSPORT_H

/*************************************************************************************
 * Transport module
 * ----------------
 *
 * This is the module that interacts with the network on one hand, while on the other
 * it communicates with the other protocol modules, such as Q.931, H.245, H.450 etc.
 *
 * The lower level can handle TPKT, Annex E types of communications in a transparent
 * way to th eupper layers.
 *
 * The upper level exports and imports (by means of APIs and callbacks) messages to the
 * different modules: Mainly Q.931, H.245 (including tunneled messages) and the
 * rest of the tunneled protocols (Annex M, Annex L).
 *
 **************************************************************************************/

#include "rvinternal.h"
#include "rvh323connection.h"
#include "pvaltree.h"

#ifdef __cplusplus
extern "C" {
#endif


/* Handle to the instance of the transport module, generated by init */
RV_DECLARE_HANDLE(HAPPTRANS);

/* Application Handle to the instance of the transport module, generated by init */
RV_DECLARE_HANDLE(HAPPATRANS);

/* Stack internal handle to a session */
RV_DECLARE_HANDLE(HSTRANSSESSION);

/* Application handle to a session, in most cases will be the call handle
   associated with that sesseion */
RV_DECLARE_HANDLE(HATRANSSESSION);

/* Stack internal host handle, used to identify a specific host connection. */
RV_DECLARE_HANDLE(HSTRANSHOST);

/* Application host handle. */
RV_DECLARE_HANDLE(HATRANSHOST);


/* Error codes that can be returned by the module's API and callbacks */
typedef enum {
        cmTransErr = -1,            /* general error */
        cmTransOK,                  /* All is ok */
        cmTransConnectionClosed,    /* The connection no longer active */
        cmTransConnectionBusy,      /* The connection is still sending previous messages */
        cmTransHostNotMultiplexed,  /* A non multiplexed host was used fr more than one session */
        cmTransWouldBlock,          /* not enough buffers for send/receive */
        cmTransIgnoreMessage        /* Ignore the message and stop process it (may be set by H.235) */
} TRANSERR;

/* Types of messages */
typedef enum {
    cmTransQ931Type,
    cmTransH245Type,
    cmTransAnnexLType,
    cmTransAnnexMType
} TRANSTYPE;

/* Types of connection */
typedef enum {
    cmTransQ931Conn,
    cmTransH245Conn
} TRANSCONNTYPE;

/* The parameters that each session may have */
typedef enum {
    cmTransParam_host,                          /* What host connection is associated with
                                                   the session (in multiplexing several
                                                   sessions may have the same host connection) */
    cmTransParam_H245Connection,                /* The host used to establish the H.245 connection
                                                    (read only param) */
    cmTransParam_isTunnelingSupported,          /* Do we support tunneling for the session */
    cmTransParam_notEstablishControl,           /* Don't open an H.245 connection */
    cmTransParam_H245Stage,                     /* when is it allowed to send the H.245 address */
    cmTransParam_isParallelTunnelingSupported,  /* Is it allowed to have both FastStart and
                                                   tunneling on the same call */
    cmTransParam_shutdownEmptyConnection,       /* Should the host connection associated with this
                                                   session be closed when it has no more
                                                   sessions attached to it (multiplexing param) */
    cmTransParam_isMultiplexed,                 /* Does the host connection associated with this
                                                   session supports multiplexing */
    cmTransParam_isAnnexESupported              /* Do we support annex E for this session
                                                   (yes/no/maybe)*/
} TRANSSESSIONPARAM;

/* The parameters that each session may have */
typedef enum
{
    cmTransHostParam_shutdownEmptyConnection,   /* Should the host connection be closed when
                                                   it has no more sessions attached to
                                                   it (multiplexing param) */
    cmTransHostParam_isMultiplexed,             /* Does the host connection supports multiplexing */
    cmTransHostParam_remoteAddress,             /* What is the Q.931 address */
    cmTransHostParam_localAddress,              /* what is out local address for Q.931 */
    cmTransHostParam_isAnnexESupported,         /* Do we support annex E on this host */
    cmTransHostParam_socketConnection           /* The connection pointer */
} TRANSHOSTPARAM;


typedef struct
{
    RvUint32 useAnnexE;
    RvUint32 t_R1;
    RvUint32 t_R2;
    RvUint32 n_R1;
    RvUint32 t_IMA1;
    RvUint32 n_IMA1;
    RvUint32 t_DT;
} CMTRANSANNEXEPARAM;


/**************************************************************************************/
/* Session related callbacks that are used by the transport module */
/**************************************************************************************/

typedef
/**************************************************************************************
 * cmEvTransNewSession (CALLBACK)
 *
 * Purpose: To report to the user that a new session was created due to a new
 *          incoming message. This callback is called only when a new message actually
 *          arrives and not when the connection is established.
 *
 * Input:   hsTrans         - The stack handle of the instance.
 *          haTrans         - The application handle of the instance.
 *          hsTransSession  - The stack handle of the session.
 *          pvtNode         - the node of the SETUP message that caused the creation.
 *
 * Output:  haTransSession  - The application handle of the session.
 *          cause           - In case of rejection, the cause (as in RELEASE COMPLETE).
 *          reasonNameId    - In case of rejection, the reason name Id (as in RELEASE COMPLETE).
 *          manualRAS       - If the appliaction is working in manual RAS mode.
 *
 **************************************************************************************/
    TRANSERR (*cmEvTransNewSessionT)(   IN  HAPPTRANS        hsTrans,
                                        IN  HAPPATRANS       haTrans,
                                        IN  HSTRANSSESSION   hsTransSession,
                                        OUT HATRANSSESSION   *haTransSession,
                                        IN  int              pvtNode,
                                        OUT int              *cause,
                                        OUT RvPstFieldId     *reasonNameId);

typedef
/**************************************************************************************
 * cmEvTransConnectionOnSessionClosed (CALLBACK)
 *
 * Purpose: To report to the user that a session was closed, either normally (i.e.
 *          by the other end) or abnormaly due to connection errors.
 *
 * Input:   hsTransSession - The stack handle of the session.
 *          haTransSession - The application handle of the session.
 *          type           - The connection type.
 *
 **************************************************************************************/
    TRANSERR (*cmEvTransConnectionOnSessionClosedT)(IN HSTRANSSESSION hsTransSession,
                                                    IN HATRANSSESSION haTransSession,
                                                    IN TRANSCONNTYPE  type);


typedef
/**************************************************************************************
 * cmEvTransSessionNewConnection (CALLBACK)
 *
 * Purpose: To report to the user that a a new connection was opened
 *          for the given session.
 *
 * Input:   hsTransSession - The stack handle of the session.
 *          haTransSession - The application handle of the session.
 *          type           - The type of the connection (Q.931 or H.245)
 *
 **************************************************************************************/
    TRANSERR (*cmEvTransSessionNewConnectionT)( IN HSTRANSSESSION   hsTransSession,
                                                IN HATRANSSESSION   haTransSession,
                                                IN TRANSCONNTYPE    type);


typedef
/**************************************************************************************
 * cmEvTransNewMessage (CALLBACK)
 *
 * Purpose: To report to the user that a new message arrived for a session.
 *
 * Input:   hsTransSession - The stack handle of the session.
 *          haTransSession - The application handle of the session.
 *          type           - The type of the message (Q.931/H.245).
 *          pvtNode        - The pvt node of the decoded message.
 *          hMsgContext    - External context associated with the message.
 *
 **************************************************************************************/
    TRANSERR (*cmEvTransNewMessageT)(IN HSTRANSSESSION          hsTransSession,
                                     IN HATRANSSESSION          haTransSession,
                                     IN RvH323ConnectionType    type,
                                     IN int                     pvtNode,
                                     IN void                    *hMsgContext);

typedef
/**************************************************************************************
 * cmEvTransWrite (CALLBACK)
 *
 * Purpose: To report to the user that new buffers are available and that a send operation
 *          may continue successfully.
 *
 * Input:   hsTransSession - The stack handle of the session which previously was pending.
 *          haTransSession - The application handle of the session.
 *
 **************************************************************************************/
    TRANSERR (*cmEvTransWriteT)(IN HSTRANSSESSION hsTransSession,
                                IN HATRANSSESSION haTransSession );


typedef
/**************************************************************************************
 * cmEvTransBadMessage (CALLBACK)
 *
 * Purpose: To report to the user that a message for a session could not be decoded
 *          or encoded.
 *
 * Input:   hsTransSession  - The stack handle of the session.
 *          haTransSession  - The application handle of the session.
 *          type            - The type of the message (Q.931/H.245).
 *          msg             - The encoded message
 *          msgSize         - The encoded message size
 *          outgoing        - RV_TRUE: outgoing message, RV_FALSE-incoming message
 *
 **************************************************************************************/
    TRANSERR (*cmEvTransBadMessageT)(IN HSTRANSSESSION          hsTransSession,
                                     IN HATRANSSESSION          haTransSession,
                                     IN RvH323ConnectionType    type,
                                     RvUint8*                   msg,
                                     int                        msgSize,
                                     RvBool                     outgoing);

typedef
/**************************************************************************************
 * cmEvTransGetMessageNode (CALLBACK)
 *
 * Purpose: To ask the user to give a node id to a skeleton of the requested message.
 *
 * Input:   hPvt    - handle to the pvt we are using
 *          msgType - The type of the message we need.
 *
 * Output:  nodeId  - node id (read-only, do not modify) of the requested message.
 *
 **************************************************************************************/
    TRANSERR (*cmEvTransGetMessageNodeT)(IN  HAPPATRANS         hAppATrans,
                                         IN  cmCallQ931MsgType  msgType,
                                         OUT int                *nodeId);

typedef
/**************************************************************************************
 * cmEvTransNewH450Message (CALLBACK)
 *
 * Purpose: To report to the user that an H.450 message was just received.
 *
 * Input:   hsTransSession  - The stack handle of the session.
 *          haTransSession  - The application handle of the session.
 *          msg             - The encoded message
 *          msgSize         - The encoded message size
 *          msgType         - The type of the message from which tunneled msgs came.
 *
 **************************************************************************************/
    TRANSERR (*cmEvTransNewH450MessageT)(IN HSTRANSSESSION  hsTransSession,
                                         IN HATRANSSESSION  haTransSession,
                                         IN int             msg,
                                         IN int             msgSize,
                                         IN int             msgType);
typedef
/**************************************************************************************
 * cmEvTransNewAnnexMMessage (CALLBACK)
 *
 * Purpose: To report to the user that an Annex M message was just received.
 *
 * Input:   hsTransSession      - The stack handle of the session.
 *          haTransSession      - The application handle of the session.
 *          annexMElement       - The node id of the annex M element of tunneling
 *          msgType         - The type of the message from which tunneled msgs came.
 *
 **************************************************************************************/
    TRANSERR (*cmEvTransNewAnnexMMessageT)(IN HSTRANSSESSION    hsTransSession,
                                           IN HATRANSSESSION    haTransSession,