MakeCall

The MakeCall API procedure is executed by application software to initiate out going phone calls.

TELEPHONY_RETURN_VALUE MakeCall(

SIPHANDLE hStateMachine,

char *pUserNameOrPhoneNumber,

char *pDestinationAddress,

int DestinationSipPort,

int PhoneLine,

BOOL Synchronous,

DWORD TimeOutMs

);

This API procedure can be used to place the following outgoing phone call types:

Directly call other SIP endpoints (Intranet or Internet)

Call SIP endpoints via a SIP proxy (Intranet or Internet)

Call local, Domestic or international phone numbers using a PSTN gateway

Parameters:

hStateMachine

[in] The handle to the telephony engine. This is the handle that was returned by a previous call to the StartSipTelephony procedure.

pUserNameOrPhoneNumber

[in] This parameter specifies either the user name of the SIP call endpoint or it specifies the PSTN (land line) phone number you want to call. Its value depends on whether you are making direct SIP to SIP calls, SIP to SIP calls via a SIP proxy, or SIP to PSTN calls via a PSTN gateway device.

SIP to SIP calls:

The pUserNameOrPhoneNumber parameter is the user name assigned to the far end sip device. In this case, the pDestinationAddress parameter specifies the location of the SIP endpoint directly (i.e. the network name or IP address of the SIP endpoint). In a PBX environment, this would be the user name or numerical extension assigned to a particular IP phone device.

SIP to SIP calls via a SIP proxy:

The pUserNameOrPhoneNumber parameter is the user name assigned to the far end sip device. The SIP proxy will use this name when contacting the far end SIP device on our behalf. The telephony engine will send the SIP invite directly to the SIP proxy. The pDestinationAddress parameter contains the SIP domain name for the proxy (Example: “MyCompanyName.com”). The telephony engine communicates with the SIP proxy using the information that was specified in a call to the EnableSipProxyServer API procedure.

Note: If the telephony engine is configured to use a SIP proxy server and a SIP domain, you can still place direct SIP to SIP phone calls if you specify the raw IP address of the destination or the UNC network name of the destination in the pDestinationAddress parameter. In other words, you can call within your domain if you set the pDestinationAddress parameter to be your domain name. You can also call outside of your domain if you simply specify a raw IP address or the UNC network name of the destination.

PSTN Phone Numbers via a PSTN Gateway:

The pUserNameOrPhoneNumber parameter is the phone number of the PSTN “land line” to call. In this case, the telephony engine sends the SIP invite message directly to a PSTN gateway address as specified by the pDestinationAddress parameter.

Depending on the PSTN gateway you are using, application software will be able to make local, domestic or international calls if parameter pUserNameOrPhoneNumber is set to something similar to the following:

“555-1234” Local Call

“999-555-1234” Long Distance Call

“+441454203490” An International Call

For those developers experienced with the contents of SIP header fields, the pUserNameOrPhoneNumber parameter is used to populate the SIP “user” field in the INVITE message. In this way, application software can create the proper PSTN dial string. For additional information, please refer to your PSTN gateway documentation.

pDestinationAddress

[in] The value of this parameter depends on the type of phone call to be placed. The value of this parameter falls within one of the following categories:

SIP to SIP calls:

The network address of the far end device you are attempting to call. Network addresses can be specified as an IP address in dotted decimal format (i.e. 192.168.0.1) or a UNC network name of the device on the network. When making direct SIP to SIP phone calls, no other network entities are involved.

SIP to SIP calls via a SIP proxy:

The domain name of the SIP proxy server. The SIP proxy domain name specified here must be the same as what you have configured via the EnableSipDomain API procedure. SIP domain names are generally specified as ‘MyCompanyName.com”

PSTN Phone Numbers via a PSTN Gateway:

The network address of the PSTN gateway. Network addresses can be specified as an IP address in dotted decimal format (i.e. 192.168.0.1) or a UNC network name of the device on the network.

DestinationSipPort

[in] This parameter specifies the UDP port where the telephony engine will send SIP packets. This parameter in conjunction with the pDestinationAddress specified earlier creates a fully qualified network description.

