sipXcallLib home page


Classes | Macros | Typedefs | Enumerations | Variables
sipXtapi.h File Reference

sipXtapi main API declarations More...

#include <memory.h>
#include <string.h>
#include <stddef.h>
Include dependency graph for sipXtapi.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  SIPX_SECURITY_ATTRIBUTES
 Container class for security attributes. More...
 
struct  SIPX_VIDEO_DISPLAY
 Structure used to pass window handle/filter interface for video calls. More...
 
struct  SIPX_CONTACT_ADDRESS
 The CONTACT_ADDRESS structure includes contact information (IP-address and port), address source type, and interface. More...
 
struct  SIPX_AUDIO_CODEC
 The SIPX_AUDIO_CODEC structure includes codec name and bandwidth info. More...
 
struct  SIPX_RTCP_STATS
 RTCP statistics computed according to RFC 3550. More...
 
struct  SIPX_VIDEO_CODEC
 The SIPX_VIDEO_CODEC structure includes codec name and bandwidth info. More...
 
struct  SIPX_CODEC_INFO
 In the MEDIA_LOCAL_START and MEDIA_REMOTE_START events the SIPX_CODEC_INFO structure is being passed up to the event handler and contains information about the negotiated audio and video codec. More...
 
struct  SIPX_CALL_OPTIONS
 This structure gets passed into sipxCallConnect, sipxCallAccept, and sipxConferenceAdd calls and sets options on a per call basis. More...
 

Macros

#define SIPX_CALLING_CONVENTION
 The SIPX_CALLING_CONVENTION define controls the default calling convention. More...
 
#define DEFAULT_UDP_PORT   5060
 Default UDP port. More...
 
#define DEFAULT_TCP_PORT   5060
 Default TCP port. More...
 
#define DEFAULT_TLS_PORT   5061
 Default TLS port. More...
 
#define DEFAULT_RTP_START_PORT   9000
 Starting RTP port for RTP port range. More...
 
#define DEFAULT_STUN_PORT   3478
 Default stun server port. More...
 
#define DEFAULT_CONNECTIONS   32
 Default number of max sim. More...
 
#define DEFAULT_IDENTITY   "sipx"
 sipx<IP>:UDP_PORT used as identify if lines are not defined. More...
 
#define DEFAULT_BIND_ADDRESS   "0.0.0.0"
 Bind to the first physical interface discovered. More...
 
#define GAIN_MIN   0
 Min acceptable gain value. More...
 
#define GAIN_MAX   100
 Max acceptable gain value. More...
 
#define GAIN_DEFAULT   70
 Nominal gain value. More...
 
#define VOLUME_MIN   0
 Min acceptable volume value. More...
 
#define VOLUME_MAX   100
 Max acceptable volume value. More...
 
#define VOLUME_DEFAULT   70
 Nominal volume value. More...
 
#define MAX_AUDIO_DEVICES   16
 Max number of input/output audio devices. More...
 
#define MAX_VIDEO_DEVICES   8
 Max number of video capture devices. More...
 
#define MAX_VIDEO_DEVICE_LENGTH   256
 Max length of video capture device string. More...
 
#define CONF_MAX_CONNECTIONS   32
 Max number of conference participants. More...
 
#define SIPX_MAX_IP_ADDRESSES   32
 Maximum number of IP addresses on the host. More...
 
#define SIPX_MAX_CALLS   64
 Maximum number of simultaneous calls. More...
 
