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

Namespace:  LanScape
Assembly:  LMEVoipManaged (in LMEVoipManaged.dll) Version: 6.0.5226.26700

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE MakeCall(
	string UserNameOrPhoneNumber,
	string DestinationAddress,
	uint DestinationSipPort,
	int PhoneLine,
	bool Synchronous,
	uint TimeOutMs
)
Visual Basic (Declaration)
Public Function MakeCall ( _
	UserNameOrPhoneNumber As String, _
	DestinationAddress As String, _
	DestinationSipPort As UInteger, _
	PhoneLine As Integer, _
	Synchronous As Boolean, _
	TimeOutMs As UInteger _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
Visual C++
public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE MakeCall(
	String^ UserNameOrPhoneNumber, 
	String^ DestinationAddress, 
	unsigned int DestinationSipPort, 
	int PhoneLine, 
	bool Synchronous, 
	unsigned int TimeOutMs
)
J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE MakeCall(
	String UserNameOrPhoneNumber,
	String DestinationAddress,
	UInt32 DestinationSipPort,
	int PhoneLine,
	boolean Synchronous,
	UInt32 TimeOutMs
)

Parameters

UserNameOrPhoneNumber
Type: System..::.String
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 UserNameOrPhoneNumber parameter is the user name assigned to the far end sip device. In this case, the DestinationAddress 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 UserNameOrPhoneNumber 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 DestinationAddress 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(String, UInt32) 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 DestinationAddress parameter. In other words, you can call within your domain if you set the DestinationAddress 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 UserNameOrPhoneNumber 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 DestinationAddress parameter.

Depending on the PSTN gateway you are using, application software will be able to make local, domestic or international calls if parameter UserNameOrPhoneNumber 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 UserNameOrPhoneNumber 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.



DestinationAddress
Type: System..::.String
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(String) 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
Type: System..::.UInt32
This parameter specifies the UDP port where the telephony engine will send SIP packets. This parameter in conjunction with the DestinationAddress specified earlier creates a fully qualified network description.
PhoneLine
Type: System..::.Int32
The zero based telephony engine phone line that will be used to make the out going phone call.
Synchronous
Type: System..::.Boolean
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
Type: System..::.UInt32
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 VoipMediaEngine..::.TELEPHONY_RETURN_VALUE data type.

Return ValueDescription
SipCallFailure
This value is returned by telephony API procedures to indicate general API failure. This error value is used as a "catch all error". If you receive this error, check to make sure that all parameters specified in the API procedure call are correct. Particularly, verify that pointers to memory regions are valid. This error return value is only used if a mapping to another specific error value does not exist.

(API return value)

SipBadParameter
One of the telephony API procedures was called by application software and was passed a pointer to an invalid memory address. Normally this error will occur when application software passes NULL pointer values to the telephony API. For managed code applications, you should never see this error unless your process space has exhausted memory.

(API return value)

SipInvalidHandle
Application software specified an invalid telephony handle in one of the API procedures. This usually indicates memory corruption on the part of application software.

(API return value)

SipNotEnabled
Indicates that the telephony engine was not enabled for normal operation. Application software should always execute the SipTelephonyEnable()()() API procedure as the final step during configuration when initializing the telephony engine.

(API return value)

SipBadUserName
A bad Sip user name string was passed to the MakeCall(String, String, UInt32, Int32, Boolean, UInt32) or MakeCallUri(String, Boolean, Int32, Boolean, UInt32) API procedures.

(API return value)

SipDomainNameNotDefined
Application software has configured proxy services but has not specified a SIP domain name using the EnableSipDomain(String) API procedure. This error can be generated for the following API procedures: TransferLine(String, String, Int32, Int32), MakeCall(String, String, UInt32, Int32, Boolean, UInt32), MakeCallUri(String, Boolean, Int32, Boolean, UInt32), and EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean).

(API return value)

