sipxtapievents.h

基于sipfoundy 公司开发的sipx协议API

{
    SIPX_SUBSCRIPTION_PENDING,      /**< THe subscription is being set up, but not yet active. */
    SIPX_SUBSCRIPTION_ACTIVE ,      /**< The subscription is currently active. */
    SIPX_SUBSCRIPTION_FAILED ,      /**< The subscription is not active due to a failure.*/
    SIPX_SUBSCRIPTION_EXPIRED ,     /**< The subscription's lifetime has expired. */
    // TBD
} SIPX_SUBSCRIPTION_STATE;

/**
 * Enumeration of cause codes for state subscription state changes.
 */
typedef enum
{
    SUBSCRIPTION_CAUSE_UNKNOWN = -1, /**< No cause specified. */
    SUBSCRIPTION_CAUSE_NORMAL     /**< Normal cause for state change. */
} SIPX_SUBSCRIPTION_CAUSE;

/**
 * An SUBSTATUS event informs that application layer of the status
 * of an outbound SUBSCRIPTION requests;
 */
typedef struct 
{
    size_t                  nSize ;     /**< the size of this structure in bytes */
    SIPX_SUB    hSub ;              /**< a handle to the subscription to which
                                         this state change occurred. */
    SIPX_SUBSCRIPTION_STATE state ;     /**< Enum state value indicating the current
                                             state of the subscription. */
    SIPX_SUBSCRIPTION_CAUSE cause;      /**< Enum cause for the state change in this
                                             event. */
    const char* szSubServerUserAgent;   /**< the User Agent header field value from
                                             the SIP SUBSCRIBE response (may be NULL) */
    
} SIPX_SUBSTATUS_INFO ;



/**
 * A NOTIFY_INFO event signifies that a NOTIFY message was received for
 * an active subscription.
 */ 
typedef struct 
{
    size_t      nSize ;             /**< the size of this structure in bytes */
    SIPX_SUB    hSub ;              /**< a handle to the subscrption which
                                         caused this NOTIFY event to be received. */
    const char* szNotiferUserAgent; /**< the User-Agent header field value from
                                         the SIP NOTIFY response (may be NULL) */
    const char* szContentType ;     /**< string indicating the info content type */     
    const void* pContent ;          /**< pointer to the NOTIFY message content */
    size_t      nContentLength ;    /**< length of the NOTIFY message content */
} SIPX_NOTIFY_INFO ;


/**
 * SIPX_CONFIG_INFO events signifies that a change in configuration was 
 * observed.
 *
 * NOTE: This structure is subject to change. 
 */ 
typedef struct
{
    size_t            nSize ;   /**< the size of this structure in bytes */
    SIPX_CONFIG_EVENT event ;   /**< event code -- see SIPX_CONFIG_EVENT for 
                                     details. */
    void*             pData;    /**< pointer to event data -- SEE SIPX_CONFIG_EVENT
                                     for details. */
} SIPX_CONFIG_INFO ;
					      


/* ============================ FUNCTIONS ================================= */

/**
 * Add a callback/observer for the purpose of receiving sipXtapi events
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param pCallbackProc Function to receive sipx events
 * @param pUserData user data passed along with event data
 */
SIPXTAPI_API SIPX_RESULT sipxEventListenerAdd(const SIPX_INST hInst,
                                             SIPX_EVENT_CALLBACK_PROC pCallbackProc,
                                             void *pUserData);
                                             
/**
 * Remove a sipXtapi event callback/observer.  Supply the same
 * pCallbackProc and pUserData values as sipxEventListenerAdd.
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param pCallbackProc Function used to receive sipx events
 * @param pUserData user data specified as part of sipxListenerAdd
 */
SIPXTAPI_API SIPX_RESULT sipxEventListenerRemove(const SIPX_INST hInst, 
                                            SIPX_EVENT_CALLBACK_PROC pCallbackProc, 
                                            void* pUserData) ;
                                             
                                             
                                            
/* ============================ DEPRECATED DEFININTIONS ======================== */


/**
 * Major call state events identify significant changes in the state of a 
 * call.
 * For backward compatibility.
 * @deprecated Use the new callback/event mechanism instead
 */
