IMFMediaSession::SetTopology method

Sets a topology on the Media Session.


HRESULT SetTopology(
  [in] DWORD       dwSetTopologyFlags,
  [in] IMFTopology *pTopology


dwSetTopologyFlags [in]

Bitwise OR of zero or more flags from the MFSESSION_SETTOPOLOGY_FLAGS enumeration.

pTopology [in]

Pointer to the topology object's IMFTopology interface.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return codeDescription

The method succeeded.


The operation cannot be performed in the Media Session's current state.


The Media Session has been shut down.


The topology has invalid values for one or more of the following attributes:


Protected content cannot be played while debugging.



If pTopology is a full topology, set the MFSESSION_SETTOPOLOGY_NORESOLUTION flag in the dwSetTopologyFlags parameter. Otherwise, the topology is assumed to be a partial topology. The Media Session uses the topology loader to resolve a partial topology into a full topology.

If the Media Session is currently paused or stopped, the SetTopology method does not take effect until the next call to IMFMediaSession::Start.

If the Media Session is currently running, or on the next call to Start, the SetTopology method does the following:

  • If the MFSESSION_SETTOPOLOGY_IMMEDIATE flag is set in dwSetTopologyFlags, the Media Session ends the current presentation immediately, clears all pending topologies, and uses pTopology to start a new presentation.
  • Otherwise, the Media Session queues pTopology and starts the new presentation when the current presentation has completed. If there is no current presentation, the new presentation starts immediately.
  • Starting in Windows 7, you can also specify the MFSESSION_SETTOPOLOGY_CLEAR_CURRENT flag to clear the current topology but leave any other pending topologies on the queue.

This method is asynchronous. If the method returns S_OK, the Media Session sends an MESessionTopologySet event when the operation completes. If the Media Session is currently paused to stopped, the Media Session does not send the MESessionTopologySet event until the next call to IMFMediaSession::Start


Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]





See also