SipCallAlreadyInProgress
Another phone call (incoming or outgoing) is in the process of entering the SipInCall state. An application can not initiate new phone calls unless all active calls have entered the SipInCall state.

(API return value)

SipUnknownHost
A network address was specified as a UNC name and DNS was used to obtain the destination IP address. DNS could not resolve the UNC network name. Make sure the spelling you specified for the destination machine is correct.

(API return value)

SipFarEndIsBusy
This event informs the application software that an attempt was made to place a call to the specified destination. The call failed because the destination is busy (already in a phone call).

(API return value, PHONE_LINE_NOTIFICATION)

SipFarEndError
This event informs the application software that an attempt was made to place a call to the specified destination. The destination existed and participated in the call's session setup. However, the call failed because the destination returned an error response when the call was being set up. Normally this is due to incompatibilities in streaming media support or possible issues associated with user and password log in, etc. at the far end.

(API return value, PHONE_LINE_NOTIFICATION)

SipCallTimeOut

Making an outbound call:

Indicates that a call was initiated using the MakeCall(String, String, UInt32, Int32, Boolean, UInt32) or MakeCallUri(String, Boolean, Int32, Boolean, UInt32) API procedures and call setup did not complete in the time specified. Either the call destination did not respond (is overloaded), the destination of the call is off line, or your host machine could not handle call setup in the time specified. To remove this error, increase the time out value specified to complete the operation.

Terminating a call:

Indicates that a call was terminated using the TerminateCall(Int32, Boolean, UInt32) API procedure and call tear down did not complete in the time specified. Either the call destination did not respond (is overloaded), the destination of the call is off line, or your host machine could not handle call termination in the time specified. To remove this error, increase the time out value specified to complete the operation.

Answering an inbound call:

Indicates that an inbound call was being answered using the GoOffHook(Int32) API procedure and call setup did not complete in the time specified. Either the call destination did not respond (is overloaded), the destination of the call is off line, or your host machine could not answer the call in the time specified. To remove this error, increase the time out value specified to complete the operation.

(API return value)

SipLineBusyOut
Application software attempted to use a phone line that was previously taken out of service by calling the BusyOutLine(Int32, Boolean) API procedure. Return the phone line to service and try the operation again. A phone line is placed back into service by calling the BusyOutLine(Int32, Boolean) API procedure with a value of FALSE.

(API return value)

SipBadPhoneLine
Application software called a telephony API procedure and specified an invalid phone line. Phone lines are numbered starting from zero. This error is most commonly returned when attempting to access phone lines in excess of the max number of lines supported by the telephony engine.

(API return value)

SipMemoryError
The telephony engine attempted to allocate system memory but the allocation failed. Make sure the host system has enough virtual memory. Increasing the amount of virtual memory can remove these errors, however if critical telephony engine code has been swapped out to disk and is not resident in physical memory, you may experience degraded audio/video performance. If you want to remove this error and obtain the best possible audio/video performance, make sure the host system has enough physical memory. To resolve this error, you may also want to consider disabling certain features of the media engine such as conference calling. You can also reduce memory requirements if you reduce the maximum signal length of internal media engine signal paths by specifying a smaller number for the MaxMixerLinebuffers member of the VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS class that is passed to the StartSipTelephony(VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS) and ReStartSipTelephony(VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS) API procedures.

(API return value, PHONE_LINE_NOTIFICATION)

SipPhoneLineAccessError
This value may be returned when initiating outgoing calls. It indicates there was an internal error detected while accessing internal phone line data. If you continually see this error, please contact LanScape support.

(API return value)

SipOutgoingCallStateError
An internal state error was detected while attempting to make an outgoing call using either the MakeCall(String, String, UInt32, Int32, Boolean, UInt32) or MakeCallUri(String, Boolean, Int32, Boolean, UInt32) API procedures. Contact LanScape support if you detect this error.

(API return value)

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(Int32) API procedure to clear the phone line's current call state history and try the call again.

(API return value)

Remarks

None.

See Also