sipXtapiEvents.h

Go to the documentation of this file.

//  
// Copyright (C) 2006-2021 SIPez LLC.  All rights reserved.
//
// Copyright (C) 2007 Robert J. Andreasen, Jr.
// 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.  All rights reserved.
// Licensed to SIPfoundry under a Contributor Agreement.
//
// $$


#ifndef _SIPXTAPIEVENT_H
#define _SIPXTAPIEVENT_H

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

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

typedef enum SIPX_EVENT_CATEGORY
{
    EVENT_CATEGORY_CALLSTATE,       
    EVENT_CATEGORY_LINESTATE,       
    EVENT_CATEGORY_INFO_STATUS,     
    EVENT_CATEGORY_INFO,            
    EVENT_CATEGORY_SUB_STATUS,      
    EVENT_CATEGORY_NOTIFY,          
    EVENT_CATEGORY_CONFIG,          
    EVENT_CATEGORY_SECURITY,        
    EVENT_CATEGORY_MEDIA,           
    EVENT_CATEGORY_KEEPALIVE        
} SIPX_EVENT_CATEGORY;

#define VALID_SIPX_EVENT_CATEGORY(x) (((x) >= EVENT_CATEGORY_CALLSTATE) && ((x) <= EVENT_CATEGORY_KEEPALIVE))

typedef bool (SIPX_CALLING_CONVENTION *SIPX_EVENT_CALLBACK_PROC)(SIPX_EVENT_CATEGORY category, 
                                                                 void* pInfo, 
                                                                 void* pUserData);
typedef enum SIPX_CALLSTATE_EVENT
{
   CALLSTATE_UNKNOWN         = 0,    
   CALLSTATE_NEWCALL         = 1000, 
   CALLSTATE_DIALTONE        = 2000, 
   CALLSTATE_REMOTE_OFFERING = 2500, 
   CALLSTATE_REMOTE_ALERTING = 3000, 
   CALLSTATE_CONNECTED       = 4000, 
   CALLSTATE_BRIDGED         = 5000, 
   CALLSTATE_HELD            = 6000, 
   CALLSTATE_REMOTE_HELD     = 7000, 
   CALLSTATE_DISCONNECTED    = 8000, 
   CALLSTATE_OFFERING        = 9000, 
   CALLSTATE_ALERTING        = 10000, 
   CALLSTATE_DESTROYED       = 11000, 
   CALLSTATE_TRANSFER_EVENT   = 12000, 
} SIPX_CALLSTATE_EVENT;

 
typedef enum SIPX_CALLSTATE_CAUSE
{
   CALLSTATE_CAUSE_UNKNOWN,        
   CALLSTATE_CAUSE_NORMAL,         
   CALLSTATE_CAUSE_TRANSFERRED,   
   CALLSTATE_CAUSE_TRANSFER,         
   CALLSTATE_CAUSE_CONFERENCE,     
   CALLSTATE_CAUSE_EARLY_MEDIA,    
   CALLSTATE_CAUSE_REQUEST_NOT_ACCEPTED, 
   CALLSTATE_CAUSE_BAD_ADDRESS,    
   CALLSTATE_CAUSE_BUSY,           
   CALLSTATE_CAUSE_RESOURCE_LIMIT, 
   CALLSTATE_CAUSE_NETWORK,        
   CALLSTATE_CAUSE_REDIRECTED,     
   CALLSTATE_CAUSE_NO_RESPONSE,    
   CALLSTATE_CAUSE_AUTH,           
   CALLSTATE_CAUSE_TRANSFER_INITIATED,  
   CALLSTATE_CAUSE_TRANSFER_ACCEPTED,  
   CALLSTATE_CAUSE_TRANSFER_TRYING,
   CALLSTATE_CAUSE_TRANSFER_RINGING,   
   CALLSTATE_CAUSE_TRANSFER_SUCCESS,
   CALLSTATE_CAUSE_TRANSFER_FAILURE,
   CALLSTATE_CAUSE_REMOTE_SMIME_UNSUPPORTED,
   CALLSTATE_CAUSE_SMIME_FAILURE,
   CALLSTATE_CAUSE_SHUTDOWN,      
   CALLSTATE_CAUSE_BAD_REFER,     
   CALLSTATE_CAUSE_NO_KNOWN_INVITE, 
   CALLSTATE_CAUSE_BYE_DURING_IDLE, 
   CALLSTATE_CAUSE_UNKNOWN_STATUS_CODE, 
   CALLSTATE_CAUSE_BAD_REDIRECT,    
   CALLSTATE_CAUSE_TRANSACTION_DOES_NOT_EXIST, 
   CALLSTATE_CAUSE_CANCEL,        
   CALLSTATE_CAUSE_NO_CODECS,     
   CALLSTATE_CAUSE_SERVER_ERROR   
} SIPX_CALLSTATE_CAUSE ;

 typedef enum SIPX_LINESTATE_EVENT
{
    LINESTATE_UNKNOWN         = 0,        
    LINESTATE_REGISTERING     = 20000,    
    LINESTATE_REGISTERED      = 21000,    
    LINESTATE_UNREGISTERING   = 22000,    
    LINESTATE_UNREGISTERED    = 23000,    
    LINESTATE_REGISTER_FAILED = 24000,    
    LINESTATE_UNREGISTER_FAILED  = 25000, 
    LINESTATE_PROVISIONED      = 26000,   
} SIPX_LINESTATE_EVENT;  


