IDvdInfo Interface


		Index Topic Contents
	Previous Topic: IDvdGraphBuilder Interface Next Topic: IEnumFilters Interface

IDvdInfo Interface

The IDvdInfo interface enables an application to query for attributes of available DVD titles and the DVD player status. It also allows for control of a DVD player beyond Annex J in the DVD specification.
When to Implement
Do not implement this interface.
When to Use
Use this interface in your application to retrieve details about a DVD-Video or about the current state of the DVD player filter graph.
Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IDvdInfo methods Description
GetCurrentDomain Retrieves the current DVD domain of the DVD player.
GetCurrentLocation Retrieves the current playback location.
GetTotalTitleTime Retrieves the total playback time for the current title.
GetCurrentButton Retrieves the number of available buttons and the currently selected button number.
GetCurrentAngle Retrieves the number of available angles and the currently selected angle number.
GetCurrentAudio Retrieves the number of available audio streams and the number of the currently selected audio stream.
GetCurrentSubpicture Retrieves the number of available subpicture streams, the currently selected subpicture stream number, and whether the subpicture display is disabled.
GetCurrentUOPS Retrieves which IDvdControl methods are valid.
GetAllSPRMs Retrieves the current contents of all system parameter registers (SPRMs).
GetAllGPRMs Retrieves the current contents of all general parameter registers (GPRMs).
GetAudioLanguage Retrieves the language of the specified audio stream within the current title.
GetSubpictureLanguage Retrieves the language of the specified subpicture stream within the current title.
GetTitleAttributes Retrieves attributes of all video, audio, and subpicture streams for the specified title, including menus.
GetVMGAttributes Retrieves attributes of all video, audio, and subpicture streams for video manager (VMG) menus.
GetCurrentVideoAttributes Retrieves the current video attributes for the current title or menu.
GetCurrentAudioAttributes Retrieves the attributes for the current audio stream in the current title or menu.
GetCurrentSubpictureAttributes Retrieves the attributes for the current subpicture stream in the current title or menu.
GetCurrentVolumeInfo Retrieves the current DVD volume information.
GetDVDTextInfo Retrieves the TXTDT_MG structure, which can contain text descriptions for title name, volume name, producer name, vocalist name, and so on, in various languages.
GetPlayerParentalLevel Retrieves the current parental level and country code settings for the DVD player.
GetNumberOfChapters Retrieves the number of chapters that are defined for a given title.
GetTitleParentalLevels Retrieves the parental levels that are defined for a particular title.
GetRoot Retrieves the root directory that is set in the player.

IDvdInfo::GetAllGPRMs
IDvdInfo Interface
Retrieves the current contents of all general parameter registers (GPRMs).
HRESULT GetAllGPRMs(
  GPRMARRAY *pRegisterArray );
Parameters

pRegisterArray
[out] Pointer to the retrieved array of general parameter registers (GPRMARRAY).

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

Use of GPRMs is title specific. GPRMs are general parameter registers. See the DVD specifications for an explanation of GPRMs.
IDvdInfo::GetAllSPRMs
IDvdInfo Interface
Retrieves the current contents of all system parameter registers (SPRMs).
HRESULT GetAllSPRMs(
  SPRMARRAY *pRegisterArray );
Parameters

pRegisterArray
[out] Pointer to the retrieved array of system parameter registers (SPRMARRAY).

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

See the DVD-Video specification for use of individual registers.
IDvdInfo::GetAudioLanguage
IDvdInfo Interface
Retrieves the language of the specified audio stream within the current title.
HRESULT GetAudioLanguage(
  ULONG nStream,
  LCID *pLanguage );
Parameters

nStream
[in] Stream number.
pLanguage
[out] Pointer to the retrieved language.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

This method does not return languages for menus. This method sets the value pointed to by pLanguage to zero if the stream does not include language. Call the Win32 GetLocaleInfo API as follows to create a human-readable string name from pLanguage:
GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);
IDvdInfo::GetCurrentAngle
IDvdInfo Interface
Retrieves the number of available angles and the currently selected angle number.
HRESULT GetCurrentAngle(
  ULONG *pnAnglesAvailable,
  ULONG *pnCurrentAngle );
Parameters

pnAnglesAvailable
[out] Pointer to the retrieved number of available angles. If the value pointed to equals 1, then the current video does not contain multiple angles.
pnCurrentAngle
[out] Pointer to the retrieved current angle number.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

