The TransferLine procedure is used to transfer an active call to another destination location. It is similar in functionality to the TransferLineUri(String, Boolean, Int32) API procedure.

The call to be transferred can also be on hold prior to the transfer operation. Transfer operations are supported for the following scenarios:

Direct SIP to SIP transfers
Indirect SIP to SIP transfers via a SIP proxy
Direct SIP to PSTN transfers via a PSTN Gateway

Call transfers share similar characteristics with placing outgoing phone calls. For additional information regarding the UserNameOrPhoneNumber and DestinationAddress parameters, please see the MakeCall(String, String, UInt32, Int32, Boolean, UInt32) API procedure.

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

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE TransferLine(
	string UserNameOrPhoneNumber,
	string DestinationAddress,
	int DestinationSipPort,
	int PhoneLine
)
Visual Basic (Declaration)
Public Function TransferLine ( _
	UserNameOrPhoneNumber As String, _
	DestinationAddress As String, _
	DestinationSipPort As Integer, _
	PhoneLine As Integer _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
Visual C++
public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE TransferLine(
	String^ UserNameOrPhoneNumber, 
	String^ DestinationAddress, 
	int DestinationSipPort, 
	int PhoneLine
)
J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE TransferLine(
	String UserNameOrPhoneNumber,
	String DestinationAddress,
	int DestinationSipPort,
	int PhoneLine
)

Parameters

UserNameOrPhoneNumber
Type: System..::.String
This parameter specifies either the user name of the SIP transfer endpoint or it specifies the PSTN (land line) phone number of the transfer destination. Its value depends on whether you are making direct SIP to SIP transfers, SIP to SIP transfers via a SIP proxy, or SIP to PSTN transfers via a PSTN gateway device.

SIP to SIP Transfers:

The UserNameOrPhoneNumber parameter is the user name assigned to the target 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 Transfers via a SIP proxy:

The UserNameOrPhoneNumber parameter is the user name assigned to the new far end transfer target (the destination of the transfer). The SIP proxy will use this name when contacting the new call destination on behalf of the transferred party. The transferred parties telephony engine will send its new SIP invite directly to the SIP proxy. The DestinationAddress parameter contains the SIP domain name for the proxy (Example: "MyCompanyName.com"). The transferred party's telephony engine used its preconfigured SIP proxy settings the user had specified using the EnableSipProxyServer(String, UInt32) API procedure. For SIP proxy transfers to function, all SIP endpoints must be configured with the same SIP proxy information (i.e. SIP proxy address and domain name).

Transfer to PSTN Phone Numbers via a PSTN Gateway:

The UserNameOrPhoneNumber parameter is the phone number of the PSTN "land line" that will be used as the transfer target. In this case, the transferred party's telephony engine sends a new 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 could transfer another SIP endpoint to a local, domestic or international call number using something similar to the following syntax:

"555-1234" Local Call
"999-555-1234" Long Distance Call
"+441454203490" An International Call


DestinationAddress
Type: System..::.String
The value of this parameter depends on the type of phone call to be placed. The value of this parameter can be either:

SIP to SIP Transfers:

The network address of the far end device that will act as the transfer target. 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 Transfers 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". For SIP proxy transfers to function, all SIP endpoints must be configured with the same SIP proxy information (i.e. SIP proxy address and domain name).

Transfer to 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..::.Int32
This parameter specifies the UDP port where the transfer target's telephony engine will send additional SIP packets. This parameter in conjunction with the DestinationAddress specified earlier creates a fully qualified network description for the transfer target.
PhoneLine
Type: System..::.Int32
The zero based telephony engine phone line that will be used to transfer the phone call.

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)

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)

SipTransfrerNotAllowed
Application software attempted to transfer a phone call using the TransferLine(String, String, Int32, Int32) API procedure that was placed on hold by the far end. Transferring a call when the far end has placed the call on hold is not supported. The only options that are possible are to: wait for the far end to remove the call from the hold state and then perform the transfer, or terminate the phone call by executing the TerminateCall(Int32, Boolean, UInt32) API procedure.

(API return value)

SipNoCallActive
Indicates that application software attempted an operation on a phone line and the phone line was not in a proper state to carry out the request. The following scenarios can generate this error: Calling the ConferenceLine(Int32, Boolean) API procedure when the phone line is not in the SipInCall or SipCallHold states. Calling the TransferLine(String, String, Int32, Int32) API procedure when the phone line is not in the SipInCall or SipCallHold states. Attempting to open a transmit media stream to a phone line using the OpenTxIvrChannel(VoipMediaEngine, Int32, Int32) API procedure and the phone line is not in the SipInCall or SipCallHold states. Application software executed the TransmitInCallIvrData(array<Object>[]()[]) API procedure using a particular phone line and the phone line was no longer in the SipInCall state.

(API return value)

Remarks

None.

See Also