typedef enum SIPX_LINESTATE_CAUSE
{
    LINESTATE_CAUSE_UNKNOWN                           = 0,                                 
    LINESTATE_REGISTERING_NORMAL                      = LINESTATE_REGISTERING + 1,         
    LINESTATE_REGISTERED_NORMAL                       = LINESTATE_REGISTERED + 1,          
    LINESTATE_UNREGISTERING_NORMAL                    = LINESTATE_UNREGISTERING + 1,       
    LINESTATE_UNREGISTERED_NORMAL                     = LINESTATE_UNREGISTERED + 1,        
    LINESTATE_REGISTER_FAILED_COULD_NOT_CONNECT       = LINESTATE_REGISTER_FAILED + 1,     
    LINESTATE_REGISTER_FAILED_NOT_AUTHORIZED          = LINESTATE_REGISTER_FAILED + 2,     
    LINESTATE_REGISTER_FAILED_TIMEOUT                 = LINESTATE_REGISTER_FAILED + 3,     
    LINESTATE_UNREGISTER_FAILED_COULD_NOT_CONNECT     = LINESTATE_UNREGISTER_FAILED + 1,   
    LINESTATE_UNREGISTER_FAILED_NOT_AUTHORIZED        = LINESTATE_UNREGISTER_FAILED + 2,   
    LINESTATE_UNREGISTER_FAILED_TIMEOUT               = LINESTATE_UNREGISTER_FAILED + 3,   
    LINESTATE_PROVISIONED_NORMAL                      = LINESTATE_PROVISIONED + 1          
} SIPX_LINESTATE_CAUSE;




enum SIPX_INFOSTATUS_EVENT
{
    INFOSTATUS_UNKNOWN       = 0 ,     
    INFOSTATUS_RESPONSE      = 30000,  
    INFOSTATUS_NETWORK_ERROR = 31000   
};


enum SIPX_CONFIG_EVENT
{
    CONFIG_UNKNOWN = 0,           
    CONFIG_STUN_SUCCESS  = 40000, 
    CONFIG_STUN_FAILURE  = 41000, 
} ;


typedef enum SIPX_SECURITY_EVENT
{
    SECURITY_UNKNOWN       = 0,
    SECURITY_ENCRYPT = 1000, 
    SECURITY_DECRYPT = 2000, 
    SECURITY_TLS              = 4000, 
} SIPX_SECURITY_EVENT;

