Microsoft DirectX 8.0 |
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:
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 methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IMediaDet Methods Description get_Filter Retrieves a pointer to the source filter currently used by the media detector. put_Filter Specifies a source filter for the media detector to use. get_OutputStreams Retrieves the number of output streams contained in the media source. get_CurrentStream Retrieves the stream number currently used by the media detector. put_CurrentStream Specifies the stream number for the media detector to use. get_StreamType Retrieves the globally unique identifier (GUID) for the media type of the current stream. get_StreamTypeB Retrieves a string representing the GUID of the media type for the current stream. get_StreamLength Retrieves the duration of the current stream. get_Filename Retrieves the name of the source file currently used by the media detector. put_Filename Specifies the name of the source file for the media detector to use. GetBitmapBits Retrieves a poster frame at the specified media time. WriteBitmapBits Retrieves a poster frame at the specified media time and writes it to a file. get_StreamMediaType Retrieves the media type of the current stream. GetSampleGrabber Retrieves a pointer to the ISampleGrabber interface. get_FrameRate Retrieves the frame rate of the current stream. EnterBitmapGrabMode Switches the media detector to bitmap grab mode and seeks the filter graph to a specified time.
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_OK Success. E_INVALIDARG Invalid argument. VFW_E_INVALIDMEDIATYPE File does not have a video stream. VFW_E_TIME_EXPIRED Could 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.
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_OK Success. E_NOINTERFACE Could not add the Sample Grabber filter to the graph. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer error. E_UNEXPECTED Unexpected error. VFW_E_INVALIDMEDIATYPE Invalid 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.
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.
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.
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.
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_FALSE Video format header does not specify a frame rate. S_OK Success. E_INVALIDARG Invalid argument. E_POINTER NULL pointer argument. VFW_E_INVALIDMEDIATYPE Invalid 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.
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER NULL 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.
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_OK Success. E_NOINTERFACE Cannot retrieve the interface because the media detector is not in bitmap grab mode. E_POINTER NULL 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.
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER NULL 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.
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER NULL 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.
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER NULL 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.
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER NULL 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.
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.
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.
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_OK Success. E_NOINTERFACE newVal does not point to a filter. E_POINTER NULL 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.
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_NOINTERFACE Could not add the Sample Grabber filter to the graph. E_FAIL Failure. E_OUTOFMEMORY Insufficient memory. E_UNEXPECTED Unexpected error. STG_E_ACCESSDENIED Cannot overwrite file. VFW_E_INVALIDMEDIATYPE Invalid 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.