#define SIPX_PORT_DISABLE   -1
 Special value that disables the transport type (e.g. More...
 
#define SIPX_PORT_AUTO   -2
 Special value that instructs sipXtapi to automatically select an open port for signaling or audio when passed to sipXinitialize. More...
 
#define SIPXTAPI_VERSION_STRING   "sipXtapi SDK %s.%s %s (built %s)"
 Version string format string. More...
 
#define SIPXTAPI_VERSION   "3.3.0"
 sipXtapi API version – automatically filled in during release process More...
 
#define SIPXTAPI_BUILDNUMBER   "0"
 Default build number – automatically filled in during release process. More...
 
#define SIPXTAPI_BUILD_WORD   3,3,0,0
 Default build word – automatically filled in during release process. More...
 
#define SIPXTAPI_FULL_VERSION   "3.3.0.0"
 Default full version number – automatically filled in during release process. More...
 
#define SIPXTAPI_BUILDDATE   "0000-00-00"
 Default build date – automatically filled in during release process. More...
 
#define SIPX_MAX_ADAPTER_NAME_LENGTH   256
 Max length of an adapter name. More...
 
#define SIPXTAPI_API   extern "C"
 Assume extern "C" for non-win32 platforms. More...
 
#define MAX_SRTP_KEY_LENGTH   31
 srtp key length More...
 
#define MAX_SMIME_KEY_LENGTH   2048
 s/mime key length More...
 
#define MAX_PKCS12_KEY_LENGTH   4096
 pkcs12 key length More...
 
#define MAX_PASSWORD_LENGTH   32
 maximum password length PKI operations More...
 
#define SIPXTAPI_CODEC_NAMELEN   32
 Maximum length for codec name. More...
 
#define SIPXTAPI_CODEC_NAMELEN   32
 Maximum length for codec name. More...
 

Typedefs

typedef enum MEDIA_TYPE MEDIA_TYPE
 Media type. More...
 
typedef enum SPEAKER_TYPE SPEAKER_TYPE
 Speaker output types are used to differentiate between the logical ringer (used to alert user of in inbound call) and speaker (in call audio device). More...
 
typedef enum SIPX_AUDIO_BANDWIDTH_ID SIPX_AUDIO_BANDWIDTH_ID
 Codec bandwidth ids are used to select a group of codecs with equal or lower bandwidth requirements. More...
 
typedef enum SIPX_VIDEO_BANDWIDTH_ID SIPX_VIDEO_BANDWIDTH_ID
 Video Codec bandwidth ids are used to select a group of codecs with equal or lower bandwidth requirements. More...
 
typedef enum SIPX_VIDEO_QUALITY_ID SIPX_VIDEO_QUALITY_ID
 Video Codec quality definitions. More...
 
typedef enum SIPX_VIDEO_FORMAT SIPX_VIDEO_FORMAT
 Enumeration of possible video sizes. More...
 
typedef enum SIPX_AUDIO_DATA_FORMAT SIPX_AUDIO_DATA_FORMAT
 Format definitions for memory resident audio data. More...
 
typedef void(* sipxLogCallback) (const char *szPriority, const char *szSource, const char *szMsg)
 Signature for a log callback function that gets passed three strings, first string is the priority level, second string is the source id of the subsystem that generated the message, and the third string is the message itself. More...
 
typedef enum SIPX_RESULT SIPX_RESULT
 SIPX_RESULT is an enumeration with all the possible result/return codes. More...
 
typedef enum SIPX_TONE_ID SIPX_TONE_ID
 DTMF/other tone ids used with sipxCallStartTone/sipxCallStopTone. More...
 
typedef SIPX_TONE_ID TONE_ID
 Left for backwards compatibility – please use SIPX_TONE_ID. More...
 
typedef enum SIPX_AUDIO_FILE_FORMAT SIPX_AUDIO_FILE_FORMAT
 Audio file format types. More...
 
typedef enum SIPX_LOG_LEVEL SIPX_LOG_LEVEL
 Various log levels available for the sipxConfigEnableLog method. More...
 
typedef void * SIPX_WINDOW_HANDLE
 Type for storing a "window object handle" - in Windows, the application should cast their HWND to a SIPX_WINDOW_HANDLE. More...
 
typedef enum SIPX_VIDEO_DISPLAY_TYPE SIPX_VIDEO_DISPLAY_TYPE
 Enum for specifying the type of display object to be used for displaying video. More...
 
typedef int SIPX_CONTACT_ID
 Type for storing Contact Record identifiers. More...
 
typedef void * SIPX_INST
 The SIPX_INST handle represents an instance of a user agent. More...
 
typedef unsigned int SIPX_LINE
 The SIPX_LINE handle represents an inbound or outbound identity. More...
 
typedef unsigned int SIPX_CALL
 The SIPX_CALL handle represents a call or connection between the user agent and another party. More...
 
typedef unsigned long SIPX_CONF
 The SIPX_CONF handle represents a collection of CALLs that have bridge (mixed) audio. More...
 
typedef unsigned long SIPX_INFO
 The SIPX_INFO handle represents a handle to an INFO message sent by a sipXtapi instance. More...
 
typedef unsigned long SIPX_PUB
 The SIPX_PUB handle represent a publisher context. More...
 
typedef unsigned long SIPX_SUB
 A SIPX_SUB handle represent a subscription to a remote publisher. More...
 
typedef unsigned long SIPX_TRANSPORT
 The SIPX_TRANSPORT handle represents a user-implementation of a network transport mechanism to be used for SIP signaling. More...
 
typedef bool(SIPX_CALLING_CONVENTIONSIPX_TRANSPORT_WRITE_PROC) (SIPX_TRANSPORT hTransport, const char *szDestinationIp, const int iDestPort, const char *szLocalIp, const int iLocalPort, const void *pData, const size_t nData, const void *pUserData)
 External Transport callback definition. More...
 
typedef void(* fnMicAudioHook) (const int nSamples, short *pSamples)
 Typedef for audio source (microphone) hook procedure. More...
 
typedef void(* fnSpkrAudioHook) (const int nSamples, short *pSamples)
 Typedef for audio target(speaker) hook procedure. More...
 
typedef enum SIPX_AEC_MODE SIPX_AEC_MODE
 SIPX_AEC_MODE defines different AEC modes. More...
 
typedef enum SIPX_NOISE_REDUCTION_MODE SIPX_NOISE_REDUCTION_MODE
 SIPX_NOISE_REDUCTION_MODE defines the various noise reduction options. More...
 

Enumerations

enum  MEDIA_TYPE { AUDIO_MEDIA, VIDEO_MEDIA }
 Media type. More...
 
enum  SPEAKER_TYPE { SPEAKER, RINGER }
 Speaker output types are used to differentiate between the logical ringer (used to alert user of in inbound call) and speaker (in call audio device). More...
 
enum  SIPX_AUDIO_BANDWIDTH_ID {
  AUDIO_CODEC_BW_VARIABLE =0, AUDIO_CODEC_BW_LOW, AUDIO_CODEC_BW_NORMAL, AUDIO_CODEC_BW_HIGH,
  AUDIO_CODEC_BW_CUSTOM, AUDIO_CODEC_BW_DEFAULT
}
 Codec bandwidth ids are used to select a group of codecs with equal or lower bandwidth requirements. More...
 
enum  SIPX_VIDEO_BANDWIDTH_ID {
  VIDEO_CODEC_BW_VARIABLE =0, VIDEO_CODEC_BW_LOW, VIDEO_CODEC_BW_NORMAL, VIDEO_CODEC_BW_HIGH,
  VIDEO_CODEC_BW_CUSTOM, VIDEO_CODEC_BW_DEFAULT
}
 Video Codec bandwidth ids are used to select a group of codecs with equal or lower bandwidth requirements. More...
 
enum  SIPX_VIDEO_QUALITY_ID { VIDEO_QUALITY_LOW =1, VIDEO_QUALITY_NORMAL =2, VIDEO_QUALITY_HIGH =3 }
 Video Codec quality definitions. More...
 
enum  SIPX_VIDEO_FORMAT { VIDEO_FORMAT_CIF =0, VIDEO_FORMAT_QCIF, VIDEO_FORMAT_SQCIF, VIDEO_FORMAT_QVGA }
 Enumeration of possible video sizes. More...
 
enum  SIPX_AUDIO_DATA_FORMAT { RAW_PCM_16 =0 }
 Format definitions for memory resident audio data. More...
 
enum  SIPX_RESULT {
  SIPX_RESULT_SUCCESS = 0, SIPX_RESULT_FAILURE, SIPX_RESULT_NOT_IMPLEMENTED, SIPX_RESULT_OUT_OF_MEMORY,
  SIPX_RESULT_INVALID_ARGS, SIPX_RESULT_BAD_ADDRESS, SIPX_RESULT_OUT_OF_RESOURCES, SIPX_RESULT_INSUFFICIENT_BUFFER,
  SIPX_RESULT_EVAL_TIMEOUT, SIPX_RESULT_BUSY, SIPX_RESULT_INVALID_STATE, SIPX_RESULT_MISSING_RUNTIME_FILES,
  SIPX_RESULT_TLS_DATABASE_FAILURE, SIPX_RESULT_TLS_BAD_PASSWORD, SIPX_RESULT_TLS_TCP_IMPORT_FAILURE, SIPX_RESULT_NSS_FAILURE,
  SIPX_RESULT_NOT_SUPPORTED, SIPX_RESULT_NETWORK_FAILURE, SIPX_RESULT_LIB_NOT_FOUND, SIPX_RESULT_OS_PLATFORM_UNSUPPORTED
}
 SIPX_RESULT is an enumeration with all the possible result/return codes. More...
 
enum  SIPX_TONE_ID {
  ID_DTMF_INVALID = 0, ID_DTMF_0 = '0', ID_DTMF_1 = '1', ID_DTMF_2 = '2',
  ID_DTMF_3 = '3', ID_DTMF_4 = '4', ID_DTMF_5 = '5', ID_DTMF_6 = '6',
  ID_DTMF_7 = '7', ID_DTMF_8 = '8', ID_DTMF_9 = '9', ID_DTMF_STAR = '*',
  ID_DTMF_POUND = '#', ID_DTMF_FLASH = '!', ID_TONE_DIALTONE = 512, ID_TONE_BUSY,
  ID_TONE_RINGBACK, ID_TONE_RINGTONE, ID_TONE_CALLFAILED, ID_TONE_SILENCE,
  ID_TONE_BACKSPACE, ID_TONE_CALLWAITING, ID_TONE_CALLHELD, ID_TONE_LOUD_FAST_BUSY
}
 DTMF/other tone ids used with sipxCallStartTone/sipxCallStopTone. More...
 
enum  SIPX_AUDIO_FILE_FORMAT { SIPX_UNKNOWN_FORMAT = 0, SIPX_WAVE_PCM_16, SIPX_WAVE_GSM }
 Audio file format types. More...
 
enum  SIPX_LOG_LEVEL {
  LOG_LEVEL_DEBUG, LOG_LEVEL_INFO, LOG_LEVEL_NOTICE, LOG_LEVEL_WARNING,
  LOG_LEVEL_ERR, LOG_LEVEL_CRIT, LOG_LEVEL_ALERT, LOG_LEVEL_EMERG,
  LOG_LEVEL_NONE
}
 Various log levels available for the sipxConfigEnableLog method. More...
 
enum  SIPX_SRTP_LEVEL { SRTP_LEVEL_NONE =0, SRTP_LEVEL_ENCRYPTION, SRTP_LEVEL_AUTHENTICATION, SRTP_LEVEL_ENCRYPTION_AND_AUTHENTICATION }
 Enumeration of the possible levels of SRTP. More...
 
enum  SIPX_CONTACT_TYPE {
  CONTACT_LOCAL, CONTACT_NAT_MAPPED, CONTACT_RELAY, CONTACT_CONFIG,
  CONTACT_AUTO = -1, CONTACT_ALL = -2
}
 SIPX_CONTACT_TYPE is an enumeration of possible address types for use with SIP contacts and SDP connection information. More...
 
enum  SIPX_TRANSPORT_TYPE { TRANSPORT_UDP = 1, TRANSPORT_TCP = 0, TRANSPORT_TLS = 3, TRANSPORT_CUSTOM = 4 }
 SIPX_TRANSPORT_TYPE defines various protocols use for signaling transport. More...
 
enum  SIPX_VIDEO_DISPLAY_TYPE { SIPX_WINDOW_HANDLE_TYPE, DIRECT_SHOW_FILTER }
 Enum for specifying the type of display object to be used for displaying video. More...
 
enum  SIPX_RTP_TRANSPORT {
  SIPX_RTP_TRANSPORT_UNKNOWN = 0x00000000, SIPX_RTP_TRANSPORT_UDP = 0x00000001, SIPX_RTP_TRANSPORT_TCP = 0x00000002, SIPX_RTP_TCP_ROLE_ACTIVE = 0x00000004,
  SIPX_RTP_TCP_ROLE_PASSIVE = 0x00000008, SIPX_RTP_TCP_ROLE_ACTPASS = 0x00000010, SIPX_RTP_TCP_ROLE_CONNECTION = 0x00000020
}
 Possible roles that a Media connection can have. More...
 
enum  SIPX_KEEPALIVE_TYPE { SIPX_KEEPALIVE_CRLF, SIPX_KEEPALIVE_STUN, SIPX_KEEPALIVE_SIP_PING, SIPX_KEEPALIVE_SIP_OPTIONS }
 SIPX_KEEPALIVE_TYPEs define different methods of keeping NAT/firewall port open. More...
 
enum  SIPX_AEC_MODE { SIPX_AEC_DISABLED, SIPX_AEC_SUPPRESS, SIPX_AEC_CANCEL, SIPX_AEC_CANCEL_AUTO }
 SIPX_AEC_MODE defines different AEC modes. More...
 
enum  SIPX_NOISE_REDUCTION_MODE { SIPX_NOISE_REDUCTION_DISABLED, SIPX_NOISE_REDUCTION_LOW, SIPX_NOISE_REDUCTION_MEDIUM, SIPX_NOISE_REDUCTION_HIGH }
 SIPX_NOISE_REDUCTION_MODE defines the various noise reduction options. More...
 

Functions

Initialization
SIPXTAPI_API SIPX_RESULT sipxInitialize (SIPX_INST *phInst, const int udpPort=DEFAULT_UDP_PORT, const int tcpPort=DEFAULT_TCP_PORT, const int tlsPort=DEFAULT_TLS_PORT, const int rtpPortStart=DEFAULT_RTP_START_PORT, const int maxConnections=DEFAULT_CONNECTIONS, const char *szIdentity=DEFAULT_IDENTITY, const char *szBindToAddr=DEFAULT_BIND_ADDRESS, bool bUseSequentialPorts=false, const char *szTLSCertificateNickname=NULL, const char *szTLSCertificatePassword=NULL, const char *szDbLocation=NULL, bool bEnableLocalAudio=true, const int internalSamplerate=8000, const int devicesSamplerate=48000, const int internalFrameSizeMs=10, const char *callInputDeviceName="", const char *callOutputDeviceName="")
 Initialize the sipX TAPI-like API layer. More...
 
SIPXTAPI_API SIPX_RESULT sipxReInitialize (SIPX_INST *phInst, const int udpPort=DEFAULT_UDP_PORT, const int tcpPort=DEFAULT_TCP_PORT, const int tlsPort=DEFAULT_TLS_PORT, const int rtpPortStart=DEFAULT_RTP_START_PORT, const int maxConnections=DEFAULT_CONNECTIONS, const char *szIdentity=DEFAULT_IDENTITY, const char *szBindToAddr=DEFAULT_BIND_ADDRESS, bool bUseSequentialPorts=false, const char *szTLSCertificateNickname=NULL, const char *szTLSCertificatePassword=NULL, const char *szDbLocation=NULL)
 Re-initialize the sipX TAPI-like API layer. More...
 
SIPXTAPI_API SIPX_RESULT sipxUnInitialize (SIPX_INST hInst, bool bForceShutdown=false)
 Uninitialize the sipX TAPI-like API layer. More...
 
Call Methods
SIPXTAPI_API SIPX_RESULT sipxCallAccept (const SIPX_CALL hCall, SIPX_VIDEO_DISPLAY *const pDisplay=NULL, SIPX_SECURITY_ATTRIBUTES *const pSecurity=NULL, SIPX_CALL_OPTIONS *options=NULL, bool bSendEarlyMedia=false)
 Accepts an inbound call and proceed immediately to alerting. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallReject (const SIPX_CALL hCall, const int errorCode=400, const char *szErrorText="Bad Request")
 Reject an inbound call (prior to alerting the user). More...
 
SIPXTAPI_API SIPX_RESULT sipxCallRedirect (const SIPX_CALL hCall, const char *szForwardURL)
 Redirect an inbound call (prior to alerting the user). More...
 
SIPXTAPI_API SIPX_RESULT sipxCallAnswer (const SIPX_CALL hCall, bool bTakeFocus=true)
 Answer an alerting call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallCreate (const SIPX_INST hInst, const SIPX_LINE hLine, SIPX_CALL *phCall)
 Create a new call for the purpose of creating an outbound connection/call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallConnect (const SIPX_CALL hCall, const char *szAddress, SIPX_CONTACT_ID contactId=0, SIPX_VIDEO_DISPLAY *const pDisplay=NULL, SIPX_SECURITY_ATTRIBUTES *const pSecurity=NULL, bool bTakeFocus=true, SIPX_CALL_OPTIONS *options=NULL, const char *szCallId=NULL)
 Connects an idle call to the designated target address. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallHold (const SIPX_CALL hCall, bool bStopRemoteAudio=true)
 Place the specified call on hold. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallUnhold (const SIPX_CALL hCall)
 Take the specified call off hold. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallDestroy (SIPX_CALL &hCall)
 Drop/Destroy the specified call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetID (const SIPX_CALL hCall, char *szId, const size_t iMaxLength)
 Get the SIP call ID of the call represented by the specified call handle. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetLocalID (const SIPX_CALL hCall, char *szId, const size_t iMaxLength)
 Get the SIP identity of the local connection. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetLine (const SIPX_CALL hCall, SIPX_LINE &hLine)
 Get the line handle for the given call if it has one. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetRemoteID (const SIPX_CALL hCall, char *szId, const size_t iMaxLength)
 Get the SIP identity of the remote connection. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetContactID (const SIPX_CALL hCall, char *szId, const size_t iMaxLength)
 Get the SIP identity of the contact connection. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetConnectionId (const SIPX_CALL hCall, int &connectionId)
 Gets the media interface connection ID. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetConference (const SIPX_CALL hCall, SIPX_CONF &hConf)
 Get the conference handle for the specified call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetRequestURI (const SIPX_CALL hCall, char *szUri, const size_t iMaxLength)
 Get the SIP request URI. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetRemoteContact (const SIPX_CALL hCall, char *szContact, const size_t iMaxLength)
 Get the SIP remote contact. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetRemoteUserAgent (const SIPX_CALL hCall, char *szAgent, const size_t iMaxLength)
 Get the remote user agent of the call represented by the specified call handle. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetInviteHeader (const SIPX_CALL hCall, const char *headerName, char *headerValue, const size_t maxValueLength, bool *inviteFromRemote, const size_t headerInstanceIndex=0)
 Get the named header value from the last SIP INVITE request (sent or received) in the context of the given call handle. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallStartTone (const SIPX_CALL hCall, const SIPX_TONE_ID toneId, const bool bLocal, const bool bRemote)
 Play a tone (DTMF, dialtone, ring back, etc) to the local and/or remote party. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallStopTone (const SIPX_CALL hCall)
 Stop playing a tone (DTMF, dialtone, ring back, etc). More...
 
SIPXTAPI_API SIPX_RESULT sipxCallAudioPlayFileStart (const SIPX_CALL hCall, const char *szFile, const bool bRepeat, const bool bLocal, const bool bRemote, const bool bMixWithMicrophone=false, const float fVolumeScaling=1.0)
 Play the designated file. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallAudioPlayFileStop (const SIPX_CALL hCall)
 Stop playing a file started with sipxCallPlayFileStart If a sipxCallDestroy is attempted while an audio file is playing, sipxCallDestroy will fail with a SIPX_RESULT_BUSY return code. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordFileStart (const SIPX_CALL hCall, const char *szFile, const SIPX_AUDIO_FILE_FORMAT recordFormat=SIPX_WAVE_PCM_16, const bool appendToFile=false, const int numChannels=1)
 Record a call session (including other parties if this is a multi-party call / conference) to a file. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordPause (const SIPX_CALL hCall)
 Pause recording call to file or buffer. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordResume (const SIPX_CALL hCall)
 Resume paused recording call to file or buffer. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordFileStop (const SIPX_CALL hCall)
 Stop recording a call to file. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordBufferStart (const SIPX_CALL hCall, const char *pBuffer, const int bufferSize, const int bufferType=RAW_PCM_16, const int maxRecordTime=-1, const int maxSilence=-1)
 Record a call session (including other parties if this is a multi-party call / conference) to a buffer. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordBufferStop (const SIPX_CALL hCall)
 Stop recording a call to buffer. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallPlayBufferStart (const SIPX_CALL hCall, const char *szBuffer, const int bufSize, const int bufType, const bool bRepeat, const bool bLocal, const bool bRemote)
 Play the specified audio data. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallPlayBufferStop (const SIPX_CALL hCall)
 Stop playing the audio started with sipxCallPlayBufferStart If a sipxCallDestroy is attempted while an audio buffer is playing, sipxCallDestroy will fail with a SIPX_RESULT_BUSY return code. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallSetMediaPassThrough (const SIPX_CALL hCall, MEDIA_TYPE mediaType, int mediaTypeStreamIndex, const char *streamReceiveAddress, int rtpPort, int rtcpPort)
 Set the address and port to which the given media stream is to be recieved. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallSubscribe (const SIPX_CALL hCall, const char *szEventType, const char *szAcceptType, SIPX_SUB *phSub, bool bRemoteContactIsGruu=false)
 Subscribe for NOTIFY events which may be published by the other end-point of the call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallUnsubscribe (const SIPX_SUB hSub)
 Unsubscribe from previously subscribed NOTIFY events. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallSendInfo (SIPX_INFO *phInfo, const SIPX_CALL hCall, const char *szContentType, const char *szContent, const size_t nContentLength)
 Sends an INFO event to the specified call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallBlindTransfer (const SIPX_CALL hCall, const char *szAddress)
 Blind transfer the specified call to another party. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallTransfer (const SIPX_CALL hSourceCall, const SIPX_CALL hTargetCall)
 Transfer the source call to the target call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallUpdateVideoWindow (const SIPX_CALL hCall, const SIPX_WINDOW_HANDLE hWnd)
 Updates the Video window with a new frame buffer. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallResizeWindow (const SIPX_CALL hCall, const SIPX_WINDOW_HANDLE hWnd)
 Resizes the video window. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetEnergyLevels (const SIPX_CALL hCall, int &iInputEnergyLevel, int &iOutputEnergyLevel, const size_t nMaxContributors, unsigned int CCSRCs[], int iEnergyLevels[], size_t &nActualContributors)
 Gets energy levels for a call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetAudioRtpSourceIds (const SIPX_CALL hCall, unsigned int &iSendSSRC, unsigned int &iReceiveSSRC)
 Gets the sending and receiving Audio RTP SSRC IDs. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallGetAudioRtcpStats (const SIPX_CALL hCall, SIPX_RTCP_STATS *pStats)
 Obtain RTCP stats for the specified call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallLimitCodecs (const SIPX_CALL hCall, const char *codecNames)
 Restrict the set of codecs that are allowed to be used for the given call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallLimitCodecPreferences (const SIPX_CALL hCall, const SIPX_AUDIO_BANDWIDTH_ID audioBandwidth, const SIPX_VIDEO_BANDWIDTH_ID videoBandwidth, const char *szVideoCodecName)
 Limits the codec preferences on a per-call basis. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallSetMicGain (const SIPX_CALL hCall, float gain)
 Sets the gain of the microphone for a given call. More...
 
SIPXTAPI_API SIPX_RESULT sipxCallSetMixOutputGain (const SIPX_CALL hCall, int bridgeOutputIndex, float gain)
 Sets the gain for all inputs to the given bridge output, except for the input of the same index which is set to 0.0f gain. More...
 
Publishing Methods
SIPXTAPI_API SIPX_RESULT sipxPublisherCreate (const SIPX_INST hInst, SIPX_PUB *phPub, const char *szResourceId, const char *szEventType, const char *szContentType, const char *pContent, const size_t nContentLength)
 Creates a publishing context, which performs the processing necessary to accept SUBSCRIBE requests, and to publish NOTIFY messages to subscribers. More...
 
SIPXTAPI_API SIPX_RESULT sipxPublisherDestroy (const SIPX_PUB hPub, const char *szContentType, const char *pFinalContent, const size_t nContentLength)
 Tears down the publishing context. More...
 
SIPXTAPI_API SIPX_RESULT sipxPublisherUpdate (const SIPX_PUB hPub, const char *szContentType, const char *pContent, const size_t nContentLength)
 Publishes an updated state to specific event via NOTIFY to its subscribers. More...
 
Conference Methods
SIPXTAPI_API SIPX_RESULT sipxConferenceCreate (const SIPX_INST hInst, SIPX_CONF *phConference)
 Create a conference handle. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferenceJoin (const SIPX_CONF hConf, const SIPX_CALL hCall)
 Join (add) an existing held call into a conference. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferenceSplit (const SIPX_CONF hConf, const SIPX_CALL hCall)
 Split (remove) a held call from a conference. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferenceAdd (const SIPX_CONF hConf, const SIPX_LINE hLine, const char *szAddress, SIPX_CALL *phNewCall, SIPX_CONTACT_ID contactId=0, SIPX_VIDEO_DISPLAY *const pDisplay=NULL, SIPX_SECURITY_ATTRIBUTES *const pSecurity=NULL, bool bTakeFocus=true, SIPX_CALL_OPTIONS *options=NULL)
 Add a new party to an existing conference. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferenceRemove (const SIPX_CONF hConf, const SIPX_CALL hCall)
 Removes a participant from conference by hanging up on them. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferenceGetCalls (const SIPX_CONF hConf, SIPX_CALL calls[], const size_t iMax, size_t &nActual)
 Gets all of the calls participating in a conference. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferenceHold (const SIPX_CONF hConf, bool bBridging=true)
 Places a conference on hold. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferenceUnhold (const SIPX_CONF hConf)
 Removes conference members from a held state. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferencePlayAudioFileStart (const SIPX_CONF hConf, const char *szFile, const bool bRepeat, const bool bLocal, const bool bRemote, const bool bMixWithMicrophone=false, const float fVolumeScaling=1.0)
 Play the designated audio file to all conference participants and/or the local speaker. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferencePlayAudioFileStop (const SIPX_CONF hConf)
 
SIPXTAPI_API SIPX_RESULT sipxConferenceDestroy (SIPX_CONF hConf)
 Destroys a conference. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferenceGetEnergyLevels (const SIPX_CONF hConf, int &iInputEnergyLevel, int &iOutputEnergyLevel)
 Gets energy levels for a conference. More...
 
SIPXTAPI_API SIPX_RESULT sipxConferenceLimitCodecPreferences (const SIPX_CONF hConf, const SIPX_AUDIO_BANDWIDTH_ID audioBandwidth, const SIPX_VIDEO_BANDWIDTH_ID videoBandwidth, const char *szVideoCodecName)
 Limits the codec preferences on a conference. More...
 
SIPXTAPI_API SIPX_RESULT sipxMediaConnectionCreate (const SIPX_CONF hConf, int &connectionId)
 Create a new media connetion that is indpendent of any existing call legs in the conference. More...
 
SIPXTAPI_API SIPX_RESULT sipxMediaConnectionRtpSetDestination (const SIPX_CONF hConf, int connectionId, MEDIA_TYPE mediaType, int mediaTypeStreamIndex, const char *streamSendAddress, int rtpPort, int rtcpPort)
 Set the destination to which RTP streams are to be sent. More...
 
SIPXTAPI_API SIPX_RESULT sipxMediaConnectionRtpStartSend (const SIPX_CONF hConf, int connectionId, int numTokens, const char *codecTokens[], int payloadIds[])
 Start sending the RTP/RTCP stream. More...
 
SIPXTAPI_API SIPX_RESULT sipxMediaConnectionRtpStopSend (const SIPX_CONF hConf, int connectionId)
 Stop sending RTP/RTCP. More...
 
Audio Methods
SIPXTAPI_API SIPX_RESULT sipxAudioSetGain (const SIPX_INST hInst, const int iLevel)
 Set the local microphone gain. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioGetGain (const SIPX_INST hInst, int &iLevel)
 Get the current microphone gain. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioMute (const SIPX_INST hInst, const bool bMute)
 Mute or unmute the microphone. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioIsMuted (const SIPX_INST hInst, bool &bMuted)
 Gets the mute state of the microphone. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioEnableSpeaker (const SIPX_INST hInst, const SPEAKER_TYPE type)
 Enables one of the speaker outputs. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioGetEnabledSpeaker (const SIPX_INST hInst, SPEAKER_TYPE &type)
 Gets the enabled speaker selection. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioSetVolume (const SIPX_INST hInst, const SPEAKER_TYPE type, const int iLevel)
 Sets the audio level for the designated speaker type. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioGetVolume (const SIPX_INST hInst, const SPEAKER_TYPE type, int &iLevel)
 Gets the audio level for the designated speaker type. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioSetAECMode (const SIPX_INST hInst, const SIPX_AEC_MODE mode)
 Enables or disables Acoustic Echo Cancellation (AEC). More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioGetAECMode (const SIPX_INST hInst, SIPX_AEC_MODE &mode)
 Get the mode of Acoustic Echo Cancellation (AEC). More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioSetAGCMode (const SIPX_INST hInst, const bool bEnable)
 Enable/Disable Automatic Gain Control (AGC). More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioGetAGCMode (const SIPX_INST hInst, bool &bEnabled)
 Get the enable/disable state of Automatic Gain Control (AGC). More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioSetNoiseReductionMode (const SIPX_INST hInst, const SIPX_NOISE_REDUCTION_MODE mode)
 Set the noise reduction mode/policy for suppressing background noise. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioGetNoiseReductionMode (const SIPX_INST hInst, SIPX_NOISE_REDUCTION_MODE &mode)
 Get the mode/policy for Noise Reduction (NR). More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioGetNumInputDevices (const SIPX_INST hInst, size_t &numDevices)
 Get the number of input devices available on this system. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioGetInputDevice (const SIPX_INST hInst, const int index, const char *&szDevice)
 Get the name/identifier for input device at position index. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioGetNumOutputDevices (const SIPX_INST hInst, size_t &numDevices)
 Get the number of output devices available on this system. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioGetOutputDevice (const SIPX_INST hInst, const int index, const char *&szDevice)
 Get the name/identifier for output device at position index. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioSetCallInputDevice (const SIPX_INST hInst, const char *szDevice)
 Set the call input device (in-call microphone). More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioSetRingerOutputDevice (const SIPX_INST hInst, const char *szDevice)
 Set the call ringer/alerting device. More...
 
SIPXTAPI_API SIPX_RESULT sipxAudioSetCallOutputDevice (const SIPX_INST hInst, const char *szDevice)
 Set the call output device (in-call speaker). More...
 
Line / Identity Methods
SIPXTAPI_API SIPX_RESULT sipxLineAdd (const SIPX_INST hInst, const char *szLineURL, SIPX_LINE *phLine, SIPX_CONTACT_ID contactId=0)
 Adds a line appearance. More...
 
SIPXTAPI_API SIPX_RESULT sipxLineAddAlias (const SIPX_LINE hLine, const char *szLineURL)
 Adds an alias for a line definition. More...
 
SIPXTAPI_API SIPX_RESULT sipxLineRegister (const SIPX_LINE hLine, const bool bRegister)
 Registers a line with the proxy server. More...
 
SIPXTAPI_API SIPX_RESULT sipxLineRemove (SIPX_LINE hLine)
 Remove the designated line appearance. More...
 
SIPXTAPI_API SIPX_RESULT sipxLineAddCredential (const SIPX_LINE hLine, const char *szUserID, const char *szPasswd, const char *szRealm)
 Adds authentication credentials to the designated line appearance. More...
 
SIPXTAPI_API SIPX_RESULT sipxLineGet (const SIPX_INST hInst, SIPX_LINE lines[], const size_t max, size_t &actual)
 Gets the active list of line identities. More...
 
SIPXTAPI_API SIPX_RESULT sipxLineGetURI (const SIPX_LINE hLine, char *szBuffer, const size_t nBuffer, size_t &nActual)
 Get the Line URI for the designated line handle. More...
 
SIPXTAPI_API SIPX_RESULT sipxLineGetContactId (const SIPX_LINE hLine, SIPX_CONTACT_ID &contactId)
 Get the contact ID for the designated line handle. More...
 
SIPXTAPI_API SIPX_RESULT sipxLineFindByURI (const SIPX_INST hInst, const char *szURI, SIPX_LINE &hLine)
 Find a line definition given a URI. More...
 
Configuration Methods
SIPXTAPI_API SIPX_RESULT sipxConfigSetLogLevel (SIPX_LOG_LEVEL logLevel)
 The sipxConfigEnableLog method enables logging for the sipXtapi API, media processing, call processing, SIP stack, and OS abstraction layer. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetLogFile (const char *szFilename)
 The sipxConfigSetlogFile method sets the filename of the log file and directs output to that file. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetLogCallback (sipxLogCallback pCallback)
 Set a callback function to collect logging information. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableGIPSTracing (SIPX_INST hInst, bool bEnable)
 Enables GIPS tracing in sipXtapi (if bundled with sipXtapi). More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetMicAudioHook (fnMicAudioHook hookProc)
 Designate a callback routine as a microphone replacement or supplement. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetSpkrAudioHook (fnSpkrAudioHook hookProc)
 Designate a callback routine for post-mixing audio data (e.g. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetEnergyLevelNotificationPeriod (const SIPX_INST hInst, int periodMs)
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetUserAgentName (const SIPX_INST hInst, const char *szName, const bool bIncludePlatformName=true)
 Sets the User-Agent name to be used with outgoing SIP messages. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetOutboundProxy (const SIPX_INST hInst, const char *szProxy)
 Defines the SIP proxy used for outbound requests. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetDnsSrvTimeouts (const int initialTimeoutInSecs, const int retries)
 Modifies the timeout values used for DNS SRV lookups. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetRegisterResponseWaitSeconds (const SIPX_INST hInst, const int seconds)
 Specifies the time to wait for a REGISTER response before sending a LINESTATE_REGISTER_FAILED (or LINESTATE_UNREGISTER_FAILED) message. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetDnsSrvFailoverTimeout (const SIPX_INST hInst, const int failoverTimeoutInSecs)
 Specifies the time to wait before trying the next DNS SRV record. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableRport (const SIPX_INST hInst, const bool bEnable)
 Enable or disable the use of "rport". More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableRportMapping (const SIPX_INST hInst, const bool bEnable)
 Enable or diable the use of IP and port provided in the response via (rport) for mapping of NAT/public IP address and port in the contact database. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetRegisterExpiration (const SIPX_INST hInst, const int nRegisterExpirationSecs)
 Specifies the expiration period for registration. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetSubscribeExpiration (const SIPX_INST hInst, const int nSubscribeExpirationSecs)
 Specifies the expiration period for subscription. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableStun (const SIPX_INST hInst, const char *szServer, int iServerPort, int iKeepAliveInSecs)
 Enables STUN (Simple Traversal of UDP through NAT) support for both UDP SIP signaling and UDP audio/video (RTP). More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigDisableStun (const SIPX_INST hInst)
 Disable the use of STUN. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableTurn (const SIPX_INST hInst, const char *szServer, const int iServerPort, const char *szUsername, const char *szPassword, const int iKeepAliveInSecs)
 Enable TURN for support for UDP audio/video (RTP). More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigDisableTurn (const SIPX_INST hInst)
 Disable the use of TURN. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableIce (const SIPX_INST hInst)
 Enables an ICE-like mechanism for determining connectivity of remote parties dynamically. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigDisableIce (const SIPX_INST hInst)
 Disable the use of ICE. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigKeepAliveAdd (const SIPX_INST hInst, SIPX_CONTACT_ID contactId, SIPX_KEEPALIVE_TYPE type, const char *remoteIp, int remotePort, int keepAliveSecs)
 Add a signaling keep alive to a remote ip address. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigKeepAliveRemove (const SIPX_INST hInst, SIPX_CONTACT_ID contactId, SIPX_KEEPALIVE_TYPE type, const char *remoteIp, int remotePort)
 Remove a signaling keepalive. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableOutOfBandDTMF (const SIPX_INST hInst, const bool bEnable)
 Enable/disable sending of RFC 2833 DTMF tones. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableInBandDTMF (const SIPX_INST hInst, const bool bEnable)
 Enable/disable sending of in-band DTMF tones. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableRTCP (const SIPX_INST hInst, const bool bEnable)
 Enable or disable sending RTCP reports. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableDnsSrv (const bool bEnable)
 Enables/disables sending of DNS SRV request for all sipXtapi instances. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigIsOutOfBandDTMFEnabled (const SIPX_INST hInst, bool &bEnable)
 Determines if sending of out-of-band DTMF tones is enabled or disabled. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigIsInBandDTMFEnabled (const SIPX_INST hInst, bool &bEnable)
 Determines if sending of in-band DTMF tones is enabled or disabled. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetVersion (char *szVersion, const size_t nBuffer)
 Get the sipXtapi API version string. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetLocalSipUdpPort (SIPX_INST hInst, int *pPort)
 Get the local UDP port for SIP signaling. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigAddContact (const SIPX_INST hInst, const char *szSipContactAddress, const int iSipContactPort, SIPX_CONTACT_ID &iNewContactId)
 Add a contact using the given IP address and port. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetLocalSipTcpPort (SIPX_INST hInst, int *pPort)
 Get the local TCP port for SIP signaling. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetLocalSipTlsPort (SIPX_INST hInst, int *pPort)
 Get the local TLS port for SIP signaling. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetAudioCodecPreferences (const SIPX_INST hInst, SIPX_AUDIO_BANDWIDTH_ID bandWidth)
 Set the preferred bandwidth requirement for codec selection. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetAudioCodecByName (const SIPX_INST hInst, const char *szCodecName)
 Set the codec preference order by name. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetAudioCodecPreferences (const SIPX_INST hInst, SIPX_AUDIO_BANDWIDTH_ID *pBandWidth)
 Get the current codec preference. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetNumAudioCodecs (const SIPX_INST hInst, int *pNumCodecs)
 Get the number of audio codecs. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetAudioCodec (const SIPX_INST hInst, const int index, SIPX_AUDIO_CODEC *pCodec)
 Get the audio codec at a certain index in the list of codecs. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoBandwidth (const SIPX_INST hInst, SIPX_VIDEO_BANDWIDTH_ID bandWidth)
 Set the bandwidth parameters for video codecs.Depending on the bandwidth parameter that is passed in the settings will be set to: More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetVideoCaptureDevices (const SIPX_INST hInst, char **arrSzCaptureDevices, int nDeviceStringLength, int nArrayLength)
 Gets the list of video capture devices. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetVideoCaptureDevice (const SIPX_INST hInst, char *szCaptureDevice, int nLength)
 Gets the current video capture device. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoCaptureDevice (const SIPX_INST hInst, const char *szCaptureDevice)
 Sets the video capture device. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoCodecByName (const SIPX_INST hInst, const char *szCodecName)
 Set the codec by name. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigResetVideoCodecs (const SIPX_INST hInst)
 Reset the codec list if it was modified by sipxConfigSetVideoCodecByName. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetVideoCodecPreferences (const SIPX_INST hInst, SIPX_VIDEO_BANDWIDTH_ID *pBandWidth)
 Get the current codec preference. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetNumVideoCodecs (const SIPX_INST hInst, int *pNumCodecs)
 Get the number of video codecs. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoFormat (const SIPX_INST hInst, SIPX_VIDEO_FORMAT videoFormat)
 Set the supported video format This method will limit the supported video format to either VIDEO_FORMAT_CIF (352x288), VIDEO_FORMAT_QCIF (176x144), VIDEO_FORMAT_SQCIF (128x92), or VIDEO_FORMAT_QVGA (320x240). More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetVideoCodec (const SIPX_INST hInst, const int index, SIPX_VIDEO_CODEC *pCodec)
 Get the video codec at a certain index in the list of codecs. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetLocalContacts (const SIPX_INST hInst, SIPX_CONTACT_ADDRESS addresses[], size_t nMaxAddresses, size_t &nActualAddresses)
 Get the local contact address available for outbound/inbound signaling and audio. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetLocalFeedbackAddress (const SIPX_INST hInst, const char *szRemoteIp, const int iRemotePort, char *szContactIp, size_t nContactIpLength, int &iContactPort, int iTimeoutMs)
 Get our local ip/port combination for the designated remote ip/port. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigGetAllLocalNetworkIps (const char *arrAddresses[], const char *arrAddressAdapter[], int &numAddresses)
 Populates an array of IP Addresses in char* form. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetSecurityParameters (const SIPX_INST hInst, const char *szDbLocation, const char *szMyCertNickname, const char *szDbPassword)
 Set security parameters for an instance of sipXtapi. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableSipShortNames (const SIPX_INST hInst, const bool bEnabled)
 Enables/Disables use of short field names in sip messages. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableSipDateHeader (const SIPX_INST hInst, const bool bEnabled)
 Enables/Disables use of date header in sip messages. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableSipAllowHeader (const SIPX_INST hInst, const bool bEnabled)
 Enables/Disables use of allow header in sip messages. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetSipAcceptLanguage (const SIPX_INST hInst, const char *szLanguage)
 Sets the Accept Language used in sip messages. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetLocationHeader (const SIPX_INST hInst, const char *szHeader)
 Sets the location header for SIP messages. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetConnectionIdleTimeout (const SIPX_INST hInst, const int idleTimeout)
 Set the connection idle timeout. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigPrepareToHibernate (const SIPX_INST hInst)
 Call this function to prepare a sipXtapi instance for a system hibernation. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigUnHibernate (const SIPX_INST hInst)
 Call this function upon returning from a system hibernation. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigEnableRtpOverTcp (const SIPX_INST hInst, bool bEnable)
 Enables RTP streaming over TCP. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoPreviewDisplay (const SIPX_INST hInst, SIPX_VIDEO_DISPLAY *const pDisplay)
 Sets the display object for the "video preview". More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigUpdatePreviewWindow (const SIPX_INST hInst, const SIPX_WINDOW_HANDLE hWnd)
 Updates the Preview window with a new frame buffer. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoQuality (const SIPX_INST hInst, const SIPX_VIDEO_QUALITY_ID quality)
 Sets the video quality. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoParameters (const SIPX_INST hInst, const int bitRate, const int frameRate)
 Sets the bit rate and frame rate parameters for video. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoBitrate (const SIPX_INST hInst, const int bitRate)
 Sets the video bitrate. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoFramerate (const SIPX_INST hInst, const int frameRate)
 Sets the video framerate. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoCpuUsage (const SIPX_INST hInst, const int cpuUsage)
 Set the cpu usage. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSubscribe (const SIPX_INST hInst, const SIPX_LINE hLine, const char *szTargetUrl, const char *szEventType, const char *szAcceptType, const SIPX_CONTACT_ID contactId, SIPX_SUB *phSub)
 Subscribe for NOTIFY events which may be published by another end-point or server. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigUnsubscribe (const SIPX_SUB hSub)
 Unsubscribe from previously subscribed NOTIFY events. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigExternalTransportAdd (SIPX_INST const hInst, SIPX_TRANSPORT &hTransport, const bool bIsReliable, const char *szTransport, const char *szLocalIP, const int iLocalPort, SIPX_TRANSPORT_WRITE_PROC writeProc, const char *szLocalRoutingId, const void *pUserData=NULL)
 Associates an external transport mechanism for SIP signaling with the given instance. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigExternalTransportRemove (const SIPX_TRANSPORT hTransport)
 Removes an external transport mechanism from the given instance. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigExternalTransportRouteByUser (const SIPX_TRANSPORT hTransport, bool bRouteByUser)
 The external transport mechanism can be configured to route by user or by destination ip/port. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigExternalTransportHandleMessage (const SIPX_TRANSPORT hTransport, const char *szSourceIP, const int iSourcePort, const char *szLocalIP, const int iLocalPort, const void *pData, const size_t nData)
 Called by the application when it receives a complete SIP message via it's external transport mechanism and want to pass it along to sipXtapi. More...
 
SIPXTAPI_API SIPX_RESULT sipxConfigSetVoiceQualityServer (const SIPX_INST hInst, const char *szServer)
 Sets the SIP target URL for voice quality reports. More...
 
Utility Functions
SIPXTAPI_API SIPX_RESULT sipxUtilUrlParse (const char *szUrl, char *szUsername, char *szHostname, int *iPort)
 Simple utility function to parse the username, host, and port from a URL. More...
 
SIPXTAPI_API SIPX_RESULT sipxUtilUrlGetDisplayName (const char *szUrl, char *szDisplayName, size_t nDisplayName)
 Simple utility function to parse the display name from a SIP URL. More...
 
SIPXTAPI_API SIPX_RESULT sipxUtilUrlUpdate (char *szUrl, size_t &nUrl, const char *szNewUsername, const char *szNewHostname, const int iNewPort)
 Simple utility function to update a URL. More...
 
SIPXTAPI_API SIPX_RESULT sipxUtilUrlGetUrlParam (const char *szUrl, const char *szParamName, size_t nParamIndex, char *szParamValue, size_t nParamValue)
 Get the Nth named url parameter from the designated url. More...
 

Variables

const SIPX_INST SIPX_INST_NULL = 0
 Represents a null instance handle. More...
 
const SIPX_LINE SIPX_LINE_NULL = 0
 Represents a null line handle. More...
 
const SIPX_CALL SIPX_CALL_NULL = 0
 Represents a null call handle. More...
 
const SIPX_CONF SIPX_CONF_NULL = 0
 Represents a null conference handle. More...
 
const SIPX_PUB SIPX_PUB_NULL = 0
 Represents a null publisher handle. More...
 
const SIPX_TRANSPORT SIPX_TRANSPORT_NULL = 0
 Represents a null transport handle. More...
 

Detailed Description

sipXtapi main API declarations

Macro Definition Documentation

#define CONF_MAX_CONNECTIONS   32

Max number of conference participants.

#define DEFAULT_BIND_ADDRESS   "0.0.0.0"

Bind to the first physical interface discovered.

#define DEFAULT_CONNECTIONS   32

Default number of max sim.

conns.

#define DEFAULT_IDENTITY   "sipx"

sipx<IP>:UDP_PORT used as identify if lines are not defined.

This define only controls the userid portion of the SIP url.

#define DEFAULT_RTP_START_PORT   9000

Starting RTP port for RTP port range.

The user agent will use ports ranging from the start port to the start port

  • (default connections * 2).
#define DEFAULT_STUN_PORT   3478

Default stun server port.

#define DEFAULT_TCP_PORT   5060

Default TCP port.

#define DEFAULT_TLS_PORT   5061

Default TLS port.

#define DEFAULT_UDP_PORT   5060

Default UDP port.

#define GAIN_DEFAULT   70

Nominal gain value.

#define GAIN_MAX   100

Max acceptable gain value.

#define GAIN_MIN   0

Min acceptable gain value.

This gain will mute mic.

#define MAX_AUDIO_DEVICES   16

Max number of input/output audio devices.

#define MAX_PASSWORD_LENGTH   32

maximum password length PKI operations

#define MAX_PKCS12_KEY_LENGTH   4096

pkcs12 key length

#define MAX_SMIME_KEY_LENGTH   2048

s/mime key length

#define MAX_SRTP_KEY_LENGTH   31

srtp key length

#define MAX_VIDEO_DEVICE_LENGTH   256

Max length of video capture device string.

#define MAX_VIDEO_DEVICES   8

Max number of video capture devices.

#define SIPX_CALLING_CONVENTION

The SIPX_CALLING_CONVENTION define controls the default calling convention.

define "SIPX_USE_STDCALL" to use the __stdcall calling convention under MSVC.

#define SIPX_MAX_ADAPTER_NAME_LENGTH   256

Max length of an adapter name.

#define SIPX_MAX_CALLS   64

Maximum number of simultaneous calls.

#define SIPX_MAX_IP_ADDRESSES   32

Maximum number of IP addresses on the host.

#define SIPX_PORT_AUTO   -2

Special value that instructs sipXtapi to automatically select an open port for signaling or audio when passed to sipXinitialize.

#define SIPX_PORT_DISABLE   -1

Special value that disables the transport type (e.g.

UDP, TCP, or TLS) when passed to sipXinitialize

#define SIPXTAPI_API   extern "C"

Assume extern "C" for non-win32 platforms.

#define SIPXTAPI_BUILD_WORD   3,3,0,0

Default build word – automatically filled in during release process.

#define SIPXTAPI_BUILDDATE   "0000-00-00"

Default build date – automatically filled in during release process.

#define SIPXTAPI_BUILDNUMBER   "0"

Default build number – automatically filled in during release process.

#define SIPXTAPI_CODEC_NAMELEN   32

Maximum length for codec name.

#define SIPXTAPI_CODEC_NAMELEN   32

Maximum length for codec name.

#define SIPXTAPI_FULL_VERSION   "3.3.0.0"

Default full version number – automatically filled in during release process.

#define SIPXTAPI_VERSION   "3.3.0"

sipXtapi API version – automatically filled in during release process

#define SIPXTAPI_VERSION_STRING   "sipXtapi SDK %s.%s %s (built %s)"

Version string format string.

#define VOLUME_DEFAULT   70

Nominal volume value.

#define VOLUME_MAX   100

Max acceptable volume value.

#define VOLUME_MIN   0

Min acceptable volume value.

Typedef Documentation

typedef void(* fnMicAudioHook) (const int nSamples, short *pSamples)

Typedef for audio source (microphone) hook procedure.

This typedef coupled with the sipxConfigSetMicAudioHook API allows developers to view, modify or substitute microphone data.

Parameters
nSamplesnumber of 16 bit unsigned PCM samples
pSamplespointer to array of samples.
typedef void(* fnSpkrAudioHook) (const int nSamples, short *pSamples)

Typedef for audio target(speaker) hook procedure.

This typedef coupled with the sipxConfigSetSpkrAudioHook API allows developers to intercept and modify audio headed for the speaker.

Parameters
nSamplesnumber of 16 bit unsigned samples
pSamplespointer to array of samples
typedef enum MEDIA_TYPE MEDIA_TYPE

Media type.

SIPX_AEC_MODE defines different AEC modes.

Options included DISABLED, SUPPRESS, CANCEL, and CANCEL_AUTO.

NOTE: This functionally is only supported when sipXtapi is bundled with VoiceEngine from Global IP Sound or Speex library.

NOTE: SIPX_AEC_SUPPRESS is not available if Speex library used.

Codec bandwidth ids are used to select a group of codecs with equal or lower bandwidth requirements.

Bandwidth requirements for supported codecs:

High:     IPCMWB    ~ 80 kbps
Normal:   PCMU      64 kbps
          PCMA      64 kbps
Low:      iLBC      13.33 kbps, 30 ms frame size and
                    15.2 kbps, 20 ms frame size
          GSM       13 kbps, 20 ms frame size
          G729      8 Kbps, 10ms frame size
          SPEEX     8 Kbps
          SPEEX_5   5.95 Kbps
          SPEEX_15  15 Kbps
          SPEEX_24  24.6 Kbps
Variable: ISAC      variable bitrate

Format definitions for memory resident audio data.

Audio file format types.

typedef unsigned int SIPX_CALL

The SIPX_CALL handle represents a call or connection between the user agent and another party.

All call operations require the call handle as a parameter.

typedef unsigned long SIPX_CONF

The SIPX_CONF handle represents a collection of CALLs that have bridge (mixed) audio.

Application developers can manipulate each leg of the conference through various conference functions.

typedef int SIPX_CONTACT_ID

Type for storing Contact Record identifiers.

See also
sipxConfigGetLocalContacts
typedef unsigned long SIPX_INFO

The SIPX_INFO handle represents a handle to an INFO message sent by a sipXtapi instance.

INFO messages are useful for communicating information between user agents within a logical call. The SIPX_INFO handle is returned when sending an INFO message via sipxCallSendInfo(...). The handle is references as part of the EVENT_CATEGORY_INFO_STATUS event callback/observer. sipXtapi will automatically deallocate this handle immediately after the status call back.

typedef void* SIPX_INST

The SIPX_INST handle represents an instance of a user agent.

A user agent includes a SIP stack and media processing framework. sipXtapi does support multiple instances of user agents in the same process space, however, certain media processing features become limited or ambiguous. For example, only one user agent should control the local system's input and output audio devices.

typedef unsigned int SIPX_LINE

The SIPX_LINE handle represents an inbound or outbound identity.

When placing outbound the application programmer must define the outbound line. When receiving inbound calls, the application can query the line.

Various log levels available for the sipxConfigEnableLog method.

Developers can choose the amount of detail available in the log. Each level includes messages generated at lower levels. For example, LOG_LEVEL_EMERG will limit the log to emergency messages, while LOG_LEVEL_ERR includes emergency messages, alert messages, critical messages, and errors. LOG_LEVEL_ERR is probably best for general runtime situations. LOG_LEVEL_INFO or LOG_LEVEL_DEBUG is best for diagnosing problems.

SIPX_NOISE_REDUCTION_MODE defines the various noise reduction options.

Options include, DISABLED, LOW, MEDIUM, and HIGH. When selecting a noise reduction level, you are trading off reducing back ground noise with the possibility of suppressing speech. We recommend selecting the LOW level.

NOTE: This functionally is only supported when sipXtapi is bundled with VoiceEngine from Global IP Sound or Speex library.

NOTE: When Speex library is used there is no difference between SIPX_NOISE_REDUCTION_LOW, SIPX_NOISE_REDUCTION_MEDIUM and SIPX_NOISE_REDUCTION_HIGH.

typedef unsigned long SIPX_PUB

The SIPX_PUB handle represent a publisher context.

Publisher are used to publish application-data to interested parties (Subscribers). This maps directly to the SIP SUBSCRIBE, and NOTIFY methods. The handle is used to mange the life cycle of the publisher.

SIPX_PUB handles are created by using sipxCreatePublisher. SIPX_PUB handles should be torn down using sipxDestroyPublisher.

typedef enum SIPX_RESULT SIPX_RESULT

SIPX_RESULT is an enumeration with all the possible result/return codes.

typedef unsigned long SIPX_SUB

A SIPX_SUB handle represent a subscription to a remote publisher.

This maps directly to the SIP SUBSCRIBE, and NOTIFY methods. The handle is used to mange the life cycle of the subscription.

SIPX_SUB handles are created by using the sipxCallSubscribe function. SIPX_SUB handles should be destroyed using the sipxCallUnsubscribe function.

typedef enum SIPX_TONE_ID SIPX_TONE_ID

DTMF/other tone ids used with sipxCallStartTone/sipxCallStopTone.

typedef unsigned long SIPX_TRANSPORT

The SIPX_TRANSPORT handle represents a user-implementation of a network transport mechanism to be used for SIP signaling.

typedef bool(SIPX_CALLING_CONVENTION * SIPX_TRANSPORT_WRITE_PROC) (SIPX_TRANSPORT hTransport, const char *szDestinationIp, const int iDestPort, const char *szLocalIp, const int iLocalPort, const void *pData, const size_t nData, const void *pUserData)

External Transport callback definition.

SIPxua will invoke this callback when there is data to write to the external transport layer. A function pointer with this signature is passed into the sipxConfigExternalTransportAdd function.

Parameters
hTransportHandle to the external transport object. Will match a transport handle obtained via a call to sipxConfigExternalTransportAdd
szDestinationIpIP address which is the destination for the write.
iDestPortPort value to which the data will be sent.
szLocalIpIP address which is the source address for the write.
iLocalPortPort value from which the data will be sent.
pDataPointer to the data to be sent.
nDataSize of the data to be sent.

Video Codec bandwidth ids are used to select a group of codecs with equal or lower bandwidth requirements.

The codec name is a combination of the actual codec name and the video resolution.

Supported codecs are:

VP71, IYUV, I420, and RGB24

Supported resolutions are

CIF (352x288), QCIF (176x144), SQCIF (128x96), and QVGA (320x240)

A VP71 codec in QCIF resolution would be named VP71-QCIF.

Enum for specifying the type of display object to be used for displaying video.

Enumeration of possible video sizes.

Video Codec quality definitions.

Quality is used as a trade off between between CPU usage and the amount of bandwidth used.

typedef void* SIPX_WINDOW_HANDLE

Type for storing a "window object handle" - in Windows, the application should cast their HWND to a SIPX_WINDOW_HANDLE.

typedef void(* sipxLogCallback) (const char *szPriority, const char *szSource, const char *szMsg)

Signature for a log callback function that gets passed three strings, first string is the priority level, second string is the source id of the subsystem that generated the message, and the third string is the message itself.

typedef enum SPEAKER_TYPE SPEAKER_TYPE

Speaker output types are used to differentiate between the logical ringer (used to alert user of in inbound call) and speaker (in call audio device).

Left for backwards compatibility – please use SIPX_TONE_ID.

Enumeration Type Documentation

enum MEDIA_TYPE

Media type.

Enumerator
AUDIO_MEDIA 
VIDEO_MEDIA 

SIPX_AEC_MODE defines different AEC modes.

Options included DISABLED, SUPPRESS, CANCEL, and CANCEL_AUTO.

NOTE: This functionally is only supported when sipXtapi is bundled with VoiceEngine from Global IP Sound or Speex library.

NOTE: SIPX_AEC_SUPPRESS is not available if Speex library used.

Enumerator
SIPX_AEC_DISABLED 

Disabled AEC; do not attempt to cancel or suppress echo.

SIPX_AEC_SUPPRESS 

Echo suppression; attempt to suppress echo by effectively forcing a half-duplex audio channel.

If you are speaking, the speaker will be silenced to avoid echo. Echo cancellation is consider a better approach/experience, however, requires more CPU consumption.

SIPX_AEC_CANCEL 

Full echo cancellation; attempt to cancel echo between the the speaker and microphone.

Depending on the quality of your speaker/microphone, this may result in some suppression. For example, if either the speaker or microphone distorts the signal (making it non-linear), it is becomes increasingly difficult to cancel. This is consider a full-duplex solution.

SIPX_AEC_CANCEL_AUTO 

Full echo cancellation; attempt to cancel echo between the the speaker and microphone; however, automatically disable echo cancellation if it appears not needed.

Codec bandwidth ids are used to select a group of codecs with equal or lower bandwidth requirements.

Bandwidth requirements for supported codecs:

High:     IPCMWB    ~ 80 kbps
Normal:   PCMU      64 kbps
          PCMA      64 kbps
Low:      iLBC      13.33 kbps, 30 ms frame size and
                    15.2 kbps, 20 ms frame size
          GSM       13 kbps, 20 ms frame size
          G729      8 Kbps, 10ms frame size
          SPEEX     8 Kbps
          SPEEX_5   5.95 Kbps
          SPEEX_15  15 Kbps
          SPEEX_24  24.6 Kbps
Variable: ISAC      variable bitrate
Enumerator
AUDIO_CODEC_BW_VARIABLE 

ID for codecs with variable bandwidth requirements.

AUDIO_CODEC_BW_LOW 

ID for codecs with low bandwidth requirements.

AUDIO_CODEC_BW_NORMAL 

ID for codecs with normal bandwidth requirements.

AUDIO_CODEC_BW_HIGH 

ID for codecs with high bandwidth requirements.

AUDIO_CODEC_BW_CUSTOM 

Possible return value for sipxConfigGetAudioCodecPreferences.

This ID indicates the available list of codecs was overridden by a sipxConfigSetAudioCodecByName call.

AUDIO_CODEC_BW_DEFAULT 

Value used to signify the default bandwidth level when calling sipxCallConnect, sipxCallAccept, or sipxConferenceAdd.

Format definitions for memory resident audio data.

Enumerator
RAW_PCM_16 

Signed 16 bit PCM data, mono, 8KHz, no header.

Audio file format types.

Enumerator
SIPX_UNKNOWN_FORMAT 
SIPX_WAVE_PCM_16 

Wave audio file with PCM 16 bit, signed, little endian encoded audio.

SIPX_WAVE_GSM 

Wave audio file with GSM encoded audio.

SIPX_CONTACT_TYPE is an enumeration of possible address types for use with SIP contacts and SDP connection information.

Application developers and choose to setup calls with specific contact types (e.g. use my local IP address, a stun-derived IP address, turn-derived IP address, etc). Unless you have complete knowledge and control of your network environment, you should likely use CONTACT_AUTO.

Enumerator
CONTACT_LOCAL 

Local address for a particular interface.

CONTACT_NAT_MAPPED 

NAT mapped address (e.g.

STUN)

CONTACT_RELAY 

Relay address (e.g.

TURN)

CONTACT_CONFIG 

Manually configured address.

CONTACT_AUTO 

Automatic contact selection; used for API parameters.

CONTACT_ALL 

SIPX_KEEPALIVE_TYPEs define different methods of keeping NAT/firewall port open.

These approaches are used for the signaling path of a call and are generally only needed under specific network configurations.

Examples: - When not using a proxy

  • When the registration period is longer then NAT bindings timeout

The STUN, and SIP_PING and SIP_OPTIONS events may also give you more information about your network NAT mappings. When you add a keepalive, you may get KEEPALIVE_FEEDBACK events with the IP/port that your peer thinks is you. For STUN, this comes from the STUN response, for the SIP keepalives, this comes from the "via" response if the remote supports rport/symmetric signaling.

Enumerator
SIPX_KEEPALIVE_CRLF 

Send a Carriage Return/Line Feed to other side.

SIPX_KEEPALIVE_STUN 

Send a Stun request to the other side.

SIPX_KEEPALIVE_SIP_PING 

Send a SIP PING method request to the other side.

SIPX_KEEPALIVE_SIP_OPTIONS 

Send a SIP OPTIONS method request to the other side.

Various log levels available for the sipxConfigEnableLog method.

Developers can choose the amount of detail available in the log. Each level includes messages generated at lower levels. For example, LOG_LEVEL_EMERG will limit the log to emergency messages, while LOG_LEVEL_ERR includes emergency messages, alert messages, critical messages, and errors. LOG_LEVEL_ERR is probably best for general runtime situations. LOG_LEVEL_INFO or LOG_LEVEL_DEBUG is best for diagnosing problems.

Enumerator
LOG_LEVEL_DEBUG 

debug-level messages

LOG_LEVEL_INFO 

informational messages

LOG_LEVEL_NOTICE 

normal, but significant, conditions

LOG_LEVEL_WARNING 

warning conditions

LOG_LEVEL_ERR 

error conditions

LOG_LEVEL_CRIT 

critical conditions

LOG_LEVEL_ALERT 

action must be taken immediately

LOG_LEVEL_EMERG 

system is unusable

LOG_LEVEL_NONE 

disable logging

SIPX_NOISE_REDUCTION_MODE defines the various noise reduction options.

Options include, DISABLED, LOW, MEDIUM, and HIGH. When selecting a noise reduction level, you are trading off reducing back ground noise with the possibility of suppressing speech. We recommend selecting the LOW level.

NOTE: This functionally is only supported when sipXtapi is bundled with VoiceEngine from Global IP Sound or Speex library.

NOTE: When Speex library is used there is no difference between SIPX_NOISE_REDUCTION_LOW, SIPX_NOISE_REDUCTION_MEDIUM and SIPX_NOISE_REDUCTION_HIGH.

Enumerator
SIPX_NOISE_REDUCTION_DISABLED 

Disable NR; Do not attempt to reduce background noise.

SIPX_NOISE_REDUCTION_LOW 

Enable NR with least amount of aggressiveness.

SIPX_NOISE_REDUCTION_MEDIUM 

Enable NR with modest amount of aggressiveness.

SIPX_NOISE_REDUCTION_HIGH 

Enable NR with highest amount of aggressiveness.

SIPX_RESULT is an enumeration with all the possible result/return codes.

Enumerator
SIPX_RESULT_SUCCESS 

Success.

SIPX_RESULT_FAILURE 

Generic Failure.

SIPX_RESULT_NOT_IMPLEMENTED 

Method/API not implemented.

SIPX_RESULT_OUT_OF_MEMORY 

Unable to allocate enough memory to perform operation.

SIPX_RESULT_INVALID_ARGS 

Invalid arguments; bad handle, argument out of range, etc.

SIPX_RESULT_BAD_ADDRESS 

Invalid SIP address.

SIPX_RESULT_OUT_OF_RESOURCES 

Out of resources (hit some max limit)

SIPX_RESULT_INSUFFICIENT_BUFFER 

Buffer too short for this operation.

SIPX_RESULT_EVAL_TIMEOUT 

The evaluation version of this product has expired.

SIPX_RESULT_BUSY 

The operation failed because the system was busy.

SIPX_RESULT_INVALID_STATE 

The operation failed because the object was in the wrong state.

For example, attempting to split a call from a conference before that call is connected.

SIPX_RESULT_MISSING_RUNTIME_FILES 

The operation failed because required runtime dependencies are missing.

SIPX_RESULT_TLS_DATABASE_FAILURE 

The operation failed because the certificate database did not initialize.

SIPX_RESULT_TLS_BAD_PASSWORD 

The operation failed because the certificate database did not accept the password.

SIPX_RESULT_TLS_TCP_IMPORT_FAILURE 

The operation failed because a TCP socket could not be imported by the SSL/TLS module.

SIPX_RESULT_NSS_FAILURE 

The operation failed due to an NSS failure.

SIPX_RESULT_NOT_SUPPORTED 

The operation is not supported in this build/configuration.

SIPX_RESULT_NETWORK_FAILURE 

The network is down or failing.

SIPX_RESULT_LIB_NOT_FOUND 

Dependent shared library not found.

SIPX_RESULT_OS_PLATFORM_UNSUPPORTED 

libraries or facilities not supported for this specific OS platform

Possible roles that a Media connection can have.

TCP is currently defined, but not fully implemented. Use at your own risk.

Enumerator
SIPX_RTP_TRANSPORT_UNKNOWN 
SIPX_RTP_TRANSPORT_UDP 
SIPX_RTP_TRANSPORT_TCP 
SIPX_RTP_TCP_ROLE_ACTIVE 
SIPX_RTP_TCP_ROLE_PASSIVE 
SIPX_RTP_TCP_ROLE_ACTPASS 
SIPX_RTP_TCP_ROLE_CONNECTION 

Enumeration of the possible levels of SRTP.

Enumerator
SRTP_LEVEL_NONE 
SRTP_LEVEL_ENCRYPTION 
SRTP_LEVEL_AUTHENTICATION 
SRTP_LEVEL_ENCRYPTION_AND_AUTHENTICATION 

DTMF/other tone ids used with sipxCallStartTone/sipxCallStopTone.

Enumerator
ID_DTMF_INVALID 

Invalid/Uninitialized DMTF Id.

ID_DTMF_0 

DMTF 0.

ID_DTMF_1 

DMTF 1.

ID_DTMF_2 

DMTF 2.

ID_DTMF_3 

DMTF 3.

ID_DTMF_4 

DMTF 4.

ID_DTMF_5 

DMTF 5.

ID_DTMF_6 

DMTF 6.

ID_DTMF_7 

DMTF 7.

ID_DTMF_8 

DMTF 8.

ID_DTMF_9 

DMTF 9.

ID_DTMF_STAR 

DMTF *.

ID_DTMF_POUND 

DMTF #.

ID_DTMF_FLASH 

DTMF Flash.

ID_TONE_DIALTONE 

Dialtone (Not supported with GIPS VoiceEngine)

ID_TONE_BUSY 

Call-busy tone (Not supported with GIPS VoiceEngine)

ID_TONE_RINGBACK 

Remote party is ringing feedback tone (Not supported with GIPS VoiceEngine)

ID_TONE_RINGTONE 

Default ring/alert tone (Not supported with GIPS VoiceEngine)

ID_TONE_CALLFAILED 

Fasy Busy / call failed tone (Not supported with GIPS VoiceEngine)

ID_TONE_SILENCE 

Silence (Not supported with GIPS VoiceEngine)

ID_TONE_BACKSPACE 

Backspace tone (Not supported with GIPS VoiceEngine)

ID_TONE_CALLWAITING 

Call waiting alert tone (Not supported with GIPS VoiceEngine)

ID_TONE_CALLHELD 

Call held feedback tone (Not supported with GIPS VoiceEngine)

ID_TONE_LOUD_FAST_BUSY 

Off hook / fast busy tone (Not supported with GIPS VoiceEngine)

SIPX_TRANSPORT_TYPE defines various protocols use for signaling transport.

The SIPX_TRANSPORT_TYPE is return in contact addresses.

Enumerator
TRANSPORT_UDP 

Indicator for a UDP socket type.

TRANSPORT_TCP 

Indicator for a TCP socket type.

TRANSPORT_TLS 

Indicator for a TLS socket type.

TRANSPORT_CUSTOM 

Indicator for a custom external transport.

Video Codec bandwidth ids are used to select a group of codecs with equal or lower bandwidth requirements.

The codec name is a combination of the actual codec name and the video resolution.

Supported codecs are:

VP71, IYUV, I420, and RGB24

Supported resolutions are

CIF (352x288), QCIF (176x144), SQCIF (128x96), and QVGA (320x240)

A VP71 codec in QCIF resolution would be named VP71-QCIF.

Enumerator
VIDEO_CODEC_BW_VARIABLE 

ID for codecs with variable bandwidth requirements.

VIDEO_CODEC_BW_LOW 

ID for codecs with low bandwidth requirements.

VIDEO_CODEC_BW_NORMAL 

ID for codecs with normal bandwidth requirements.

VIDEO_CODEC_BW_HIGH 

ID for codecs with high bandwidth requirements.

VIDEO_CODEC_BW_CUSTOM 

Possible return value for sipxConfigGetVideoCodecPreferences.

This ID indicates the available list of codecs was overridden by a sipxConfigSetVideoCodecByName call.

VIDEO_CODEC_BW_DEFAULT 

Value used to signify the default bandwidth level when calling sipxCallLimitCodecPreferences.

Enum for specifying the type of display object to be used for displaying video.

Enumerator
SIPX_WINDOW_HANDLE_TYPE 

A handle to the window for the remote video display.

DIRECT_SHOW_FILTER 

A DirectShow render filter object for handling the remote video display.

Enumeration of possible video sizes.

Enumerator
VIDEO_FORMAT_CIF 

352x288

VIDEO_FORMAT_QCIF 

176x144

VIDEO_FORMAT_SQCIF 

128x96

VIDEO_FORMAT_QVGA 

320x240

Video Codec quality definitions.

Quality is used as a trade off between between CPU usage and the amount of bandwidth used.

Enumerator
VIDEO_QUALITY_LOW 

Low quality video.

VIDEO_QUALITY_NORMAL 

Normal quality video.

VIDEO_QUALITY_HIGH 

High quality video.

Speaker output types are used to differentiate between the logical ringer (used to alert user of in inbound call) and speaker (in call audio device).

Enumerator
SPEAKER 

Speaker / in call device.

RINGER 

Ringer / alerting device.

Function Documentation

SIPXTAPI_API SIPX_RESULT sipxAudioEnableSpeaker ( const SIPX_INST  hInst,
const SPEAKER_TYPE  type 
)

Enables one of the speaker outputs.

Parameters
hInstInstance pointer obtained by sipxInitialize.
typeThe type of the speaker either the logical ringer (used to alert user of in inbound call) or speaker (in call audio device).
SIPXTAPI_API SIPX_RESULT sipxAudioGetAECMode ( const SIPX_INST  hInst,
SIPX_AEC_MODE mode 
)

Get the mode of Acoustic Echo Cancellation (AEC).

Note: This API is only supported when bundled with VoiceEngine from Global IP Sound or Speex library.

Parameters
hInstInstance pointer obtained by sipxInitialize.
modeAEC mode.
See also
SIPX_AEC_MODE
SIPXTAPI_API SIPX_RESULT sipxAudioGetAGCMode ( const SIPX_INST  hInst,
bool &  bEnabled 
)

Get the enable/disable state of Automatic Gain Control (AGC).

Note: This API is only supported when bundled with VoiceEngine from Global IP Sound or Speex library.

Parameters
hInstInstance pointer obtained by sipxInitialize.
bEnabledtrue if AGC is enabled; otherwise false.
SIPXTAPI_API SIPX_RESULT sipxAudioGetEnabledSpeaker ( const SIPX_INST  hInst,
SPEAKER_TYPE type 
)

Gets the enabled speaker selection.

Parameters
hInstInstance pointer obtained by sipxInitialize.
typeThe type of the speaker either the logical ringer (used to alert user of in inbound call) or speaker (in call audio device).
SIPXTAPI_API SIPX_RESULT sipxAudioGetGain ( const SIPX_INST  hInst,
int &  iLevel 
)

Get the current microphone gain.

Parameters
hInstInstance pointer obtained by sipxInitialize.
iLevelThe level of the gain of the microphone
SIPXTAPI_API SIPX_RESULT sipxAudioGetInputDevice ( const SIPX_INST  hInst,
const int  index,
const char *&  szDevice 
)

Get the name/identifier for input device at position index.

Parameters
hInstInstance pointer obtained by sipxInitialize.
indexZero based index of the input device to be queried.
szDeviceReference an character string pointer to receive the device name.
SIPXTAPI_API SIPX_RESULT sipxAudioGetNoiseReductionMode ( const SIPX_INST  hInst,
SIPX_NOISE_REDUCTION_MODE mode 
)

Get the mode/policy for Noise Reduction (NR).

Note: This API is only supported when bundled with VoiceEngine from Global IP Sound or Speex library.

Parameters
hInstInstance pointer obtained by sipxInitialize.
modenoise reduction mode.
See also
SIPX_NOISE_REDUCTION_MODE
SIPXTAPI_API SIPX_RESULT sipxAudioGetNumInputDevices ( const SIPX_INST  hInst,
size_t &  numDevices 
)

Get the number of input devices available on this system.

Parameters
hInstInstance pointer obtained by sipxInitialize.
numDevicesThe number of input devices available on this system.
SIPXTAPI_API SIPX_RESULT sipxAudioGetNumOutputDevices ( const SIPX_INST  hInst,
size_t &  numDevices 
)

Get the number of output devices available on this system.

Parameters
hInstInstance pointer obtained by sipxInitialize.
numDevicesThe number of output devices available on this system.
SIPXTAPI_API SIPX_RESULT sipxAudioGetOutputDevice ( const SIPX_INST  hInst,
const int  index,
const char *&  szDevice 
)

Get the name/identifier for output device at position index.

Parameters
hInstInstance pointer obtained by sipxInitialize.
indexZero based index of the output device to be queried.
szDeviceReference an character string pointer to receive the device name.
SIPXTAPI_API SIPX_RESULT sipxAudioGetVolume ( const SIPX_INST  hInst,
const SPEAKER_TYPE  type,
int &  iLevel 
)

Gets the audio level for the designated speaker type.

Parameters
hInstInstance pointer obtained by sipxInitialize.
typeThe type of the speaker either the logical ringer (used to alert user of in inbound call) or speaker (in call audio device).
iLevelThe level of the gain of the microphone
SIPXTAPI_API SIPX_RESULT sipxAudioIsMuted ( const SIPX_INST  hInst,
bool &  bMuted 
)

Gets the mute state of the microphone.

Parameters
hInstInstance pointer obtained by sipxInitialize.
bMutedTrue if the microphone has been muted and false if it is not mute
SIPXTAPI_API SIPX_RESULT sipxAudioMute ( const SIPX_INST  hInst,
const bool  bMute 
)

Mute or unmute the microphone.

Parameters
hInstInstance pointer obtained by sipxInitialize.
bMuteTrue if the microphone is to be muted and false if it is not to be muted
SIPXTAPI_API SIPX_RESULT sipxAudioSetAECMode ( const SIPX_INST  hInst,
const SIPX_AEC_MODE  mode 
)

Enables or disables Acoustic Echo Cancellation (AEC).

By default, sipXtapi assumes SIPX_AEC_CANCEL_AUTO. Change this parameter will modify the policy for both existing and new calls.

Note: This API is only supported when bundled with VoiceEngine from Global IP Sound or Speex library.

Parameters
hInstInstance pointer obtained by sipxInitialize.
modeAEC mode.
See also
SIPX_AEC_MODE
SIPXTAPI_API SIPX_RESULT sipxAudioSetAGCMode ( const SIPX_INST  hInst,
const bool  bEnable 
)

Enable/Disable Automatic Gain Control (AGC).

By default, AGC is disabled.

Note: This API is only supported when bundled with VoiceEngine from Global IP Sound or Speex library.

Parameters
hInstInstance pointer obtained by sipxInitialize.
bEnabletrue to enable AGC or false to disable
SIPXTAPI_API SIPX_RESULT sipxAudioSetCallInputDevice ( const SIPX_INST  hInst,
const char *  szDevice 
)

Set the call input device (in-call microphone).

Parameters
hInstInstance pointer obtained by sipxInitialize.
szDeviceCharacter string pointer to be set to a string name of the output device.
SIPXTAPI_API SIPX_RESULT sipxAudioSetCallOutputDevice ( const SIPX_INST  hInst,
const char *  szDevice 
)

Set the call output device (in-call speaker).

Parameters
hInstInstance pointer obtained by sipxInitialize.
szDeviceThe call output device.
SIPXTAPI_API SIPX_RESULT sipxAudioSetGain ( const SIPX_INST  hInst,
const int  iLevel 
)

Set the local microphone gain.

If the microphone is muted, resetting the gain will not enable audio – you must unmute the microphone.

Parameters
hInstInstance pointer obtained by sipxInitialize.
iLevelThe level of the local microphone gain
SIPXTAPI_API SIPX_RESULT sipxAudioSetNoiseReductionMode ( const SIPX_INST  hInst,
const SIPX_NOISE_REDUCTION_MODE  mode 
)

Set the noise reduction mode/policy for suppressing background noise.

By default sipXtapi assumes SIPX_NOISE_REDUCTION_LOW. Change this parameter will modify the policy for both existing and new calls.

Note: This API is only supported when bundled with VoiceEngine from Global IP Sound or Speex library.

Parameters
hInstInstance pointer obtained by sipxInitialize.
modenoise reduction mode.
See also
SIPX_NOISE_REDUCTION_MODE
SIPXTAPI_API SIPX_RESULT sipxAudioSetRingerOutputDevice ( const SIPX_INST  hInst,
const char *  szDevice 
)

Set the call ringer/alerting device.

Parameters
hInstInstance pointer obtained by sipxInitialize.
szDeviceThe call ringer/alerting device.
SIPXTAPI_API SIPX_RESULT sipxAudioSetVolume ( const SIPX_INST  hInst,
const SPEAKER_TYPE  type,
const int  iLevel 
)

Sets the audio level for the designated speaker type.

If the speaker type is enabled, the change it audio will be heard instantly.

Parameters
hInstInstance pointer obtained by sipxInitialize.
typeThe type of the speaker either the logical ringer (used to alert user of in inbound call) or speaker (in call audio device).
iLevelThe level of the gain of the microphone 8 (see VOLUME_MIN, VOLUME_MAX and VOLUME_DEFAULT)
SIPXTAPI_API SIPX_RESULT sipxCallAccept ( const SIPX_CALL  hCall,
SIPX_VIDEO_DISPLAY *const  pDisplay = NULL,
SIPX_SECURITY_ATTRIBUTES *const  pSecurity = NULL,
SIPX_CALL_OPTIONS options = NULL,
bool  bSendEarlyMedia = false 
)

Accepts an inbound call and proceed immediately to alerting.

This method is invoked in response to a NEWCALL event. Whenever a new call is received, the application developer should ACCEPT (proceed to ringing), REJECT (send back busy), or REDIRECT the call.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
pDisplayPointer to an object describing the display object for rendering remote video.
pSecurityPointer to an object describing the security attributes for the call.
optionsPointer to a SIPX_CALL_OPTIONS structure.
bSendEarlyMediaflag to send early media (RTP) upon accepting the call
See also
sipxConfigSetLocationHeader
sipxConfigSetAudioCodecPreferences
SIPXTAPI_API SIPX_RESULT sipxCallAnswer ( const SIPX_CALL  hCall,
bool  bTakeFocus = true 
)

Answer an alerting call.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
bTakeFocusShould SIPxua place the newly answered call in focus (engage local microphone and speaker). In some cases, application developer may want to answer the call in the background and play audio while the user finishes up with their active (in focus) call.
SIPXTAPI_API SIPX_RESULT sipxCallAudioPlayFileStart ( const SIPX_CALL  hCall,
const char *  szFile,
const bool  bRepeat,
const bool  bLocal,
const bool  bRemote,
const bool  bMixWithMicrophone = false,
const float  fVolumeScaling = 1.0 
)

Play the designated file.

The file may be a raw 16 bit signed PCM at 8000 samples/sec, mono, little endian or a .WAV file. If a sipxCallDestroy is attempted while an audio file is playing, sipxCallDestroy will fail with a SIPX_RESULT_BUSY return code. Call sipxCallAudioPlayFileStop before making the call to sipxCallDestroy.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. Audio files can only be played in the context of a call.
szFileFilename for the audio file to be played.
bRepeatTrue if the file is supposed to be played repeatedly
bLocalTrue if the audio file is to be rendered locally.
bRemoteTrue if the audio file is to be rendered by the remote endpoint.
bMixWithMicrophoneTrue to mix the audio with the microphone data or false to replace it. This option is only supported when sipXtapi is bundled with GIPS VoiceEngine.
fVolumeScalingVolume down scaling for the audio file. Valid values are between 0 and 1.0, where 1.0 is the no down-scaling. This option is only supported when sipXtapi is bundled with GIPS VoiceEngine.
SIPXTAPI_API SIPX_RESULT sipxCallAudioPlayFileStop ( const SIPX_CALL  hCall)

Stop playing a file started with sipxCallPlayFileStart If a sipxCallDestroy is attempted while an audio file is playing, sipxCallDestroy will fail with a SIPX_RESULT_BUSY return code.

Call sipxCallAudioPlayFileStop before making the call to sipxCallDestroy.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. Audio files can only be played and stopped in the context of a call.
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordBufferStart ( const SIPX_CALL  hCall,
const char *  pBuffer,
const int  bufferSize,
const int  bufferType = RAW_PCM_16,
const int  maxRecordTime = -1,
const int  maxSilence = -1 
)

Record a call session (including other parties if this is a multi-party call / conference) to a buffer.

Conference join operation on this call will cause the recording to stop. In case of conference recording, this function should be called for single conference call only. Conference recording will continue even after the original call had been dropped/split, as long as there is at least one call left in the conference. If the original call has been dropped, use handle of other call in the conference to stop recording.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
pBufferBuffer to record data to.
bufferSizeSize of the buffer in bytes.
bufferTypeThe audio encoding format for the data as specified by the SIPX_AUDIO_DATA_FORMAT enumerations. Currently only RAW_PCM_16 is supported.
maxRecordTimeMaximum time to record in milliseconds. Recording stops automatically when this amount of time is recorded. Pass -1 to disable time limit.
maxSilenceMaximum silence time before recording is stopped automatically. Pass -1 to disable stop on silence.
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordBufferStop ( const SIPX_CALL  hCall)

Stop recording a call to buffer.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordFileStart ( const SIPX_CALL  hCall,
const char *  szFile,
const SIPX_AUDIO_FILE_FORMAT  recordFormat = SIPX_WAVE_PCM_16,
const bool  appendToFile = false,
const int  numChannels = 1 
)

Record a call session (including other parties if this is a multi-party call / conference) to a file.

The resulting file will be a PCM WAV file. Conference join operation on this call will cause the recording to stop. In case of conference recording, this function should be called for single conference call only. Conference recording will continue even after the original call had been dropped/split, as long as there is at least one call left in the conference. If the original call has been dropped, use handle of other call in the conference to stop recording.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szFileFilename for the resulting audio file.
recordFormat- audio file format to use when creating recording file
appendToFile- true/false if file exists, append to it as opposed to replacing it. Note: existing file must be of the same audio format requested or start record will fail.
numChannels- the number of channels to record in the wav file. Must be less than compile time maximum channels for recording.

Note: If recording with append in rapid stop, start situations, be sure to wait for the MEDIA_RECORDFILE_STOP media event before starting to append to the same record file or you risk having multiple file handles open on the same file with unpredictable results.

SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordFileStop ( const SIPX_CALL  hCall)

Stop recording a call to file.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordPause ( const SIPX_CALL  hCall)

Pause recording call to file or buffer.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
SIPXTAPI_API SIPX_RESULT sipxCallAudioRecordResume ( const SIPX_CALL  hCall)

Resume paused recording call to file or buffer.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
SIPXTAPI_API SIPX_RESULT sipxCallBlindTransfer ( const SIPX_CALL  hCall,
const char *  szAddress 
)

Blind transfer the specified call to another party.

Monitor the TRANSFER state events for details on the transfer attempt. If the call is not already on hold, the party will be placed on hold.

Assuming that all parties are using sipXtapi, all of the calls are active (not held), and the transfer works, you should expect the following event sequence:

Transferee (party being transfered):

The transferee's original call will be placed on remote hold from the transfer controller and will then put itself on full hold before starting the transfer. The transfer is implemented as a new call – this allows the developer to reclaim the original call if the transfer fails. The NEWCALL event will include a cause for of CALLSTATE_CAUSE_TRANSFER and the hAssociatedCall member of the SIPX_CALLSTATE_INFO structure will include the handle of the original call.

Original Call: MEDIA_LOCAL_STOP
Original Call: MEDIA_REMOTE_STOP
Original Call: CALLSTATE_REMOTE_HELD
Original Call: CALLSTATE_HELD
New Call: CALLSTATE_NEWCALL
New Call: CALLSTATE_REMOTE_OFFERING
New Call: CALLSTATE_REMOTE_ALERTING
New Call: CALLSTATE_CONNECTED
New Call: MEDIA_LOCAL_START
New Call: MEDIA_REMOTE_START

After the transfer completes, the application developer must destroy the original call using sipxCallDestroy. If the new call fails for any reason, the application layer should resume the original call by taking it off hold.

Transfer Controller (this user agent):

The transfer controller will automatically take the call out of focus and place it on hold. Afterwards, the transfer controller will receive CALLSTATE_TRANSFER_EVENTs indicating the status of the transfer.

Source Call: CALLSTATE_TRANSFER_EVENT::CALLSTATE_CAUSE_TRANSFER_INITIATED
Source Call: CALLSTATE_BRIDGED
Source Call: CALLSTATE_HELD
Source Call: MEDIA_CAUSE_HOLD
Source Call: MEDIA_CAUSE_HOLD
Source Call: CALLSTATE_TRANSFER_EVENT::CALLSTATE_CAUSE_TRANSFER_ACCEPTED
Source Call: CALLSTATE_TRANSFER_EVENT::CALLSTATE_CAUSE_TRANSFER_RINGING
Source Call: CALLSTATE_TRANSFER_EVENT::CALLSTATE_CAUSE_TRANSFER_SUCCESS
Source Call: CALLSTATE_DISCONNECTED

Upon success, the call will automatically be disconnected, however, the application layer needs to call sipXcallDestroy to free the handle and call processing resources.

Transfer Target (identified by szAddress):

The transferee will go through the normal event progression for an incoming call:

New Call: CALLSTATE_NEWCALL
New Call: CALLSTATE_OFFERING
New Call: CALLSTATE_ALERTING
New Call: CALLSTATE_CONNECTED

If the transfer target rejects the call or fails to answer, the transfer will fail.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szAddressSIP url identifing the transfer target (who the call identified by hCall will be transfered to).
See also
SIPX_CALLSTATE_EVENT
SIPX_CALLSTATE_CAUSE
SIPXTAPI_API SIPX_RESULT sipxCallConnect ( const SIPX_CALL  hCall,
const char *  szAddress,
SIPX_CONTACT_ID  contactId = 0,
SIPX_VIDEO_DISPLAY *const  pDisplay = NULL,
SIPX_SECURITY_ATTRIBUTES *const  pSecurity = NULL,
bool  bTakeFocus = true,
SIPX_CALL_OPTIONS options = NULL,
const char *  szCallId = NULL 
)

Connects an idle call to the designated target address.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szAddressSIP url of the target party
contactIdId of the desired contact record to use for this call. The id refers to a Contact Record obtained by a call to sipxConfigGetLocalContacts. The application can choose a contact record of type LOCAL, NAT_MAPPED, CONFIG, or RELAY. The Contact Type allows you to control whether the user agent and media processing advertises the local address (e.g. LOCAL contact of 10.1.1.x or 192.168.x.x), the NAT-derived address to the target party, or, local contact addresses of other types. The Contact Record's eTransportType field indicates the type of network transport to be used for call signalling. this can be UPD, TCP, or TLS. If the eTransportType field value is greater than 3, this indicates that a custom EXTERNAL TRANSPORT mechanism is to be used, and the value of the eTransportType field indicates the SIPX_TRANSPORT handle associated with the EXTERNAL TRANSPORT.
pDisplayPointer to an object describing the display object for rendering remote video.
pSecurityPointer to an object describing the security attributes for the call.
bTakeFocusShould SIPxua place the this call in focus (engage local microphone and speaker). In some cases, application developer may want to place the call in the background and play audio while the user finishes up with their active (in focus) call.
optionsPointer to a SIPX_CALL_OPTIONS structure.
szCallIdA call-id for the session, if NULL, one is generated.
See also
sipxConfigSetLocationHeader
sipxConfigSetAudioCodecPreferences
SIPXTAPI_API SIPX_RESULT sipxCallCreate ( const SIPX_INST  hInst,
const SIPX_LINE  hLine,
SIPX_CALL phCall 
)

Create a new call for the purpose of creating an outbound connection/call.

As a side effect, a DIALTONE event is fired to simulate the PSTN world. Generally an application would simulate dialtone in reaction to that event.

Parameters
hInstInstance pointer obtained by sipxInitialize.
hLineLine Identity for the outbound call. The line identity helps defines the "From" caller-id. The line identity can't be SIPX_LIINE_NULL for an outbound call.
phCallPointer to a call handle. Upon success, this value is replaced with a valid call handle. Success is determined by the SIPX_RESULT result code.
SIPXTAPI_API SIPX_RESULT sipxCallDestroy ( SIPX_CALL hCall)

Drop/Destroy the specified call.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
SIPXTAPI_API SIPX_RESULT sipxCallGetAudioRtcpStats ( const SIPX_CALL  hCall,
SIPX_RTCP_STATS pStats 
)

Obtain RTCP stats for the specified call.

This API is only supported when sipXtapi is bundled with VoiceEngine from GIPS.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
pStatsStructure to place call stats, the structure's cbSize member must be filled out prior to calling this API. For example: myStats.cbSize = sizeof(SIPX_RTCP_STATS);
SIPXTAPI_API SIPX_RESULT sipxCallGetAudioRtpSourceIds ( const SIPX_CALL  hCall,
unsigned int &  iSendSSRC,
unsigned int &  iReceiveSSRC 
)

Gets the sending and receiving Audio RTP SSRC IDs.

The SSRC ID is used to identify the RTP/audio stream. The call must be in the connected state for this request to succeed.

This API is only supported when sipXtapi is bundled with VoiceEngine from GIPS.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
iSendSSRCThe RTP SSRC used when sending audio
iReceiveSSRCThe RTP SSRC used by the remote party to sending audio
SIPXTAPI_API SIPX_RESULT sipxCallGetConference ( const SIPX_CALL  hCall,
SIPX_CONF hConf 
)

Get the conference handle for the specified call.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
hConfConference handle for this call (if the call is part of a conference)
SIPXTAPI_API SIPX_RESULT sipxCallGetConnectionId ( const SIPX_CALL  hCall,
int &  connectionId 
)

Gets the media interface connection ID.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
connectionIdReference to the returned connection identifier.
SIPXTAPI_API SIPX_RESULT sipxCallGetContactID ( const SIPX_CALL  hCall,
char *  szId,
const size_t  iMaxLength 
)

Get the SIP identity of the contact connection.

The identity represents the originator of the message.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szIdBuffer to store the ID. A zero-terminated string will be copied into this buffer on success.
iMaxLengthMax length of the ID buffer.
SIPXTAPI_API SIPX_RESULT sipxCallGetEnergyLevels ( const SIPX_CALL  hCall,
int &  iInputEnergyLevel,
int &  iOutputEnergyLevel,
const size_t  nMaxContributors,
unsigned int  CCSRCs[],
int  iEnergyLevels[],
size_t &  nActualContributors 
)

Gets energy levels for a call.

The call must be in the connected state for this request to succeed.

This API is only supported when sipXtapi is bundled with VoiceEngine from GIPS.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
iInputEnergyLevelInput/Microphone energy level ranging from 0 to 9.
iOutputEnergyLevelOutput/Speaker energy level ranging from 0 to 9. The output energy level is pre-mixed (before mixing any files/tones or other parties). sipxConferenceGetEnergyLevels provides an API to obtain post-mixed energy levels.
nMaxContributorsMax number of contributors/energy levels. Contributors are derived by looking at the contributing RTP source IDs from the RTP stream.
CCSRCsArray of contributing source ids. This array will be filled in up to a max of nMaxContributors. See nActualContributors for the actual number of elements returned.
iEnergyLevelsEnergy level for each contributing source id ranging from 0 to 9. This array in up to a max of nMaxContributors. See nActualContributors for the actual number of elements returned.
nActualContributorsThe actual number of contributing source ids and energy levels returned.
SIPXTAPI_API SIPX_RESULT sipxCallGetID ( const SIPX_CALL  hCall,
char *  szId,
const size_t  iMaxLength 
)

Get the SIP call ID of the call represented by the specified call handle.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szIdBuffer to store the ID. A zero-terminated string will be copied into this buffer on success.
iMaxLengthMax length of the ID buffer
SIPXTAPI_API SIPX_RESULT sipxCallGetInviteHeader ( const SIPX_CALL  hCall,
const char *  headerName,
char *  headerValue,
const size_t  maxValueLength,
bool *  inviteFromRemote,
const size_t  headerInstanceIndex = 0 
)

Get the named header value from the last SIP INVITE request (sent or received) in the context of the given call handle.

Parameters
hCallhandle to a call.
headerName- name of the header field for which the value is to be retrieved (case insensative)
headerValue- SIP header field value retrieved from the INVITE if it exist and this is a SIP call
maxValueLength- maximum number of characters including null terminator that may be set in headerValue
inviteFromRemote- TRUE/FALSE the SIP INVITE was received from the remote end of the call (as opposed to sent by this end)
headerInstanceIndex- some SIP header fields may have multiple instances. This index indicates which instance of the header field of the given name. The first instance has index = 0.
Returns
SIPX_RESULT_SUCCESS if the named header field was found SIPX_RESULT_FAILURE if the INVITE message exists, but the named header was not set in the INVITE SIPX_RESULT_INVALID_STATE if this is not a SIP call or the call has not yet been initiated by an INVITE
SIPXTAPI_API SIPX_RESULT sipxCallGetLine ( const SIPX_CALL  hCall,
SIPX_LINE hLine 
)

Get the line handle for the given call if it has one.

Parameters
hCall- Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
hLine- handle to call for local side of call. Note: not all calls have a line handle. Set to SIPX_LINE_NULL if line handle does not exist for call.
SIPXTAPI_API SIPX_RESULT sipxCallGetLocalID ( const SIPX_CALL  hCall,
char *  szId,
const size_t  iMaxLength 
)

Get the SIP identity of the local connection.

The identity represents either 1) who was called in the case of a inbound call, or 2) the line identity used in an outbound call.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szIdBuffer to store the ID. A zero-terminated string will be copied into this buffer on success.
iMaxLengthMax length of the ID buffer.
SIPXTAPI_API SIPX_RESULT sipxCallGetRemoteContact ( const SIPX_CALL  hCall,
char *  szContact,
const size_t  iMaxLength 
)

