ITAddress::CreateCall method (tapi3if.h)

Article
10/13/2021

The CreateCall method creates a new Call object that can be used to make an outgoing call and returns a pointer to the object's ITBasicCallControl interface. The newly created call is in the CS_IDLE state and has no media or terminals selected.

Acceptable input values for call address, address type, and media types are specific to the telephony service provider that supports the current address. For information on TSPs shipped with Windows 2000, see About The Telephony Service Provider (TSP). For third party TSPs, see the documentation provided by the vender.

Syntax

HRESULT CreateCall(
  [in]  BSTR               pDestAddress,
  [in]  long               lAddressType,
  [in]  long               lMediaTypes,
  [out] ITBasicCallControl **ppCall
);

Parameters

[in] pDestAddress

This BSTR string contains a destination address. The format is provider-specific. This pointer can be NULL for non-dialed addresses (such as with a hot phone) or when all dialing is performed using ITBasicCallControl::Dial. NULL in combination with a NULLpGroupID in ITBasicCallControl::Pickup results in a group pickup. Service providers that have inverse multiplexing capabilities can allow an application to specify multiple addresses at once.

[in] lAddressType

Contains an address type constant, such as LINEADDRESSTYPE_PHONENUMBER, which describes the format of the address. The value must be valid for this address. Use ITAddressCapabilities::get_AddressCapability with AddressCap set to AC_ADDRESSTYPES to verify the value.

[in] lMediaTypes

Identifies the media type or types that will be involved in the call session.

[out] ppCall

Pointer to ITBasicCallControl interface.

Return value

This method can return one of these values.

Value	Meaning
S_OK	Method succeeded.
E_INVALIDARG	The address type, lAddressType, is invalid or specifies more than one address type.
E_OUTOFMEMORY	Insufficient memory exists to perform the operation.
E_POINTER	The ppCall parameter is not a valid pointer.

Remarks

The application must use SysAllocString to allocate memory for the pDestAddress parameter and use SysFreeString to free the memory when the variable is no longer needed.

When the address type is LINEADDRESSTYPE_SDP, the application should call the ITSDP::get_IsValid method on pDestAddress to verify that the SDP information contained is properly constructed according to RFC 2327.

Calls used as consultation calls, such as during a conference, transfer, or forward operation, must be created using this method.

TAPI calls the AddRef method on the ITBasicCallControl interface returned by ITAddress::CreateCall. The application must call Release on the ITBasicCallControl interface to free resources associated with it.

Note This method is not precisely the same as lineMakeCall in TAPI 2. It supplies TAPI with much of the same information, but parallel operations are not performed until ITBasicCallControl::Connect is called.

Requirements

Requirement	Value
Target Platform	Windows
Header	tapi3if.h (include Tapi3.h)
Library	Uuid.lib
DLL	Tapi3.dll