ITStream::SelectTerminal method (tapi3if.h)

The SelectTerminal method selects an ITTerminal object onto the stream.

Syntax

HRESULT SelectTerminal(
  ITTerminal *pTerminal
);

Parameters

pTerminal

Pointer to ITTerminal interface of selected terminal.

Return value

This method can return one of these values.

Value Meaning
S_OK
Method succeeded.
E_POINTER
The pTerminal parameter is not a valid pointer.
E_OUTOFMEMORY
Insufficient memory exists to perform the operation.
TAPI_E_MAXTERMINALS
Multiple terminals have been selected on the stream, but media mixing or splitting is not possible.
TAPI_E_INVALIDTERMINAL
The terminal selected is not valid.

Remarks

Terminals can be selected at any time, irrespective of whether the transport is in a state that allows it to stream media. If the transport is in a state that allows it to stream media, and the application has not successfully invoked ITStream::PauseStream or ITStream::StopStream on the stream, or has successfully invoked ITStream::StartStream for this stream more recently than it has successfully invoked ITStream::PauseStream or ITStream::StopStream for this stream, then streaming starts automatically as soon as the terminal is selected. If a terminal is selected on the stream before the transport enters a state in which it can stream media, and no subsequent calls to StopStream or PauseStream are made, then the stream starts automatically when the transport enters a state in which it can stream media.

The CME_STREAM_ACTIVE event is generated when streaming actually starts, which may be later than the SelectTerminal call. The CME_STREAM_FAIL or CME_TERMINAL_FAIL event is generated when streaming actually fails, which may also be later than the SelectTerminal call.

A terminal can be selected onto a stream only if the results of ITTerminal::get_MediaType match ITStream::get_MediaType. In addition, some MSPs may require a match between ITTerminal::get_Direction and ITStream::get_Direction, although the interface does not enforce this.

Some MSPs may not allow more than a certain number of terminals, typically one, to be simultaneously selected on the same stream, but the interface itself does not enforce any such restriction. Selecting multiple terminals at one time on the same stream is useful, for example, to allow recording of an incoming audio stream to a file while listening to the stream on a pair of speakers.

A given terminal can be selected onto only one stream.

Requirements

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

See also

ITStream

Media Service Provider Interface (MSPI)