Angles are interleaved video streams that presumably contain the same scene shot from different camera angles.
This method returns an error unless the domain is DVD_DOMAIN_Title.
IDvdInfo::GetCurrentAudio
IDvdInfo Interface
Retrieves the number of available audio streams and the number of the currently selected audio stream.
HRESULT GetCurrentAudio(
  ULONG *pnStreamsAvailable,
  ULONG *pnCurrentStream );
Parameters

pnStreamsAvailable
[out] Pointer to the retrieved number of available audio streams
pnCurrentStream
[out] Pointer to the current stream number.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

This method returns an error unless the domain is DVD_DOMAIN_Title.
IDvdInfo::GetCurrentAudioAttributes
IDvdInfo Interface
Retrieves the attributes for the current audio stream in the current title or menu.
HRESULT GetCurrentAudioAttributes(
  DVD_AudioATR *pATR );
Parameters

pATR
[out] Pointer to the retrieved audio attributes.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

See the DVD-Video specification for information about DVD_AudioATR.
IDvdInfo::GetCurrentButton
IDvdInfo Interface
Retrieves the number of available buttons and the currently selected button number.
HRESULT GetCurrentButton(
  ULONG *pnButtonsAvailable,
  ULONG *pnCurrentButton );
Parameters

pnButtonsAvailable
[out] Pointer to the number of buttons available.
pnCurrentButton
[out] Pointer to the number of the current button.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

If buttons are not present this method returns zero for both pnButtonsAvailable and pnCurrentButton.
IDvdInfo::GetCurrentDomain
IDvdInfo Interface
Retrieves the current DVD domain of the DVD player.
HRESULT GetCurrentDomain(
  DVD_DOMAIN *pDomain );
Parameters

pDomain
[out] Pointer to the current domain which is a member of the DVD_DOMAIN enumerated type.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:

Value Meaning
E_FAIL Failure.
E_INVALIDARG Input argument is invalid.
E_NOTIMPL Method is not supported.
E_OUTOFMEMORY Out of memory (insufficient buffer space).
E_POINTER NULL pointer argument.
E_UNEXPECTED DVD is not initialized or domain is not DVD_DOMAIN_Title.
VFW_E_DVD_OPERATION_INHIBITED Requested action cannot occur at this point in the movie due to the authoring of the current DVD-Video disc.
S_OK Success.
VFW_E_DVD_INVALIDDOMAIN Requested action is not supported on this domain (DVD_DOMAIN).

IDvdInfo::GetCurrentLocation
IDvdInfo Interface
Retrieves the current playback location.
HRESULT GetCurrentLocation(
  DVD_PLAYBACK_LOCATION *pLocation );
Parameters

pLocation
[out] Pointer to the retrieved playback location information in a DVD_PLAYBACK_LOCATION structure.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
The default implementation of this method returns E_UNEXPECTED if the current domain is not DVD_DOMAIN_Title.
Remarks

This method retrieves information sufficient to restart playback of a video from the current playback location in titles that don't explicitly disable seeking to the current location.
This method returns an error unless the domain is DVD_DOMAIN_Title.
IDvdInfo::GetCurrentSubpicture
IDvdInfo Interface
Retrieves the number of available subpicture streams, the currently selected subpicture stream number, and whether the subpicture display is disabled.
HRESULT GetCurrentSubpicture(
  ULONG *pnStreamsAvailable,
  ULONG *pnCurrentStream,
  BOOL *pIsDisabled );
Parameters

pnStreamsAvailable
[out] Pointer to the retrieved number of available subpicture streams.
pnCurrentStream
[out] Pointer to the retrieved number of the currently selected subpicture stream.
pIsDisabled
[out] Pointer to a value indicating whether the subpicture display is disabled.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

Subpicture streams authored as forcedly activated streams will be displayed even if the application has disabled subpicture display with the IDvdControl::SubpictureStreamChange method.
This method returns an error unless the domain is DVD_DOMAIN_Title.
IDvdInfo::GetCurrentSubpictureAttributes
IDvdInfo Interface
Retrieves the attributes for the current subpicture stream in the current title or menu.
HRESULT GetCurrentSubpictureAttributes(
  DVD_SubpictureATR *pATR );
Parameters

pATR
[out] Pointer to the retrieved subpicture attributes.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

See the DVD-Video specification for information about DVD_SubpictureATR.
IDvdInfo::GetCurrentUOPS
IDvdInfo Interface
Retrieves which IDvdControl methods are currently valid.
HRESULT GetCurrentUOPS(
  VALID_UOP_SOMTHING_OR_OTHER *pUOP );
Parameters

