Microsoft DirectX 8.0

IDvdInfo2 Interface

The IDvdInfo2 interface is implemented by the DVD Navigator source filter and provides methods to query for various attributes of the disc or the DVD Navigator's state. IDvdInfo2 is the companion interface to IDvdControl2. IDvdInfo2 groups the DVD Navigator's "get" methods and IDvdControl2 groups the "set" methods. Together they provide DVD navigation and playback functionality beyond the DVD Annex J specification.

Note  The information provided by some of these methods can also be obtained through event notifications sent from the DVD Navigator to the application's message loop. For example, to get the current DVD domain, you can call IDvdInfo2::GetCurrentDomain or you can handle the EC_DVD_DOMAIN_CHANGE event in your application's message loop and extract the new domain from the event's lParam1 parameter.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IDvdInfo2 methodsDescription
Menus
GetButtonAtPositionRetrieves the button located at the specified point within the display window.
GetButtonRectRetrieves the rectangle coordinates of the specified button.
GetCurrentButtonRetrieves the number of available buttons and the number of the currently selected button.
GetDefaultMenuLanguageRetrieves the default menu language.
GetMenuLanguagesRetrieves all the languages available for all menus on the disc.
GetVMGAttributesRetrieves attributes of all video, audio, and subpicture streams for the video manager menu.
Titles
GetNumberOfChaptersRetrieves the number of chapters in a given title.
GetTitleAttributesRetrieves attributes of all video, audio, and subpicture streams for the specified title and its menus.
GetTotalTitleTimeRetrieves the total playback time for the current title.
Disc Information
GetAllSPRMsRetrieves the current contents of all system parameter registers (SPRMs).
GetAllGPRMsRetrieves the current contents of all general parameter registers (GPRMs).
GetCurrentUOPSRetrieves a set of flags indicating which navigation commands, if any, the content authors have explicitly disabled for the current disc location.
GetDiscIDRetrieves a system-generated 64-bit "unique" identification number for the specified DVD.
GetDVDVolumeInfoRetrieves the current DVD volume information.
Video Stream
GetCurrentAngleRetrieves the number of available angles in the current angle block and the currently selected angle number.
GetCurrentVideoAttributesRetrieves the video attributes of the current title or menu.
Audio Stream
GetAudioAttributesRetrieves the attributes of the specified audio stream in the current title or menu.
GetAudioLanguageRetrieves the language of the specified audio stream within the current title.
GetCurrentAudioRetrieves the number of available audio streams and the number of the currently selected audio stream.
GetDecoderCapsRetrieves the DVD decoder's maximum data rate for video, audio, and subpicture (in forward and reverse) as well as support for various types of audio (Dolby AC-3, MPEG-2, DTS, SDDS, LPCM).
GetDefaultAudioLanguageRetrieves the default audio language.
GetKaraokeAttributesRetrieves the karaoke attributes of the specified audio stream in the current title or menu.
IsAudioStreamEnabledDetermines if the specified audio stream is enabled in the current title.
Subpicture Stream
GetCurrentSubpictureRetrieves the number of available subpicture streams in the current title, the currently selected subpicture stream number, and the state of the subpicture.
GetDefaultSubpictureLanguageRetrieves the default subpicture language.
GetSubpictureAttributesRetrieves the attributes of the specified subpicture stream in the current title or menu.
GetSubpictureLanguageRetrieves the language of the specified subpicture stream within the current title.
IsSubpictureStreamEnabledDetermines if the specified subpicture stream is enabled in the current title.
Parental Levels
GetPlayerParentalLevelRetrieves the current parental level and ISO 3166 country code settings for the DVD Navigator.
GetTitleParentalLevelsRetrieves the parental levels that are defined for a particular title.
DVD Navigator State Information
GetCmdFromEventRetrieves an IDvdCmd object from an EC_DVD_CMD_START, EC_DVD_CMD_END, or VFW_E_DVD_CMD_CANCELLED event.
GetCurrentDomainRetrieves the DVD domain in which the DVD Navigator is currently located.
GetCurrentLocationRetrieves the current playback location.
GetDVDDirectoryRetrieves the root directory that is set in the DVD Navigator.
GetStateRetrieves a bookmark containing the disc location and DVD Navigator state information.
DVD Text Strings
GetDVDTextNumberOfLanguagesRetrieves the number of text languages for the current DVD or disc side.
GetDVDTextLanguageInfoRetrieves the information for the specified text string language block.
GetDVDTextStringAsNativeRetrieves the text string for the specified language as an array of bytes.
GetDVDTextStringAsUnicodeRetrieves the text string for the specified language in Unicode™.

IDvdInfo2::GetAllGPRMs

IDvdInfo2 Interface

Retrieves the current contents of all general parameter registers (GPRMs).

Syntax

HRESULT GetAllGPRMs(
  GPRMARRAY *pRegisterArray
);

Parameters

pRegisterArray
[out] Pointer to a GPRMARRAY that receives all 16 current GPRM values. See Remarks.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.

Remarks

GPRMs are 16-bit registers that each disc can use in unique ways for temporary data storage. The file Dvdif.idl contains the following typedefs.

typedef WORD DVD_REGISTER;
typedef DVD_REGISTER    GPRMARRAY[16];
typedef DVD_REGISTER    SPRMARRAY[24];

Note  A player application using the DVD Navigator does not need to access these registers for any Annex J playback or navigation control. This method is provided for player applications implementing advanced functionality. Do not attempt to modify the GPRMs directly unless you have a thorough knowledge of the DVD specification, and the ways in which the GPRMs are used on the particular discs to be played.

See Also