typedef enum SIPX_CALLSTATE_MAJOR
{
    UNKNOWN         = 0,    /**< An UNKNOWN event is generated when the state for a call
                                 is no longer known.  This is generally an error
                                 condition; see the minor event for specific causes. */
    NEWCALL         = 1000, /**< The NEWCALL event indicates that a new call has been
                                 created automatically by the sipXtapi.  This event is
                                 most frequently generated in response to an inbound
                                 call request.  */
    DIALTONE        = 2000, /**< The DIALTONE event indicates that a new call has been
                                 created for the purpose of placing an outbound call.
                                 The application layer should determine if it needs to
                                 simulate dial tone for the end user. */
    REMOTE_OFFERING = 2500, /**< The REMOTE_OFFERING event indicates that a call setup
                                 invitation has been sent to the remote party.  The
                                 invitation may or may not every receive a response.  If
                                 a response is not received in a timely manor, sipXtapi
                                 will move the call into a disconnected state.  If
                                 calling another sipXtapi user agent, the reciprocate
                                 state is OFFER. */
    REMOTE_ALERTING = 3000, /**< The REMOTE_ALERTING event indicates that a call setup
                                 invitation has been accepted and the end user is in the
                                 alerting state (ringing).  Depending on the SIP
                                 configuration, end points, and proxy servers involved,
                                 this event should only last for 3 minutes.  Afterwards,
                                 the state will automatically move to DISCONNECTED.  If
                                 calling another sipXtapi user agent, the reciprocate
                                 state is ALERTING. */
    CONNECTED       = 4000, /**< The CONNECTED state indicates that call has been setup
                                 between the local and remote party.  Audio should be
                                 flowing provided and the microphone and speakers should
                                 be engaged. */
    DISCONNECTED    = 5000, /**< The DISCONNECTED state indicates that a call was
                                 disconnected or failed to connect.  A call may move
                                 into the DISCONNECTED states from almost every other
                                 state.  Please review the DISCONNECTED minor events to
                                 understand the cause. */
    OFFERING        = 6000, /**< An OFFERING state indicates that a new call invitation
                                 has been extended to this user agent.  Application
                                 developers should invoke sipxCallAccept(),
                                 sipxCallReject() or sipxCallRedirect() in response.
                                 Not responding will result in an implicit call
                                 sipXcallReject(). */
    ALERTING        = 7000, /**< An ALERTING state indicates that an inbound call has
                                 been accepted and the application layer should alert
                                 the end user.  The alerting state is limited to 3
                                 minutes in most configurations; afterwards the call
                                 will be canceled.  Applications will generally play
                                 some sort of ringing tone in response to this event. */
    DESTROYED       = 8000, /**< The DESTORYED event indicates the underlying resources
                                 have been removed for a call.  This is the last event
                                 that the application will receive for any call.  The
                                 call handle is invalid after this event is received. */
    AUDIO_EVENT     = 9000, /**< The  AUDIO_EVENT event indicates the RTP session has 
                                 either started or stopped. */
    TRANSFER        = 10000, /**< The transfer state indicates a state change in a 
                                 transfer attempt.  Please see the TRANSFER cause 
                                 codes for details on each state transition */
    SECURITY_EVENT  = 11000, /** The SECURITY_EVENT is sent to the application 
                                 when S/MIME or SRTP events occur which the application
                                 should know about. */ 
    IDENTITY_CHANGE = 12000 /**  The identity of the remote party on this call has changed
                                 to the identity given  in szRemoteIdentity. */
                                 
} SIPX_CALLSTATE_MAJOR ;



/**
 * Minor call events identify the reason for a SIPX_CALLSTATE_MAJOR event or
 * provide more detail.
 * For backward compatibility.
 * @deprecated Use the new callback/event mechanism instead
 */
typedef enum SIPX_CALLSTATE_MINOR
{
    NEW_CALL_NORMAL            = NEWCALL + 1,          /**< See NEWCALL major event */
    NEW_CALL_TRANSFERRED       = NEWCALL + 2,	       /**< Call created because a transfer has is
	                                                        occurring */
    NEW_CALL_TRANSFER          = NEWCALL + 3,          /**< Call created because a transfer has 
                                                            been initiated locally. */
    DIALTONE_UNKNOWN           = DIALTONE + 1,         /**< See DIALTONE major event */
    DIALTONE_CONFERENCE        = DIALTONE,             /**< Call created as part of conference */
    REMOTE_OFFERING_NORMAL     = REMOTE_OFFERING + 1,  /**< See REMOTE_OFFERING major event */
    REMOTE_ALERTING_NORMAL     = REMOTE_ALERTING + 1,  /**< Remote party is alerting, play ringback
                                                            locally */
    REMOTE_ALERTING_MEDIA,                             /**< Remote party is alerting and providing
                                                            ringback audio*/
    CONNECTED_ACTIVE           = CONNECTED + 1,        /**< Call is connected and active (playing
                                                            local media)*/
    CONNECTED_ACTIVE_HELD,                             /**< Call is connected, held (not playing local
                                                            media), and bridging media for a
                                                            conference */
    CONNECTED_INACTIVE,                                /**< Call is held (not playing local media) and
                                                            is not bridging any other calls */
    DISCONNECTED_BADADDRESS    = DISCONNECTED + 1,     /**< Disconnected: Invalid or unreachable
                                                            address */
    DISCONNECTED_BUSY,                                 /**< Disconnected: Caller or Callee was busy*/
    DISCONNECTED_NORMAL,                               /**< Disconnected: Normal call tear down (either
                                                            local or remote)*/
    DISCONNECTED_RESOURCES,                            /**< Disconnected: Not enough resources
                                                            available to complete call*/
    DISCONNECTED_NETWORK,                              /**< Disconnected: A network error cause call
                                                            to fail*/
    DISCONNECTED_REDIRECTED,                           /**< Disconnected: Call was redirected a
                                                            different user agent */
    DISCONNECTED_NO_RESPONSE,                          /**< Disconnected: No response was received */
    DISCONNECTED_AUTH,                                 /**< Disconnected: Unable to authenticate */
    DISCONNECTED_UNKNOWN,                              /**< Disconnected: Unknown reason */

    OFFERING_ACTIVE            = OFFERING + 1,         /**< See OFFERING major event */
    ALERTING_NORMAL            = ALERTING + 1,         /**< See ALERTING major event */
    DESTROYED_NORMAL           = DESTROYED + 1,        /**< See DESTROYED major event */

    AUDIO_START                = AUDIO_EVENT + 1,      /**< RTP session started */
    AUDIO_STOP                 = AUDIO_START + 1,      /**< RTP session stopped */

    TRANSFER_INITIATED         = TRANSFER + 1,         /**< A transfer attempt has been initiated.  This event
                                                            is sent when a user agent attempts either a blind
                                                            or consultative transfer. */
    TRANSFER_ACCEPTED,                                 /**< A transfer attempt has been accepted by the remote
                                                            transferee.  This event indicates that the