## IDvdInfo Interface

The IDvdInfo interface enables an application to query for attributes of available digital versatile disc (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 video attributes for the current title or menu.
GetCurrentAudioAttributes | Retrieves the audio attributes for the stream in the current title or menu.
GetCurrentSubpictureAttributes | Retrieves the video attributes for the 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.

###

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 with 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 audio attributes for the 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.
E_UOP_PROHIBITED | 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 video attributes for the 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 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 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 a 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 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

This method works only for simple linear movies.

###

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.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.