IDvdControl2::SetGPRM

IDvdInfo2::GetAllSPRMs

IDvdInfo2 Interface

Retrieves the current contents of all system parameter registers (SPRMs).

Syntax

HRESULT GetAllSPRMs(
  SPRMARRAY *pRegisterArray
);

Parameters

pRegisterArray
[out] Pointer to a variable of type SPRMARRAY that receives the address of an array of SPRMs. See Remarks.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.

Remarks

The 24 SPRMs are used to hold information on current language, subpicture, and other navigation data. The file Dvdif.idl contains the following typedefs.

typedef WORD DVD_REGISTER;
typedef DVD_REGISTER    GPRMARRAY[16];
typedef DVD_REGISTER    SPRMARRAY[24];

Note  A player application doesn't need to access these registers for any standard navigation functionality. To use these registers effectively, you will probably need a more detailed knowledge of the DVD navigation commands than is provided in this documentation. The following table lists the contents of each register. Bits within the word are referred to as b0 (low order bit) through b15 (high order bit).

RegisterContents
0 ISO-639 language code (two lowercase ASCII letters). Default value is undefined.
1 Low 4 bits (b0-b3) contain audio stream number (0 to 7) or 15 (none). Default value is 15.
2 Low 6 bits (b0-b5) contain subpicture stream number (0 to 31) or 62 (none) or 63 (dummy stream for forced subpicture). 7th bit (b6) contains subpicture display flag (0 = don’t display subpicture). Default value is 62.
3 Low 4 bits (b0-b3) contain angle number (1 to 9). Default value is 1.
4 Low 7 bits (b0-b6) contain title number (1 to 99). Default value is 1.
5 Low 7 bits (b0-b6) contain title number within current VTS (1 to 99). Default value is 1.
6 Low 15 bits (b0-b14) contain PGC number in current title (1 to 32767). Default value is undefined.
7 Low 10 bits (b0-b9) contain chapter number (1 to 99). Default value is 1. Value undefined unless title is one_sequential_PGC_title.
8 High 6 bits (b10-b15) contain button number (1 to 36). Default value is 1024 (button 1).
9 Timer count, in seconds (0 to 65535). Default value is 0.
10Low 15 bits (b0-b14) contain PGC number in current title (1 to 32767). Default value is undefined.
11Six flags (b2: mix ch2 to ch1, b3: mix ch3 to ch1, b4: mix ch4 to ch1, b10 mix ch2 to ch0, b11: mix ch3 to ch0, b12: mix ch4 to ch0). Flag value of 0 means don’t mix. Default value for all flags is 0. Value undefined if not playing Karaoke stream.
12ISO-3166 country code (two uppercase ASCII letters) or 65535 (not specified). Default value is undefined.
13Low 4 bits (b0-b3) contain parental level (1 to 8) or 15 (none). Default value is undefined.
14b8-b9 contain preferred display mode (0 = 4:3, 3 = 16:9). b10-b11 contain current video output mode (0 = normal [4:3 or 16:9], 1 = panscan, 2 = letterbox). Default value is undefined.
15Nine flags (b2: SDDS karaoke, b3: DTS karaoke, b4: MPEG karaoke, b6: Dolby Digital karaoke, b7: PCM karaoke, b10: SDDS playback, b11: DTS playback, b12: MPEG playback, b14: Dolby Digital playback). Flag value of 0 means incapable, 1 means capable. Default value is undefined.
16ISO-639 language code (two lowercase ASCII letters) or 65535 (not specified). Default value is 65535.
17Language extension code (0 = not specified, 1 = normal audio, 2 = audio for visually impaired, 3 = director comments #1, 4 = director comments #2). Default value is 0.
18ISO-639 language code (two lowercase ASCII letters) or 65535 (not specified). Default value is 65535.
19Language extension code (0 = not specified, 1 = normal subtitles, 2 = large subtitles, 3 = subtitles for children, 5 = normal Closed Captions, 6 = large Closed Captions, 7 = Closed Captions for children, 9 = forced subtitles, 13 = director comments, 14 = large director comments, 15 = director comments for children). Default value is 0.
20Low 8 bits (b0-b7) contain region code (1 to 8).

IDvdInfo2::GetAudioAttributes

IDvdInfo2 Interface

Retrieves the attributes of the specified audio stream in the current title or menu.

Syntax

HRESULT GetAudioAttributes(
  ULONG ulStream,
  DVD_AudioAttributes *pATR
);

Parameters

ulStream
[in] Variable of type ULONG specifying the audio stream whose attributes you wish to query. See Remarks.
pATR
[out] Pointer to a DVD_AudioAttributes structure that is filled with the attributes of the specified audio stream.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_UNEXPECTEDThe DVD Navigator is not initialized.
VFW_E_DVD_NO_ATTRIBUTESThe stream's audio attributes are not available for some reason.
E_POINTERInvalid argument.

Remarks

ulStream can be any index number from 0 through 7 or one of the following values:

DVD_DEFAULT_AUDIO_STREAMto query for the attributes of the default audio stream.
DVD_STREAM_DATA_CURRENT to query the current stream.
DVD_STREAM_DATA_VMGM to query for the VMGM's audio attributes
DVD_STREAM_DATA_VTSM to query for the VTSM's audio attributes

The use of this method is demonstrated in the DVDSample application in CDvdCore::GetAudioAttributes() and CAudioLangDlg::GetAudioLang.

IDvdInfo2::GetAudioLanguage

IDvdInfo2 Interface

Retrieves the language of the specified audio stream within the current title.

Syntax

HRESULT GetAudioLanguage(
  ULONG ulStream,
  LCID *pLanguage
);

Parameters

ulStream
[in] Audio stream number for the language being retrieved.
pLanguage
[out] Pointer to an LCID that receives the language information.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERThe pLanguage parameter is NULL.
E_UNEXPECTEDThe DVD Navigator is not initialized.
VFW_E_DVD_INVALIDDOMAINDVD Navigator is not in a valid domain.

Remarks

This method does not return languages for menus. It sets the value pointed to by pLanguage to zero if the stream contains an unknown language. Call the Microsoft® Win32® GetLocaleInfo function as follows to create a human-readable string name from pLanguage. LOCALE_SENGLANGUAGE is the locale information type, pszString is a pointer to a buffer to receive the requested data, and cbSize specifies the size of pszString.

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

See Also

IDvdControl2::SelectAudioStream

IDvdInfo2::GetButtonAtPosition

IDvdInfo2 Interface

Retrieves the button located at the specified point within the display window.

Syntax

HRESULT GetButtonAtPosition(
  POINT point,
  ULONG *puButtonIndex
);

Parameters

point
[in] Current mouse pointer position as retrieved through the Win32 WM_MOUSEMOVE message.
puButtonIndex
[out] Pointer to a variable of type ULONG that receives the index (from 1 through 36) of the button at the current mouse pointer position.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERThe puButtonIndex parameter is invalid.
VFW_E_DVD_NO_BUTTONNo button at point.

Remarks

This method is typically called in response to a mouse pointer move within a DVD menu display window. Be sure to check for success in the HRESULT before trying to retrieve the button number; this method only sets the value of puButtonIndex if a button is found at the specified point. DVD buttons do not necessarily have highlighted rectangles, button rectangles can overlap, and button rectangles do not always correspond to the visual representation of the buttons.

See Also

IDvdControl2::ActivateButton

IDvdInfo2::GetButtonRect

IDvdInfo2 Interface

Retrieves the rectangle coordinates for the specified menu button. (This method is currently not implemented.)

Syntax

HRESULT GetButtonRect(
  ULONG ulButton
  RECT *pRect
);

Parameters

ulButton
[in] Variable of type ULONG, from 1 through 36, that specifies the button.
pRect
[out] Pointer to a variable of type RECT that receives the coordinates of the button's rectangle.

Return Value

Returns one of the following HRESULT values.

E_NOTIMPLThis method is currently not implemented

IDvdInfo2::GetCmdFromEvent

IDvdInfo2 Interface

Retrieves an IDvdCmd object from an EC_DVD_CMD_START or EC_DVD_CMD_END event.

Syntax

HRESULT GetCmdFromEvent(
  LONG_PTR lParam1,
  IDvdCmd **ppCmdObj
);

Parameters

lParam1
[in] Event notification's lParam1 parameter.
ppCmdObj
[out] Address of a pointer to an IDvdCmd command object that is associated with the command that fired the event.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_FAILThe command no longer exists.
E_POINTERInvalid argument.

Remarks

This method maps the lParam1 parameter of an EC_DVD_CMD_START or EC_DVD_CMD_END event into an IDvdCmd object that is associated with the command that fired the event. You can then call WaitForStart or WaitForEnd to control the blocking behavior of the DVD Navigator with respect to that command. The IDvdCmd object is created by the DVD Navigator and the returned pointer has already had its reference count incremented, so you must release it after WaitForStart or WaitForEnd returns.

See Also

Synchronizing DVD commands, EC_DVD_CMD_START, EC_DVD_CMD_END

IDvdInfo2::GetCurrentAngle

IDvdInfo2 Interface

Retrieves the number of available angles in the current angle block and the currently selected angle number.

Syntax

HRESULT GetCurrentAngle(
  ULONG *pulAnglesAvailable,
  ULONG *pulCurrentAngle
);

Parameters

pulAnglesAvailable
[out] Pointer to a variable of type ULONG that receives the number of available angles. There are up to nine angles in an angle block, numbered 1 through 9. If the value equals 1, then the DVD Navigator is not in an angle block.
pulCurrentAngle
[out] Pointer to a variable of type ULONG that receives the current angle number.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.
VFW_E_DVD_INVALIDDOMAINDVD Navigator is not initialized or not in a valid domain.

Remarks

Note that angle and menu button indexes are 1-based, while audio and subpicture stream indexes are 0-based. When the DVD Navigator is about to enter an angle block, it sends the application an EC_DVD_ANGLES_AVAILABLE event notification with the lParam set to 1. Applications will typically call GetCurrentAngle and IDvdControl2::SelectAngle within their event handler for EC_DVD_ANGLES_AVAILABLE.

This method is demonstrated in the DVDSample application in CAngleDlg::MakeAngleList.

See Also

IDvdControl2::SelectAngle, EC_DVD_ANGLES_AVAILABLE, EC_DVD_ANGLE_CHANGE

IDvdInfo2::GetCurrentAudio

IDvdInfo2 Interface

Retrieves the number of available audio streams and the number of the currently selected audio stream.

Syntax

HRESULT GetCurrentAudio(
  ULONG *pulStreamsAvailable,
  ULONG *pulCurrentStream
);

Parameters

pulStreamsAvailable
[out] Pointer to a variable of type ULONG that receives the number of available audio streams.
pulCurrentStream
[out] Pointer to a variable of type ULONG that receives the currently selected audio stream number in the current title.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInput arguments are invalid.
VFW_E_DVD_INVALIDDOMAINThe DVD Navigator is not initialized or not in a valid domain.

Remarks

To get the available audio languages on the disc, call GetCurrentAudio and then call GetAudioLanguage for each stream, starting from zero through (pulStreamsAvailable - 1) to get the language content.

See Also

EC_DVD_AUDIO_STREAM_CHANGE, IDvdControl2::SelectAudioStream

IDvdInfo2::GetCurrentButton

IDvdInfo2 Interface

Retrieves the number of available buttons and the number of the currently selected button.

Syntax

HRESULT GetCurrentButton(
  ULONG *pulButtonsAvailable,
  ULONG *pulCurrentButton
);

Parameters

pulButtonsAvailable
[out] Pointer to a variable of type ULONG that receives the number of buttons available.
pulCurrentButton
[out] Pointer to a variable of type ULONG that receives the number (from 1 through 36) of the currently selected button.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTEROne of the pointer arguments is not valid.

Remarks

If buttons are not present, both pulButtonsAvailable and pulCurrentButton are set to zero.

See Also

EC_DVD_BUTTON_CHANGE, IDvdControl2::ActivateButton

IDvdInfo2::GetCurrentDomain

IDvdInfo2 Interface

Retrieves the domain in which the DVD Navigator is currently located.

Syntax

HRESULT GetCurrentDomain(
  DVD_DOMAIN *pDomain
);

Parameters

pDomain
[out] Pointer to a variable of type DVD_DOMAIN that receives the current domain.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_UNEXPECTED Unexpected error.
E_POINTERInvalid argument.

Remarks

You can use this method to test whether the DVD Navigator is finished playing in a particular title domain. An application doesn't have to test for the current domain before calling an IDvdControl2 method such as PlayTitle, PlayForwards, and so on. The DVD Navigator tests for the domain and simply does nothing, returning VFW_E_DVD_INVALIDDOMAIN, if the current command is invalid for the domain.

See Also

DomainsEC_DVD_DOMAIN_CHANGE

IDvdInfo2::GetCurrentLocation

IDvdInfo2 Interface

Retrieves the current playback location.

Syntax

HRESULT GetCurrentLocation(
  DVD_PLAYBACK_LOCATION2 *pLocation
);

Parameters

pLocation
[out] Pointer to a variable of type DVD_PLAYBACK_LOCATION2 that receives the playback location information.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERThe pLocation parameter is invalid.
VFW_E_DVD_INVALIDDOMAINThe DVD Navigator is in an invalid domain.

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. After the disc has been ejected, the information returned by this method will not necessarily be sufficient to restart playback. To save the current location and state information to disc so that the user can return to the same location at any later time, use GetState.

IDvdInfo2::GetCurrentSubpicture

IDvdInfo2 Interface

Retrieves the number of available subpicture streams in the current title, the currently selected subpicture stream number, and the state of the subpicture.

Syntax

HRESULT GetCurrentSubpicture(
  ULONG *pulStreamsAvailable,
  ULONG *pulCurrentStream,
  BOOL *pbIsDisabled
);

Parameters

pulStreamsAvailable
[out] Pointer to a variable of type ULONG that receives the number of available subpicture streams.
pulCurrentStream
[out] Pointer to a variable of type ULONG that receives the number of the currently selected subpicture stream.
pbIsDisabled
[out] Pointer to a variable of type BOOL that receives a value indicating whether the subpicture display is disabled; TRUE means it is disabled.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.
VFW_E_DVD_INVALIDDOMAINThe DVD Navigator is not initialized or not in the Title domain.

Remarks

DVD content authors can specify that any particular subpicture stream on a disc is forcedly activated, meaning that the DVD authors require this stream to display whether the viewer wants to watch it or not. The DVD Navigator complies with all such commands from the disc, meaning that forcedly activated streams are displayed even if the application has disabled subpicture display with the IDvdControl2::SetSubpictureState method.

See Also

EC_DVD_SUBPICTURE_STREAM_CHANGE, IDvdControl2::SelectSubpictureStream

IDvdInfo2::GetCurrentVideoAttributes

IDvdInfo2 Interface

Retrieves the video attributes of the current title or menu.

Syntax

HRESULT GetCurrentVideoAttributes(
    DVD_VideoAttributes *pATR
);

Parameters

pATR
[out] Pointer to a DVD_VideoAttributes structure that receives the attributes.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.
E_UNEXPECTEDThe DVD Navigator is not initialized.

Remarks

The use of this method is demonstrated in the DVDSample application in CDvdCore::GetVideoAttributes().

IDvdInfo2::GetDecoderCaps

IDvdInfo2 Interface

Retrieves the DVD decoder's maximum data rate for video, audio, and subpicture (in forward and reverse) as well as support for various types of audio (AC-3, MPEG-2, DTS, SDDS, LPCM).

Syntax

HRESULT GetDecoderCaps(
  DVD_DECODER_CAPS *pCaps
);

Parameters

pCaps
[out] Pointer to a variable of type DVD_DECODER_CAPS that receives the information about the decoder.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
VFW_E_WRONG_STATEThe filter graph has not been initialized.

IDvdInfo2::GetDefaultAudioLanguage

IDvdInfo2 Interface

Retrieves the default audio language.

Syntax

HRESULT GetDefaultAudioLanguage(
  LCID *pLanguage,
  DVD_AUDIO_LANG_EXT *pAudioExtension
);

Parameters

pLanguage
[out] Pointer to an LCID that receives the default language information.
pAudioExtension
Pointer to a variable of type DVD_AUDIO_LANG_EXT that receives a value indicating the default DVD audio language extension.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERThe pLanguage parameter is NULL.
E_UNEXPECTEDThe DVD Navigator is not initialized.
VFW_E_DVD_INVALIDDOMAINDVD Navigator is not in a valid domain.

See Also

IDvdControl2::SelectAudioStream, IDvdControl2::SelectDefaultAudioLanguage

IDvdInfo2::GetDefaultMenuLanguage

IDvdInfo2 Interface

Retrieves the default menu language.

Syntax

HRESULT GetDefaultMenuLanguage(
  LCID *pLanguage
);

Parameters

pLanguage
[out] Pointer to an LCID that receives the language information.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERThe pLanguage parameter is NULL.
E_UNEXPECTEDThe DVD Navigator is not initialized.
VFW_E_DVD_INVALIDDOMAINDVD Navigator is not in a valid domain.

See Also

IDvdControl2::SelectDefaultMenuLanguage

IDvdInfo2::GetDefaultSubpictureLanguage

IDvdInfo2 Interface

Retrieves the default subpicture language.

Syntax

HRESULT GetDefaultSubpictureLanguage(
  LCID *pLanguage,
  DVD_SUBPICTURE_LANG_EXT *pSubpictureExtension
);

Parameters

pLanguage
[out] Pointer to an LCID that receives the language information.
pSubpictureExtension
[out] Pointer to a variable of type DVD_SUBPICTURE_LANG_EXT that receives one of the allowable values indicating the default language extension.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERThe pLanguage parameter is NULL.
E_UNEXPECTEDThe DVD Navigator is not initialized.
VFW_E_DVD_INVALIDDOMAINDVD Navigator is not in a valid domain.

See Also

IDvdControl2::SelectDefaultSubpictureLanguage

IDvdInfo2::GetDiscID

IDvdInfo2 Interface

Retrieves a system-generated 64-bit identification number for the specified DVD.

Syntax

HRESULT GetDiscID(
    LPCWSTR pszwPath,
    ULONGLONG *pullDiscID
  );

Parameters

pszwPath
[in] Path of the volume to use for the disc ID. Specify NULL to use the current DVD volume.
pullDiscID
[out] Pointer to a variable of type ULONGLONG that receives the 64-bit disc ID.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_UNEXPECTED The DVD Navigator is not initialized.

Remarks

The DVD Navigator calculates a "unique" ID based on based on file sizes, dates, and other information, and not the BCA value. This number is guaranteed to be the same each time the disc is played. The ID applies to all replicated copies of a disc. In other words, all copies of a specific movie will have the same ID. The odds that two separate titles will have the same ID is sufficiently remote that this ID can be considered "unique" for all practical purposes.

IDvdInfo2::GetDVDDirectory

IDvdInfo2 Interface

Retrieves the root directory that is set in the DVD Navigator.

Syntax

HRESULT GetDVDDirectory(
  LPWSTR pszwPath,
  ULONG ulMaxSize,
  ULONG *pulActualSize
);

Parameters

pszwPath
[out, size_is(cbMaxSize)] Pointer to a buffer that receives the path string.
ulMaxSize
[in] Size of the buffer, in WCHARs.
pulActualSize
[out] Pointer to a variable that receives the size of actual data returned, in WCHARs.

Remarks

This method is demonstrated in the DVDSample application in CDvdCore::GetDriveLetter.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGThe buffer is not large enough to hold the string.
VFW_E_DVD_INVALIDDOMAINThe DVD Navigator is not in a valid domain.

IDvdInfo2::GetKaraokeAttributes

IDvdInfo2 Interface

Retrieves the karaoke attributes of the specified audio stream in the current title or menu.

Syntax

HRESULT GetKaraokeAttributes(
  ULONG ulStream,
  DVD_KaraokeAttributes *pATR
);

Parameters

ulStream
[in] Variable of type ULONG specifying the index of the audio stream whose attributes you want to query. See Remarks.
pATR
[out] Pointer to a DVD_KaraokeAttributes structure that is filled with the karaoke attributes.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.
E_UNEXPECTEDThe DVD Navigator is not initialized.
VFW_E_DVD_NOT_IN_KARAOKE_MODE The specified stream is not in karaoke format.
VFW_E_DVD_INVALIDDOMAIN The DVD Navigator is not in the title domain.
VFW_E_DVD_NO_ATTRIBUTES The karaoke attributes for the specified stream are not available for some reason.

Remarks

This method does not explicitly return the number of channels in the stream. You can obtain that information through a call to IDvdInfo2::GetAudioAttributes. This method is demonstrated in the DVDSample application in CKaraokeDlg::DoModal.

The ulStream parameter may be a value from 0 through 7, or one of the following:
DVD_STREAM_DATA_CURRENT (0x800)to query the currently selected audio stream.
DVD_DEFAULT_AUDIO_STREAMto query the default audio stream.

IDvdInfo2::GetSubpictureAttributes

IDvdInfo2 Interface

Retrieves the attributes of the specified subpicture stream in the specified title or menu.

Syntax

HRESULT GetSubpictureAttributes(
  ULONG ulStream,
  DVD_SubpictureAttributes *pAttributes
  );

Parameters

ulStream
[in] Index number, from 0 through 31, of the subpicture stream to query. See Remarks.
pAttributes
[out] Pointer to a DVD_SubpictureAttributes structure that receives the subpicture attributes.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_FAILNo subpicture streams were found.
E_POINTERInvalid argument.
VFW_E_ATTRIBUTES_DO_NOT_EXIST The subpicture has no defined attributes.

Remarks

The index numbers 0-31 are valid only for titles. Menus have only one subpicture stream, which must be specified using one of the constants in the table below:

DVD_STREAM_DATA_CURRENT (0x800)to query the currently selected subpicture stream.
DVD_STREAM_DATA_VMGM (0x400)to query the subpicture attributes for the Video Manager or "Top" Menu.
DVD_STREAM_DATA_VTSM (0x401)to query the subpicture attributes for the currently selected Video Title Set Menu.

This method is demonstrated in the DVDSample application in CDvdCore::GetSPAttributes() and CSPLangDlg::GetSPLang.

See Also

DVD Menus, IsSubpictureStreamEnabled

IDvdInfo2::GetCurrentUOPS

IDvdInfo2 Interface

Retrieves a set of flags indicating which navigation commands, if any, the content authors have explicitly disabled for the current disc location.

Syntax

HRESULT GetCurrentUOPS(
  ULONG *pulUOPs
);

Parameters

pulUOPs
[out] Pointer to a variable of type ULONG that is a bitwise OR of VALID_UOP_FLAG values. Each bit represents the state (valid or not valid) of a user operation (UOP). If the bit is set, then that user operation is prohibited. See Remarks.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERpulUOPs is not a valid pointer.

Remarks

DVD authors can insert UOP commands at almost any place on the disc to disallow a navigation command that would otherwise be permitted within the current DVD domain. In other words, UOP commands enable disc authors to override the usual navigation permissions.

A DVD player application should normally never have to use this method because the DVD Navigator automatically checks all UOP permissions before proceeding with any command, and will return VFW_E_DVD_OPERATION_INHIBITED from any method if the command is invalid under the current UOP. If your application needs to track the current UOP permissions itself, you can call GetCurrentUOPS whenever the current UOP permissions are required, or you can handle the EC_DVD_VALID_UOPS_CHANGE event notification in your message loop and retrieve the UOP information from the lParam1 parameter. The latter approach is generally more efficient.

See Also

EC_DVD_VALID_UOPS_CHANGE

IDvdInfo2::GetDVDVolumeInfo

IDvdInfo2 Interface

Retrieves the current DVD volume information.

Syntax

HRESULT GetDVDVolumeInfo(
    ULONG *pulNumOfVolumes,
    ULONG *pulVolume,
    DVD_DISC_SIDE *pSide,
    ULONG *pulNumOfTitles
    );

Parameters

pulNumOfVolumes
[out] Pointer to a variable of type ULONG that receives the number of volumes in the volume set.
pulVolume
[out] Pointer to a variable of type ULONG that receives the volume number for this root directory.
pSide
[out] Pointer to a variable of type DVD_DISC_SIDE that receives the current disc side.
pulNumOfTitles
[out] Pointer to a variable of type ULONG that receives the number of titles available in this volume.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.

Remarks

Some discs can be distributed as part of multidisc set. "Volume" in this context can mean either "disc" or "disc side", depending on how the disc was authored.

IDvdInfo2::GetDVDTextLanguageInfo

IDvdInfo2 Interface

Retrieves the information for the specified text string language block.

Syntax

HRESULT GetDVDTextLanguageInfo(
    ULONG ulLangIndex,
    ULONG *pulNumOfStrings,
    LCID pLangCode,
    DVD_TextCharSet *pbCharacterSet
  );

Parameters

ulLangIndex
[in] Index specifying the language block. See Remarks.
pulNumOfStrings
[out] Pointer to a variable of type ULONG that receives the number of strings for the specified language block.
pLangCode
[out] Pointer to a variable of type LCID that contains the ISO 639 language code.
pbCharacterSet
[out] Pointer to a DVD_TextCharSet enumeration that receives a value indicating which character set is used for the specified language.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.
E_UNEXPECTEDAn unexpected internal error occurred.

Remarks

Call GetDVDTextNumberOfLanguages to set up the index of all the available text languages for menus and subpictures. Then, for each index entry, call GetDVDTextLanguageInfo to retrieve the information for that particular language (number of strings, language code, character set).

See Also

Working with DVD Text Strings

IDvdInfo2::GetDVDTextNumberOfLanguages

IDvdInfo2 Interface

Retrieves the number of text languages for the current DVD or disc side.

Syntax

HRESULT GetDVDTextNumberOfLanguages(
    ULONG *pulNumOfLangs
  );

Parameters

pulNumOfLangs
[out] Pointer to a variable of type ULONG that receives the number of text languages.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.
E_UNEXPECTED An unexpected internal error occurred.

Remarks

Depending on how the disc is authored, the number of languages will be valid either for the entire disc, or for the current side only.

See Also

Working with DVD Text Strings

IDvdInfo2::GetDVDTextStringAsNative

IDvdInfo2 Interface

Retrieves the text string for the specified language as an array of bytes.

Syntax

HRESULT GetDVDTextStringAsNative(
  ULONG ulLangIndex,
  ULONG ulStringIndex,
  BYTE *pchBuffer,
  ULONG ulMaxBufferSize,
  ULONG *pulActualSize,
  DVD_TextStringType *pType
);

Parameters

ulLangIndex
[in] Language index.
ulStringIndex
[in] String index of the given language.
pchBuffer
[out] Pointer to a buffer that receives the text string. If pchBuffer is NULL, then this method returns only the size of the string in pulActualSize.
ulMaxBufferSize
[in] Maximum string size allowed (size of pchBuffer).
pulActualSize
[out] Actual length, in bytes, of the string returned in pchBuffer, including the terminating NULL.
pType
[out] Pointer to a variable of type DVD_TextStringType that receives the type of string data returned.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.
E_UNEXPECTEDAn unexpected internal error occurred.

Remarks

In general, a robust application can handle Unicode™ strings. So, when getting a string, you generally first call GetDVDTextStringAsUnicode. But because some strings might contain characters that cannot be represented in Unicode, if GetDVDTextStringAsUnicode fails, the application can try calling GetDVDTextStringAsNative.

A terminating NULL is appended to the returned string.

See Also

Working with DVD Text Strings

IDvdInfo2::GetDVDTextStringAsUnicode

IDvdInfo2 Interface

Retrieves the text string for the specified language and string indexes in Unicode™.

Syntax

HRESULT GetDVDTextStringAsUnicode(
    ULONG ulLangIndex,
    ULONG ulStringIndex,
    TCHAR *pchBuffer,
    ULONG ulMaxBufferSize,
    ULONG *pulActualSize,
    enum DVD_TextStringType *pType
  );

Parameters

ulLangIndex
[in] Language index.
ulStringIndex
[in] String index of the given language.
pchBuffer
[out] Pointer to a buffer that receives the text string. If pchBuffer is NULL, then this method returns only the size of the string in pulActualSize.
ulMaxBufferSize
[in] Maximum string size allowed, calculated as sizeof(pchBuffer)/sizeof(*pchBuffer).
pulActualSize
[out] Pointer to a variable of type ULONG that receives the actual length of the string returned in pchBuffer, including the terminating NULL.
pType
[out] Pointer to a variable of type DVD_TextStringType that receives the type of string data returned.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.
E_UNEXPECTED An unexpected internal error occurred.

Remarks

In general, a robust application can handle Unicode™ strings. So, when getting a string, you generally first call GetDVDTextStringAsUnicode. But because some strings might contain characters that cannot be represented in Unicode, if GetDVDTextStringAsUnicode fails, the application can try calling GetDVDTextStringAsNative.

A terminating NULL is appended to the returned string.

See Also

Working with DVD Text Strings

IDvdInfo2::GetMenuLanguages

IDvdInfo2 Interface

Retrieves all the languages available for all menus on the disc.

Syntax

HRESULT GetMenuLanguages(
    LCID *pLanguages,
    ULONG ulMaxLanguages,
    ULONG *puActualLanguages
  );

Parameters

pLanguages
[out] Pointer to an LCID array that receives the languages returned. To retrieve only the number of languages available for menus, and not the actual languages themselves, specify NULL for pLanguages.
ulMaxLanguages
[in] Maximum number of languages to retrieve.
puActualLanguages
[out] Pointer to a variable of type ULONG that receives the actual number of languages retrieved.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_UNEXPECTEDThe DVD Navigator is not initialized.

IDvdInfo2::GetNumberOfChapters

IDvdInfo2 Interface

Retrieves the number of chapters in a given title.

Syntax

HRESULT GetNumberOfChapters(
  ULONG ulTitle,
  ULONG *pulNumOfChapters
);

Parameters

ulTitle
[in] Variable of type ULONG that specifies the title.
pulNumOfChapters
[out] Pointer to a variable of type ULONG that receives the number of chapters for the specified title.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_POINTERA parameter is invalid.
E_UNEXPECTEDThe DVD Navigator is not initialized.

Remarks

Call this method to get the number of chapters before calling IDvdControl2::PlayChapter, to ensure that you specify a valid chapter number.

IDvdInfo2::GetPlayerParentalLevel

IDvdInfo2 Interface

Retrieves the current parental level and ISO 3166 country code settings for the DVD Navigator.

Syntax

HRESULT GetPlayerParentalLevel(
  ULONG *pulParentalLevel,
  ULONG *pulCountryCode
);

Parameters

pulParentalLevel
[out] Pointer to a variable of type ULONG that receives a value indicating the current parental level. Valid parental levels are 1 through 8 if parental management is enabled, 0xFFFFFFFF if parental management is disabled.
pulCountryCode
[out] Pointer to a variable of type ULONG that receives a value indicating the current country code (ISO 3166 Alpha-2 Code).

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERA parameter is invalid.

Remarks

Parental management is disabled by default in the DVD Navigator. This method is demonstrated in the DVDSample application in CDvdCore::GetParentalLevel.

See Also

Enforcing Parental Management Levels, EC_DVD_PARENTAL_LEVEL_CHANGE

IDvdInfo2::GetState

IDvdInfo2 Interface

Retrieves a bookmark containing the disc location and DVD Navigator state information.

Syntax

HRESULT GetState(
    IDvdState **pStateData
);

Parameters

pStateData
[out] Address of a pointer to the IDvdState interface of a DvdState object allocated by the DVD Navigator.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_UNEXPECTEDDVD Navigator is not initialized.

Remarks

When this method is called, the DVD Navigator creates a new state object and saves the current location into it, as well as the current parental level and other state information. The DVDState object can be used to restore the DVD Navigator to the saved location at a later time through a call to IDvdControl2::SetState. This enables viewers to stop viewing in the middle of a disc, save the location, and come back at some later time to begin viewing where they left off, with all the internal settings restored as they were before.

The DVD Navigator calls AddRef on the DvdState object before returning it to the application. The application must call Release on the object when it is finished with it.

This method is demonstrated in the DVDSample application in CDvdCore::RestoreBookmark.

IDvdInfo2::GetSubpictureLanguage

IDvdInfo2 Interface

Retrieves the language of the specified subpicture stream within the current title.

Syntax

HRESULT GetSubpictureLanguage(
  ULONG ulStream,
  LCID *pLanguage
  );

Parameters

ulStream
[in] Number of the subpicture stream for which the language is being retrieved.
pLanguage
[out] Pointer to an LCID that receives the locale information. The language information can then be extracted from the LCID by using the Win32 MAKELANGID macro.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
VFW_E_DVD_INVALIDDOMAINThe DVD Navigator is not initialized or not in a valid domain.

Remarks

To get the text languages available for a menu, call GetMenuLanguages. GetSubpictureLanguage sets the value pointed to by pLanguage to zero if the stream contains an unknown language. Call the Win32 GetLocaleInfo function as follows to create a human-readable string name from pLanguage. LOCALE_SENGLANGUAGE is the locale information type, pszString is a pointer to a buffer to receive the requested data, and cbSize specifies the size of pszString.

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

IDvdInfo2::GetTitleAttributes

IDvdInfo2 Interface

Retrieves attributes of all video, audio, and subpicture streams for the specified title and its menus.

Syntax

HRESULT GetTitleAttributes(
    ULONG ulTitle,
    DVD_MenuAttributes *pMenu,
    DVD_TitleAttributes *pTitle 
    );

Parameters

ulTitle
[in] Variable of type ULONG, from 1 through 99, specifying the requested title number. Specify 0xFFFFFFFF for the current title.
pMenu
[out] Pointer to a DVD_MenuAttributes structure that receives the attributes of the menu associated with the specified title.
pTitle
[out] Pointer to a DVD_TitleAttributes structure that receives the attributes of the specified title.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGThe nTitle parameter is invalid.
E_INVALIDDOMAIN The DVD Navigator is not in the title domain.
E_POINTERThe pMenu or pTitle parameter is invalid.
E_UNEXPECTEDDVD Navigator is not initialized or some other internal error occurred.

IDvdInfo2::GetTitleParentalLevels

IDvdInfo2 Interface

Retrieves the parental levels that are defined for a particular title.

Syntax

HRESULT GetTitleParentalLevels(
    ULONG ulTitle,
    ULONG *pulParentalLevels
  );

Parameters

ulTitle
[in] Title for which parental levels are requested. Specify 0xfffffff to return the parental levels for the current title.
pulParentalLevels
[out] Pointer to a variable of type ULONG that receives a bitwise OR combination of DVD_PARENTAL_LEVEL values defined for the title.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_UNEXPECTEDThe DVD Navigator is not initialized.

Remarks

A title can contain different parental levels for different sections.

See Also

Setting and Enforcing Parental Management Levels

IDvdInfo2::GetTotalTitleTime

IDvdInfo2 Interface

Retrieves the total playback time for the current title.

Syntax

HRESULT GetTotalTitleTime(
    DVD_HMSF_TIMECODE *pTotalTime,
    ULONG *pulTimeCodeFlags
  );

Parameters

pTotalTime
[out] Pointer to a variable of type DVD_HMSF_TIMECODE that receives the total time in hours, minutes, seconds, and frames.
pulTimeCodeFlags
[out] Pointer to a variable of type ULONG that receives a DVD_TIMECODE_FLAGS value indicating the frame rate at which the disc was authored to play. Specify NULL if you don't want to receive the timecode information.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.
VFW_E_DVD_INVALIDDOMAINThe DVD Navigator is not in the title domain.
VFW_S_DVD_NON_ONE_SEQUENTIALThe title is not a one sequential video title.

Remarks

The total title time is the time required to play the title sequentially, not counting any stills, pauses, and so on.

This method is for use only with one sequential video titles, which are titles such as movies in which each chapter automatically branches to the next chapter so that the entire title plays continuously without stopping. Nonsequential video titles are titles whose chapters do not automatically play one after another. Because of variations in how DVD authors encode time information on nonsequential video titles, do not use this method to determine the total time for such titles.

IDvdInfo2::GetVMGAttributes

IDvdInfo2 Interface

Retrieves attributes of all video, audio, and subpicture streams for the Video Manager Menu.

Syntax

HRESULT GetVMGAttributes(
  DVD_MenuAttributes *pATR
);

Parameters

pATR
[out] Pointer to a DVD_MenuAttributes structure that receives the attributes.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERInvalid argument.
E_UNEXPECTED The DVD Navigator is not initialized.

Remarks

The Video Manager Menu is not associated with any particular title number.

IDvdInfo2::IsAudioStreamEnabled

IDvdInfo2 Interface

Determines if the specified audio stream is enabled in the current title.

Syntax

HRESULT IsAudioStreamEnabled(
    ULONG ulStreamNum,
    BOOL *pbEnabled
    );

Parameters

ulStreamNum
[in] Audio stream number to test.
pbEnabled
[out] Pointer to a variable of type BOOL that receives a value of TRUE if the audio stream is enabled, or FALSE otherwise.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_UNEXPECTEDThe DVD Navigator is not initialized.

Remarks

A DVD can have up to eight separate audio streams, although typically not all the streams will be enabled for each title. Use IsAudioStreamEnabled to determine whether a particular stream is enabled for the current title, and then call IDvdControl2::SelectAudioStream to select one of the enabled streams.

IDvdInfo2::IsSubpictureStreamEnabled

IDvdInfo2 Interface

Determines if the specified subpicture stream is enabled in the current title.

Syntax

HRESULT IsSubpictureStreamEnabled(
    ULONG ulStreamNum,
    BOOL *pbEnabled
);

Parameters

ulStreamNum
[in] Subpicture stream number to test.
pbEnabled
[out] Pointer to a variable of type BOOL that receives a value of TRUE if the audio stream is enabled, or FALSE otherwise.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_UNEXPECTEDThe DVD Navigator is not initialized.

Remarks

A DVD can have up to 32 separate subpicture streams, although typically not all the streams will be enabled for each title. Use IsSubpictureStreamEnabled to determine whether a particular stream is enabled for the current title, and then call IDvdControl2::SelectSubpictureStream to select one of the enabled streams.