typedef enum SIPX_SECURITY_CAUSE
{
    SECURITY_CAUSE_UNKNOWN = 0,                      
    SECURITY_CAUSE_NORMAL,                           
    SECURITY_CAUSE_ENCRYPT_SUCCESS,                  
    SECURITY_CAUSE_ENCRYPT_FAILURE_LIB_INIT,         
    SECURITY_CAUSE_ENCRYPT_FAILURE_BAD_PUBLIC_KEY,   
    SECURITY_CAUSE_ENCRYPT_FAILURE_INVALID_PARAMETER,
    SECURITY_CAUSE_DECRYPT_SUCCESS,                  
    SECURITY_CAUSE_DECRYPT_FAILURE_DB_INIT,          
    SECURITY_CAUSE_DECRYPT_FAILURE_BAD_DB_PASSWORD,  
    SECURITY_CAUSE_DECRYPT_FAILURE_INVALID_PARAMETER,
    SECURITY_CAUSE_DECRYPT_BAD_SIGNATURE,            
    SECURITY_CAUSE_DECRYPT_MISSING_SIGNATURE,        
    SECURITY_CAUSE_DECRYPT_SIGNATURE_REJECTED,       
    SECURITY_CAUSE_TLS_SERVER_CERTIFICATE,           
    SECURITY_CAUSE_TLS_BAD_PASSWORD,                
    SECURITY_CAUSE_TLS_LIBRARY_FAILURE,             
    SECURITY_CAUSE_REMOTE_HOST_UNREACHABLE,         
    SECURITY_CAUSE_TLS_CONNECTION_FAILURE,          
    SECURITY_CAUSE_TLS_HANDSHAKE_FAILURE,           
    SECURITY_CAUSE_SIGNATURE_NOTIFY,                
    SECURITY_CAUSE_TLS_CERTIFICATE_REJECTED         
} SIPX_SECURITY_CAUSE;


typedef enum SIPX_MEDIA_EVENT
{
    MEDIA_UNKNOWN     = 0,      
    MEDIA_LOCAL_START = 50000,  
    MEDIA_LOCAL_STOP,           
    MEDIA_REMOTE_START,         
    MEDIA_REMOTE_STOP,          
    MEDIA_REMOTE_SILENT,        
    MEDIA_PLAYFILE_START,       
    MEDIA_PLAYFILE_FINISH,      
    MEDIA_PLAYFILE_STOP,        
    MEDIA_PLAYBUFFER_START,     
    MEDIA_PLAYBUFFER_FINISH,    
    MEDIA_PLAYBUFFER_STOP,      
    MEDIA_RECORDFILE_START,     
    MEDIA_RECORD_PAUSE,         
    MEDIA_RECORD_RESUME,        
    MEDIA_RECORDFILE_STOP,      
    MEDIA_RECORDBUFFER_START,   
    MEDIA_RECORDBUFFER_STOP,    
    MEDIA_REMOTE_DTMF,          
    MEDIA_DEVICE_FAILURE,       
    MEDIA_REMOTE_ACTIVE,        
    MEDIA_MIC_ENERGY_LEVEL,     
    MEDIA_SPEAKER_ENERGY_LEVEL, 
    MEDIA_RTP_ENERGY_LEVEL,     
    MEDIA_H264_SPS,             
    MEDIA_H264_PPS,             
    MEDIA_INPUT_DEVICE_NOT_PRESENT, 
    MEDIA_OUTPUT_DEVICE_NOT_PRESENT, 
    MEDIA_INPUT_DEVICE_NOW_PRESENT, 
    MEDIA_OUTPUT_DEVICE_NOW_PRESENT 
} SIPX_MEDIA_EVENT;


typedef enum SIPX_KEEPALIVE_EVENT
{
    KEEPALIVE_START,        
    KEEPALIVE_FEEDBACK,     
    KEEPALIVE_FAILURE,      
    KEEPALIVE_STOP          
} SIPX_KEEPALIVE_EVENT ;

typedef enum SIPX_KEEPALIVE_CAUSE
{
    KEEPALIVE_CAUSE_NORMAL
} SIPX_KEEPALIVE_CAUSE ;


typedef struct SIPX_KEEPALIVE_INFO
{
    size_t                  nSize ;     
    SIPX_KEEPALIVE_EVENT    event ;     
    SIPX_KEEPALIVE_CAUSE    cause ;     
    SIPX_KEEPALIVE_TYPE     type ;      
    const char*             szRemoteAddress ;   
    int                     remotePort ;        
    int                     keepAliveSecs ;     
    const char*             szFeedbackAddress;  
    int                     feedbackPort ;      
} SIPX_KEEPALIVE_INFO ;