PhoneLine

[in] The zero based telephony engine phone line that will be used to make the out going phone call.

Synchronous

[in] If this parameter is non zero (TRUE), the procedure will not return until: the call is connected, an error has been detected, or a user specified timeout has occurred. If this parameter is zero (FALSE), then MakeCall will return immediately with the return value of SipSuccess.

If you do not place a phone call synchronously, the call’s progress and state changes should be monitored by application software using the event notification callback mechanism.

TimeOutMs

[in] If the phone call is being made synchronously, then this parameter specifies the maximum timeout in milliseconds the procedure will wait for the call to go active (answered by the far end).

Return Value:

If the function succeeds, the return value will be SipSuccess.

If the function fails, the return value will be one of the following values as specified by the TELEPHONY_RETURN_VALUE data type.

Value	Description
SipCallFailure	This is a generic "catch all" API error. If an error condition is not specified by any other API error value, this error will be returned.
SipBadParameter	For API procedures that receive pointers from user software, this error indicates that a NULL pointer condition was detected. Make sure all pointers your software passes to the telephony API are valid.
SipInvalidHandle	An API procedure was passed an invalid handle. The telephony engine attempts to verify user specified telephony handles and returns this error when an invalid handle is detected.
SipNotEnabled	A telephony API operation was attempted but the telephony engine has not yet been enabled. For example: You will get this error if you attempt to place an out bound phone call using the MakeCall API procedure when the telephony engine is not yet enabled. After the telephony engine is instantiated, perform all other required configuration. The last step to perform is to enable the telephony engine using the SipTelephonyEnable API procedure. Once the telephony engine is enabled, you will be able to receive and initiate calls.
SipBadUserName	When making an out bound call using the MakeCall API procedure, the pointer to the call's destination user name was either a NULL pointer or the destination user name contained white space characters. Specify a valid destination user name pointer parameter. Also, destination user names must contain no white space characters.
SipDomainNameNotDefined	A telephony operation was specified that requires a SIP domain name to be defined. Call the EnableSipDomain API procedure before attempting this operation.
SipCallAlreadyInProgress	SWITCH_LINE Mode: When the telephony engine is instantiated in SWITCH_LINE mode, multiple calls can be placed on separate lines at the same time. This error is returned only if application software requests that a new out bound call be initiated on a phone line that is already handling a phone call. For further information see LINE_MODE
SipUnknownHost	The telephony engine failed to resolve the IP address of another machine that was specified by a UNC network name. This error predominately occurs when the specified name of the target machine is spelled incorrectly. How IP addresses are resolved depends on your network configuration. Normally DNS is recommended for IP address resolution. Other possibilities are WINS name resolution or NetBios. Make sure your network is properly configured for name resolution.
SipFarEndIsBusy	When making an out bound phone call using the MakeCall API procedure, this error is returned if the far end of the call indicates that it is busy.
SipFarEndError	When making an out bound phone call using the MakeCall API procedure, this error is returned if the far end of the call indicates that it detected an error during call setup. This error can happen if you call another SIP enabled device that does not support the media type the out bound call was configured to use.
SipCallTimeOut	Indicates that the operation timed out waiting for completion. To remove this error, increase the time out value specified to complete the operation.
SipLineBusyOut	Indicates that a telephony operation was requested on a phone line that has been "busied out". To remove this error, remove the phone line from the "busy out" state and try the operation again. Any phone line that has been taken out of service (busied out) can not be used.
SipBadPhoneLine	A telephony operation was specified using an invalid phone line. Phone lines are numbered starting from zero.
SipMemoryError	A memory error was detected while attempting to initiate the outgoing call.
SipPhoneLineAccessError	An internal error was detected that disallowed access to internal phone line data.
SipOutgoingCallStateError	An internal state error was detected while attempting to make the outgoing call. Contact LanScape support if you detect this error.
SipCallStateHistoryMustBeRead	This error return value indicates that call state history for the phone line has been enabled and existing call state history must be cleared before attempting to use the phone line again. Call the ClearRecordedCallStates API procedure to clear the phone line's current call state history and try the call again.