IMFMediaEngineExtension::BeginCreateObject method (mfmediaengine.h)

Article
10/13/2021

Begins an asynchronous request to create either a byte stream or a media source.

Syntax

HRESULT BeginCreateObject(
  [in]           BSTR             bstrURL,
  [in]           IMFByteStream    *pByteStream,
  [in]           MF_OBJECT_TYPE   type,
  [out]          IUnknown         **ppIUnknownCancelCookie,
  [in]           IMFAsyncCallback *pCallback,
  [in, optional] IUnknown         *punkState
);

Parameters

[in] bstrURL

The URL of the media resource.

[in] pByteStream

A pointer to the IMFByteStream interface.

If the type parameter equals MF_OBJECT_BYTESTREAM, this parameter is NULL.

If type equals MF_OBJECT_MEDIASOURCE, this parameter either contains a pointer to a byte stream or is NULL. See Remarks for more information.

[in] type

A member of the MF_OBJECT_TYPE enumeration that specifies which type of object to create.

Value	Meaning
MF_OBJECT_BYTESTREAM	Create a byte stream. The byte stream must support the IMFByteStream interface.
MF_OBJECT_MEDIASOURCE	Create a media source. The media source must support the IMFMediaSource interface.

[out] ppIUnknownCancelCookie

Receives a pointer to the IUnknown interface. This pointer can be used to cancel the asynchronous operation, by passing the pointer to the IMFMediaEngineExtension::CancelObjectCreation method.

The caller must release the interface. This parameter can be NULL.

[in] pCallback

A pointer to the IMFAsyncCallback interface. This interface is used to signal the completion of the asynchronous operation.

[in, optional] punkState

A pointer to the IUnknown interface of an object implemented by the caller. You can use this object to hold state information for the callback. The object is returned to the caller when the callback is invoked. This parameter can be NULL.

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This method requests the object to create either a byte stream or a media source, depending on the value of the type parameter:

If type is MF_OBJECT_BYTESTREAM, the method creates a byte stream for the URL that is specified in bstrURL. In this case, the pByteStream parameter is NULL.
If type is MF_OBJECT_MEDIASOURCE, the method creates a media source, using the byte stream that is specified in the pByteStream parameter. Note that pByteStream can also be NULL in this case.

The method is performed asynchronously. The Media Engine calls the IMFMediaEngineExtension::EndCreateObject method to complete the operation.

Implementation Notes

A Media Engine extension can be used to support a custom byte stream object, a custom media source, or both. For a byte stream, create the byte stream object when type equals MF_OBJECT_BYTESTREAM. For a media source, create the source when the type equals MF_OBJECT_MEDIASOURCE.

To load a URL, the Media Engine performs the following steps:

Try to create a byte stream from the URL.
If a byte stream is successfully created, try to create a media source from the byte stream.
If a byte stream cannot be created, try to create a media source directly from the URL.

At each step, the Media Engine calls IMFMediaEngineExtension::BeginCreateObject on the extension object. If the BeginCreateObject method fails, the Media Engine tries the Source Resolver.

In your BeginCreateObject method, you can choose to handle any of the following cases:

The type parameter is MF_OBJECT_BYTESTREAM. Create a byte stream from the URL.
The type parameter is MF_OBJECT_MEDIASOURCE and pByteStream points to a byte stream. Use the byte stream to create a media source.
The type parameter is MF_OBJECT_MEDIASOURCE and pByteStream is NULL. Create a media source from the URL.

Return a failure code for any cases that you do not handle.

Examples:

To support a custom media format, implement a media source. If the media source does not require any special byte-stream implementation, create the media source when type is MF_OBJECT_MEDIASOURCE and pByteStream is non-NULL. The standard Microsoft Media Foundation byte stream implementation will be used in this case.
To support a custom URL scheme, handle the case where type is MF_OBJECT_BYTESTREAM and return a byte stream object that is capable of reading the URL.

If the BeginCreateObject method succeeds, the operation should be performed asynchronously. When the operation completes, call the IMFAsyncCallback::Invoke method on the callback interface specified in pCallback. The Media Engine completes the operation by calling IMFMediaEngineExtension::EndCreateObject.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	mfmediaengine.h