Get the SIP remote contact.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szContactBuffer to store the remote contact. A zero-terminated string will be copied into this buffer on success.
iMaxLengthMax length of the remote contact buffer.
SIPXTAPI_API SIPX_RESULT sipxCallGetRemoteID ( const SIPX_CALL  hCall,
char *  szId,
const size_t  iMaxLength 
)

Get the SIP identity of the remote connection.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szIdBuffer to store the ID. A zero-terminated string will be copied into this buffer on success.
iMaxLengthMax length of the ID buffer.
SIPXTAPI_API SIPX_RESULT sipxCallGetRemoteUserAgent ( const SIPX_CALL  hCall,
char *  szAgent,
const size_t  iMaxLength 
)

Get the remote user agent of the call represented by the specified call handle.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szAgentBuffer to store the user agent name. A zero-terminated string will be copied into this buffer on success.
iMaxLengthMax length of the buffer
SIPXTAPI_API SIPX_RESULT sipxCallGetRequestURI ( const SIPX_CALL  hCall,
char *  szUri,
const size_t  iMaxLength 
)

Get the SIP request URI.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szUriBuffer to store the request URI. A zero-terminated string will be copied into this buffer on success.
iMaxLengthMax length of the request URI buffer.
SIPXTAPI_API SIPX_RESULT sipxCallHold ( const SIPX_CALL  hCall,
bool  bStopRemoteAudio = true 
)

