sipxtapievents.h

来自「基于sipfoundy 公司开发的sipx协议API」· C头文件 代码 · 共 914 行 · 第 1/4 页

                                                            transferee supports transfers (REFER method).  The
                                                            event is fired upon a 2xx class response to the SIP
                                                            REFER request. */
    TRANSFER_TRYING,                                   /**< The transfer target is attempting the transfer.  
                                                            This event is sent when transfer target (or proxy /
                                                            B2BUA) receives the call invitation, but before the
                                                            the tranfer target accepts is. */
    TRANSFER_RINGING,                                  /**< The transfer target is ringing.  This event is 
                                                            generally only sent during blind transfer.  
                                                            Consultative transfer should proceed directly to 
                                                            TRANSFER_SUCCESS or TRANSFER_FAILURE. */
    TRANSFER_SUCCESS,                                  /**< The transfer was completed successfully.  The
                                                            original call to transfer target will
                                                            automatically disconnect.*/
    TRANSFER_FAILURE,                                  /**< The transfer failed.  After a transfer fails,
                                                            the application layer is responsible for 
                                                            recovering original call to the transferee. 
                                                            That call is left on hold. */
    SECURITY_SELF_SIGNED_CERT = SECURITY_EVENT + 1,    /**< A self-signed certificate is being used for S/MIME. */
    SECURITY_SESSION_NOT_SECURED,                      /**< Fired if a secure session could not be made. */
    SECURITY_REMOTE_SMIME_UNSUPPORTED,                 /**< Fired if the remote party's user-agent does not
                                                                             support S/MIME. */
    IDENTITY_CHANGE_UNKNOWN = IDENTITY_CHANGE + 1,   /**< The P-Asserted-Identity changed for a unknown reason
                                                                             The identity may have changed because of a transfer or
                                                                             some other reason, but the signalling did not give any
                                                                             indication as to why it changed. */

} SIPX_CALLSTATE_MINOR ;


/**
 * Enumeration of possible Line Events.
 */
typedef enum SIPX_LINE_EVENT_TYPE_MAJOR
{
   SIPX_LINE_EVENT_UNKNOWN          = -1,       /**< This is the initial Line event state. */
   SIPX_LINE_EVENT_REGISTERING      = 20000,    /**< The REGISTERING event is fired when sipXtapi
                                                     has successfully sent a REGISTER message,
                                                     but has not yet received a success response from the
                                                     registrar server */
   SIPX_LINE_EVENT_REGISTERED       = 21000,    /**< The REGISTERED event is fired after sipXtapi has received
                                                     a response from the registrar server, indicating a successful
                                                     registration. */
   SIPX_LINE_EVENT_UNREGISTERING    = 22000,    /**< The UNREGISTERING event is fired when sipXtapi
                                                     has successfully sent a REGISTER message with an expires=0 parameter,
                                                     but has not yet received a success response from the
                                                     registrar server */
   SIPX_LINE_EVENT_UNREGISTERED     = 23000,    /**< The UNREGISTERED event is fired after sipXtapi has received
                                                     a response from the registrar server, indicating a successful
                                                     un-registration. */
   SIPX_LINE_EVENT_REGISTER_FAILED  = 24000,    /**< The REGISTER_FAILED event is fired to indicate a failure of REGISTRATION.
                                                     It is fired in the following cases:  
                                                     The client could not connect to the registrar server.
                                                     The registrar server challenged the client for authentication credentials,
                                                     and the client failed to supply valid credentials.
                                                     The registrar server did not generate a success response (status code == 200)
                                                     within a timeout period.  */
   SIPX_LINE_EVENT_UNREGISTER_FAILED  = 25000, /**< The UNREGISTER_FAILED event is fired to indicate a failure of un-REGISTRATION.
                                                     It is fired in the following cases:  
                                                     The client could not connect to the registrar server.
                                                     The registrar server challenged the client for authentication credentials,
                                                     and the client failed to supply valid credentials.
                                                     The registrar server did not generate a success response (status code == 200)
                                                     within a timeout period.  */
   SIPX_LINE_EVENT_PROVISIONED      = 26000    /**<  The PROVISIONED event is fired when a sipXtapi Line is added, and Registration is not 
                                                     requested (i.e. - sipxLineAdd is called with a bRegister parameter of false. */ 
} SIPX_LINE_EVENT_TYPE_MAJOR;

/**
 * Enumeration of possible minor Line Events.
 */
typedef enum SIPX_LINE_EVENT_TYPE_MINOR
{
    LINE_EVENT_UNKNOWN                                 = -1,       /**< No cause specified. */
    LINE_EVENT_REGISTERING_NORMAL                      = SIPX_LINE_EVENT_REGISTERING + 1, 
    LINE_EVENT_REGISTERED_NORMAL                       = SIPX_LINE_EVENT_REGISTERED + 1, 
    LINE_EVENT_UNREGISTERING_NORMAL                    = SIPX_LINE_EVENT_UNREGISTERING + 1, 
    LINE_EVENT_UNREGISTERED_NORMAL                     = SIPX_LINE_EVENT_UNREGISTERED + 1, 
    LINE_EVENT_REGISTER_FAILED_COULD_NOT_CONNECT       = SIPX_LINE_EVENT_REGISTER_FAILED + 1, 
    LINE_EVENT_REGISTER_FAILED_NOT_AUTHORIZED          = SIPX_LINE_EVENT_REGISTER_FAILED + 2, 
    LINE_EVENT_REGISTER_FAILED_TIMEOUT                 = SIPX_LINE_EVENT_REGISTER_FAILED + 3, 
    LINE_EVENT_UNREGISTER_FAILED_COULD_NOT_CONNECT     = SIPX_LINE_EVENT_UNREGISTER_FAILED + 1, 
    LINE_EVENT_UNREGISTER_FAILED_NOT_AUTHORIZED        = SIPX_LINE_EVENT_UNREGISTER_FAILED + 2, 
    LINE_EVENT_UNREGISTER_FAILED_TIMEOUT               = SIPX_LINE_EVENT_UNREGISTER_FAILED + 3, 
    LINE_EVENT_PROVISIONED_NORMAL                      = SIPX_LINE_EVENT_PROVISIONED + 1     
} SIPX_LINE_EVENT_TYPE_MINOR;

