sipXtapi main API declarations More...
#include <memory.h>
#include <string.h>
#include <stddef.h>
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 64 |
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_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. 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... | |
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 | sipxAudioGetCurrentInputDevice (const SIPX_INST hInst, int &index, const char *&szDevice) |
Get the name/identifier for the current input device used by sipX. 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 | sipxAudioGetCurrentOutputDevice (const SIPX_INST hInst, int &index, const char *&szDevice) |
Get the name/identifier for the current output device used by sipX. 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... | |
sipXtapi main API declarations
#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
#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 64 |
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 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.
nSamples | number of 16 bit unsigned PCM samples |
pSamples | pointer 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.
nSamples | number of 16 bit unsigned samples |
pSamples | pointer to array of samples |
typedef enum MEDIA_TYPE MEDIA_TYPE |
Media type.
typedef enum SIPX_AEC_MODE SIPX_AEC_MODE |
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.
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.
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
typedef enum SIPX_AUDIO_DATA_FORMAT SIPX_AUDIO_DATA_FORMAT |
Format definitions for memory resident audio data.
typedef enum SIPX_AUDIO_FILE_FORMAT SIPX_AUDIO_FILE_FORMAT |
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.
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.
typedef enum SIPX_LOG_LEVEL SIPX_LOG_LEVEL |
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.
typedef enum SIPX_NOISE_REDUCTION_MODE SIPX_NOISE_REDUCTION_MODE |
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.
hTransport | Handle to the external transport object. Will match a transport handle obtained via a call to sipxConfigExternalTransportAdd |
szDestinationIp | IP address which is the destination for the write. |
iDestPort | Port value to which the data will be sent. |
szLocalIp | IP address which is the source address for the write. |
iLocalPort | Port value from which the data will be sent. |
pData | Pointer to the data to be sent. |
nData | Size of the data to be sent. |
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.
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.
typedef enum SIPX_VIDEO_DISPLAY_TYPE SIPX_VIDEO_DISPLAY_TYPE |
Enum for specifying the type of display object to be used for displaying video.
typedef enum SIPX_VIDEO_FORMAT SIPX_VIDEO_FORMAT |
Enumeration of possible video sizes.
typedef enum SIPX_VIDEO_QUALITY_ID SIPX_VIDEO_QUALITY_ID |
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).
typedef SIPX_TONE_ID TONE_ID |
Left for backwards compatibility – please use SIPX_TONE_ID.
enum MEDIA_TYPE |
enum SIPX_AEC_MODE |
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
enum SIPX_CONTACT_TYPE |
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.
enum SIPX_KEEPALIVE_TYPE |
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
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.
enum SIPX_LOG_LEVEL |
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.
enum SIPX_RESULT |
SIPX_RESULT is an enumeration with all the possible result/return codes.
enum SIPX_RTP_TRANSPORT |
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 |
enum SIPX_SRTP_LEVEL |
enum SIPX_TONE_ID |
DTMF/other tone ids used with sipxCallStartTone/sipxCallStopTone.
enum SIPX_TRANSPORT_TYPE |
SIPX_TRANSPORT_TYPE defines various protocols use for signaling transport.
The SIPX_TRANSPORT_TYPE is return in contact addresses.
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 SIPX_VIDEO_FORMAT |
enum SPEAKER_TYPE |
SIPXTAPI_API SIPX_RESULT sipxAudioEnableSpeaker | ( | const SIPX_INST | hInst, |
const SPEAKER_TYPE | type | ||
) |
Enables one of the speaker outputs.
hInst | Instance pointer obtained by sipxInitialize. |
type | The 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.
hInst | Instance pointer obtained by sipxInitialize. |
mode | 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.
hInst | Instance pointer obtained by sipxInitialize. |
bEnabled | true if AGC is enabled; otherwise false. |
SIPXTAPI_API SIPX_RESULT sipxAudioGetCurrentInputDevice | ( | const SIPX_INST | hInst, |
int & | index, | ||
const char *& | szDevice | ||
) |
Get the name/identifier for the current input device used by sipX.
hInst | Instance pointer obtained by sipxInitialize. |
index | Zero based index of the input device. |
szDevice | Reference an character string pointer to receive the device name. |
SIPXTAPI_API SIPX_RESULT sipxAudioGetCurrentOutputDevice | ( | const SIPX_INST | hInst, |
int & | index, | ||
const char *& | szDevice | ||
) |
Get the name/identifier for the current output device used by sipX.
hInst | Instance pointer obtained by sipxInitialize. |
index | Zero based index of the input device. |
szDevice | Reference an character string pointer to receive the device name. |
SIPXTAPI_API SIPX_RESULT sipxAudioGetEnabledSpeaker | ( | const SIPX_INST | hInst, |
SPEAKER_TYPE & | type | ||
) |
Gets the enabled speaker selection.
hInst | Instance pointer obtained by sipxInitialize. |
type | The 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.
hInst | Instance pointer obtained by sipxInitialize. |
iLevel | The 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.
hInst | Instance pointer obtained by sipxInitialize. |
index | Zero based index of the input device to be queried. |
szDevice | Reference 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.
hInst | Instance pointer obtained by sipxInitialize. |
mode | 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.
hInst | Instance pointer obtained by sipxInitialize. |
numDevices | The 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.
hInst | Instance pointer obtained by sipxInitialize. |
numDevices | The 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.
hInst | Instance pointer obtained by sipxInitialize. |
index | Zero based index of the output device to be queried. |
szDevice | Reference 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.
hInst | Instance pointer obtained by sipxInitialize. |
type | The type of the speaker either the logical ringer (used to alert user of in inbound call) or speaker (in call audio device). |
iLevel | The 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.
hInst | Instance pointer obtained by sipxInitialize. |
bMuted | True 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.
hInst | Instance pointer obtained by sipxInitialize. |
bMute | True 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.
hInst | Instance pointer obtained by sipxInitialize. |
mode | 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.
hInst | Instance pointer obtained by sipxInitialize. |
bEnable | true 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).
hInst | Instance pointer obtained by sipxInitialize. |
szDevice | Character 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).
hInst | Instance pointer obtained by sipxInitialize. |
szDevice | The 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.
hInst | Instance pointer obtained by sipxInitialize. |
iLevel | The 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.
hInst | Instance pointer obtained by sipxInitialize. |
mode | noise reduction mode. |
SIPXTAPI_API SIPX_RESULT sipxAudioSetRingerOutputDevice | ( | const SIPX_INST | hInst, |
const char * | szDevice | ||
) |
Set the call ringer/alerting device.
hInst | Instance pointer obtained by sipxInitialize. |
szDevice | The 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.
hInst | Instance pointer obtained by sipxInitialize. |
type | The type of the speaker either the logical ringer (used to alert user of in inbound call) or speaker (in call audio device). |
iLevel | The 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
pDisplay | Pointer to an object describing the display object for rendering remote video. |
pSecurity | Pointer to an object describing the security attributes for the call. |
options | Pointer to a SIPX_CALL_OPTIONS structure. |
bSendEarlyMedia | flag to send early media (RTP) upon accepting the call |
SIPXTAPI_API SIPX_RESULT sipxCallAnswer | ( | const SIPX_CALL | hCall, |
bool | bTakeFocus = true |
||
) |
Answer an alerting call.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
bTakeFocus | Should 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.
hCall | Handle 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. |
szFile | Filename for the audio file to be played. |
bRepeat | True if the file is supposed to be played repeatedly |
bLocal | True if the audio file is to be rendered locally. |
bRemote | True if the audio file is to be rendered by the remote endpoint. |
bMixWithMicrophone | True 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. |
fVolumeScaling | Volume 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.
hCall | Handle 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
pBuffer | Buffer to record data to. |
bufferSize | Size of the buffer in bytes. |
bufferType | The audio encoding format for the data as specified by the SIPX_AUDIO_DATA_FORMAT enumerations. Currently only RAW_PCM_16 is supported. |
maxRecordTime | Maximum time to record in milliseconds. Recording stops automatically when this amount of time is recorded. Pass -1 to disable time limit. |
maxSilence | Maximum 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.
hCall | Handle 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szFile | Filename 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.
hCall | Handle 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.
hCall | Handle 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.
hCall | Handle 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:
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.
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.
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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szAddress | SIP url identifing the transfer target (who the call identified by hCall will be transfered to). |
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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szAddress | SIP url of the target party |
contactId | Id 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. |
pDisplay | Pointer to an object describing the display object for rendering remote video. |
pSecurity | Pointer to an object describing the security attributes for the call. |
bTakeFocus | Should 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. |
options | Pointer to a SIPX_CALL_OPTIONS structure. |
szCallId | A call-id for the session, if NULL, one is generated. |
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.
hInst | Instance pointer obtained by sipxInitialize. |
hLine | Line 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. |
phCall | Pointer 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.
hCall | Handle 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
pStats | Structure 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
iSendSSRC | The RTP SSRC used when sending audio |
iReceiveSSRC | The 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
hConf | Conference 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
connectionId | Reference 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szId | Buffer to store the ID. A zero-terminated string will be copied into this buffer on success. |
iMaxLength | Max 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
iInputEnergyLevel | Input/Microphone energy level ranging from 0 to 9. |
iOutputEnergyLevel | Output/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. |
nMaxContributors | Max number of contributors/energy levels. Contributors are derived by looking at the contributing RTP source IDs from the RTP stream. |
CCSRCs | Array 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. |
iEnergyLevels | Energy 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. |
nActualContributors | The 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szId | Buffer to store the ID. A zero-terminated string will be copied into this buffer on success. |
iMaxLength | Max 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.
hCall | handle 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. |
SIPXTAPI_API SIPX_RESULT sipxCallGetLine | ( | const SIPX_CALL | hCall, |
SIPX_LINE & | hLine | ||
) |
Get the line handle for the given call if it has one.
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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szId | Buffer to store the ID. A zero-terminated string will be copied into this buffer on success. |
iMaxLength | Max 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szContact | Buffer to store the remote contact. A zero-terminated string will be copied into this buffer on success. |
iMaxLength | Max 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szId | Buffer to store the ID. A zero-terminated string will be copied into this buffer on success. |
iMaxLength | Max 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szAgent | Buffer to store the user agent name. A zero-terminated string will be copied into this buffer on success. |
iMaxLength | Max length of the buffer |
SIPXTAPI_API SIPX_RESULT sipxCallGetRequestURI | ( | const SIPX_CALL | hCall, |
char * | szUri, | ||
const size_t | iMaxLength | ||
) |
Get the SIP request URI.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szUri | Buffer to store the request URI. A zero-terminated string will be copied into this buffer on success. |
iMaxLength | Max 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
bStopRemoteAudio | Flag 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
audioBandwidth | A bandwidth id to limit audio codecs. Pass in AUDIO_CODEC_BW_DEFAULT to leave audio codecs unchanged. |
videoBandwidth | A 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. |
szVideoCodecName | Codec name that limits the supported video codecs to this one video codec. |
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.
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.
hCall | Handle 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. |
szBuffer | Pointer to the audio data to be played. |
bufSize | Length, in bytes, of the audio data. |
bufType | The audio encoding format for the data as specified by the SIPX_AUDIO_DATA_FORMAT enumerations. Currently only RAW_PCM_16 is supported. |
bRepeat | True if the audio is supposed to be played repeatedly |
bLocal | True if the audio is to be rendered locally. |
bRemote | True 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.
hCall | Handle 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szForwardURL | SIP 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
errorCode | RFC specified error code. |
szErrorText | null 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
hWnd | Window 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).
phInfo | Pointer to an INFO message handle, whose value is set by this method. |
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
szContentType | String representation of the INFO content type |
szContent | Pointer to the INFO messasge's content |
nContentLength | Size 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.
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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
gain | Floating 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 |
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.
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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
toneId | ID of the tone to play |
bLocal | Should the tone be played locally? |
bRemote | Should 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.
hCall | Handle 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.
hCall | The call handle of the call associated with the subscription. |
szEventType | A 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". |
szAcceptType | A 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" |
phSub | Pointer to a subscription handle whose value is set by this function. This handle allows you to cancel the subscription and differentiate between NOTIFY events. |
bRemoteContactIsGruu | indicates 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:
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.
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.
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.
hSourceCall | Handle to the source call (transferee). |
hTargetCall | Handle to the target call (transfer target). |
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.
hCall | Handle 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.
hSub | The 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.
hCall | Handle to a call. Call handles are obtained either by invoking sipxCallCreate or passed to your application through a listener interface. |
hWnd | Window 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.
hConf | Handle to a conference. Conference handles are obtained by invoking sipxConferenceCreate. |
hLine | Line 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. |
szAddress | SIP URL of the conference participant to add |
phNewCall | Pointer to a call handle to store new call. |
contactId | Id 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. |
pDisplay | Pointer to an object describing the display object for rendering remote video. |
pSecurity | Pointer to an object describing the security attributes for the call. |
bTakeFocus | Should 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. |
options | Pointer to a SIPX_CALL_OPTIONS structure. |
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.
hInst | Instance pointer obtained by sipxInitialize. |
phConference | Pointer 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.
hConf | Handle 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.
hConf | Handle to a conference. Conference handles are obtained by invoking sipxConferenceCreate. |
calls | An array of call handles filled in by the API. |
iMax | The maximum number of call handles to return. |
nActual | The 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.
hConf | Handle to a conference. Conference handles are obtained by invoking sipxConferenceCreate. |
iInputEnergyLevel | Input/Microphone energy level ranging from 0 to 9. |
iOutputEnergyLevel | Output/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.
hConf | Handle to a conference. Conference handles are obtained by invoking sipxConferenceCreate. |
bBridging | true 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.
hConf | Conference handle obtained by calling sipxConferenceCreate. |
hCall | Call 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.
hConf | Handle to a conference. Conference handles are obtained by invoking sipxConferenceCreate. |
audioBandwidth | A bandwidth id to limit audio codecs. Pass in AUDIO_CODEC_BW_DEFAULT to leave audio codecs unchanged. |
videoBandwidth | A 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. |
szVideoCodecName | Codec name that limits the supported video codecs to this one video codec. |
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.
hConf | Conference handle obtained by calling sipxConferenceCreate. |
szFile | Filename for the audio file to be played. |
bRepeat | True if the file is supposed to be played repeatedly |
bLocal | True if the audio file is to be rendered locally. |
bRemote | True if the audio file is to be rendered by the remote endpoint. |
bMixWithMicrophone | True 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. |
fVolumeScaling | Volume 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.
hConf | Handle to a conference. Conference handles are obtained by invoking sipxConferenceCreate. |
hCall | Call 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.
hConf | Handle to a conference. Conference handles are obtained by invoking sipxConferenceCreate. |
hCall | Call 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.
hConf | Handle 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.
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.
hInst | Instance pointer obtained by sipxInitialize. |
SIPXTAPI_API SIPX_RESULT sipxConfigDisableStun | ( | const SIPX_INST | hInst | ) |
Disable the use of STUN.
See sipxConfigEnableStun for details on STUN.
hInst | Instance pointer obtained by sipxInitialize. |
SIPXTAPI_API SIPX_RESULT sipxConfigDisableTurn | ( | const SIPX_INST | hInst | ) |
Disable the use of TURN.
See sipxConfigEnableTurn for details TURN.
hInst | Instance 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.
bEnable | Enable 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.
hInst | Instance pointer obtained by sipxInitialize. |
bEnable | true 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.
hInst | Instance pointer obtained by sipxInitialize |
bEnable | Enable 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.
hInst | Instance pointer obtained by sipxInitialize |
bEnable | Enable 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.
hInst | Instance pointer obtained by sipxInitialize. |
bEnable | Enable 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.
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.
hInst | Instance pointer obtained by sipxInitialize |
bEnable | Enable 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.
hInst | Instance pointer obtained by sipxInitialize |
bEnable | True 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.
hInst | Instance pointer obtained by sipxInitialize |
bEnabled | True 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.
hInst | Instance pointer obtained by sipxInitialize |
bEnabled | True 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.
hInst | Instance pointer obtained by sipxInitialize |
bEnabled | True 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:
hInst | Instance pointer obtained by sipxInitialize |
szServer | The stun server that should be used for discovery. |
iServerPort | The port of the stun server that should be used for discovery. |
iKeepAliveInSecs | This 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.
hInst | Instance pointer obtained by sipxInitialize. |
szServer | The TURN server that should be used for relaying. |
iServerPort | The TURN sever port that should be used for relaying |
szUsername | TURN username for authentication |
szPassword | TURN password for authentication |
iKeepAliveInSecs | This 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.
hInst | An instance handle obtained from sipxInitialize. |
hTransport | Reference to a SIPX_TRANSPORT handle. This function will assign a value to the referenced handle. |
bIsReliable | If 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. |
szTransport | Transport 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" |
szLocalIP | IP address which is the source address for the write. |
iLocalPort | Port value from which the data will be sent. |
writeProc | Function pointer to the callback for writing data using the transport mechanism. |
szLocalRoutingId | A local routing id pass back to the write proc callback. |
pUserData | User 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.
hTransport | Handle to the external transport object. Obtained via a call to sipxConfigExternalTransportAdd |
szSourceIP | IP address which was the source of the data which was read. |
iSourcePort | Port value from which the data was sent. |
szLocalIP | Local IP address on which the data was received. |
iLocalPort | Local port value on which the data was received. |
pData | Pointer to the data which was received, which should point to a single and complete SIP message. |
nData | Size 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.
hTransport | Handle 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.
hTransport | Handle to the external transport object. Obtained via a call to sipxConfigExternalTransportAdd |
bRouteByUser | true 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
arrAddresses | Pre-allocated array to be popluated with ip addresses. |
arrAddressAdapter | For each record in arrAddresses, there is a corresponding record, with the same index, in arrAddressAdpater which represents the "sipx adapter name" for that address |
numAddresses | Input: 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.
hInst | Instance pointer obtained by sipxInitialize |
index | Index in the list of codecs |
pCodec | SIPX_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.
hInst | Instance pointer obtained by sipxInitialize |
pBandWidth | pointer 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.
hInst | Instance pointer obtained by sipxInitialize |
addresses | A pre-allocated list of SIPX_CONTACT_ADDRESS structures. This data will be filled in by the API call. |
nMaxAddresses | The maximum number of addresses supplied by the addresses parameter. |
nActualAddresses | The 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.
hInst | Instance pointer obtained by sipxInitialize |
szRemoteIp | IP of remote party |
iRemotePort | port or remote party |
szContactIp | Buffer to place local contact IP if successful |
nContactIpLength | Length of szContactIp buffer |
iContactPort | Int to place contact port |
iTimeoutMs | Timeout 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.
hInst | Instance pointer obtained by sipxInitialize |
pPort | Pointer 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.
hInst | Instance pointer obtained by sipxInitialize |
pPort | Pointer 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.
hInst | Instance pointer obtained by sipxInitialize |
pPort | Pointer 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.
hInst | Instance pointer obtained by sipxInitialize |
pNumCodecs | Pointer 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.
hInst | Instance pointer obtained by sipxInitialize |
pNumCodecs | Pointer 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.
szVersion | Buffer to store the version string. A zero-terminated string will be copied into this buffer on success. |
nBuffer | Size 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.
hInst | Instance pointer obtained by sipxInitialize |
szCaptureDevice | Character array to be populated by this function call. |
nLength | Max 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.
hInst | Instance pointer obtained by sipxInitialize |
arrSzCaptureDevices | Array of character arrays to be populated by this function call. |
nDeviceStringLength | Length of buffer in arrSzCaptureDevice array. |
nArrayLength | Number 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.
hInst | Instance pointer obtained by sipxInitialize |
index | Index in the list of codecs |
pCodec | SIPX_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.
hInst | Instance pointer obtained by sipxInitialize |
pBandWidth | pointer 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.
hInst | Instance pointer obtained by sipxInitialize |
bEnable | in-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.
hInst | Instance pointer obtained by sipxInitialize |
bEnable | Out-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.
hInst | Instance pointer obtained by sipxInitialize |
contactId | Contact 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. |
type | Designates the method of keep alives. |
remoteIp | Remote IP address used to send keep alives. The caller is responsible for converting hostnames to IP address. |
remotePort | Remote port used to send keep alives. |
keepAliveSecs | The number of seconds to wait before resending. If the value is <= 0, only one keep alive will be sent (calling sipxConfigKeepAliveRemove will fail). |
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.
hInst | Instance pointer obtained by sipxInitialize |
contactId | Contact 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. |
type | Designates the method of keep alives. |
remoteIp | Remote 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. |
remotePort | Remote port used to send keep alives. |
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.
hInst | Instance 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.
hInst | Instance 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.
hInst | Instance pointer obtained by sipxInitialize |
szCodecName | space 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.
hInst | Instance pointer obtained by sipxInitialize |
bandWidth | Valid 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.
hInst | Instance pointer obtained by sipxInitialize |
idleTimeout | The 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.
hInst | Instance pointer obtained by sipxInitialize. |
failoverTimeoutInSecs | Number 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):
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.
hInst | Instance pointer obtained by sipxInitialize |
szHeader | - Location header |
SIPXTAPI_API SIPX_RESULT sipxConfigSetLogCallback | ( | sipxLogCallback | pCallback | ) |
Set a callback function to collect logging information.
This function directs logging output to the specified function.
pCallback | is 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.
szFilename | The 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
logLevel | Designates 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.
hInst | Instance pointer obtained by sipxInitialize. |
szProxy | the 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.
hInst | Instance pointer obtained by sipxInitialize. |
nRegisterExpirationSecs | Number 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.
hInst | Instance pointer obtained by sipxInitialize. |
seconds | The 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.
hInst | Instance pointer obtained by sipxInitialize |
szDbLocation | The directory in which the certificate database resides. |
szMyCertNickname | The local user's certificate nickname, for database lookup. |
szDbPassword | The 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"
hInst | Instance 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.
hInst | Instance pointer obtained by sipxInitialize. |
nSubscribeExpirationSecs | Number 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.
hInst | Instance pointer obtained by sipxInitialize. |
szName | The user-agent name. |
bIncludePlatformName | Indicates 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.
hInst | Instance pointer obtained by sipxInitialize |
bandWidth | Valid bandwidth requirements are VIDEO_CODEC_BW_LOW, VIDEO_CODEC_BW_NORMAL, and VIDEO_CODEC_BW_HIGH. |
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoBitrate | ( | const SIPX_INST | hInst, |
const int | bitRate | ||
) |
Sets the video bitrate.
hInst | Instance pointer obtained by sipxInitialize |
bitRate | Bit rate parameter |
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoCaptureDevice | ( | const SIPX_INST | hInst, |
const char * | szCaptureDevice | ||
) |
Sets the video capture device.
hInst | Instance pointer obtained by sipxInitialize |
szCaptureDevice | Pointer 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.
hInst | Instance pointer obtained by sipxInitialize |
szCodecName | codec name |
SIPXTAPI_API SIPX_RESULT sipxConfigSetVideoCpuUsage | ( | const SIPX_INST | hInst, |
const int | cpuUsage | ||
) |
Set the cpu usage.
hInst | Instance pointer obtained by sipxInitialize |
cpuUsage | CPU 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.
hInst | Instance pointer obtained by sipxInitialize |
frameRate | Frame 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.
hInst | Instance pointer obtained by sipxInitialize |
bitRate | Bit rate parameter in kbps |
frameRate | Frame 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".
hInst | Instance pointer obtained by sipxInitialize |
pDisplay | Pointer 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.
hInst | Instance pointer obtained by sipxInitialize |
quality | Id 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.
hInst | An instance handle obtained from sipxInitialize. |
szServer | Target 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.
hInst | Instance pointer obtained by sipxInitialize |
hLine | Line Identity for the outbound call. The line identity helps defines the "From" caller-id. |
szTargetUrl | The Url of the publishing end-point. |
szEventType | A 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". |
szAcceptType | A 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" |
contactId | Id 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. |
phSub | Pointer 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.
hInst | Instance 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.
hSub | The 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.
hInst | Instance pointer obtained by sipxInitialize |
hWnd | Window 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.
phInst | A pointer to a hInst that must be various other sipXtapi routines. |
udpPort | The 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. |
tcpPort | The 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. |
tlsPort | NOT YET SUPPORTED |
rtpPortStart | The 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. |
maxConnections | The maximum number of simultaneous connections that the sipX layer will support. |
szIdentity | The 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. |
szBindToAddr | Defines 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. |
bUseSequentialPorts | If 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. |
szTLSCertificateNickname | Nickname of the certificate to use as an SSL server. |
szTLSCertificatePassword | Password for the SSL server certificate. |
szDbLocation | Path to the certificate database. |
bEnableLocalAudio | Enable use of local microphone and speaker. Set to false if you're running on a server hardware without a sound card. |
internalSamplerate | Samplerate 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. |
devicesSamplerate | Samplerate 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. |
internalFrameSizeMs | Size 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. |
callInputDeviceName | Name 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. |
callOutputDeviceName | Name 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.
hInst | Instance pointer obtained by sipxInitialize. |
szLineURL | The address of record for the line identity. Can be prepended with a Display Name. e.g. - "Zaphod Beeblebrox" <sip:zaphb@fourty-two.net> |
phLine | Pointer to a line handle. Upon success, a handle to the newly added line is returned. |
contactId | Id 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. |
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.
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.
hLine | Handle to a line appearance. Line handles are obtained by creating a line using the sipxLineAdd function or by receiving a line event notification. |
szUserID | user id used for the line appearance. |
szPasswd | passwd used for the line appearance. |
szRealm | realm 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.
hInst | Instance pointer obtained by sipxInitialize. |
szURI | URI used to search for a line definition |
hLine | line 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.
hInst | Instance pointer obtained by sipxInitialize. |
lines | Pre-allocated array of line handles. |
max | Maximum number of lines to return. |
actual | Actual 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.
hLine | Handle to a line appearance. Line handles are obtained by creating a line using the sipxLineAdd function or by receiving a line event notification. |
contactId | contact 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.
hLine | Handle to a line appearance. Line handles are obtained by creating a line using the sipxLineAdd function or by receiving a line event notification. |
szBuffer | Buffer to place line URL. A NULL value will return the amount of storage needed in nActual. |
nBuffer | Size of szBuffer in bytes (not to exceed) |
nActual | Actual 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.
hLine | Handle to a line appearance. Line handles are obtained by creating a line using the sipxLineAdd function or by receiving a line event notification. |
bRegister | true 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.
hLine | Handle 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
[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.
[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.
[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.
[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.
hInst | Instance pointer obtained by sipxInitialize. |
phPub | Pointer to a publisher handle - this method modifies the value to refer to the newly created publishing context. |
szResourceId | The 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 |
szEventType | A string representing the type of event that can be published. |
szContentType | String representation of the content type being published. |
pContent | Pointer to the NOTIFY message's body content. |
nContentLength | Size of the content to be published. |
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.
hPub | Handle of the publishing context to destroy (returned from a call to sipxCreatePublisher) |
szContentType | String representation of the content type being published |
pFinalContent | Pointer to the NOTIFY message's body content |
nContentLength | Size 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.
hPub | Handle of the publishing context (returned from a call to sipxCreatePublisher) |
szContentType | String representation of the content type being published |
pContent | Pointer to the NOTIFY message's body content |
nContentLength | Size 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).
phInst | A 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. |
udpPort | The 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. |
tcpPort | The 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. |
tlsPort | NOT YET SUPPORTED |
rtpPortStart | The 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. |
maxConnections | The maximum number of simultaneous connections that the sipX layer will support. |
szIdentity | The 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. |
szBindToAddr | Defines 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. |
bUseSequentialPorts | If 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. |
szTLSCertificateNickname | Nickname of the certificate to use as an SSL server. |
szTLSCertificatePassword | Password for the SSL server certificate. |
szDbLocation | Path to the certificate database. |
bEnableLocalAudio | Should 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.
hInst | An instance handle obtained from sipxInitialize. |
bForceShutdown | forces 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.
szUrl | The url to parse |
szParamName | Name of the url parameter |
nParamIndex | Index of the url parameter (zero-based). This is used if you have multiple url parameters with the same name – otherwise, you should use 0. |
szParamValue | Buffer to place parameter value |
nParamValue | size 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.
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.