Place the specified call on hold.

When placing calls on hold or having a remote party place you on hold the event sequences will differ. In this documentation, we refer to "local" hold and/or "focus" and "remote" and/or "full" hold. A call is on local hold when that call is taken out of focus and is no longer connected to the local microphone and speaker. Remote hold is used to indicate that RTP is no longer flowing between parties. The "bRemoteStopAudio" flags to this method controls whether the party is placed on local hold or full hold. See the table below for expected events:

                    RTP Flowing  RTP Stopped
                    ---------    -----------
        In Focus    CONNECTED    REMOTE_HELD
    Out of Focus     BRIDGED        HELD
*

CONNECTED indicates that both RTP is flowing and the call is attached to the local. This is the normal state for a connected call.

BRIDGED indicates that RTP is flowing, but the call is out of focus. This event is generally caused by holding a conference (conference will bridge by default) or if you accept/place a new call without explicitly holding the active call.

REMOTE_HELD indicates that RTP has stopped flowing. This is generally caused when the remote side places you on hold. The call is still locally in focus and audio will automatically resume once your are take off remote hold.

HELD indicates that both RTP has stopped flowing and the call is out of focus.

Developers can also expect media events (e.g. MEDIA_LOCAL_STOP) whenever RTP is stopped (REMOTE_HELD and HELD). Since media is still flowing for CONNECTED and BRIDGED, no media stop events are sent.