/**
 * Signature for event callback/observer.  Application developers should
 * not block the calling thread.
 *
 * @deprecated Use SIPX_EVENT_CALLBACK_PROC instead
 * @param hCall Source of event
 * @param hLine Line call was made on
 * @param eMajor Major event ID
 * @param eMinor Minor event ID
 * @param pUserData User data provided when listener was added
 */
typedef void (*CALLBACKPROC)( SIPX_CALL hCall,
                              SIPX_LINE hLine,
                              SIPX_CALLSTATE_MAJOR eMajor,
                              SIPX_CALLSTATE_MINOR eMinor,
                              void* pUserData) ;

/**
 * Signature for line event callback/observer.  Application developers should
 * not block the calling thread.
 *
 * @deprecated Use the new callback/event mechanism instead
 * @param hLine Line call was made on
 * @param eMajor Major event ID
 * @param pUserData User data provided when listener was added
 */
typedef void (*LINECALLBACKPROC)(SIPX_LINE hLine, 
						         SIPX_LINE_EVENT_TYPE_MAJOR eMajor, 
						         void* pUserData);    						      


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

/**
 * Add a callback/observer for the purpose of receiving call events
 *
 * @deprecated Use sipxEventListenerAdd instead
 * @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 sipxListenerAdd(const SIPX_INST hInst,
                                         CALLBACKPROC pCallbackProc,
                                         void* pUserData) ;

/**
 * Remove a call event callback/observer.  Supply the same
 * pCallbackProc and pUserData values as sipxListenerAdd.
 *
 * @deprecated Use sipxEventListenerRemove instead
 * @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 sipxListenerRemove(const SIPX_INST hInst,
                                            CALLBACKPROC pCallbackProc,
                                            void* pUserData) ;


/**
 * Create a printable string version of the designated call state event ids.
 * This is generally used for debugging.
 *
 * @param eMajor sipxtapi major event code
 * @param eMinor sipxtapi minor event code
 * @param szBuffer buffer to store event string
 * @param nBuffer length of string buffer szBuffer
 */
SIPXTAPI_API char* sipxCallEventToString(SIPX_CALLSTATE_MAJOR eMajor,
                                     SIPX_CALLSTATE_MINOR eMinor,
                                     char*  szBuffer,
                                     size_t nBuffer) ;

/**
 * Create a printable string version of the designated event.
 * This is generally used for debugging.
 *
 * @param category Event category code
 * @param pEvent Pointer to the Event.
 * @param szBuffer buffer to store event string
 * @param nBuffer length of string buffer szBuffer
 */
SIPXTAPI_API char* sipxEventToString(const SIPX_EVENT_CATEGORY category,
                                     const void* pEvent,
                                     char*  szBuffer,
                                     size_t nBuffer);
/**
 * Add a callback/observer for the purpose of receiving Line events
 *
 * 
 * @deprecated Use sipxEventListenerAdd instead
 * @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 sipxLineListenerAdd(const SIPX_INST hInst,
                                         LINECALLBACKPROC pCallbackProc,
                                         void* pUserData);

/**
 * Remove a Line event callback/observer.  Supply the same
 * pCallbackProc and pUserData values as sipxLineListenerAdd.
 *
 * @deprecated Use sipxEventListenerRemove instead
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param pCallbackProc Function used to receive sipx Line events
 * @param pUserData user data specified as part of sipxListenerAdd
 */
SIPXTAPI_API SIPX_RESULT sipxLineListenerRemove(const SIPX_INST hInst,
                                                LINECALLBACKPROC pCallbackProc,
                                                void* pUserData);
/**
 * Create a printable string version of the designated line event ids.
 * This is generally used for debugging.
 *
 * @deprecated Use the new callback/event mechanism instead
 * @param lineTypeMajor major event type id
 * @param lineTypeMinor minor event type id
 * @param szBuffer buffer to store event string
 * @param nBuffer length of string buffer szBuffer
 */
SIPXTAPI_API char* sipxLineEventToString(SIPX_LINE_EVENT_TYPE_MAJOR lineTypeMajor,
                                         SIPX_LINE_EVENT_TYPE_MINOR lineTypeMinor,
                                         char*  szBuffer,
                                         size_t nBuffer);

/**
 * Create a printable string version of the designated config event.
 * This is generally used for debugging.
 *
 * @param event Configuration event id
 * @param szBuffer Buffer to store event string
 * @param nBuffer Length of string buffer szBuffer
 */
SIPXTAPI_API char* sipxConfigEventToString(SIPX_CONFIG_EVENT event, 
                                           char* szBuffer, 
                                           size_t nBuffer) ;

#endif /* ifndef _sipXtapiEvents_h_ */