Microsoft DirectX 8.0

IMediaDet Interface

Retrieves information about a media file, such as the number of streams and the type, duration, and frame rate of each stream. This interface also contains methods for retrieving poster frames from a video stream. The media detector exposes this interface. Use this interface in Microsoft® DirectShow® Editing Services (DES) applications.

To obtain information about a file, perform the following steps:

  1. Create an instance of the media detector by calling CoCreateInstance. The class ID is CLSID_MediaDet.
  2. Call put_Filename to specify the name of the source file. (Alternatively, call put_Filter.)
  3. Call get_OutputStreams to obtain the number of output streams in the source.
  4. Call put_CurrentStream to specify a particular stream.
  5. Call any of the following methods: get_StreamType, get_StreamMediaType, get_StreamLength, or get_FrameRate.

To retrieve poster frames, call GetBitmapBits or WriteBitmapBits. Alternatively, call EnterBitmapGrabMode and then GetSampleGrabber to obtain a pointer to the ISampleGrabber interface. All three of these methods put the media detector into a new mode, called bitmap grab mode. The informational methods described previously do not work in this mode. Therefore, obtain any information you need before retrieving poster frames, or else create new instances of the media detector for each stream.

Requirements

Requires Qedit.h.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IMediaDet MethodsDescription
get_FilterRetrieves a pointer to the source filter currently used by the media detector.
put_FilterSpecifies a source filter for the media detector to use.
get_OutputStreamsRetrieves the number of output streams contained in the media source.
get_CurrentStreamRetrieves the stream number currently used by the media detector.
put_CurrentStreamSpecifies the stream number for the media detector to use.
get_StreamTypeRetrieves the globally unique identifier (GUID) for the media type of the current stream.
get_StreamTypeBRetrieves a string representing the GUID of the media type for the current stream.
get_StreamLengthRetrieves the duration of the current stream.
get_FilenameRetrieves the name of the source file currently used by the media detector.
put_FilenameSpecifies the name of the source file for the media detector to use.
GetBitmapBitsRetrieves a poster frame at the specified media time.
WriteBitmapBitsRetrieves a poster frame at the specified media time and writes it to a file.
get_StreamMediaTypeRetrieves the media type of the current stream.
GetSampleGrabberRetrieves a pointer to the ISampleGrabber interface.
get_FrameRateRetrieves the frame rate of the current stream.
EnterBitmapGrabModeSwitches the media detector to bitmap grab mode and seeks the filter graph to a specified time.

IMediaDet::EnterBitmapGrabMode

IMediaDet Interface

Switches the media detector to bitmap grab mode and seeks the filter graph to a specified time.

Syntax

HRESULT EnterBitmapGrabMode(
    double StreamTime
);

Parameters

StreamTime
Time, in seconds, to which the graph seeks.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess.
E_INVALIDARGInvalid argument.
VFW_E_INVALIDMEDIATYPEFile does not have a video stream.
VFW_E_TIME_EXPIREDCould not seek.

Remarks

Before calling this method, set the file name and stream by calling put_Filename and put_CurrentStream.

This method inserts the Sample Grabber filter into the filter graph. You can then call GetSampleGrabber to obtain a pointer to the ISampleGrabber interface. Once the media detector enters bitmap grab mode, the various informational methods in IMediaDet do not work.

The GetBitmapBits or WriteBitmapBits methods also put the media detector into bitmap grab mode.

IMediaDet::GetBitmapBits

IMediaDet Interface

Retrieves a poster frame at the specified media time.

Syntax

HRESULT GetBitmapBits(
    double StreamTime, 
    long *pBufferSize, 
    char *pBuffer, 
    long Width, 
    long Height
);

Parameters

StreamTime
Time at which to retrieve the poster frame.
pBufferSize
Pointer to a variable that receives the required buffer size. If pBuffer is NULL, the variable receives the size of the buffer needed to retrieve the poster frame. If pBuffer is not NULL, this parameter is ignored.
pBuffer
Pointer to a buffer that receives the poster frame.
Width
Width of the poster frame image, in pixels.
Height
Height of the poster frame image, in pixels.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess.
E_NOINTERFACECould not add the Sample Grabber filter to the graph.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer error.
E_UNEXPECTEDUnexpected error.
VFW_E_INVALIDMEDIATYPEInvalid media type.

Remarks

Before calling this method, set the file name and stream by calling put_Filename and put_CurrentStream.

To determine the size of the buffer that is required, call this method with pBuffer equal to NULL. The size is returned in the variable pointed to by pBufferSize. Then create the buffer and call the method again, as shown in the following code.