NOTE: If this call is part of a conference, sipxCallHold will only change the remote held state (RTP). You must use sipxConferenceHold to change call focus.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
bStopRemoteAudioFlag which controls whether sipXtapi takes the call out of focus (stops engaging local audio microphone and speaker) or stops sending/receiving audio. Specify true to stop audio (default) or false to take the call out of focus. To play audio or generate tones to a remote connection while on hold, please specify false. This parameter is ignored (and assumed true) if the call is part of a conference.
SIPXTAPI_API SIPX_RESULT sipxCallLimitCodecPreferences ( const SIPX_CALL  hCall,
const SIPX_AUDIO_BANDWIDTH_ID  audioBandwidth,
const SIPX_VIDEO_BANDWIDTH_ID  videoBandwidth,
const char *  szVideoCodecName 
)

Limits the codec preferences on a per-call basis.

This API will force a codec renegotiation with the specified call regardless if the codecs changed. A renegotiation includes sending a new INVITE with an updated SDP list. Local audio will be stopped and restarted during this process, however, hold events are not sent to the application.

NOTE: If a call is on remote hold, it will be taken off remote hold.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
audioBandwidthA bandwidth id to limit audio codecs. Pass in AUDIO_CODEC_BW_DEFAULT to leave audio codecs unchanged.
videoBandwidthA bandwidth id to limit video bitrate and framerate. (see sipxConfigSetVideoBandwidth for an explanation on how bandwidth ids affect bitrate and framerate). Pass in AUDIO_CODEC_BW_DEFAULT to leave these parameters unchanged.
szVideoCodecNameCodec name that limits the supported video codecs to this one video codec.
See also
sipxConfigSetVideoBandwidth
SIPXTAPI_API SIPX_RESULT sipxCallLimitCodecs ( const SIPX_CALL  hCall,
const char *  codecNames 
)

Restrict the set of codecs that are allowed to be used for the given call.

This method does not force signalling to occur. Codecs must be restricted before the offer or answer SDP is sent from this side.

Parameters
hCall- call handle for call on which to restrict codec set
codecNames- space delimited list of codec names. Note: codecNames MUST be a subset of the codecs enabled via sipxConfigSetAudioCodecByName TELEPHONE-EVENT is implicitly included
SIPXTAPI_API SIPX_RESULT sipxCallPlayBufferStart ( const SIPX_CALL  hCall,
const char *  szBuffer,
const int  bufSize,
const int  bufType,
const bool  bRepeat,
const bool  bLocal,
const bool  bRemote 
)

Play the specified audio data.

Currently the only data format that is supported is raw 16 bit signed PCM at 8000 samples/sec, mono, little endian. If a sipxCallDestroy is attempted while an audio buffer is playing, sipxCallDestroy will fail with a SIPX_RESULT_BUSY return code. Call sipxCallPlayBufferStop before making the call to sipxCallDestroy.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. Audio can only be played in the context of a call.
szBufferPointer to the audio data to be played.
bufSizeLength, in bytes, of the audio data.
bufTypeThe audio encoding format for the data as specified by the SIPX_AUDIO_DATA_FORMAT enumerations. Currently only RAW_PCM_16 is supported.
bRepeatTrue if the audio is supposed to be played repeatedly
bLocalTrue if the audio is to be rendered locally.
bRemoteTrue if the audio is to be rendered by the remote endpoint.
SIPXTAPI_API SIPX_RESULT sipxCallPlayBufferStop ( const SIPX_CALL  hCall)

Stop playing the audio started with sipxCallPlayBufferStart If a sipxCallDestroy is attempted while an audio buffer is playing, sipxCallDestroy will fail with a SIPX_RESULT_BUSY return code.

Call sipxCallPlayBufferStop before making the call to sipxCallDestroy.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. Audio can only be played and stopped in the context of a call.
SIPXTAPI_API SIPX_RESULT sipxCallRedirect ( const SIPX_CALL  hCall,
const char *  szForwardURL 
)

Redirect an inbound call (prior to alerting the user).

This method must be invoked before the end user is alerted (before sipxCallAccept). Whenever a new call is received, the application developer should ACCEPT (proceed to ringing), REJECT (send back busy), or REDIRECT the call.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szForwardURLSIP url to forward/redirect the call to.
SIPXTAPI_API SIPX_RESULT sipxCallReject ( const SIPX_CALL  hCall,
const int  errorCode = 400,
const char *  szErrorText = "Bad Request" 
)

Reject an inbound call (prior to alerting the user).

This method must be invoked before the end user is alerted (before sipxCallAccept). Whenever a new call is received, the application developer should ACCEPT (proceed to ringing), REJECT (send back busy), or REDIRECT the call.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
errorCodeRFC specified error code.
szErrorTextnull terminated text string to explain the error code.
SIPXTAPI_API SIPX_RESULT sipxCallResizeWindow ( const SIPX_CALL  hCall,
const SIPX_WINDOW_HANDLE  hWnd 
)

Resizes the video window.

Should be called when the window receives a SIZE message.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
hWndWindow handle of the video window.
SIPXTAPI_API SIPX_RESULT sipxCallSendInfo ( SIPX_INFO phInfo,
const SIPX_CALL  hCall,
const char *  szContentType,
const char *  szContent,
const size_t  nContentLength 
)

Sends an INFO event to the specified call.

This method will fail with an SIPX_RESULT_INVALID_STATE return code if an existing INFO message transaction is still outstanding (sipXtapi has not received a final response to the initial request).

Parameters
phInfoPointer to an INFO message handle, whose value is set by this method.
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
szContentTypeString representation of the INFO content type
szContentPointer to the INFO messasge's content
nContentLengthSize of the INFO content
SIPXTAPI_API SIPX_RESULT sipxCallSetMediaPassThrough ( const SIPX_CALL  hCall,
MEDIA_TYPE  mediaType,
int  mediaTypeStreamIndex,
const char *  streamReceiveAddress,
int  rtpPort,
int  rtcpPort 
)

Set the address and port to which the given media stream is to be recieved.

This is generally used when a separate process is to recieve the media stream.

Parameters
hCall- call handle for the RTP stream
mediaType- audio or video
mediaTypeStreamIndex- connection Id
streamReceiveAddress- IP address on which RTP stream is to be received
rtpPort- RTP port on which to receive stream
rtcpPort- RTCP port on which to recieve stream
SIPXTAPI_API SIPX_RESULT sipxCallSetMicGain ( const SIPX_CALL  hCall,
float  gain 
)

Sets the gain of the microphone for a given call.

This gain is applied digitally inside of the media engine.

Note
Right now this is implemented for sipXmediaLib with Topology enabled only.
Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
gainFloating point gain to apply. Gain should be >0. Internally, inside of a media engine, it may be represented as fixed point value. (values for gain recommended in the 0.001-10.0 range) The default value is 1.0. Clipping may occur for values greater than 1.0. Also
See also
sipxCallHold with the bStopRemoteAudio=false may be useful.
SIPXTAPI_API SIPX_RESULT sipxCallSetMixOutputGain ( const SIPX_CALL  hCall,
int  bridgeOutputIndex,
float  gain 
)

Sets the gain for all inputs to the given bridge output, except for the input of the same index which is set to 0.0f gain.

Parameters
hCall- handle to call using the bridge mixer.
bridgeOutputIndex- output index on the bridge whose input gains are to be set.
gain- new gain value to set for inputs. (values for gain recommended in the 0.001-10.0 range) The default value is 1.0. Clipping may occur for values greater than 1.0
SIPXTAPI_API SIPX_RESULT sipxCallStartTone ( const SIPX_CALL  hCall,
const SIPX_TONE_ID  toneId,
const bool  bLocal,
const bool  bRemote 
)

Play a tone (DTMF, dialtone, ring back, etc) to the local and/or remote party.

See the DTMF_ constants for built-in tones. If a sipxCallDestroy is attempted while a tone is playing, sipxCallDestroy will fail with a SIPX_RESULT_BUSY return code. Call sipxCallStopTone before making the call to sipxConferenceDestroy. DTMF is sent via RFC 2833 method.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
toneIdID of the tone to play
bLocalShould the tone be played locally?
bRemoteShould the tone be played to the remote party?
SIPXTAPI_API SIPX_RESULT sipxCallStopTone ( const SIPX_CALL  hCall)

Stop playing a tone (DTMF, dialtone, ring back, etc).

to local and remote parties. Under a GIPS VoiceEngine build, this method is a NOP – VoiceEngine only plays tones for a specific time interval. If a sipxCallDestroy is attempted while a tone is playing, sipxCallDestroy will fail with a SIPX_RESULT_BUSY return code. Call sipxCallStopTone before making the call to sipxConferenceDestroy.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
SIPXTAPI_API SIPX_RESULT sipxCallSubscribe ( const SIPX_CALL  hCall,
const char *  szEventType,
const char *  szAcceptType,
SIPX_SUB phSub,
bool  bRemoteContactIsGruu = false 
)

Subscribe for NOTIFY events which may be published by the other end-point of the call.

This API differs from sipxConfigSubscribe in that it allows you to use the contact address from the remote party as the subscription target (see the bRemoteContactIsGruu parameter).

sipXtapi will automatically refresh subscriptions until sipxCallUnsubscribe is called. Please make sure you call sipxCallUnsubscribe before tearing down your call.

Parameters
hCallThe call handle of the call associated with the subscription.
szEventTypeA string representing the type of event that can be published. This string is used to populate the "Event" header in the SIP SUBSCRIBE request. For example, if checking voicemail status, your would use "message-summary".
szAcceptTypeA string representing the types of NOTIFY events that this client will accept. This string is used to populate the "Accept" header in the SIP SUBSCRIBE request. For example, if checking voicemail status, you would use "application/simple-message-summary"
phSubPointer to a subscription handle whose value is set by this function. This handle allows you to cancel the subscription and differentiate between NOTIFY events.
bRemoteContactIsGruuindicates whether the Contact for the remote side of the call can be assumed to be a Globally Routable Unique URI (GRUU). Normally one cannot assume that a contact is a GRUU and the To or From address for the remote side is assumed to be an Address Of Record (AOR) that is globally routable.
SIPXTAPI_API SIPX_RESULT sipxCallTransfer ( const SIPX_CALL  hSourceCall,
const SIPX_CALL  hTargetCall 
)

Transfer the source call to the target call.

This method can be used to implement consultative transfer (transfer initiator can speak with the transfer target prior to transferring). If you wish to consult privately, create a new call to the transfer target. If you wish consult and allow the source (transferee) to participant in the conversation, create a conference and then transfer one leg to another.

If not already on hold, the transferee (hSourceCall) is placed on hold as part of the transfer operation.

The event sequence may differ slightly depending on whether the calls are part of a conference (attended transfer) or individual calls (semi- attended transfer).

Assuming the calls are part of a conference and not on hold, the event sequences are as follows:

Transfer Controller (this user agent):

Source Call: CALLSTATE_TRANSFER_EVENT::CALLSTATE_CAUSE_TRANSFER_INITIATED
Source Call: CALLSTATE_REMOTE_HELD
Source Call: MEDIA_LOCAL_STOP
Source Call: MEDIA_REMOTE_STOP
Source Call: CALLSTATE_TRANSFER_EVENT::CALLSTATE_CAUSE_TRANSFER_ACCEPTED
Source Call: CALLSTATE_TRANSFER_EVENT::CALLSTATE_CAUSE_TRANSFER_SUCCESS
Source Call: CALLSTATE_TRANSFER_EVENT::CALLSTATE_DISCONNECTED
Source Call: CALLSTATE_TRANSFER_EVENT::CALLSTATE_DESTROYED

The source call will automatically be disconnected if the transfer is successful. Also, if the source call is part of a conference, the call will automatically be destroyed. If not part of a conference, the application must destroy the call using sipxCallDestroy.

Target Call: CALLSTATE_REMOTE_HELD
Target Call: MEDIA_LOCAL_STOP
Target Call: MEDIA_REMOTE_STOP
Target Call: CALLSTATE_DISCONNECTED
Target Call: CALLSTATE_DESTROYED

The target call is remote held as part of the transfer operation. If the target call is part of a conference, it will automatically be destroyed. Otherwise, the application layer is responsible for calling sipxCallDestroy.

Transferee (user agent on other side of hSourceCall):

The transferee will create a new call to the transfer target and automatically disconnect the original call upon success. The new call will be created with a cause of CALLSTATE_CAUSE_TRANSFER in the SIPX_CALLSTATE_INFO event data. The application layer can look at the hAssociatedCall member to connect the new call to the original call.

Original Call: MEDIA_LOCAL_STOP
Original Call: MEDIA_REMOTE_STOP
Original Call: CALLSTATE_REMOTE_HELD
Original Call: CALLSTATE_HELD
Original Call: CALLSTATE_DISCONNECTED
New Call: CALLSTATE_NEWCALL::CALLSTATE_CAUSE_TRANSFER
New Call: CALLSTATE_REMOTE_OFFERING
New Call: CALLSTATE_CONNECTED
New Call: MEDIA_LOCAL_START
New Call: MEDIA_REMOTE_START

The application is responsible for calling sipxCallDestroy on the original call after the CALLSTATE_DISCONNECT event.

Transfer Target (user agent on other side of hTargetCall):

The transfer target will automatically receive and answer the inbound call from the transferee. After this completes, the original call is disconnected.

CALLSTATE_NEWCALL::CALLSTATE_CAUSE_TRANSFERRED
CALLSTATE_CONNECTED
MEDIA_LOCAL_START
MEDIA_REMOTE_START

Please note that no offering event was fired. The target does not have the option to accept or reject the call. If this call was part of a conference, the new call is automatically added to the same conference.

Parameters
hSourceCallHandle to the source call (transferee).
hTargetCallHandle to the target call (transfer target).
See also
SIPX_CALLSTATE_EVENT
SIPX_CALLSTATE_CAUSE
SIPXTAPI_API SIPX_RESULT sipxCallUnhold ( const SIPX_CALL  hCall)

Take the specified call off hold.

This API will take the call off both local hold and remote/full hold.

See also
sipxCallHold for a description of expected events associated with hold events.
Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
SIPXTAPI_API SIPX_RESULT sipxCallUnsubscribe ( const SIPX_SUB  hSub)

Unsubscribe from previously subscribed NOTIFY events.

This method will send another subscription request with an expires time of 0 (zero) to end your subscription.

Parameters
hSubThe subscription handle obtained from the call to sipxCallSubscribe.
SIPXTAPI_API SIPX_RESULT sipxCallUpdateVideoWindow ( const SIPX_CALL  hCall,
const SIPX_WINDOW_HANDLE  hWnd 
)

Updates the Video window with a new frame buffer.

