sipxtapievents.h

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

// 
// 
// Copyright (C) 2005-2006 SIPez LLC.
// Licensed to SIPfoundry under a Contributor Agreement.
// 
// Copyright (C) 2004-2006 SIPfoundry Inc.
// Licensed by SIPfoundry under the LGPL license.
// 
// Copyright (C) 2004-2006 Pingtel Corp.
// Licensed to SIPfoundry under a Contributor Agreement.
// 
// $$
//////////////////////////////////////////////////////////////////////////////

/**
 * @file sipXtapiEvents.h
 * sipXtapi event declarations
 *
 * The sipXtapiEvents.h header file defines all of the events fired as part of
 * receiving inbound calls and placing outbound calls.  Each event notification
 * is comprised of a major event and a minor event.  The major event identifies
 * a significant state transition (e.g. from connected to disconnected.  The minor
 * event identifies the reason for the change (cause code).
 *
 * Below you will find state diagrams that show the typical event transitions
 * for both outbound and inbound calls.
 *
 * @image html callevents_inbound.gif
 *
 * Figure 1: Event flows for an inbound call (received call)
 *
 * @image html callevents_outbound.gif
 *
 * Figure 2: Event flows for an outbound call (placed call)
 */
#ifndef _SIPXTAPIEVENT_H
#define _SIPXTAPIEVENT_H


// SYSTEM INCLUDES
// APPLICATION INCLUDES
#include "sipXtapi.h"

// DEFINES
// MACROS
// EXTERNAL FUNCTIONS
// EXTERNAL VARIABLES
// CONSTANTS
// FORWARD DECLARATIONS


/**
 * Enum with all of the possible event types.
 */
typedef enum SIPX_EVENT_CATEGORY
{
    EVENT_CATEGORY_CALLSTATE,       /**< CALLSTATE events signify a change in state of a 
                                         call.  States range from the notification of a 
                                         new call to ringing to connection established to 
                                         changes in audio state (starting sending, stop 
                                         sending) to termination of a call. */
    EVENT_CATEGORY_LINESTATE,       /**< LINESTATE events indicate changes in the status 
                                         of a line appearance.  Lines identify inbound 
                                         and outbound identities and can be either 
                                         provisioned (hardcoded) or configured to 
                                         automatically register with a registrar.  
                                         Lines also encapsulate the authentication 
                                         criteria needed for dynamic registrations. */
    EVENT_CATEGORY_INFO_STATUS,     /**< INFO_STATUS events are sent when the application 
                                         requests sipXtapi to send an INFO message to 
                                         another user agent.  The status event includes 
                                         the response for the INFO method.  Application 
                                         developers should look at this event to determine 
                                         the outcome of the INFO message. */
    EVENT_CATEGORY_INFO,            /**< INFO events are sent to the application whenever 
                                         an INFO message is received by the sipXtapi user 
                                         agent.  INFO messages are sent to a specific call.
                                         sipXtapi will automatically acknowledges the INFO 
                                         message at the protocol layer. */
    EVENT_CATEGORY_SUB_STATUS,      /**< Subscription events: OK or expired, notify, etc.*/
    EVENT_CATEGORY_NOTIFY,          /**< Notification of subscribed-to events */
    EVENT_CATEGORY_CONFIG           /**< CONFIG events signify changes in configuration.
                                         For example, when requesting STUN support, a 
                                         notification is sent with the STUN outcome (either
                                         SUCCESS or FAILURE) */
} SIPX_EVENT_CATEGORY;


/**
 * Signature for event callback/observer.  Application developers should
 * not block the calling thread.
 *
 * @param category The category of the event (call, line, subscription, notify, etc.).
 * @param pInfo Pointer to the event info structure.
 * @param pUserData User data provided when listener was added
 */
typedef bool (*SIPX_EVENT_CALLBACK_PROC)(SIPX_EVENT_CATEGORY category, 
                                         void* pInfo, 
                                         void* pUserData);


/**
 * Major call state events identify significant changes in the state of a 
 * call.
 */
typedef enum SIPX_CALLSTATE_EVENT
{
    CALLSTATE_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. */
    CALLSTATE_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.  */
	CALLSTATE_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. */
	CALLSTATE_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. */
	CALLSTATE_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. */
	CALLSTATE_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. */
	CALLSTATE_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. */
	CALLSTATE_OFFERING        = 6000, /**< An OFFERING state indicates that a new call invitation 
                                 has been extended this user agent.  Application 
                                 developers should invoke sipxCallAccept(), 
                                 sipxCallReject() or sipxCallRedirect() in response.  
                                 Not responding will result in an implicit call 
                                 sipXcallReject(). */

/** VIDEO: The CALLSTATE_INFO should contain supported remote audio and video codecs offered */

                                 
    CALLSTATE_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. */

/** VIDEO: The CALLSTATE_INFO should contain supported remote audio and video codecs offered */


    CALLSTATE_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. */
	CALLSTATE_AUDIO_EVENT      = 9000, /**< The  AUDIO_EVENT event indicates the RTP session has 
                                 either started or stopped. */
    CALLSTATE_TRANSFER         = 10000, /**< The transfer state indicates a state change in a 
                                 transfer attempt.  Please see the CALLSTATE_TRANSFER cause 
                                 codes for details on each state transition */
    CALLSTATE_SECURITY_EVENT   = 11000, /** The SECURITY_EVENT is sent to the application 
                                           when S/MIME or SRTP events occur which the application
                                           should know about. */ 
    CALLSTATE_IDENTITY_CHANGE  = 12000 /** The identity of the remote party on this call has changed
                                           to the identity given  in szRemoteIdentity. */
} SIPX_CALLSTATE_EVENT;

 
/**
 * Callstate cuase events identify the reason for a Callstate event or 
 * provide more detail.
 */