long BufferSize = 0;
GetBitmapBits(StreamTime, &BufferSize, NULL, Width, Height);
char *pBuffer = new char[BufferSize];
GetBitmapBits(StreamTime, 0, pBuffer, Width, Height);

This method puts the media detector into bitmap grab mode. Once this method has been called, the various stream information methods in IMediaDet do not work, unless you create a new instance of the media detector.

IMediaDet::get_CurrentStream

IMediaDet Interface

Retrieves the stream number currently used by the media detector.

Syntax

HRESULT get_CurrentStream(
    long *pVal
);

Parameters

pVal
[out, retval] Pointer to a variable that receives the current stream number.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IMediaDet::get_Filename

IMediaDet Interface

Retrieves the name of the source file currently used by the media detector.

Syntax

HRESULT get_Filename(
    BSTR *pVal
);

Parameters

pVal
[out, retval] Pointer to a variable that receives the file name.

Return Value

Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.

Remarks

The method allocates memory for the string. The application must call SysFreeString to free the memory.

IMediaDet::get_Filter

IMediaDet Interface

Retrieves a pointer to the source filter currently used by the media detector.

Syntax

HRESULT get_Filter(
    IUnknown **ppVal
);

Parameters

ppVal
[out, retval] Address of a pointer to receive the filter's IUnknown interface. If no source filter is in use, the value is set to NULL.

Return Value

Returns an HRESULT value.

Remarks

When the method returns, if *ppVal is not NULL, the IUnknown interface has an outstanding reference count. Be sure to release the interface when you are finished using it.

IMediaDet::get_FrameRate

IMediaDet Interface

Retrieves the frame rate of the current stream. The stream must be a video stream.

Syntax

HRESULT get_FrameRate(
    double *pVal
);

Parameters

pVal
[out, retval] Pointer to a variable that receives the frame rate, in frames per second.

Return Value

Returns an HRESULT value. Possible values include the following:

S_FALSEVideo format header does not specify a frame rate.
S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERNULL pointer argument.
VFW_E_INVALIDMEDIATYPEInvalid media type.

Remarks

This method cannot retrieve the frame rate from an ASF file.

Before calling this method, set the file name and stream by calling put_Filename and put_CurrentStream.

If the media detector is in bitmap grab mode, this method returns E_INVALIDARG. For more information, see EnterBitmapGrabMode.

IMediaDet::get_OutputStreams

IMediaDet Interface

Retrieves the number of output streams contained in the media source.

Syntax

HRESULT get_OutputStreams(
    long *pVal
);

Parameters

pVal
[out, retval] Pointer to a variable that receives the number of output streams.

Return Value

Returns one of the following HRESULT values:

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERNULL pointer argument.

Remarks

Before calling this method, call put_Filename to set the file name.

If the media detector is in bitmap grab mode, this method returns E_INVALIDARG. For more information, see EnterBitmapGrabMode.

IMediaDet::GetSampleGrabber

IMediaDet Interface

Retrieves a pointer to the ISampleGrabber interface, which enables an application to retrieve individual samples from a media stream.

Syntax

HRESULT GetSampleGrabber( 
    ISampleGrabber **ppVal 
);

Parameters

ppVal
[out] Address of a pointer to receive the ISampleGrabber interface.

Return Value

Returns one of the following HRESULT values:

S_OKSuccess.
E_NOINTERFACECannot retrieve the interface because the media detector is not in bitmap grab mode.
E_POINTERNULL pointer argument.

Remarks

Call EnterBitmapGrabMode before calling this method. The ISampleGrabber interface enables you to retrieve individual media samples from the stream. If you just need a bitmap for a poster frame, call the IMediaDet::GetBitmapBits method instead. The ISampleGrabber interface is more flexible, but requires more work by the application.

If this method succeeds, the ISampleGrabber interface that it returns has an outstanding reference count. Be sure to release the interface when you are finished using it.

IMediaDet::get_StreamLength

IMediaDet Interface

Retrieves the duration of the current stream.

Syntax

HRESULT get_StreamLength(
    double *pVal
);

Parameters

pVal
[out, retval] Pointer to a variable that receives the duration of the stream, in seconds.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERNULL pointer argument.

Remarks

Before calling this method, set the file name and stream by calling put_Filename and put_CurrentStream.

If the media detector is in bitmap grab mode, this method returns E_INVALIDARG. For more information, see EnterBitmapGrabMode.

IMediaDet::get_StreamMediaType

IMediaDet Interface

Retrieves the media type of the current stream.

Syntax

HRESULT get_StreamMediaType(
    AM_MEDIA_TYPE *pVal
);

