ITTerminalSupport::CreateTerminal method (tapi3if.h)

Article
02/22/2024

The CreateTerminal method creates and initializes a new ITTerminal object based on the dynamic terminal class and media. The terminal class is identified by a GUID. The GUID must be converted to a string using StringFromIID to pass to this method.

Syntax

HRESULT CreateTerminal(
  [in]  BSTR               pTerminalClass,
  [in]  long               lMediaType,
  [in]  TERMINAL_DIRECTION Direction,
  [out] ITTerminal         **ppTerminal
);

Parameters

[in] pTerminalClass

Pointer to BSTR containing the terminal class (GUID) for the new terminal object.

[in] lMediaType

Pointer to the media type for the new terminal object.

[in] Direction

TERMINAL_DIRECTION descriptor of the terminal direction.

[out] ppTerminal

Pointer to the ITTerminal object created.

Return value

This method can return one of these values.

Value	Meaning
S_OK	Method succeeded.
E_INVALIDARG	The pTerminalClass or lMediaType parameter is not valid.
E_POINTER	The ppTerminal parameter is not a valid pointer.
E_OUTOFMEMORY	Insufficient memory exists to create the ITTerminal object.
E_MEDIATYPE	The lMediaType parameter is invalid.
TAPI_E_NOTSUPPORTED	Dynamic terminal creation is not supported.

Remarks

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

Once a terminal is created, it can be selected onto only one call.

TAPI calls the AddRef method on the ITTerminal interface returned by ITTerminalSupport::CreateTerminal. The application must call Release on the ITTerminal interface to free resources associated with it.

Requirements

Requirement	Value
Target Platform	Windows
Header	tapi3if.h (include Tapi3.h)