IMFPMediaPlayer::CreateMediaItemFromURL method (mfplay.h)

Article
12/05/2018

[The feature associated with this page, MFPlay, is a legacy feature. It has been superseded by MediaPlayer and IMFMediaEngine. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer and IMFMediaEngine instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

Creates a media item from a URL.

Syntax

HRESULT CreateMediaItemFromURL(
  [in]  LPCWSTR       pwszURL,
  [in]  BOOL          fSync,
  [in]  DWORD_PTR     dwUserData,
  [out] IMFPMediaItem **ppMediaItem
);

Parameters

[in] pwszURL

Null-terminated string that contains the URL of a media file.

[in] fSync

If TRUE, the method blocks until it completes. If FALSE, the method does not block and completes asynchronously.

[in] dwUserData

Application-defined value to store in the media item. To retrieve this value from the media item, call IMFPMediaItem::GetUserData.

[out] ppMediaItem

Receives a pointer to the IMFPMediaItem interface. The caller must release the interface. If fSync is TRUE, this parameter must be a valid pointer. If bSync is FALSE, this parameter must be NULL.

Return value

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

Return code	Description
S_OK	The method succeeded.
E_INVALIDARG	Invalid argument.
MF_E_INVALIDREQUEST	Invalid request. This error can occur when fSync is FALSE and the application did not provide a callback interface. See Remarks.
MF_E_SHUTDOWN	The object's Shutdown method was called.
MF_E_UNSUPPORTED_SCHEME	Unsupported protocol.

Remarks

This method does not queue the media item for playback. To queue the item for playback, call IMFPMediaPlayer::SetMediaItem.

The CreateMediaItemFromURL method can be called either synchronously or asynchronously:

If fSync is TRUE, the method completes synchronously. The IMFPMediaItem pointer is returned in the ppMediaItem parameter.
If fSync is FALSE, the method completes asynchronously. When the operation completes, the application's IMFPMediaPlayerCallback::OnMediaPlayerEvent callback method is invoked. The event type is MFP_EVENT_TYPE_MEDIAITEM_CREATED. The event data contains the IMFPMediaItem pointer for the new media item.

The callback interface is set when you first call MFPCreateMediaPlayer to create the MFPlay player object. If you do not provide a callback interface, the fSync parameter must be TRUE. Otherwise, CreateMediaItemFromURL returns MF_E_INVALIDREQUEST.

If you make multiple asynchronous calls to CreateMediaItemFromURL, they are not guaranteed to complete in the same order. Use the dwUserData parameter to match created media items with pending requests.

Currently, this method returns MF_E_UNSUPPORTED_SCHEME if the URL specifies any of the following protocols: rtsp*, mms*, or mcast. If you want to use the Media Foundation network source with MFPlay, first use the Source Resolver to create the source, and then call IMFPMediaPlayer::CreateMediaItemFromObject.

Configuring the Source

Internally, this method creates a media source. To configure the media source, do the following:

Call QueryInterface on the IMFPMediaPlayer pointer to get the IPropertyStore interface.
Call IPropertyStore::SetValue to set properties for the media source. For a list of configuration properties, see Configuring a Media Source. Third-party media sources may define custom properties.
Call the CreateMediaItemFromURL method to create the media item.

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	mfplay.h

Partager via