Parameters

pVal
[out, retval] Pointer to an AM_MEDIA_TYPE structure that is filled with the media type.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERNULL pointer argument.

Remarks

Before calling this method, set the file name and stream by calling put_Filename and put_CurrentStream.

If the media detector is in bitmap grab mode, this method returns E_INVALIDARG. For more information, see EnterBitmapGrabMode.

IMediaDet::get_StreamType

IMediaDet Interface

Retrieves the globally unique identifier (GUID) for the media type of the current stream.

Syntax

HRESULT get_StreamType(
    GUID *pVal
);

Parameters

pVal
[out, retval] Pointer to a variable that receives the major type GUID for the media type.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERNULL pointer argument.

Remarks

This method retrieves the majortype member of the AM_MEDIA_TYPE structure. The AM_MEDIA_TYPE structure describes the format of the stream, and the majortype member is a GUID that indicates the general category, such as audio or video. For a video stream, the GUID is MEDIATYPE_Video. For audio, it is MEDIATYPE_Audio. To retrieve the entire AM_MEDIA_TYPE structure, call the get_StreamMediaType method.

Before calling this method, set the file name and stream by calling put_Filename and put_CurrentStream.

If the media detector is in bitmap grab mode, this method returns E_INVALIDARG. For more information, see EnterBitmapGrabMode.

IMediaDet::get_StreamTypeB

IMediaDet Interface

Retrieves a string representing the GUID of the media type for the current stream.

Syntax

HRESULT get_StreamTypeB(
    BSTR *pVal
);

Parameters

pVal
[out, retval] Pointer to a BSTR that receives a string representation of the media type GUID.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERNULL pointer argument.

Remarks

The returned BSTR is formatted like the following: {73647561-0000-0010-8000-00AA00389B71}

The method allocates memory for the string. The application must call SysFreeString to free the memory.

Before calling this method, set the file name and stream by calling put_Filename and put_CurrentStream.

If the media detector is in bitmap grab mode, this method returns E_INVALIDARG. For more information, see EnterBitmapGrabMode.

IMediaDet::put_CurrentStream

IMediaDet Interface

Specifies the stream number for the media detector to use.

Syntax

HRESULT put_CurrentStream(
    long newVal
);

Parameters

newVal
[in] Stream number.

Return Value

Returns S_OK if successful, or E_INVALIDARG otherwise.

Remarks

Before calling this method, call put_Filename to set the file name. Call get_OutputStreams to determine the number of streams contained in the source file.

If the media detector is in bitmap grab mode, this method returns E_INVALIDARG. For more information, see EnterBitmapGrabMode.

IMediaDet::put_Filename

IMediaDet Interface

Specifies the name of the source file for the media detector to use.

Syntax

HRESULT put_Filename(
    BSTR newVal
);

Parameters

newVal
[in] File name of the source.

Return Value

Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.

IMediaDet::put_Filter

IMediaDet Interface

Specifies a source filter for the media detector to use.

Syntax

HRESULT put_Filter(
    IUnknown *newVal
);

Parameters

newVal
[in] Pointer to the source filter's IUnknown interface.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess.
E_NOINTERFACEnewVal does not point to a filter.
E_POINTERNULL pointer argument.

Remarks

Instead of calling put_Filename, an application can call this method with a pointer to a source filter's IUnknown interface. Do not use a filter already connected to the filter graph.

IMediaDet::WriteBitmapBits

IMediaDet Interface

Retrieves a poster frame at the specified media time and writes it to a file.

Syntax

HRESULT WriteBitmapBits(
    double StreamTime, 
    long Width, 
    long Height, 
    BSTR Filename 
);

Parameters

StreamTime
Time at which to retrieve the poster frame.
Width
Width of the poster frame image, in pixels.
Height
Height of the poster frame image, in pixels.
Filename
Path of the file in which to save the poster frame. If the file already exists, this method overwrites it.

Return Value

Returns S_OK it successful. Otherwise, returns an HRESULT value that indicates the cause of the error. Possible error codes include the following:

E_NOINTERFACECould not add the Sample Grabber filter to the graph.
E_FAILFailure.
E_OUTOFMEMORYInsufficient memory.
E_UNEXPECTEDUnexpected error.
STG_E_ACCESSDENIEDCannot overwrite file.
VFW_E_INVALIDMEDIATYPEInvalid media type.

Remarks

Before calling this method, set the file name and stream by calling put_Filename and put_CurrentStream.

This method puts the media detector into bitmap grab mode. Once this method has been called, the various stream information methods in IMediaDet do not work, unless you create a new instance of the media detector.