pUOP
[out] Pointer to a DWORD containing the retrieved valid user operations (UOP).

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

This method is useful because DVD titles can enable or disable individual user operations at almost any point during playback.
IDvdInfo::GetCurrentVideoAttributes
IDvdInfo Interface
Retrieves the current video attributes for the current title or menu.
HRESULT GetCurrentVideoAttributes(
  DVD_VideoATR *pATR );
Parameters

pATR
[out] Pointer to the retrieved video attributes.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

See the DVD-Video specification for information about DVD_VideoATR.
IDvdInfo::GetCurrentVolumeInfo
IDvdInfo Interface
Retrieves the current DVD volume information.
HRESULT GetCurrentVolumeInfo(
  ULONG *pNumOfVol,
  ULONG *pThisVolNum,
  DVD_DISC_SIDE *pSide,
  ULONG *pNumOfTitles );
Parameters

pNumOfVol
[out] Pointer to the retrieved number of volumes in the volume set.
pThisVolNum
[out] Pointer to the retrieved volume number for this root directory.
pSide
[out] Pointer to the retrieved current disc side (DVD_DISC_SIDE).
pNumOfTitles
[out] Pointer to the retrieved number of titles available in this volume.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
IDvdInfo::GetDVDTextInfo
IDvdInfo Interface
Retrieves the TXTDT_MG structure, which can contain text descriptions for title name, volume name, producer name, vocalist name, and so on, in various languages.
HRESULT GetDVDTextInfo(
  BYTE *pTextManager,
  ULONG cbBufSize,
  ULONG *pcbActualSize );
Parameters

pTextManager
[out, size_is(cbBufSize)] Pointer to the retrieved text manager.
cbBufSize
[in] Size of the buffer for pTextManager, in bytes.
pcbActualSize
[out] Pointer to a value containing the number of bytes of data returned.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

If the supplied buffer size in cbBufSize is too small for the data, (for example if cbBufSize equals zero), then this method returns E_OUTOFMEMORY and sets the value pointed to by pcbActualSize to the required size.
Refer to Section 4.1.6 and Annex A of the DVD-Video specification for more information.
IDvdInfo::GetNumberOfChapters
IDvdInfo Interface
Retrieves the number of chapters that are defined for a given title.
HRESULT GetNumberOfChapters(
  ULONG ulTitle,
  ULONG *pNumberOfChapters
  );
Parameters

ulTitle
[in] Title for which to retrieve the number of chapters.
pNumberOfChapters
[out] Retrieved number of chapters for the specified title.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
IDvdInfo::GetPlayerParentalLevel
IDvdInfo Interface
Retrieves the current parental level and country code settings for the DVD player.
HRESULT GetPlayerParentalLevel(
  ULONG *pParentalLevel,
  ULONG *pCountryCode
  );
Parameters

pParentalLevel
[out] Pointer to a value indicating the current parental level.
pCountryCode
[out] Pointer to a value indicating the current country code.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

See Table 3.3.4-1 of the DVD-Video specification for the defined parental levels.
See ISO3166 : Alpha-2 Code for the country codes.
Valid Parental Levels are 1 through 8 if parental management is enabled, 0xffffffff if parental management is disabled.
IDvdInfo::GetRoot
IDvdInfo Interface
Retrieves the root directory that is set in the player.
HRESULT GetRoot(
  LPTSTR pRoot,
  ULONG cbBufSize,
  ULONG *pcbActualSize
  );
Parameters

pRoot
[out, size_is(cbBufSize)] Pointer to the buffer to receive the root string.
cbBufSize
[in] Size of buffer passed in, in bytes.
pcbActualSize
[out] Pointer to a value containing the size of the actual data returned.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

If a valid root was found, this method returns the root string. Otherwise, it returns zero for pcbActualSize, indicating that a valid root directory has not been found or initialized.
IDvdInfo::GetSubpictureLanguage
IDvdInfo Interface
Retrieves the language of the specified subpicture stream within the current title.
HRESULT GetSubpictureLanguage(
  ULONG nStream,
  LCID *pLanguage );
Parameters

nStream
[in] Stream number.
pLanguage
[out] Pointer to the retrieved language.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

This method does not return languages for menus. This method sets the value pointed to by pLanguage to zero if the stream does not include language. Call the Win32 GetLocaleInfo API as follows to create a human-readable string name from pLanguage.
GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);
This method returns an error unless the domain is DVD_DOMAIN_Title.
IDvdInfo::GetTitleAttributes
IDvdInfo Interface
Retrieves attributes of all video, audio, and subpicture streams for the specified title, including menus.
HRESULT GetTitleAttributes(
  ULONG nTitle,
  DVD_ATR *pATR );