Should be called when the window receives a PAINT message.

Parameters
hCallHandle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface.
hWndWindow handle of the video preview window.
SIPXTAPI_API SIPX_RESULT sipxConferenceAdd ( const SIPX_CONF  hConf,
const SIPX_LINE  hLine,
const char *  szAddress,
SIPX_CALL phNewCall,
SIPX_CONTACT_ID  contactId = 0,
SIPX_VIDEO_DISPLAY *const  pDisplay = NULL,
SIPX_SECURITY_ATTRIBUTES *const  pSecurity = NULL,
bool  bTakeFocus = true,
SIPX_CALL_OPTIONS options = NULL 
)

Add a new party to an existing conference.

A connection is automatically initiated for the specified address.

Parameters
hConfHandle to a conference. Conference handles are obtained by invoking sipxConferenceCreate.
hLineLine Identity for the outbound call. The line identity helps defines the "From" caller-id. The line identity can't be SIPX_LIINE_NULL, as it's an outbound call.
szAddressSIP URL of the conference participant to add
phNewCallPointer to a call handle to store new call.
contactIdId of the desired contact record to use for this call. The id refers to a Contact Record obtained by a call to sipxConfigGetLocalContacts. The application can choose a contact record of type LOCAL, NAT_MAPPED, CONFIG, or RELAY. The Contact Type allows you to control whether the user agent and media processing advertises the local address (e.g. LOCAL contact of 10.1.1.x or 192.168.x.x), the NAT-derived address to the target party, or, local contact addresses of other types.
pDisplayPointer to an object describing the display object for rendering remote video.
pSecurityPointer to an object describing the security attributes for the call.
bTakeFocusShould SIPxua place the newly answered call in focus (engage local microphone and speaker). In some cases, application developer may want to answer the call in the background and play audio while the user finishes up with their active (in focus) call.
optionsPointer to a SIPX_CALL_OPTIONS structure.
See also
sipxConferenceCreate
sipxConfigSetLocationHeader
sipxConfigGetLocalContacts
sipxConfigSetAudioCodecPreferences
SIPXTAPI_API SIPX_RESULT sipxConferenceCreate ( const SIPX_INST  hInst,
SIPX_CONF phConference 
)

Create a conference handle.

Conferences are an association of calls where the audio media is mixed. sipXtapi supports conferences up to 4 (CONF_MAX_CONNECTIONS) parties in its default configuration.

Parameters
hInstInstance pointer obtained by sipxInitialize.
phConferencePointer to a conference handle. Upon success, this value is replaced with a valid conference handle. Success is determined by the SIPX_RESULT result code.
SIPXTAPI_API SIPX_RESULT sipxConferenceDestroy ( SIPX_CONF  hConf)

Destroys a conference.

All participants within a conference are dropped.

Parameters
hConfHandle to a conference. Conference handles are obtained by invoking sipxConferenceCreate.
SIPXTAPI_API SIPX_RESULT sipxConferenceGetCalls ( const SIPX_CONF  hConf,
SIPX_CALL  calls[],
const size_t  iMax,
size_t &  nActual 
)

Gets all of the calls participating in a conference.

Parameters
hConfHandle to a conference. Conference handles are obtained by invoking sipxConferenceCreate.
callsAn array of call handles filled in by the API.
iMaxThe maximum number of call handles to return.
nActualThe actual number of call handles returned.
SIPXTAPI_API SIPX_RESULT sipxConferenceGetEnergyLevels ( const SIPX_CONF  hConf,
int &  iInputEnergyLevel,
int &  iOutputEnergyLevel 
)

Gets energy levels for a conference.

The conference must be in the connected state (not held or bridged) for this request to succeed.

This API is only supported when sipXtapi is bundled with VoiceEngine from GIPS.