typedef enum SIPX_CALLSTATE_CAUSE
{
	CALLSTATE_NEW_CALL_NORMAL		  = CALLSTATE_NEWCALL + 1,	        /**< See NEWCALL callstate event */
	CALLSTATE_NEW_CALL_TRANSFERRED	  = CALLSTATE_NEWCALL + 2,	        /**< Call created because a transfer has is
	                                                                         occurring */
	CALLSTATE_NEW_CALL_TRANSFER	      = CALLSTATE_NEWCALL + 3,	        /**< Call created because a transfer has 
                                                                             been initiated locally. */
	CALLSTATE_DIALTONE_UNKNOWN        = CALLSTATE_DIALTONE + 1,         /**< See DIALTONE callstate event */
    CALLSTATE_DIALTONE_CONFERENCE     = CALLSTATE_DIALTONE,             /**< Call created as part of conference */
	CALLSTATE_REMOTE_OFFERING_NORMAL  = CALLSTATE_REMOTE_OFFERING + 1,  /**< See REMOTE_OFFERING callstate event */
	CALLSTATE_REMOTE_ALERTING_NORMAL  = CALLSTATE_REMOTE_ALERTING + 1,  /**< Remote party is alerting, play ringback 
                                                                             locally */
	CALLSTATE_REMOTE_ALERTING_MEDIA,                                    /**< Remote party is alerting and providing 
                                                                             ringback audio*/
	CALLSTATE_CONNECTED_ACTIVE		  = CALLSTATE_CONNECTED + 1,        /**< Call is connected and active (playing 
                                                                             local media)*/
	CALLSTATE_CONNECTED_ACTIVE_HELD,                                    /**< Call is connected, held (not playing local
                                                                             media), and bridging media for a 
                                                                             conference */
    CALLSTATE_CONNECTED_INACTIVE,                                       /**< Call is held (not playing local media) and
                                                                             is not bridging any other calls */
    CALLSTATE_CONNECTED_REQUEST_NOT_ACCEPTED,                           /**< The callee rejected a hold request, or some other
                                                                             request for a change in the session, and the connection
                                                                             is still active. */                                                     
	CALLSTATE_DISCONNECTED_BADADDRESS = CALLSTATE_DISCONNECTED + 1,     /**< Disconnected: Invalid or unreachable 
                                                                             address */
	CALLSTATE_DISCONNECTED_BUSY,                                        /**< Disconnected: Caller or Callee was busy*/
	CALLSTATE_DISCONNECTED_NORMAL,                                      /**< Disconnected: Normal call tear down (either 
                                                                             local or remote)*/
    CALLSTATE_DISCONNECTED_RESOURCES,                                   /**< Disconnected: Not enough resources 
                                                                             available to complete call*/
    CALLSTATE_DISCONNECTED_NETWORK,                                     /**< Disconnected: A network error cause call 
                                                                             to fail*/
	CALLSTATE_DISCONNECTED_REDIRECTED,                                  /**< Disconnected: Call was redirected a 
                                                                             different user agent */
	CALLSTATE_DISCONNECTED_NO_RESPONSE,                                 /**< Disconnected: No response was received */
    CALLSTATE_DISCONNECTED_AUTH,                                        /**< Disconnected: Unable to authenticate */
    CALLSTATE_DISCONNECTED_UNKNOWN,                                     /**< Disconnected: Unknown reason */

	CALLSTATE_OFFERING_ACTIVE		  = CALLSTATE_OFFERING + 1,         /**< See OFFERING callstate event */
	CALLSTATE_ALERTING_NORMAL		  = CALLSTATE_ALERTING + 1,         /**< See ALERTING callstate event */
	CALLSTATE_DESTROYED_NORMAL        = CALLSTATE_DESTROYED + 1,        /**< See DESTROYED callstate event */

    CALLSTATE_AUDIO_START             = CALLSTATE_AUDIO_EVENT + 1,      /**< RTP session started */
    CALLSTATE_AUDIO_STOP              = CALLSTATE_AUDIO_START + 1,      /**< RTP session stopped */