Parameters

nTitle
[in] Requested title number. Specify 0xFFFFFFFF for the current title.
pATR
[out] Pointer to the retrieved attributes structure (DVD_ATR).

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
IDvdInfo::GetTitleParentalLevels
IDvdInfo Interface
Retrieves the parental levels that are defined for a particular title.
HRESULT GetTitleParentalLevels(
  ULONG ulTitle,
  ULONG *pParentalLevels
  );
Parameters

ulTitle
[in] Title for which parental levels are requested.
pParentalLevels
[out] Logical OR combination of the parental levels defined for the title. Valid parental levels are DVD_PARENTAL_LEVEL_8, DVD_PARENTAL_LEVEL_6, and DVD_PARENTAL_LEVEL_1.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
IDvdInfo::GetTotalTitleTime
IDvdInfo Interface
Retrieves the total playback time for the current title.
HRESULT GetTotalTitleTime(
  ULONG *pTotalTime );
Parameters

pTotalTime
[out] Pointer to the total time in DVD_TIMECODE format, which includes hours, minutes, seconds, and frames.

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

The method is restricted to simple linear movies by design.
IDvdInfo::GetVMGAttributes
IDvdInfo Interface
Retrieves attributes of all video, audio, and subpicture streams for video manager (VMG) menus.
HRESULT GetVMGAttributes(
  DVD_ATR *pATR );
Parameters

pATR
[out] Pointer to the retrieved attributes structure (DVD_ATR).

Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.
Remarks

The video manager contains a separate group of streams, such as the DVD_MENU_Title menus and are not associated with any particular title number.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.
Top of Page

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IDvdInfo methods	Description
GetCurrentDomain	Retrieves the current DVD domain of the DVD player.
GetCurrentLocation	Retrieves the current playback location.
GetTotalTitleTime	Retrieves the total playback time for the current title.
GetCurrentButton	Retrieves the number of available buttons and the currently selected button number.
GetCurrentAngle	Retrieves the number of available angles and the currently selected angle number.
GetCurrentAudio	Retrieves the number of available audio streams and the number of the currently selected audio stream.
GetCurrentSubpicture	Retrieves the number of available subpicture streams, the currently selected subpicture stream number, and whether the subpicture display is disabled.
GetCurrentUOPS	Retrieves which IDvdControl methods are valid.
GetAllSPRMs	Retrieves the current contents of all system parameter registers (SPRMs).
GetAllGPRMs	Retrieves the current contents of all general parameter registers (GPRMs).
GetAudioLanguage	Retrieves the language of the specified audio stream within the current title.
GetSubpictureLanguage	Retrieves the language of the specified subpicture stream within the current title.
GetTitleAttributes	Retrieves attributes of all video, audio, and subpicture streams for the specified title, including menus.
GetVMGAttributes	Retrieves attributes of all video, audio, and subpicture streams for video manager (VMG) menus.
GetCurrentVideoAttributes	Retrieves the current video attributes for the current title or menu.
GetCurrentAudioAttributes	Retrieves the attributes for the current audio stream in the current title or menu.
GetCurrentSubpictureAttributes	Retrieves the attributes for the current subpicture stream in the current title or menu.
GetCurrentVolumeInfo	Retrieves the current DVD volume information.
GetDVDTextInfo	Retrieves the TXTDT_MG structure, which can contain text descriptions for title name, volume name, producer name, vocalist name, and so on, in various languages.
GetPlayerParentalLevel	Retrieves the current parental level and country code settings for the DVD player.
GetNumberOfChapters	Retrieves the number of chapters that are defined for a given title.
GetTitleParentalLevels	Retrieves the parental levels that are defined for a particular title.
GetRoot	Retrieves the root directory that is set in the player.

Value	Meaning
E_FAIL	Failure.
E_INVALIDARG	Input argument is invalid.
E_NOTIMPL	Method is not supported.
E_OUTOFMEMORY	Out of memory (insufficient buffer space).
E_POINTER	NULL pointer argument.
E_UNEXPECTED	DVD is not initialized or domain is not DVD_DOMAIN_Title.
VFW_E_DVD_OPERATION_INHIBITED	Requested action cannot occur at this point in the movie due to the authoring of the current DVD-Video disc.
S_OK	Success.
VFW_E_DVD_INVALIDDOMAIN	Requested action is not supported on this domain (DVD_DOMAIN).