typedef enum SIPX_MEDIA_CAUSE
{
    MEDIA_CAUSE_NORMAL,             
    MEDIA_CAUSE_HOLD,               
    MEDIA_CAUSE_UNHOLD,             
    MEDIA_CAUSE_FAILED,             
    MEDIA_CAUSE_DEVICE_UNAVAILABLE, 
    MEDIA_CAUSE_INCOMPATIBLE,        
    MEDIA_CAUSE_DTMF_START,          
    MEDIA_CAUSE_DTMF_STOP,           
    MEDIA_CAUSE_DEVICE_NOW_AVAILABLE 
} SIPX_MEDIA_CAUSE ;

typedef enum SIPX_MEDIA_TYPE
{
    MEDIA_TYPE_AUDIO,   
    MEDIA_TYPE_VIDEO,   
} SIPX_MEDIA_TYPE ;


typedef struct SIPX_MEDIA_INFO
{
    size_t              nSize ;     
    SIPX_MEDIA_EVENT    event ;     
    SIPX_MEDIA_CAUSE    cause ;     
    SIPX_MEDIA_TYPE     mediaType ; 
    SIPX_CALL           hCall ;     
    SIPX_CODEC_INFO     codec ;     
    int                 idleTime;   
    SIPX_TONE_ID        toneId;     
    const char*         deviceName; 
} SIPX_MEDIA_INFO ;


typedef struct SIPX_CALLSTATE_INFO
{
    // TODO: Add a bitmask that identified which structure items are valid.  For 
    //       example, codec and hAssociatedCall are only valid for certain event
    //       sequences.

    size_t    nSize;                
    SIPX_CALL hCall;                
    SIPX_LINE hLine;                
    SIPX_CALLSTATE_EVENT event;     
    SIPX_CALLSTATE_CAUSE cause;     
    SIPX_CALL hAssociatedCall ;     
} SIPX_CALLSTATE_INFO; 


typedef struct                      
{
    size_t    nSize ;               
    SIPX_LINE hLine;                
    SIPX_LINESTATE_EVENT event ;    
    SIPX_LINESTATE_CAUSE cause ;    
} SIPX_LINESTATE_INFO ;


typedef enum SIPX_MESSAGE_STATUS
{
    SIPX_MESSAGE_OK,                  
    SIPX_MESSAGE_FAILURE,             
    SIPX_MESSAGE_SERVER_FAILURE,      
    SIPX_MESSAGE_GLOBAL_FAILURE,      
} SIPX_MESSAGE_STATUS ;

typedef struct SIPX_INFOSTATUS_INFO
{
    size_t              nSize ;             
    SIPX_INFO           hInfo ;             
    SIPX_MESSAGE_STATUS status ;            
    int                 responseCode ;      
    const char*         szResponseText ;    
    SIPX_INFOSTATUS_EVENT event;            
} SIPX_INFOSTATUS_INFO ;


typedef struct SIPX_INFO_INFO
{
    size_t      nSize ;             
    SIPX_CALL   hCall ;             
    SIPX_LINE   hLine ;             
    const char* szFromURL ;         
    const char* szUserAgent;        
    const char* szContentType ;     
    const char* pContent ;          
    size_t      nContentLength ;    
} SIPX_INFO_INFO ;

typedef enum SIPX_SUBSCRIPTION_STATE
{
    SIPX_SUBSCRIPTION_PENDING,      
    SIPX_SUBSCRIPTION_ACTIVE ,      
    SIPX_SUBSCRIPTION_FAILED ,      
    SIPX_SUBSCRIPTION_EXPIRED ,     
    // TBD
} SIPX_SUBSCRIPTION_STATE;

typedef enum SIPX_SUBSCRIPTION_CAUSE
{
    SUBSCRIPTION_CAUSE_UNKNOWN = -1, 
    SUBSCRIPTION_CAUSE_NORMAL     
} SIPX_SUBSCRIPTION_CAUSE;

typedef struct SIPX_SUBSTATUS_INFO
{
    size_t nSize ;                      
    SIPX_SUB hSub ;                     
    SIPX_SUBSCRIPTION_STATE state ;     
    SIPX_SUBSCRIPTION_CAUSE cause;      
    const char* szSubServerUserAgent;   
} SIPX_SUBSTATUS_INFO ;


