sipxtapiinternal.h

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

                       const char* szRemoteAddress,
                       SIPX_CALLSTATE_MAJOR eMajorState,
                       SIPX_CALLSTATE_MINOR eMinorState,
                       void* pEventData = NULL,
                       const char* szRemoteAssertedIdentity = NULL);

/**
 * Fires a Line Event to the listeners.
 */                           
void sipxFireLineEvent(const void* pSrc,
                       const char* szLineIdentifier,
                       SIPX_LINE_EVENT_TYPE_MAJOR major,
                       SIPX_LINE_EVENT_TYPE_MINOR minor,
                       const char *bodyBytes = NULL
                       );

/**
 * Bubbles up all non-line and non-call events to the application layer
 */
void sipxFireEvent(const void* pSrc,
                   SIPX_EVENT_CATEGORY category, 
                   void* pInfo);
                     
SIPX_INSTANCE_DATA* findSessionByCallManager(const void* pCallManager) ;

SIPX_CALL_DATA* sipxCallLookup(const SIPX_CALL hCall, SIPX_LOCK_TYPE type);
void sipxCallReleaseLock(SIPX_CALL_DATA*, SIPX_LOCK_TYPE type);
void sipxCallObjectFree(const SIPX_CALL hCall);
SIPX_CALL sipxCallLookupHandle(const UtlString& callID, const void* pSrc);
void destroyCallData(SIPX_CALL_DATA* pData);
UtlBoolean validCallData(SIPX_CALL_DATA* pData);
UtlBoolean sipxCallGetCommonData(SIPX_CALL hCall,
                                 SIPX_INSTANCE_DATA** pInst,
                                 UtlString* pStrCallId,
                                 UtlString* pStrRemoteAddress,
                                 UtlString* pLineId,
                                 UtlString* pGhostCallId = NULL) ;

SIPX_CONF sipxCallGetConf(SIPX_CALL hCall) ;

UtlBoolean sipxCallGetState(SIPX_CALL hCall, 
                            SIPX_CALLSTATE_EVENT& lastEvent,
                            SIPX_CALLSTATE_CAUSE& lastCause,
                            SIPX_INTERNAL_CALLSTATE& state) ;

UtlBoolean sipxCallSetState(SIPX_CALL hCall, 
                            SIPX_CALLSTATE_EVENT event,
                            SIPX_CALLSTATE_CAUSE cause) ;

SIPX_CONTACT_TYPE sipxCallGetLineContactType(SIPX_CALL hCall) ;

SIPX_LINE_DATA* sipxLineLookup(const SIPX_LINE hLine, SIPX_LOCK_TYPE type);
void sipxLineReleaseLock(SIPX_LINE_DATA* pData, SIPX_LOCK_TYPE type) ;
void sipxLineObjectFree(const SIPX_LINE hLine) ;
SIPX_LINE sipxLineLookupHandle(const char* szLineURI);
UtlBoolean validLineData(const SIPX_LINE_DATA*) ;

UtlBoolean sipxRemoveCallHandleFromConf(const SIPX_CONF hConf,
                                        const SIPX_CALL hCall) ;

SIPX_CONF_DATA* sipxConfLookup(const SIPX_CONF hConf, SIPX_LOCK_TYPE type) ;
void sipxConfReleaseLock(SIPX_CONF_DATA* pData, SIPX_LOCK_TYPE type) ;
void sipxConfFree(const SIPX_CONF hConf) ;
UtlBoolean validConfData(const SIPX_CONF_DATA* pData) ;

void sipxIncSessionCount();
void sipxDecSessionCount();
int sipxGetSessionCount();

UtlBoolean sipxIsCallInFocus() ;

/**
 * Frees the INFO structure allocated by a call to sipxCallSendInfo
 *
 * @param pData Pointer to SIPX_INFO_DATA structure
 */
void sipxInfoFree(SIPX_INFO_DATA* pData);

/**
 * Releases the INFO handle created by a call to sipxCallSendInfo.
 * Also cals sipxInfoFree.
 *
 * @param hInfo Handle to the Info object
 */
void sipxInfoObjectFree(SIPX_INFO hInfo);