Parameters
hConfHandle to a conference. Conference handles are obtained by invoking sipxConferenceCreate.
iInputEnergyLevelInput/Microphone energy level ranging from 0 to 9.
iOutputEnergyLevelOutput/Speaker energy level ranging from 0 to 9. The output energy level is post-mixed (after mixing all files/tones and other parties. sipxCallGetEnergyLevel provides an API to obtain pre-mixed energy levels.
SIPXTAPI_API SIPX_RESULT sipxConferenceHold ( const SIPX_CONF  hConf,
bool  bBridging = true 
)

Places a conference on hold.

This API can be used to place a conference on local hold (continue to bridge participants) or full hold (remaining participants cannot talk to each other). The default is local hold/bridged. The bBridged flag can be used to change this behavior (false for full hold).

Developers may also hold/unhold individual conference participants by calling sipxCallHold and sipxCallUnhold on individual call handles. The sipxConferenceGetCalls API can be used to enumerate conference participants.

See also
sipxCallHold for a description of the expected events.
Parameters
hConfHandle to a conference. Conference handles are obtained by invoking sipxConferenceCreate.
bBridgingtrue for a bridging conference hold, false for a non-bridging conference hold.
SIPXTAPI_API SIPX_RESULT sipxConferenceJoin ( const SIPX_CONF  hConf,
const SIPX_CALL  hCall 
)

Join (add) an existing held call into a conference.

An existing call can be added to a virgin conference without restriction. Additional calls, must be connected and on remote hold for this operation to succeed. A remote hold can be accomplished by calling sipxCallHold on the joining party. The application layer must wait for the CALLSTATE_HELD event prior to calling join. No events are fired as part of the operation and the newly joined call is left on hold. The application layer should call sipxCallUnhold on the new participant to finalize the join.

Parameters
hConfConference handle obtained by calling sipxConferenceCreate.
hCallCall handle of the call to join into the conference.
SIPXTAPI_API SIPX_RESULT sipxConferenceLimitCodecPreferences ( const SIPX_CONF  hConf,
const SIPX_AUDIO_BANDWIDTH_ID  audioBandwidth,
const SIPX_VIDEO_BANDWIDTH_ID  videoBandwidth,
const char *  szVideoCodecName 
)

Limits the codec preferences on a conference.

This API will force a codec renegotiation with the specified calls regardless if the codecs changed. A renegotiation includes sending a new INVITE with an updated SDP list. Local audio will be stopped and restarted during this process, however, hold events are not sent to the application.

NOTE: If any calls are on remote hold, they will be taken off hold.

Parameters
hConfHandle to a conference. Conference handles are obtained by invoking sipxConferenceCreate.
audioBandwidthA bandwidth id to limit audio codecs. Pass in AUDIO_CODEC_BW_DEFAULT to leave audio codecs unchanged.
videoBandwidthA bandwidth id to limit video bitrate and framerate. (see sipxConfigSetVideoBandwidth for an explanation on how bandwidth ids affect bitrate and framerate). Pass in AUDIO_CODEC_BW_DEFAULT to leave these parameters unchanged.
szVideoCodecNameCodec name that limits the supported video codecs to this one video codec.
See also
sipxConfigSetVideoBandwidth
SIPXTAPI_API SIPX_RESULT sipxConferencePlayAudioFileStart ( const SIPX_CONF  hConf,
const char *  szFile,
const bool  bRepeat,
const bool  bLocal,
const bool  bRemote,
const bool  bMixWithMicrophone = false,
const float  fVolumeScaling = 1.0 
)

Play the designated audio file to all conference participants and/or the local speaker.

The file may be a raw 16 bit signed PCM at 8000 samples/sec, mono, little endian or a .WAV file. If a sipxConferenceDestroy is attempted while an audio file is playing, sipxConferenceDestroy will fail with a SIPX_RESULT_BUSY return code. Call sipxConferencePlayAudioFileStop before making the call to sipxConferenceDestroy.

Parameters
hConfConference handle obtained by calling sipxConferenceCreate.
szFileFilename for the audio file to be played.
bRepeatTrue if the file is supposed to be played repeatedly
bLocalTrue if the audio file is to be rendered locally.
bRemoteTrue if the audio file is to be rendered by the remote endpoint.
bMixWithMicrophoneTrue to mix the audio with the microphone data or false to replace it. This option is only supported when sipXtapi is bundled with GIPS VoiceEngine.
fVolumeScalingVolume down scaling for the audio file. Valid values are between 0 and 1.0, where 1.0 is the no down-scaling. This option is only supported when sipXtapi is bundled with GIPS VoiceEngine.
SIPXTAPI_API SIPX_RESULT sipxConferencePlayAudioFileStop ( const SIPX_CONF  hConf)
SIPXTAPI_API SIPX_RESULT sipxConferenceRemove ( const SIPX_CONF  hConf,
const SIPX_CALL  hCall 
)

Removes a participant from conference by hanging up on them.

Parameters
hConfHandle to a conference. Conference handles are obtained by invoking sipxConferenceCreate.
hCallCall handle identifying which call to remove from the conference by hanging up.
SIPXTAPI_API SIPX_RESULT sipxConferenceSplit ( const SIPX_CONF  hConf,
const SIPX_CALL  hCall 
)

Split (remove) a held call from a conference.

This method will remove the specified call from the conference.

The call must be connected and on remote hold for this operation to succeed. A remote hold can be accomplished by calling sipxCallHold on the conference participant or by placing the entire conference on hold with bridging disabled. The application layer must wait for the CALLSTATE_HELD event prior to calling split. No events are fired as part of the operation and the split call is left on hold.

Parameters
hConfHandle to a conference. Conference handles are obtained by invoking sipxConferenceCreate.
hCallCall handle of the call that should be removed from the the conference.
SIPXTAPI_API SIPX_RESULT sipxConferenceUnhold ( const SIPX_CONF  hConf)

Removes conference members from a held state.

This method will take a call off either local or remote/full hold.

See also
sipxConferenceHold for details on holding conferences.
sipxCallHold for a description of the expected events.
Parameters
hConfHandle to a conference. Conference handles are obtained by invoking sipxConferenceCreate.
SIPXTAPI_API SIPX_RESULT sipxConfigAddContact ( const SIPX_INST  hInst,
const char *  szSipContactAddress,
const int  iSipContactPort,
SIPX_CONTACT_ID iNewContactId 
)

Add a contact using the given IP address and port.

This can be used for IP address spoofing in the SIP Contact and SDP/RTP c address.

Parameters
szSipContactAddress- IP address to use in SIP Contact in initial REGISTER and INVITE requests as well as the c field in the SDP.
iSipContactPort- port to use in the SIP Contact headers.
iNewContactId- contactId to use to specify this contact should be used (see , , ).
SIPXTAPI_API SIPX_RESULT sipxConfigDisableIce ( const SIPX_INST  hInst)

Disable the use of ICE.

See sipxConfigEnableICE for details.

Parameters
hInstInstance pointer obtained by sipxInitialize.
SIPXTAPI_API SIPX_RESULT sipxConfigDisableStun ( const SIPX_INST  hInst)

Disable the use of STUN.

See sipxConfigEnableStun for details on STUN.

Parameters
hInstInstance pointer obtained by sipxInitialize.
SIPXTAPI_API SIPX_RESULT sipxConfigDisableTurn ( const SIPX_INST  hInst)

Disable the use of TURN.

See sipxConfigEnableTurn for details TURN.

Parameters
hInstInstance pointer obtained by sipxInitialize.
SIPXTAPI_API SIPX_RESULT sipxConfigEnableDnsSrv ( const bool  bEnable)

Enables/disables sending of DNS SRV request for all sipXtapi instances.

DNS SRV is enabled by default.

Parameters
bEnableEnable or disable DNS SRV resolution.
SIPXTAPI_API SIPX_RESULT sipxConfigEnableGIPSTracing ( SIPX_INST  hInst,
bool  bEnable 
)

Enables GIPS tracing in sipXtapi (if bundled with sipXtapi).

Log entries are under the facility "VIDEOENGINE" and "VOICEENGINE" and are Base64 encoded (to avoid issues with binary data.

NOTE: Tracing must be enabled prior to setting up a call.

Parameters
hInstInstance pointer obtained by sipxInitialize.
bEnabletrue to enable GIPS tracing or false to disable.
SIPXTAPI_API SIPX_RESULT sipxConfigEnableIce ( const SIPX_INST  hInst)

Enables an ICE-like mechanism for determining connectivity of remote parties dynamically.

By default, ICE is disabled.

The current sipXtapi implementation is a bastardization of draft-ietf-mmusic-ice-04. In subsequent release, this will conform to draft-ietf-mmusic-ice-05 or the latest draft.

SIPXTAPI_API SIPX_RESULT sipxConfigEnableInBandDTMF ( const SIPX_INST  hInst,
const bool  bEnable 
)

Enable/disable sending of in-band DTMF tones.

In-band DTMF is disabled by default.

This function is currently not implemented.

Parameters
hInstInstance pointer obtained by sipxInitialize
bEnableEnable or disable in-band DTMF tones.
SIPXTAPI_API SIPX_RESULT sipxConfigEnableOutOfBandDTMF ( const SIPX_INST  hInst,
const bool  bEnable 
)

Enable/disable sending of RFC 2833 DTMF tones.

If disabled the tones will be sent in-band (if in-band DTMF is enabled). RFC 2833 DTMF is enabled by default.

Generally, out-of-band DTMF should always be enabled. In-band DTMF can be distorted and unrecognized by gateways/IVRs/ACDs when using compressed codecs such as G729. By nature, many compressed codecs are lossy and cannot regenerate DTMF signals. If you find that you need to disable out-of-band DTMF (due to duplicate DTMF signals) on another device, please consider reconfiguring that other device.

This function is currently not implemented.

Parameters
hInstInstance pointer obtained by sipxInitialize
bEnableEnable or disable out-of-band DTMF tones.
SIPXTAPI_API SIPX_RESULT sipxConfigEnableRport ( const SIPX_INST  hInst,
const bool  bEnable 
)

Enable or disable the use of "rport".

If rport is included on a via, responses should be sent back to the originating port – not what is advertised as part of via. Additionally, the sip stack will not receive messages sent to the originating port unless this is enabled.

Parameters
hInstInstance pointer obtained by sipxInitialize.
bEnableEnable or disable the use of rport.
SIPXTAPI_API SIPX_RESULT sipxConfigEnableRportMapping ( const SIPX_INST  hInst,
const bool  bEnable 
)

Enable or diable the use of IP and port provided in the response via (rport) for mapping of NAT/public IP address and port in the contact database.

By default rport mapping is enabled.

Parameters
bEnable- true/false if IP address and port provided via rport should be used for contact database NAT address mapping.
SIPXTAPI_API SIPX_RESULT sipxConfigEnableRTCP ( const SIPX_INST  hInst,
const bool  bEnable 
)

Enable or disable sending RTCP reports.

By default, RTCP is enabled and sends reports every ~5 seconds. RTCP is enabled by default.

Parameters
hInstInstance pointer obtained by sipxInitialize
bEnableEnable or disable sending of RTCP reports.
SIPXTAPI_API SIPX_RESULT sipxConfigEnableRtpOverTcp ( const SIPX_INST  hInst,
bool  bEnable 
)

Enables RTP streaming over TCP.

Enabling this feature allows the application to use RTP streaming over TCP or UDP.

Parameters
hInstInstance pointer obtained by sipxInitialize
bEnableTrue allows RTP-over-TCP, false disallows it.
SIPXTAPI_API SIPX_RESULT sipxConfigEnableSipAllowHeader ( const SIPX_INST  hInst,
const bool  bEnabled 
)

Enables/Disables use of allow header in sip messages.

Parameters
hInstInstance pointer obtained by sipxInitialize
bEnabledTrue if allow header, false if no allow header
SIPXTAPI_API SIPX_RESULT sipxConfigEnableSipDateHeader ( const SIPX_INST  hInst,
const bool  bEnabled 
)

Enables/Disables use of date header in sip messages.

Parameters
hInstInstance pointer obtained by sipxInitialize
bEnabledTrue if date header, false if no date header
SIPXTAPI_API SIPX_RESULT sipxConfigEnableSipShortNames ( const SIPX_INST  hInst,
const bool  bEnabled 
)

Enables/Disables use of short field names in sip messages.

Parameters
hInstInstance pointer obtained by sipxInitialize
bEnabledTrue if short names, false if long names
SIPXTAPI_API SIPX_RESULT sipxConfigEnableStun ( const SIPX_INST  hInst,
const char *  szServer,
int  iServerPort,
int  iKeepAliveInSecs 
)

Enables STUN (Simple Traversal of UDP through NAT) support for both UDP SIP signaling and UDP audio/video (RTP).

STUN helps user agents determine thier external IP address from the inside of NAT/Firewall. This method should be invoked immediately after calling sipxInitialize and before creating any lines or calls. Enabling STUN while calls are setup should not effect the media path of existing calls. The "contact" address uses for UDP signaling may change on the next request.

TODO :: STUN conforms to IETF RFC/DRAFT XXXX with the following exceptions:

Parameters
hInstInstance pointer obtained by sipxInitialize
szServerThe stun server that should be used for discovery.
iServerPortThe port of the stun server that should be used for discovery.
iKeepAliveInSecsThis setting controls how often to refresh the stun binding. The most aggressive NAT/Firewall solutions free port mappings after 30 seconds of non-use. We recommend a value of 28 seconds to be safe.
SIPXTAPI_API SIPX_RESULT sipxConfigEnableTurn ( const SIPX_INST  hInst,
const char *  szServer,
const int  iServerPort,
const char *  szUsername,
const char *  szPassword,
const int  iKeepAliveInSecs 
)

Enable TURN for support for UDP audio/video (RTP).

TURN allows VoIP communications while operating behind a symmetric NAT or firewall (cannot only receive data from the same IP/port that you have sent to).

This implementation is based on draft-rosenberg-midcom-turn-04.

Parameters
hInstInstance pointer obtained by sipxInitialize.
szServerThe TURN server that should be used for relaying.
iServerPortThe TURN sever port that should be used for relaying
szUsernameTURN username for authentication
szPasswordTURN password for authentication
iKeepAliveInSecsThis setting controls how often to refresh the TURN binding. The recommended value is 28 seconds.
SIPXTAPI_API SIPX_RESULT sipxConfigExternalTransportAdd ( SIPX_INST const  hInst,
SIPX_TRANSPORT hTransport,
const bool  bIsReliable,
const char *  szTransport,
const char *  szLocalIP,
const int  iLocalPort,
SIPX_TRANSPORT_WRITE_PROC  writeProc,
const char *  szLocalRoutingId,
const void *  pUserData = NULL 
)

Associates an external transport mechanism for SIP signaling with the given instance.

Parameters
hInstAn instance handle obtained from sipxInitialize.
hTransportReference to a SIPX_TRANSPORT handle. This function will assign a value to the referenced handle.
bIsReliableIf false, indicates that SIPxua should retry external transport writes in case of response timeouts. If true, SIPxua will not attempt retries in case of a response timeouts. For connection oriented transport (like TCP), bIsReliable should be true, for packet oriented transport (like UDP), bIsReliable should be false.
szTransportTransport type string to be used in SIP URIs. For example, passing in a szTransport of "flibble" will cause the transport tag to be added to the URI like so: "sip:mickey\@example.com;transport=flibble"
szLocalIPIP address which is the source address for the write.
iLocalPortPort value from which the data will be sent.
writeProcFunction pointer to the callback for writing data using the transport mechanism.
szLocalRoutingIdA local routing id pass back to the write proc callback.
pUserDataUser data passed back to the write proc.
SIPXTAPI_API SIPX_RESULT sipxConfigExternalTransportHandleMessage ( const SIPX_TRANSPORT  hTransport,
const char *  szSourceIP,
const int  iSourcePort,
const char *  szLocalIP,
const int  iLocalPort,
const void *  pData,
const size_t  nData 
)

Called by the application when it receives a complete SIP message via it's external transport mechanism and want to pass it along to sipXtapi.

The application is responsible for preparing the Data so that it is composed of a single and complete SIP message.

Parameters
hTransportHandle to the external transport object. Obtained via a call to sipxConfigExternalTransportAdd
szSourceIPIP address which was the source of the data which was read.
iSourcePortPort value from which the data was sent.
szLocalIPLocal IP address on which the data was received.
iLocalPortLocal port value on which the data was received.
pDataPointer to the data which was received, which should point to a single and complete SIP message.
nDataSize of the data which was received.
SIPXTAPI_API SIPX_RESULT sipxConfigExternalTransportRemove ( const SIPX_TRANSPORT  hTransport)

Removes an external transport mechanism from the given instance.

Will fail if transport in use.

Parameters
hTransportHandle to the external transport object. Obtained via a call to sipxConfigExternalTransportAdd
SIPXTAPI_API SIPX_RESULT sipxConfigExternalTransportRouteByUser ( const SIPX_TRANSPORT  hTransport,
bool  bRouteByUser 
)

The external transport mechanism can be configured to route by user or by destination ip/port.

User is the default.

Parameters
hTransportHandle to the external transport object. Obtained via a call to sipxConfigExternalTransportAdd
bRouteByUsertrue to route by user (default), false to route by destination ip/port.
SIPXTAPI_API SIPX_RESULT sipxConfigGetAllLocalNetworkIps ( const char *  arrAddresses[],
const char *  arrAddressAdapter[],
int &  numAddresses 
)

Populates an array of IP Addresses in char* form.

The array must be preallocated to contain MAX_IP_ADDRESSES elements.

WARNING: THIS API IS DEPRECATED AND WILL CHANGE IN FUTURE REVISIONS

Parameters
arrAddressesPre-allocated array to be popluated with ip addresses.
arrAddressAdapterFor each record in arrAddresses, there is a corresponding record, with the same index, in arrAddressAdpater which represents the "sipx adapter name" for that address
numAddressesInput: Size of the preallocated arrays. Output: Number of IPs found by the system.
SIPXTAPI_API SIPX_RESULT sipxConfigGetAudioCodec ( const SIPX_INST  hInst,
const int  index,
SIPX_AUDIO_CODEC pCodec 
)

Get the audio codec at a certain index in the list of codecs.

Use this function in conjunction with sipxConfigGetNumAudioCodecs to enumerate the list of audio codecs. This method will return SIPX_RESULT_SUCCESS if able to set the audio codec preferences. SIPX_RESULT_FAILURE is returned if the audio codec can not be retrieved.

Parameters
hInstInstance pointer obtained by sipxInitialize
indexIndex in the list of codecs
pCodecSIPX_AUDIO_CODEC structure that holds information (name, bandwidth requirement) about the codec.
SIPXTAPI_API SIPX_RESULT sipxConfigGetAudioCodecPreferences ( const SIPX_INST  hInst,
SIPX_AUDIO_BANDWIDTH_ID pBandWidth 
)

Get the current codec preference.

Parameters
hInstInstance pointer obtained by sipxInitialize
pBandWidthpointer to an integer that will contain AUDIO_CODEC_BW_LOW, AUDIO_CODEC_BW_NORMAL, or AUDIO_CODEC_BW_HIGH. AUDIO_CODEC_BW_CUSTOM will be returned if a specific codec was et using the sipxConfigSetAudioCodecByName function.
SIPXTAPI_API SIPX_RESULT sipxConfigGetLocalContacts ( const SIPX_INST  hInst,
SIPX_CONTACT_ADDRESS  addresses[],
size_t  nMaxAddresses,
size_t &  nActualAddresses 
)

Get the local contact address available for outbound/inbound signaling and audio.

The local contact addresses will always include the local IP addresses. The local contact addresses may also include external NAT- derived addresses (e.g. STUN). See the definition of SIPX_CONTACT_ADDRESS for more details on the structure.

Determining which contact address to use depends on your network topology. If you have a proxy/edge proxy within the same firewall/NAT space, you can use the LOCAL UDP, TCP, or TLS contact type for your calls. If your proxy resides outside of the firewall/NAT space, you should use the NAT_MAPPED or RELAY contact type (UDP only). Both NAT_MAPPED and RELAY use your STUN-derived IP address, however RELAY requests TURN for media paths.

Parameters
hInstInstance pointer obtained by sipxInitialize
addressesA pre-allocated list of SIPX_CONTACT_ADDRESS structures. This data will be filled in by the API call.
nMaxAddressesThe maximum number of addresses supplied by the addresses parameter.
nActualAddressesThe actual number of addresses populated in the addresses parameter.
SIPXTAPI_API SIPX_RESULT sipxConfigGetLocalFeedbackAddress ( const SIPX_INST  hInst,
const char *  szRemoteIp,
const int  iRemotePort,
char *  szContactIp,
size_t  nContactIpLength,
int &  iContactPort,
int  iTimeoutMs 
)

Get our local ip/port combination for the designated remote ip/port.

This API will look at all of the stun and/or SIP message results to see if a NAT binding exists for this particular host. If using a proxy server, this is generally never needed, however, in peer-to-peer modes this can sometimes help you get through NATs when using out-of-band registrars / signaling helpers (not recommended – use a proxy instead).

For this API to be useful, you need to add a keepalive to the remote host prior to calling this API. This may optionally block if a keep-alive request has been started, but we are waiting for a response.

Parameters
hInstInstance pointer obtained by sipxInitialize
szRemoteIpIP of remote party
iRemotePortport or remote party
szContactIpBuffer to place local contact IP if successful
nContactIpLengthLength of szContactIp buffer
iContactPortInt to place contact port
iTimeoutMsTimeout in MS. Values of 0 (or less) signal not to block. Any other value is rounded up to multiple of 50ms. For VoIP, a value of 500ms seems plenty (latency longer than 300ms will result in a fairly bad audio experience).
SIPXTAPI_API SIPX_RESULT sipxConfigGetLocalSipTcpPort ( SIPX_INST  hInst,
int *  pPort 
)

Get the local TCP port for SIP signaling.

The port is supplied in the call to sipXinitialize; however, the port may be allocated dynamically. This method will return SIPX_RESULT_SUCCESS if able to return the port value. SIPX_RESULT_FAILURE is returned if the protocol is not enabled.

Parameters
hInstInstance pointer obtained by sipxInitialize
pPortPointer to a port number. This value must not be NULL.
SIPXTAPI_API SIPX_RESULT sipxConfigGetLocalSipTlsPort ( SIPX_INST  hInst,
int *  pPort 
)

Get the local TLS port for SIP signaling.

The port is supplied in the call to sipXinitialize; however, the port may be allocated dynamically. This method will return SIPX_RESULT_SUCCESS if able to return the port value. SIPX_RESULT_FAILURE is returned if the protocol is not enabled.

Parameters
hInstInstance pointer obtained by sipxInitialize
pPortPointer to a port number. This value must not be NULL.
SIPXTAPI_API SIPX_RESULT sipxConfigGetLocalSipUdpPort ( SIPX_INST  hInst,
int *  pPort 
)

Get the local UDP port for SIP signaling.

The port is supplied in the call to sipXinitialize; however, the port may be allocated dynamically. This method will return SIPX_RESULT_SUCCESS if able to return the port value. SIPX_RESULT_FAILURE is returned if the protocol is not enabled.

Parameters
hInstInstance pointer obtained by sipxInitialize
pPortPointer to a port number. This value must not be NULL.
SIPXTAPI_API SIPX_RESULT sipxConfigGetNumAudioCodecs ( const SIPX_INST  hInst,
int *  pNumCodecs 
)

Get the number of audio codecs.

This method will return SIPX_RESULT_SUCCESS if able to set the audio codec preferences. SIPX_RESULT_FAILURE is returned if the number of codecs can no be retrieved.

Parameters
hInstInstance pointer obtained by sipxInitialize
pNumCodecsPointer to the number of codecs. This value must not be NULL.
SIPXTAPI_API SIPX_RESULT sipxConfigGetNumVideoCodecs ( const SIPX_INST  hInst,
int *  pNumCodecs 
)

Get the number of video codecs.

This method will return SIPX_RESULT_SUCCESS if able to set the audio codec preferences. SIPX_RESULT_FAILURE is returned if the number of codecs can no be retrieved.

Parameters
hInstInstance pointer obtained by sipxInitialize
pNumCodecsPointer to the number of codecs. This value must not be NULL.
SIPXTAPI_API SIPX_RESULT sipxConfigGetVersion ( char *  szVersion,
const size_t  nBuffer 
)

Get the sipXtapi API version string.

Parameters
szVersionBuffer to store the version string. A zero-terminated string will be copied into this buffer on success.
nBufferSize of szBuffer in bytes (not to exceed). A size of 48 bytes should be sufficient in most cases.
SIPXTAPI_API SIPX_RESULT sipxConfigGetVideoCaptureDevice ( const SIPX_INST  hInst,
char *  szCaptureDevice,
int  nLength 
)

Gets the current video capture device.

Parameters
hInstInstance pointer obtained by sipxInitialize
szCaptureDeviceCharacter array to be populated by this function call.
nLengthMax length of szCaptureDevice buffer.
SIPXTAPI_API SIPX_RESULT sipxConfigGetVideoCaptureDevices ( const SIPX_INST  hInst,
char **  arrSzCaptureDevices,
int  nDeviceStringLength,
int  nArrayLength 
)

Gets the list of video capture devices.

Parameters
hInstInstance pointer obtained by sipxInitialize
arrSzCaptureDevicesArray of character arrays to be populated by this function call.
nDeviceStringLengthLength of buffer in arrSzCaptureDevice array.
nArrayLengthNumber of strings (of length nDeviceStringLength) in the arrSzCaptureDevice array.
SIPXTAPI_API SIPX_RESULT sipxConfigGetVideoCodec ( const SIPX_INST  hInst,
const int  index,
SIPX_VIDEO_CODEC pCodec 
)

Get the video codec at a certain index in the list of codecs.

Use this function in conjunction with sipxConfigGetNumVideoCodecs to enumerate the list of video codecs. This method will return SIPX_RESULT_SUCCESS if able to set the video codec preferences. SIPX_RESULT_FAILURE is returned if the video codec can not be retrieved.

Parameters
hInstInstance pointer obtained by sipxInitialize
indexIndex in the list of codecs
pCodecSIPX_VIDEO_CODEC structure that holds information (name, bandwidth requirement) about the codec.
SIPXTAPI_API SIPX_RESULT sipxConfigGetVideoCodecPreferences ( const SIPX_INST  hInst,
SIPX_VIDEO_BANDWIDTH_ID pBandWidth 
)

Get the current codec preference.

Parameters
hInstInstance pointer obtained by sipxInitialize
pBandWidthpointer to an integer that will contain AUDIO_CODEC_BW_LOW, AUDIO_CODEC_BW_NORMAL, or AUDIO_CODEC_BW_HIGH. AUDIO_CODEC_BW_CUSTOM will be returned if a specific codec was set using the sipxConfigSetVideoCodecByName function.
SIPXTAPI_API SIPX_RESULT sipxConfigIsInBandDTMFEnabled ( const SIPX_INST  hInst,
bool &  bEnable 
)

Determines if sending of in-band DTMF tones is enabled or disabled.

Parameters
hInstInstance pointer obtained by sipxInitialize
bEnablein-band DTMF tones enabled or disabled.
SIPXTAPI_API SIPX_RESULT sipxConfigIsOutOfBandDTMFEnabled ( const SIPX_INST  hInst,
bool &  bEnable 
)

Determines if sending of out-of-band DTMF tones is enabled or disabled.

Parameters
hInstInstance pointer obtained by sipxInitialize
bEnableOut-of-band DTMF tones enabled or disabled.
SIPXTAPI_API SIPX_RESULT sipxConfigKeepAliveAdd ( const SIPX_INST  hInst,
SIPX_CONTACT_ID  contactId,
SIPX_KEEPALIVE_TYPE  type,
const char *  remoteIp,
int  remotePort,
int  keepAliveSecs 
)

Add a signaling keep alive to a remote ip address.

Parameters
hInstInstance pointer obtained by sipxInitialize
contactIdContact ID used for the keep alive. sipXtapi will send keep alives from the interface identified by the contactId. Specify a contactId of -1 to send keep alives from all interfaces.
typeDesignates the method of keep alives.
remoteIpRemote IP address used to send keep alives. The caller is responsible for converting hostnames to IP address.
remotePortRemote port used to send keep alives.
keepAliveSecsThe number of seconds to wait before resending. If the value is <= 0, only one keep alive will be sent (calling sipxConfigKeepAliveRemove will fail).
See also
sipxConfigGetLocalContacts
SIPXTAPI_API SIPX_RESULT sipxConfigKeepAliveRemove ( const SIPX_INST  hInst,
SIPX_CONTACT_ID  contactId,
SIPX_KEEPALIVE_TYPE  type,
const char *  remoteIp,
int  remotePort 
)

Remove a signaling keepalive.

Parameters
hInstInstance pointer obtained by sipxInitialize
contactIdContact ID used for the keep alive. sipXtapi will remove keep alives from the interface identified by the contactId. Specify a contactId of -1 to remove keep alives from all interfaces.
typeDesignates the method of keep alives.
remoteIpRemote IP address used to send keep alives. The caller is responsible for converting hostnames to IP address. This value must match what was specified in sipxConfigKeepAliveAdd.
remotePortRemote port used to send keep alives.
See also
sipxConfigGetLocalContacts
SIPXTAPI_API SIPX_RESULT sipxConfigPrepareToHibernate ( const SIPX_INST  hInst)

Call this function to prepare a sipXtapi instance for a system hibernation.

This function is not thread-safe.

Parameters
hInstInstance pointer obtained by sipxInitialize
SIPXTAPI_API SIPX_RESULT sipxConfigResetVideoCodecs ( const SIPX_INST  hInst)

Reset the codec list if it was modified by sipxConfigSetVideoCodecByName.

This resets the selection to a full codec list. This method will return SIPX_RESULT_SUCCESS if able to set the audio codec. SIPX_RESULT_FAILURE is returned if the codec is not set.

Parameters
hInstInstance pointer obtained by sipxInitialize
SIPXTAPI_API SIPX_RESULT sipxConfigSetAudioCodecByName ( const SIPX_INST  hInst,
const char *  szCodecName 
)

Set the codec preference order by name.

The codec name(s) must match one of the supported codecs otherwise this function will fail. This method will return SIPX_RESULT_SUCCESS if able to set the audio codec. SIPX_RESULT_FAILURE is returned if the codec is not set.

Parameters
hInstInstance pointer obtained by sipxInitialize
szCodecNamespace delimited list of codec names. Note: TELEPHONE-EVENT is implicitly included
SIPXTAPI_API SIPX_RESULT sipxConfigSetAudioCodecPreferences ( const SIPX_INST  hInst,
SIPX_AUDIO_BANDWIDTH_ID  bandWidth 
)

Set the preferred bandwidth requirement for codec selection.

Whenever possible a codec matching that requirement will be selected for a call. This method will return SIPX_RESULT_SUCCESS if able to set the audio codec preferences. SIPX_RESULT_FAILURE is returned if the preference is not set.

Parameters
hInstInstance pointer obtained by sipxInitialize
bandWidthValid bandwidth requirements are AUDIO_CODEC_BW_LOW, AUDIO_CODEC_BW_NORMAL, and AUDIO_CODEC_BW_HIGH.
SIPXTAPI_API SIPX_RESULT sipxConfigSetConnectionIdleTimeout ( const SIPX_INST  hInst,
const int  idleTimeout 
)

Set the connection idle timeout.

If a media connection is idle for this threshold, a SILENCE event will be fired to the application layer.

Applications may decide to tear down the call after receiving this event under the assumption that the remote party is gone away. Be careful when using codecs that support silence suppression – Some implementations continue to send RTP heartbeats, however, others will not send any data and may appear to be dead.

Parameters
hInstInstance pointer obtained by sipxInitialize
idleTimeoutThe time in seconds that a socket is idle before a MEDIA_REMOTE_SILENT event is fired.
SIPXTAPI_API SIPX_RESULT sipxConfigSetDnsSrvFailoverTimeout ( const SIPX_INST  hInst,
const int  failoverTimeoutInSecs 
)

Specifies the time to wait before trying the next DNS SRV record.

The user agent will attempt to obtain DNS SRV resolutions for the child DNS SRV records. This setting is the time allowed for attempting a lookup - if the time expires without a lookup, then next child is attempted.

Parameters
hInstInstance pointer obtained by sipxInitialize.
failoverTimeoutInSecsNumber of seconds until the next DNS SRV record is tried.
SIPXTAPI_API SIPX_RESULT sipxConfigSetDnsSrvTimeouts ( const int  initialTimeoutInSecs,
const int  retries 
)

Modifies the timeout values used for DNS SRV lookups.

In generally, you shouldn't need to modified these, however, if you find yourself in a situation where a router/network fails to send responses to DNS SRV requests these values can be tweaked. Note, failing to send responses is different then a receiving an no-such-animal response.

The default values are initialTimeout = 5 seconds, and 4 retries. The time waited is doubled after each timeout, so with the default settings, a single DNS SRV can block for 75 seconds (5 + 10 + 20 + 40). In general, 4 DNS SRV requests are made for each hostname (e.g. domain.com):

  • _sip._udp.domain.com
  • _sip._tcp.domain.com
  • _sip._udp.domain.com.domain.com
  • _sip._tcp.domain.com.domain.com

If DNS response are dropped in the network (or your DNS server is down), the API will block for 3 minutes.

SIPXTAPI_API SIPX_RESULT sipxConfigSetEnergyLevelNotificationPeriod ( const SIPX_INST  hInst,
int  periodMs 
)
SIPXTAPI_API SIPX_RESULT sipxConfigSetLocationHeader ( const SIPX_INST  hInst,
const char *  szHeader 
)

Sets the location header for SIP messages.

The location header will be included in SIP requests and responses. You can disable the location header on a call-by-call basis in the by changing the bEnableLocationHeader flag on sipxCallAccept, sipxCallConnect, and sipxConferenceAdd methods.

Parameters
hInstInstance pointer obtained by sipxInitialize
szHeader- Location header
See also
sipxCallAccept
sipxCallConnect
sipxConferenceAdd
SIPXTAPI_API SIPX_RESULT sipxConfigSetLogCallback ( sipxLogCallback  pCallback)

Set a callback function to collect logging information.

This function directs logging output to the specified function.

Parameters
pCallbackis a pointer to a callback function. This callback function gets passed three strings, first string is the priority level, second string is the source id of the subsystem that generated the message, and the third string is the message itself.
SIPXTAPI_API SIPX_RESULT sipxConfigSetLogFile ( const char *  szFilename)

The sipxConfigSetlogFile method sets the filename of the log file and directs output to that file.

NOTE: At this time no validation is performed on the specified filename. Please make sure the directories exist and the appropriate permissions are available.

Parameters
szFilenameThe filename for the log file. Designated a NULL filename will disable logging, however, threads/resources will not be deallocated.
SIPXTAPI_API SIPX_RESULT sipxConfigSetLogLevel ( SIPX_LOG_LEVEL  logLevel)

The sipxConfigEnableLog method enables logging for the sipXtapi API, media processing, call processing, SIP stack, and OS abstraction layer.

Logging is disabled by default. The underlying framework makes no attempts to bound the log file to a fixed size.

Log Format: time:event id:facility:priority:host name:task name:task id:process id:log message

Parameters
logLevelDesignates the amount of detail includes in the log. See SIPX_LOG_LEVEL for more details.
SIPXTAPI_API SIPX_RESULT sipxConfigSetMicAudioHook ( fnMicAudioHook  hookProc)

Designate a callback routine as a microphone replacement or supplement.

The callback is invoked with microphone data and the data can be reviewed, modified, replaced, or discarded.

This callback proc must NOT block and must return data quickly. Additionally, the method should not call any blocking function (i.e. IO operations, malloc, new, etc).

Data must be formatted as mono 16-bit signed PCM, little endian, 8000 samples per second. The callback is handed 80 samples (10ms) of data at a time.

SIPXTAPI_API SIPX_RESULT sipxConfigSetOutboundProxy ( const SIPX_INST  hInst,
const char *  szProxy 
)

Defines the SIP proxy used for outbound requests.

Parameters
hInstInstance pointer obtained by sipxInitialize.
szProxythe new outbound proxy
SIPXTAPI_API SIPX_RESULT sipxConfigSetRegisterExpiration ( const SIPX_INST  hInst,
const int  nRegisterExpirationSecs 
)

Specifies the expiration period for registration.

After setting this configuration, all subsequent REGISTER messages will be sent with the new registration period.

Parameters
hInstInstance pointer obtained by sipxInitialize.
nRegisterExpirationSecsNumber of seconds until the expiration of a REGISTER message
SIPXTAPI_API SIPX_RESULT sipxConfigSetRegisterResponseWaitSeconds ( const SIPX_INST  hInst,
const int  seconds 
)

Specifies the time to wait for a REGISTER response before sending a LINESTATE_REGISTER_FAILED (or LINESTATE_UNREGISTER_FAILED) message.

If not set, the user-agent will use a 4 second timeout.

Parameters
hInstInstance pointer obtained by sipxInitialize.
secondsThe number of seconds to wait for a REGISTER response, before it is considered a failure.
SIPXTAPI_API SIPX_RESULT sipxConfigSetSecurityParameters ( const SIPX_INST  hInst,
const char *  szDbLocation,
const char *  szMyCertNickname,
const char *  szDbPassword 
)

Set security parameters for an instance of sipXtapi.

Deprecated:
These should be set using sipxInitialize.
Parameters
hInstInstance pointer obtained by sipxInitialize
szDbLocationThe directory in which the certificate database resides.
szMyCertNicknameThe local user's certificate nickname, for database lookup.
szDbPasswordThe password for the certificated database.
SIPXTAPI_API SIPX_RESULT sipxConfigSetSipAcceptLanguage ( const SIPX_INST  hInst,
const char *  szLanguage 
)

Sets the Accept Language used in sip messages.

e.g. - "EN"

Parameters
hInstInstance pointer obtained by sipxInitialize
szLanguage- Accept Language string
SIPXTAPI_API SIPX_RESULT sipxConfigSetSpkrAudioHook ( fnSpkrAudioHook  hookProc)

Designate a callback routine for post-mixing audio data (e.g.

to speaker data). The hook may review, modify, replace, or discard data.

This callback proc must NOT block and must return data quickly. Additionally, the method should not call any blocking function (i.e. IO operations, malloc, new, etc).

Data must be formatted as mono 16-bit signed PCM, little endian, 8000 samples per second. The callback is handed 80 samples (10ms) of data at a time.

SIPXTAPI_API SIPX_RESULT sipxConfigSetSubscribeExpiration ( const SIPX_INST  hInst,
const int  nSubscribeExpirationSecs 
)

Specifies the expiration period for subscription.

After setting this configuration, all subsequent SUBSCRIBE messages will be sent with the new subscribe period.

Parameters
hInstInstance pointer obtained by sipxInitialize.
nSubscribeExpirationSecsNumber of seconds until the expiration of a SUBSCRIBE message
SIPXTAPI_API SIPX_RESULT sipxConfigSetUserAgentName ( const SIPX_INST  hInst,
const char *  szName,
const bool  bIncludePlatformName = true 
)

Sets the User-Agent name to be used with outgoing SIP messages.

Parameters
hInstInstance pointer obtained by sipxInitialize.
szNameThe user-agent name.
bIncludePlatformNameIndicates whether or not to append the platform description onto the user agent name.
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoBandwidth ( const SIPX_INST  hInst,
SIPX_VIDEO_BANDWIDTH_ID  bandWidth 
)

Set the bandwidth parameters for video codecs.Depending on the bandwidth parameter that is passed in the settings will be set to:

VIDEO_CODEC_BW_LOW bitrate 5 kbps, framerate 10 fps VIDEO_CODEC_BW_NORMAL bitrate 70 kbps, framerate is what it was set to with sipxConfigSetVideoParameters or 30 if not set. VIDEO_CODEC_BW_HIGH bitrate 400 kbps, framerate is what it was set to with sipxConfigSetVideoParameters or 30 if not set.

This method will return SIPX_RESULT_SUCCESS if able to set the video codec preferences. SIPX_RESULT_FAILURE is returned if the preference is not set.

Parameters
hInstInstance pointer obtained by sipxInitialize
bandWidthValid bandwidth requirements are VIDEO_CODEC_BW_LOW, VIDEO_CODEC_BW_NORMAL, and VIDEO_CODEC_BW_HIGH.
See also
sipxConfigSetVideoParameters
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoBitrate ( const SIPX_INST  hInst,
const int  bitRate 
)

Sets the video bitrate.

Parameters
hInstInstance pointer obtained by sipxInitialize
bitRateBit rate parameter
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoCaptureDevice ( const SIPX_INST  hInst,
const char *  szCaptureDevice 
)

Sets the video capture device.

Parameters
hInstInstance pointer obtained by sipxInitialize
szCaptureDevicePointer to a character array containing the name of the desired video capture device.
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoCodecByName ( const SIPX_INST  hInst,
const char *  szCodecName 
)

Set the codec by name.

The name must match one of the supported codecs otherwise this function will fail. This method will return SIPX_RESULT_SUCCESS if able to set the video codec. SIPX_RESULT_FAILURE is returned if the codec is not set.

Parameters
hInstInstance pointer obtained by sipxInitialize
szCodecNamecodec name
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoCpuUsage ( const SIPX_INST  hInst,
const int  cpuUsage 
)

Set the cpu usage.

Parameters
hInstInstance pointer obtained by sipxInitialize
cpuUsageCPU usage in percent
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoFormat ( const SIPX_INST  hInst,
SIPX_VIDEO_FORMAT  videoFormat 
)

Set the supported video format This method will limit the supported video format to either VIDEO_FORMAT_CIF (352x288), VIDEO_FORMAT_QCIF (176x144), VIDEO_FORMAT_SQCIF (128x92), or VIDEO_FORMAT_QVGA (320x240).

The method will return SIPX_RESULT_SUCCESS if it is able to set the video format, SIPX_RESULT_FAILURE is returned if the video format can not be set.

SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoFramerate ( const SIPX_INST  hInst,
const int  frameRate 
)

Sets the video framerate.

Parameters
hInstInstance pointer obtained by sipxInitialize
frameRateFrame rate parameter
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoParameters ( const SIPX_INST  hInst,
const int  bitRate,
const int  frameRate 
)

Sets the bit rate and frame rate parameters for video.

Parameters
hInstInstance pointer obtained by sipxInitialize
bitRateBit rate parameter in kbps
frameRateFrame rate parameter frames per second
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoPreviewDisplay ( const SIPX_INST  hInst,
SIPX_VIDEO_DISPLAY *const  pDisplay 
)

Sets the display object for the "video preview".

Parameters
hInstInstance pointer obtained by sipxInitialize
pDisplayPointer to a video preview display object.
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoQuality ( const SIPX_INST  hInst,
const SIPX_VIDEO_QUALITY_ID  quality 
)

Sets the video quality.

Parameters
hInstInstance pointer obtained by sipxInitialize
qualityId setting the video quality.
SIPXTAPI_API SIPX_RESULT sipxConfigSetVoiceQualityServer ( const SIPX_INST  hInst,
const char *  szServer 
)

Sets the SIP target URL for voice quality reports.

Voice Quality reports are sent at the completion of each call and give details on the voice quality (latency, noise, MOS scores, etc). Presently, this is not implemented in the open source version.

This must be enabled prior to creating a call or receiving a new call indiciation. Likewise, changes will not take effect for existing calls.

Parameters
hInstAn instance handle obtained from sipxInitialize.
szServerTarget SIP URL for the voice quality reports. A value of NULL will disable voice quality reports.
SIPXTAPI_API SIPX_RESULT sipxConfigSubscribe ( const SIPX_INST  hInst,
const SIPX_LINE  hLine,
const char *  szTargetUrl,
const char *  szEventType,
const char *  szAcceptType,
const SIPX_CONTACT_ID  contactId,
SIPX_SUB phSub 
)

Subscribe for NOTIFY events which may be published by another end-point or server.

sipXtapi will automatically refresh subscriptions until sipxConfigUnsubscribe is called. Please make sure you call sipxCallUnsubscribe before tearing down your instance of sipXtapi.

Parameters
hInstInstance pointer obtained by sipxInitialize
hLineLine Identity for the outbound call. The line identity helps defines the "From" caller-id.
szTargetUrlThe Url of the publishing end-point.
szEventTypeA string representing the type of event that can be published. This string is used to populate the "Event" header in the SIP SUBSCRIBE request. For example, if checking voicemail status, your would use "message-summary".
szAcceptTypeA string representing the types of NOTIFY events that this client will accept. This string is used to populate the "Accept" header in the SIP SUBSCRIBE request. For example, if checking voicemail status, you would use "application/simple-message-summary"
contactIdId of the desired contact record to use for this call. The id refers to a Contact Record obtained by a call to sipxConfigGetLocalContacts. The application can choose a contact record of type LOCAL, NAT_MAPPED, CONFIG, or RELAY. The Contact Type allows you to control whether the user agent and media processing advertises the local address (e.g. LOCAL contact of 10.1.1.x or 192.168.x.x), the NAT-derived address to the target party, or, local contact addresses of other types.
phSubPointer to a subscription handle whose value is set by this funtion. This handle allows you to cancel the subscription and differeniate between NOTIFY events.
SIPXTAPI_API SIPX_RESULT sipxConfigUnHibernate ( const SIPX_INST  hInst)

Call this function upon returning from a system hibernation.

This function is not thread-safe.

Parameters
hInstInstance pointer obtained by sipxInitialize
SIPXTAPI_API SIPX_RESULT sipxConfigUnsubscribe ( const SIPX_SUB  hSub)

Unsubscribe from previously subscribed NOTIFY events.

This method will send another subscription request with an expires time of 0 (zero) to end your subscription.

Parameters
hSubThe subscription handle obtained from the call to sipxConfigSubscribe.
SIPXTAPI_API SIPX_RESULT sipxConfigUpdatePreviewWindow ( const SIPX_INST  hInst,
const SIPX_WINDOW_HANDLE  hWnd 
)

Updates the Preview window with a new frame buffer.

Should be called when the window receives a PAINT message.

Parameters
hInstInstance pointer obtained by sipxInitialize
hWndWindow handle of the video preview window.
SIPXTAPI_API SIPX_RESULT sipxInitialize ( SIPX_INST phInst,
const int  udpPort = DEFAULT_UDP_PORT,
const int  tcpPort = DEFAULT_TCP_PORT,
const int  tlsPort = DEFAULT_TLS_PORT,
const int  rtpPortStart = DEFAULT_RTP_START_PORT,
const int  maxConnections = DEFAULT_CONNECTIONS,
const char *  szIdentity = DEFAULT_IDENTITY,
const char *  szBindToAddr = DEFAULT_BIND_ADDRESS,
bool  bUseSequentialPorts = false,
const char *  szTLSCertificateNickname = NULL,
const char *  szTLSCertificatePassword = NULL,
const char *  szDbLocation = NULL,
bool  bEnableLocalAudio = true,
const int  internalSamplerate = 8000,
const int  devicesSamplerate = 48000,
const int  internalFrameSizeMs = 10,
const char *  callInputDeviceName = "",
const char *  callOutputDeviceName = "" 
)

Initialize the sipX TAPI-like API layer.

This method initialized the basic SIP stack and media process resources and must be called before any other sipxXXX methods. Additionally, this method fills in a SIPX_INST parameter which must be passed to a number of sipX methods.

Parameters
phInstA pointer to a hInst that must be various other sipXtapi routines.
udpPortThe default UDP port for the SIP protocol stack. The port cannot be changed after initialization. Right now, the UDP port and TCP port numbers MUST be equal. Pass a value of SIPX_PORT_DISABLE (-1) to disable disable UDP or a value of SIPX_PORT_AUTO (-2) to automatically select an open UDP port.
tcpPortThe default TCP port for the SIP protocol stack. The port cannot be changed after initialization. Right now, the UDP port and TCP port numbers MUST be equal. Pass a value of SIPX_PORT_DISABLE (-1) to disable disable TCP or a value of SIPX_PORT_AUTO (-2) to automatically select an open TCP port.
tlsPortNOT YET SUPPORTED
rtpPortStartThe starting port for inbound RTP traffic. The sipX layer will use ports starting at rtpPortStart and ending at (rtpPortStart + 2 * maxConnections) - 1. Pass a value of SIPX_PORT_AUTO (-2) to automatically select an open port.
maxConnectionsThe maximum number of simultaneous connections that the sipX layer will support.
szIdentityThe default outbound identity used by the SIP stack if no lines are defined. Generally, the szIdentity is only used for inbound calls since all of sipXtapi APIs required a line ID for outbound calls. The identity will be used to form the "From" field (caller-id) and the username/URL parameters are may be used as part of the "Contact" header. In other words, this field does not impact any routing aspects of the call session.
szBindToAddrDefines which IP/address the user agent / rtp stack will listen on. The default "0.0.0.0" listens on all interfaces. The address must be in dotted decimal form – hostnames will not work.
bUseSequentialPortsIf unable to bind to the udpPort, tcpPort, or tlsPort, try sequential ports until a successful port is found. If enabled, sipXtapi will try 10 sequential port numbers after the initial port.
szTLSCertificateNicknameNickname of the certificate to use as an SSL server.
szTLSCertificatePasswordPassword for the SSL server certificate.
szDbLocationPath to the certificate database.
bEnableLocalAudioEnable use of local microphone and speaker. Set to false if you're running on a server hardware without a sound card.
internalSamplerateSamplerate at which all internal processing is performed. E.g. if you use G.722 codec which has 16K samplerate, but set inernal samplerate to 8000, then you will hear little difference from G.711, becase incoming audio will be downsampled to 8000 and outgoing audio will be upsampled from 8000. Note however, that working with 8000 internal samplerate requires less CPU power, and thus it is set by default to 8000.
devicesSamplerateSamplerate used by audio input/output drivers. It is set to 48000 by default, because it's the native samplerate for the most modern soundcards and they produce less jitter and drift at this samplerate. We downsample/upsample to internal samplerate transparently under the hood.
internalFrameSizeMsSize of an audio frame (in milliseconds), used for internal processing. Default value of 10ms is a recommended value unless you really know what you're doing. If you want to run this on a slow CPU, you may want to set this to 20ms, but it will increase latency and thus is not generally recommended.
callInputDeviceNameName of the audio device to use as input device during a call. Can be changed later with sipxAudioSetCallInputDevice(). Use empty string to select default (OS-dependent) device.
callOutputDeviceNameName of the audio device to use as output device during a call. Can be changed later with sipxAudioSetCallOutputDevice(). Use empty string to select default (OS-dependent) device.
SIPXTAPI_API SIPX_RESULT sipxLineAdd ( const SIPX_INST  hInst,
const char *  szLineURL,
SIPX_LINE phLine,
SIPX_CONTACT_ID  contactId = 0 
)

Adds a line appearance.

A line appearance defines your address of record and is used both as your "From" caller-id and as the public identity to which you will receive calls for. Directing calls to a particular user agent is achieved using registrations.

Parameters
hInstInstance pointer obtained by sipxInitialize.
szLineURLThe address of record for the line identity. Can be prepended with a Display Name. e.g. - "Zaphod Beeblebrox" <sip:zaphb@fourty-two.net>
phLinePointer to a line handle. Upon success, a handle to the newly added line is returned.
contactIdId of the desired contact record to use for this line. The id refers to a Contact Record obtained by a call to sipxConfigGetLocalContacts. The application can choose a contact record of type LOCAL, NAT_MAPPED, CONFIG, or RELAY. The Contact Type allows you to control whether the user agent and media processing advertises the local address (e.g. LOCAL contact of 10.1.1.x or 192.168.x.x), the NAT-derived address to the target party, or, local contact addresses of other types.
See also
sipxConfigGetLocalContacts
SIPXTAPI_API SIPX_RESULT sipxLineAddAlias ( const SIPX_LINE  hLine,
const char *  szLineURL 
)

Adds an alias for a line definition.

Line aliases are used to map an inbound call request to an existing line definition. You should only need to an a alias if your network infrastructure directs calls to this user agent using multiple identities. For example, if user agent registers as "sip:bandreasen\@example.com"; however, calls can also be directed to you via an exention (e.g. sip:122@example.com).

If sipXtapi receives a call with an unknown line, you can still answer and interact wtih the call; however, the line handle will be SIPX_LINE_NULL in all event callbacks. Adding an aliases allows you to correlate another line url with your line definition and receive real line handles with event callbacks.

Line aliases are not used for outbound calls.

See also
sipxConfigGetLocalContacts
SIPXTAPI_API SIPX_RESULT sipxLineAddCredential ( const SIPX_LINE  hLine,
const char *  szUserID,
const char *  szPasswd,
const char *  szRealm 
)

Adds authentication credentials to the designated line appearance.

Credentials are often required by registration services to verify that the line is being used by the line appearance/address of record owner.

Parameters
hLineHandle to a line appearance. Line handles are obtained by creating a line using the sipxLineAdd function or by receiving a line event notification.
szUserIDuser id used for the line appearance.
szPasswdpasswd used for the line appearance.
szRealmrealm for which the user and passwd are valid. Supply NULL for automatic realm.
SIPXTAPI_API SIPX_RESULT sipxLineFindByURI ( const SIPX_INST  hInst,
const char *  szURI,
SIPX_LINE hLine 
)

Find a line definition given a URI.

Parameters
hInstInstance pointer obtained by sipxInitialize.
szURIURI used to search for a line definition
hLineline handle if successful
SIPXTAPI_API SIPX_RESULT sipxLineGet ( const SIPX_INST  hInst,
SIPX_LINE  lines[],
const size_t  max,
size_t &  actual 
)

Gets the active list of line identities.

Parameters
hInstInstance pointer obtained by sipxInitialize.
linesPre-allocated array of line handles.
maxMaximum number of lines to return.
actualActual number of valid lines returned.
SIPXTAPI_API SIPX_RESULT sipxLineGetContactId ( const SIPX_LINE  hLine,
SIPX_CONTACT_ID contactId 
)

Get the contact ID for the designated line handle.

Parameters
hLineHandle to a line appearance. Line handles are obtained by creating a line using the sipxLineAdd function or by receiving a line event notification.
contactIdcontact Id specified during line creation
SIPXTAPI_API SIPX_RESULT sipxLineGetURI ( const SIPX_LINE  hLine,
char *  szBuffer,
const size_t  nBuffer,
size_t &  nActual 
)

Get the Line URI for the designated line handle.

Parameters
hLineHandle to a line appearance. Line handles are obtained by creating a line using the sipxLineAdd function or by receiving a line event notification.
szBufferBuffer to place line URL. A NULL value will return the amount of storage needed in nActual.
nBufferSize of szBuffer in bytes (not to exceed)
nActualActual number of bytes written
SIPXTAPI_API SIPX_RESULT sipxLineRegister ( const SIPX_LINE  hLine,
const bool  bRegister 
)

Registers a line with the proxy server.

Registrations will be re-registered automatically, before they expire.

Unless your user agent is designated a static IP address or DNS name and that routing information is provisioned into a SIP server, you should register the line by calling this function.

Please unregister your line before calling sipxLineRemove.

Parameters
hLineHandle to a line appearance. Line handles are obtained by creating a line using the sipxLineAdd function or by receiving a line event notification.
bRegistertrue if Registration is desired, otherwise, an Unregister is performed.
SIPXTAPI_API SIPX_RESULT sipxLineRemove ( SIPX_LINE  hLine)

Remove the designated line appearance.

If the line was previous registered using the sipxLineRegister API, please unregister the line and wait for the unregistered event before calling sipxLineRemove. Otherwise, the line will be removed without unregistering.

Parameters
hLineHandle to a line appearance. Line handles are obtained by creating a line using the sipxLineAdd function or by receiving a line event notification.
SIPXTAPI_API SIPX_RESULT sipxMediaConnectionCreate ( const SIPX_CONF  hConf,
int &  connectionId 
)

Create a new media connetion that is indpendent of any existing call legs in the conference.

This media connection is for independent control independent of SIP call control. RTP streams may be stopped and started manually via the sipXtapi methods: sipxConferenceRtpSetDestination sipxConferenceRtpStartSend sipxConferenceRtpStopSend

Parameters
[in]hConf- conference handle indicating which media interface in which the new media connection is to be created.
[out]connectionId- handle/id for the media connection created.
SIPXTAPI_API SIPX_RESULT sipxMediaConnectionRtpSetDestination ( const SIPX_CONF  hConf,
int  connectionId,
MEDIA_TYPE  mediaType,
int  mediaTypeStreamIndex,
const char *  streamSendAddress,
int  rtpPort,
int  rtcpPort 
)

Set the destination to which RTP streams are to be sent.

Parameters
[in]hConf- conference handle indicating which media interface the connection belongs.
[in]connectionId- handle/id for media connection
[in]mediaType- media stream type (e.g. VIDEO_MEDIA, AUDIO_MEDIA)
[in]mediaTypeStreamIndex- index to which stream for the given type of media for now limited to 1 stream (i.e. index = 0)
[in]streamSendAddress- remote IP address to send RTP to
[in]rtpPort- port at remote address to send RTP stream to
[in]rtcpPort- port at remote address to send RTCP stream to
SIPXTAPI_API SIPX_RESULT sipxMediaConnectionRtpStartSend ( const SIPX_CONF  hConf,
int  connectionId,
int  numTokens,
const char *  codecTokens[],
int  payloadIds[] 
)

Start sending the RTP/RTCP stream.

Parameters
[in]hConf- conference handle indicating which media interface the connection belongs.
[in]connectionId- handle/id for media connection
[in]numTokens- number of codec tokens in codecTokens array
[in]codecTokens- array of codec names
[in]payloadIds- payload ID to use for corresponding codec in codecTokens array
SIPXTAPI_API SIPX_RESULT sipxMediaConnectionRtpStopSend ( const SIPX_CONF  hConf,
int  connectionId 
)

Stop sending RTP/RTCP.

Parameters
[in]hConf- conference handle indicating which media interface the connection belongs.
[in]connectionId- handle/id for media connection
SIPXTAPI_API SIPX_RESULT sipxPublisherCreate ( const SIPX_INST  hInst,
SIPX_PUB phPub,
const char *  szResourceId,
const char *  szEventType,
const char *  szContentType,
const char *  pContent,
const size_t  nContentLength 
)

Creates a publishing context, which performs the processing necessary to accept SUBSCRIBE requests, and to publish NOTIFY messages to subscribers.

The resource may be specific to a single call, conference or global to this user agent. The naming of the resource ID determines the scope.

Parameters
hInstInstance pointer obtained by sipxInitialize.
phPubPointer to a publisher handle - this method modifies the value to refer to the newly created publishing context.
szResourceIdThe resourceId to the state information being published. This must match the request URI of the incoming SUBSCRIBE request (only the user ID, host and port are significant in matching the request URI). Examples: fred@10.0.0.1:5555, sip:conference1@192.160.0.1, sip:kate@example.com
szEventTypeA string representing the type of event that can be published.
szContentTypeString representation of the content type being published.
pContentPointer to the NOTIFY message's body content.
nContentLengthSize of the content to be published.
Returns
If the resource already has a a publisher created for the given event type, SIPX_RESULT_INVALID_ARGS is returned.
SIPXTAPI_API SIPX_RESULT sipxPublisherDestroy ( const SIPX_PUB  hPub,
const char *  szContentType,
const char *  pFinalContent,
const size_t  nContentLength 
)

Tears down the publishing context.

Any existing subscriptions are sent a final NOTIFY request. If pFinalContent is not NULL and nContentLength > 0 the given publish state is given otherwise the final NOTIFY requests are sent with no body or state.

Parameters
hPubHandle of the publishing context to destroy (returned from a call to sipxCreatePublisher)
szContentTypeString representation of the content type being published
pFinalContentPointer to the NOTIFY message's body content
nContentLengthSize of the content to be published
SIPXTAPI_API SIPX_RESULT sipxPublisherUpdate ( const SIPX_PUB  hPub,
const char *  szContentType,
const char *  pContent,
const size_t  nContentLength 
)

Publishes an updated state to specific event via NOTIFY to its subscribers.

Parameters
hPubHandle of the publishing context (returned from a call to sipxCreatePublisher)
szContentTypeString representation of the content type being published
pContentPointer to the NOTIFY message's body content
nContentLengthSize of the content to be published
SIPXTAPI_API SIPX_RESULT sipxReInitialize ( SIPX_INST phInst,
const int  udpPort = DEFAULT_UDP_PORT,
const int  tcpPort = DEFAULT_TCP_PORT,
const int  tlsPort = DEFAULT_TLS_PORT,
const int  rtpPortStart = DEFAULT_RTP_START_PORT,
const int  maxConnections = DEFAULT_CONNECTIONS,
const char *  szIdentity = DEFAULT_IDENTITY,
const char *  szBindToAddr = DEFAULT_BIND_ADDRESS,
bool  bUseSequentialPorts = false,
const char *  szTLSCertificateNickname = NULL,
const char *  szTLSCertificatePassword = NULL,
const char *  szDbLocation = NULL 
)

Re-initialize the sipX TAPI-like API layer.

This method will remove all lines, conferences, calls, publishers, and subscribers, and listeners. Before calling this function, the application should unregister all registered lines.

Your listeners are NOT maintained. You should also reset any of your configuration settings (rport, outbound proxy, etc).

Parameters
phInstA pointer to a SIPX_INST variable. Your old SIPX_INST handle will be invalid after this call. Calling any routines with the old SIPX_INST variable is undefined and may result in an exception.
udpPortThe default UDP port for the SIP protocol stack. The port cannot be changed after initialization. Right now, the UDP port and TCP port numbers MUST be equal. Pass a value of SIPX_PORT_DISABLE (-1) to disable disable UDP or a value of SIPX_PORT_AUTO (-2) to automatically select an open UDP port.
tcpPortThe default TCP port for the SIP protocol stack. The port cannot be changed after initialization. Right now, the UDP port and TCP port numbers MUST be equal. Pass a value of SIPX_PORT_DISABLE (-1) to disable disable TCP or a value of SIPX_PORT_AUTO (-2) to automatically select an open TCP port.
tlsPortNOT YET SUPPORTED
rtpPortStartThe starting port for inbound RTP traffic. The sipX layer will use ports starting at rtpPortStart and ending at (rtpPortStart + 2 * maxConnections) - 1. Pass a value of SIPX_PORT_AUTO (-2) to automatically select an open port.
maxConnectionsThe maximum number of simultaneous connections that the sipX layer will support.
szIdentityThe default outbound identity used by the SIP stack if no lines are defined. Generally, the szIdentity is only used for inbound calls since all of sipXtapi APIs required a line ID for outbound calls. The identity will be used to form the "From" field (caller-id) and the username/URL parameters are may be used as part of the "Contact" header. In other words, this field does not impact any routing aspects of the call session.
szBindToAddrDefines which IP/address the user agent / rtp stack will listen on. The default "0.0.0.0" listens on all interfaces. The address must be in dotted decimal form – hostnames will not work.
bUseSequentialPortsIf unable to bind to the udpPort, tcpPort, or tlsPort, try sequential ports until a successful port is found. If enabled, sipXtapi will try 10 sequential port numbers after the initial port.
szTLSCertificateNicknameNickname of the certificate to use as an SSL server.
szTLSCertificatePasswordPassword for the SSL server certificate.
szDbLocationPath to the certificate database.
bEnableLocalAudioShould local sound card be engaged or not. Setting this parameter to FALSE is useful for server applications which should work without a sound card installed.
SIPXTAPI_API SIPX_RESULT sipxUnInitialize ( SIPX_INST  hInst,
bool  bForceShutdown = false 
)

Uninitialize the sipX TAPI-like API layer.

This method tears down the basic SIP stack and media process resources and should be called before exiting the process. Users are responsible for ending all calls and unregistering line appearances before calling sipxUnInitialize. Failing to end calls/conferences or remove lines will result in a SIPX_RESULT_BUSY return code.

Parameters
hInstAn instance handle obtained from sipxInitialize.
bForceShutdownforces sipXtapi to shutdown regardless of live calls/unregistered lines. Enabling this in NOT RECOMMENDED, please tear down all calls and lines prior to calling sipxUnitialize.
SIPXTAPI_API SIPX_RESULT sipxUtilUrlGetDisplayName ( const char *  szUrl,
char *  szDisplayName,
size_t  nDisplayName 
)

Simple utility function to parse the display name from a SIP URL.

SIPXTAPI_API SIPX_RESULT sipxUtilUrlGetUrlParam ( const char *  szUrl,
const char *  szParamName,
size_t  nParamIndex,
char *  szParamValue,
size_t  nParamValue 
)

Get the Nth named url parameter from the designated url.

Parameters
szUrlThe url to parse
szParamNameName of the url parameter
nParamIndexIndex of the url parameter (zero-based). This is used if you have multiple url parameters with the same name – otherwise, you should use 0.
szParamValueBuffer to place parameter value
nParamValuesize of parameter value buffer (szParamValue)
SIPXTAPI_API SIPX_RESULT sipxUtilUrlParse ( const char *  szUrl,
char *  szUsername,
char *  szHostname,
int *  iPort 
)

Simple utility function to parse the username, host, and port from a URL.

All url, field, and header parameters are ignored. You may also specify NULL for any parameters (except szUrl) which are not needed. Lastly, the caller must allocate enough storage space for each url component – if in doubt use the length of the supplied szUrl.

SIPXTAPI_API SIPX_RESULT sipxUtilUrlUpdate ( char *  szUrl,
size_t &  nUrl,
const char *  szNewUsername,
const char *  szNewHostname,
const int  iNewPort 
)

Simple utility function to update a URL.

If the szUrl isn't large enough, or is NULL, this function will fail, however, the nUrl will contained the required size in bytes.

To leave an existing component unchanged, use NULL for strings and -1 for ports.

If the szUrl isn't large enough, this function will fail. Specify a NULL szUrl to request required length. To leave an existing component unchanged, use NULL for strings and -1 for ports.

Variable Documentation

const SIPX_CALL SIPX_CALL_NULL = 0

Represents a null call handle.

const SIPX_CONF SIPX_CONF_NULL = 0

Represents a null conference handle.

const SIPX_INST SIPX_INST_NULL = 0

Represents a null instance handle.

const SIPX_LINE SIPX_LINE_NULL = 0

Represents a null line handle.

const SIPX_PUB SIPX_PUB_NULL = 0

Represents a null publisher handle.

const SIPX_TRANSPORT SIPX_TRANSPORT_NULL = 0

Represents a null transport handle.