typedef struct SIPX_NOTIFY_INFO
{
    size_t      nSize ;             
    SIPX_SUB    hSub ;              
    const char* szNotiferUserAgent; 
    const char* szContentType ;     
    const void* pContent ;          
    size_t      nContentLength ;    
} SIPX_NOTIFY_INFO ;


typedef struct SIPX_CONFIG_INFO
{
    size_t            nSize ;   
    SIPX_CONFIG_EVENT event ;   
    void*             pData;    
} SIPX_CONFIG_INFO ;
                                              

typedef struct SIPX_SECURITY_INFO
{
    size_t              nSize ;             
    char*               szSRTPkey;          
    void*               pCertificate;       
    int                 nCertificateSize;   
    SIPX_SECURITY_EVENT event;              
    SIPX_SECURITY_CAUSE cause;              
    char*               szSubjAltName;      
    char*               callId;             
    SIPX_CALL           hCall;              
    char*               remoteAddress;      
} SIPX_SECURITY_INFO ;


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

SIPXTAPI_API SIPX_RESULT sipxDuplicateEvent(SIPX_EVENT_CATEGORY category, 
                                            const void*         pEventSource, 
                                            void**              pEventCopy) ;


SIPXTAPI_API SIPX_RESULT sipxFreeDuplicatedEvent(SIPX_EVENT_CATEGORY category, 
                                                 void*               pEventCopy) ;

SIPXTAPI_API SIPX_RESULT sipxEventListenerAdd(const SIPX_INST hInst,
                                             SIPX_EVENT_CALLBACK_PROC pCallbackProc,
                                             void *pUserData);
                                             
SIPXTAPI_API SIPX_RESULT sipxEventListenerRemove(const SIPX_INST hInst, 
                                                 SIPX_EVENT_CALLBACK_PROC pCallbackProc, 
                                                 void* pUserData) ;

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

SIPXTAPI_API char* sipxCallEventToString(SIPX_CALLSTATE_EVENT event,
                                         SIPX_CALLSTATE_CAUSE cause,
                                         char*  szBuffer,
                                         size_t nBuffer) ;


SIPXTAPI_API char* sipxEventToString(const SIPX_EVENT_CATEGORY category,
                                     const void* pEvent,
                                     char*  szBuffer,
                                     size_t nBuffer);

SIPXTAPI_API char* sipxLineEventToString(SIPX_LINESTATE_EVENT event,
                                         SIPX_LINESTATE_CAUSE cause,
                                         char*  szBuffer,
                                         size_t nBuffer);
 

SIPXTAPI_API char* sipxConfigEventToString(SIPX_CONFIG_EVENT event, 
                                           char* szBuffer, 
                                           size_t nBuffer) ;

SIPXTAPI_API char* sipxSubStatusStateToString(SIPX_SUBSCRIPTION_STATE state, 
                                            char* szBuffer, 
                                            size_t nBuffer) ; 
                                            
SIPXTAPI_API char* sipxSubStatusCauseToString(SIPX_SUBSCRIPTION_CAUSE cause, 
                                            char* szBuffer, 
                                            size_t nBuffer) ; 

SIPXTAPI_API char* sipxSecurityEventToString(SIPX_SECURITY_EVENT event, 
                                           char* szBuffer, 
                                           size_t nBuffer);

SIPXTAPI_API char* sipxSecurityCauseToString(SIPX_SECURITY_CAUSE cause, 
                                           char* szBuffer, 
                                           size_t nBuffer);

SIPXTAPI_API char* sipxMediaEventToString(SIPX_MEDIA_EVENT event,
                                          char* szBuffer,
                                          size_t nBuffer);

SIPXTAPI_API char* sipxMediaCauseToString(SIPX_MEDIA_CAUSE cause,
                                          char* szBuffer,
                                          size_t nBuffer);

SIPXTAPI_API char* sipxKeepaliveEventToString(SIPX_KEEPALIVE_EVENT event,
                                              char* szBuffer,
                                              size_t nBuffer);

SIPXTAPI_API char* sipxKeepaliveCauseToString(SIPX_KEEPALIVE_CAUSE cause,
                                              char* szBuffer,
                                              size_t nBuffer);

#endif /* ifndef _sipXtapiEvents_h_ */