void sipxGetContactHostPort(SIPX_INSTANCE_DATA* pData, 
                            SIPX_CONTACT_TYPE   contactType, 
                            Url&                uri) ;
  //: Get the external host and port given the contact preference

/**
 * Looks up the SIPX_INFO_DATA structure pointer, given the SIPX_INFO handle.
 * @param hInfo Info Handle
 * @param type Lock type to use during lookup.
 */
SIPX_INFO_DATA* sipxInfoLookup(const SIPX_INFO hInfo, SIPX_LOCK_TYPE type);

/**
 * Unlocks the mutex associated with the INFO DATA
 * 
 * @param pData pointer to the SIPX_INFO structure
 * @param type Type of lock (read or write)
 */
void sipxInfoReleaseLock(SIPX_INFO_DATA* pData, SIPX_LOCK_TYPE type);

/**
 * Adds a log entry to the system log - made necessary to add logging
 * capability on the API level.
 * 
 * @param logLevel priority of the log entry
 * @param format a format string for the following variable argument list
 */
SIPXTAPI_API void sipxLogEntryAdd(OsSysLogPriority logLevel, 
                     const char *format,
                     ...);

/**
 * Utility function for setting allowed methods on a 
 * instance's user-agent.
 */
SIPXTAPI_API SIPX_RESULT sipxConfigAllowMethod(const SIPX_INST hInst, const char* method, const bool bAllow = true);

/**
 * Get the list of active calls for the specified call manager instance
 */
SIPXTAPI_API SIPX_RESULT sipxGetActiveCallIds(SIPX_INST hInst, int maxCalls, int& actualCalls, UtlString callIds[]) ;

/**
 * Callback for subscription client state
 */
void sipxSubscribeClientSubCallback(enum SipSubscribeClient::SubscriptionState newState,
                                   const char* earlyDialogHandle,
                                   const char* dialogHandle,
                                   void* applicationData,
                                   int responseCode,
                                   const char* responseText,
                                   long expiration,
                                   const SipMessage* subscribeResponse);

/**
 * Callback for subscription client NOTIFY content
 */
void sipxSubscribeClientNotifyCallback(const char* earlyDialogHandle,
                                     const char* dialogHandle,
                                     void* applicationData,
                                     const SipMessage* notifyRequest);

/**
 * Look for leaks in internal handles
 */
SIPXTAPI_API SIPX_RESULT sipxCheckForHandleLeaks() ;


/**
 * Flush handles to remove peaks between test cases -- this *WILL* leak
 * memory.
 */
SIPXTAPI_API SIPX_RESULT sipxFlushHandles() ;


/**
 * Translate tone ids to implementation specific codes
 *
 * @param toneId sipx-internal tone id
 * @param xlateId implementation-specific tone id
 */
SIPXTAPI_API SIPX_RESULT sipxTranslateToneId(const TONE_ID toneId,
                                             TONE_ID& xlateId) ;


/**
 * Gets an CpMediaInterface pointer, associated with the call connection.
 *
 * @param hCall Handle to a call.  Call handles are obtained either by 
 *        invoking sipxCallCreate or passed to your application through
 *        a listener interface.
 * @param ppInstData pointer to a memory address that is set to the media interface
 *        pointer.
 */                                                 
SIPXTAPI_API SIPX_RESULT sipxCallGetConnectionMediaInterface(const SIPX_CALL hCall,
                                                           void** ppInstData);
                                                           
                                                           
#ifdef VOICE_ENGINE
    #include "GipsVoiceEngineLib.h"
    #include "GIPSAECTuningWizardAPI.h"
#ifdef VIDEO
#ifdef _WIN32       
    #include <windows.h>
    #include "GipsVideoEngineWindows.h"
#endif
#endif 
    /**
     * For Gips VoiceEngine versions of sipXtapi, this method will
     * return the GipsVoiceEngineLib pointer associated with the
     * call.
     *
     * @param hCall Handle to a call.  Call handles are obtained either by 
     *        invoking sipxCallCreate or passed to your application through
     *        a listener interface.
     */
    SIPXTAPI_API GipsVoiceEngineLib* sipxCallGetVoiceEnginePtr(const SIPX_CALL hCall);


    /**
     * For Gips VoiceEngine versions of sipXtapi, this method will
     * return the GipsVoiceEngineLib pointer associated with the
     * factory implementation.
     *
     * @param hInst Instance pointer obtained by sipxInitialize
     */
    SIPXTAPI_API GipsVoiceEngineLib* sipxConfigGetVoiceEnginePtr(const SIPX_INST hInst);
    
    /**
     * For Gips VoiceEngine versions of sipXtapi, this method will
     * return a Audio Tuning Wizard pointer associated with the
     * factory implementation.
     *
     * @param hInst Instance pointer obtained by sipxInitialize
     */
    SIPXTAPI_API GIPSAECTuningWizard* sipxConfigGetVoiceEngineAudioWizard();

#ifdef VIDEO
    /**
     * For Gips VoiceEngine versions of sipXtapi, this method will
     * return the GipsVoiceEngineLib pointer associated with the
     * factory implementation.
     *
     * @param hInst Instance pointer obtained by sipxInitialize
     */
    SIPXTAPI_API GipsVideoEngineWindows* sipxConfigGetVideoEnginePtr(const SIPX_INST hInst);
#endif VIDEO

    /**
     * For Gips VoiceEngine versions of sipXtapi, this method will
     * enable or disable insertion of VoiceEngine trace output into the 
     * sipXtapi log.
     *
     * @param hInst Instance pointer obtained by sipxInitialize
     * @param bEnable Enable or disable VoceEngine trace output
     */
    SIPXTAPI_API SIPX_RESULT sipxEnableAudioLogging(const SIPX_INST hInst, bool bEnable);
#endif
                                                           
/**
 * Subscribes for Message Waiting Indicator NOTIFY messages from the Voicemail
 * server.
 *
 * NOTE: This API will change
 * 
 * @param hInst Instance pointer obtained by sipxInitialize
 * @param szSubscribeURL Voicemail subscription string - the voicemail server 
 *        to subscribe to.
 */
SIPXTAPI_API SIPX_RESULT sipxConfigVoicemailSubscribe(const SIPX_INST hInst, 
                                                      const char* szSubscribeURL);

/**
 * set readable string value for SIPX_INTERNAL_CALLSTATE enumeration
 * @param internalCallState call state enumeration
 * @param stateString human readable equivalent to internalCallState
 */
void getInternalCallStateString(SIPX_INTERNAL_CALLSTATE internalCallState, UtlString stateString);

UtlBoolean sipxCallSetRemoveInsteadofDrop(SIPX_CALL hCall) ;
UtlBoolean sipxCallIsRemoveInsteadOfDropSet(SIPX_CALL hCall) ;

/**
 * Serialize into a human readable format the SIPX_CALL_DATA
 * @param hCall - call handle to serialize
 * @param serializedDump - string containing the human readable dump of the struct
 */
SIPX_RESULT sipxCallDataToString(SIPX_CALL hCall, UtlString& serializedDump);

/**
 * Serialize into a human readable format the SIPX_CONF_DATA
 * @param hConf - conference handle to serialize
 * @param serializedDump - string containing the human readable dump of the struct
 */
SIPX_RESULT sipxConfDataToString(SIPX_CONF hCall, UtlString& serializedDump);

/* ============================ SIPX_CALL_DATA FUNCTIONS ================================= */
// Would like to migrate SIPX_CALL_DATA to a full fledged class.  The following
// are the beginnings of what should be methods for SIPX_CALL_DATA.

/**
 * Serialize into a human readable format the SIPX_CALL_DATA
 * @param pointer to SIPX_CALL_DATA to serialize
 * @param serializedDump string containing the human readable dump of the struct
 */
void SipxCallData_toString(const SIPX_CALL_DATA* pCallData, UtlString& serializedDump);

/* ============================ SIPX_CONF_DATA FUNCTIONS ================================= */
// Would like to migrate SIPX_CONF_DATA to a full fledged class.  The following
// are the beginnings of what should be methods for SIPX_CONF_DATA.

/**
 * Serialize into a human readable format the SIPX_CONF_DATA
 * @param pointer to SIPX_CONF_DATA to serialize
 * @param serializedDump string containing the human readable dump of the struct
 */
void SipxConfData_toString(const SIPX_CONF_DATA* pConfData, UtlString& serializedDump);

#endif /* ] _SIPXTAPIINTERNAL_H */