Microsoft DirectX 8.0 |
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 methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IDvdInfo2 methods Description Menus GetButtonAtPosition Retrieves the button located at the specified point within the display window. GetButtonRect Retrieves the rectangle coordinates of the specified button. GetCurrentButton Retrieves the number of available buttons and the number of the currently selected button. GetDefaultMenuLanguage Retrieves the default menu language. GetMenuLanguages Retrieves all the languages available for all menus on the disc. GetVMGAttributes Retrieves attributes of all video, audio, and subpicture streams for the video manager menu. Titles GetNumberOfChapters Retrieves the number of chapters in a given title. GetTitleAttributes Retrieves attributes of all video, audio, and subpicture streams for the specified title and its menus. GetTotalTitleTime Retrieves the total playback time for the current title. Disc Information GetAllSPRMs Retrieves the current contents of all system parameter registers (SPRMs). GetAllGPRMs Retrieves the current contents of all general parameter registers (GPRMs). GetCurrentUOPS Retrieves a set of flags indicating which navigation commands, if any, the content authors have explicitly disabled for the current disc location. GetDiscID Retrieves a system-generated 64-bit "unique" identification number for the specified DVD. GetDVDVolumeInfo Retrieves the current DVD volume information. Video Stream GetCurrentAngle Retrieves the number of available angles in the current angle block and the currently selected angle number. GetCurrentVideoAttributes Retrieves the video attributes of the current title or menu. Audio Stream GetAudioAttributes Retrieves the attributes of the specified audio stream in the current title or menu. GetAudioLanguage Retrieves the language of the specified audio stream within the current title. GetCurrentAudio Retrieves the number of available audio streams and the number of the currently selected audio stream. GetDecoderCaps 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 (Dolby AC-3, MPEG-2, DTS, SDDS, LPCM). GetDefaultAudioLanguage Retrieves the default audio language. GetKaraokeAttributes Retrieves the karaoke attributes of the specified audio stream in the current title or menu. IsAudioStreamEnabled Determines if the specified audio stream is enabled in the current title. Subpicture Stream GetCurrentSubpicture Retrieves the number of available subpicture streams in the current title, the currently selected subpicture stream number, and the state of the subpicture. GetDefaultSubpictureLanguage Retrieves the default subpicture language. GetSubpictureAttributes Retrieves the attributes of the specified subpicture stream in the current title or menu. GetSubpictureLanguage Retrieves the language of the specified subpicture stream within the current title. IsSubpictureStreamEnabled Determines if the specified subpicture stream is enabled in the current title. Parental Levels GetPlayerParentalLevel Retrieves the current parental level and ISO 3166 country code settings for the DVD Navigator. GetTitleParentalLevels Retrieves the parental levels that are defined for a particular title. DVD Navigator State Information GetCmdFromEvent Retrieves an IDvdCmd object from an EC_DVD_CMD_START, EC_DVD_CMD_END, or VFW_E_DVD_CMD_CANCELLED event. GetCurrentDomain Retrieves the DVD domain in which the DVD Navigator is currently located. GetCurrentLocation Retrieves the current playback location. GetDVDDirectory Retrieves the root directory that is set in the DVD Navigator. GetState Retrieves a bookmark containing the disc location and DVD Navigator state information. DVD Text Strings GetDVDTextNumberOfLanguages Retrieves the number of text languages for the current DVD or disc side. GetDVDTextLanguageInfo Retrieves the information for the specified text string language block. GetDVDTextStringAsNative Retrieves the text string for the specified language as an array of bytes. GetDVDTextStringAsUnicode Retrieves the text string for the specified language in Unicode.
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_OK Success. E_POINTER Invalid 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
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_OK Success. E_POINTER Invalid 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).
Register Contents 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. 10 Low 15 bits (b0-b14) contain PGC number in current title (1 to 32767). Default value is undefined. 11 Six 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. 12 ISO-3166 country code (two uppercase ASCII letters) or 65535 (not specified). Default value is undefined. 13 Low 4 bits (b0-b3) contain parental level (1 to 8) or 15 (none). Default value is undefined. 14 b8-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. 15 Nine 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. 16 ISO-639 language code (two lowercase ASCII letters) or 65535 (not specified). Default value is 65535. 17 Language 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. 18 ISO-639 language code (two lowercase ASCII letters) or 65535 (not specified). Default value is 65535. 19 Language 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. 20 Low 8 bits (b0-b7) contain region code (1 to 8).
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_OK Success. E_UNEXPECTED The DVD Navigator is not initialized. VFW_E_DVD_NO_ATTRIBUTES The stream's audio attributes are not available for some reason. E_POINTER Invalid argument.
Remarks
ulStream can be any index number from 0 through 7 or one of the following values:
DVD_DEFAULT_AUDIO_STREAM to 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.
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER The pLanguage parameter is NULL. E_UNEXPECTED The DVD Navigator is not initialized. VFW_E_DVD_INVALIDDOMAIN DVD 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
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER The puButtonIndex parameter is invalid. VFW_E_DVD_NO_BUTTON No 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
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_NOTIMPL This method is currently not implemented
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_OK Success. E_FAIL The command no longer exists. E_POINTER Invalid 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
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_OK Success. E_POINTER Invalid argument. VFW_E_DVD_INVALIDDOMAIN DVD 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
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_OK Success. E_POINTER Input arguments are invalid. VFW_E_DVD_INVALIDDOMAIN The 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
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_OK Success. E_POINTER One of the pointer arguments is not valid.
Remarks
If buttons are not present, both pulButtonsAvailable and pulCurrentButton are set to zero.
See Also
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_OK Success. E_UNEXPECTED Unexpected error. E_POINTER Invalid 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
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER The pLocation parameter is invalid. VFW_E_DVD_INVALIDDOMAIN The 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.
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_OK Success. E_POINTER Invalid argument. VFW_E_DVD_INVALIDDOMAIN The 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
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_OK Success. E_POINTER Invalid argument. E_UNEXPECTED The DVD Navigator is not initialized.
Remarks
The use of this method is demonstrated in the DVDSample application in CDvdCore::GetVideoAttributes().
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_OK Success. VFW_E_WRONG_STATE The filter graph has not been initialized.
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER The pLanguage parameter is NULL. E_UNEXPECTED The DVD Navigator is not initialized. VFW_E_DVD_INVALIDDOMAIN DVD Navigator is not in a valid domain.
See Also
IDvdControl2::SelectAudioStream, IDvdControl2::SelectDefaultAudioLanguage
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER The pLanguage parameter is NULL. E_UNEXPECTED The DVD Navigator is not initialized. VFW_E_DVD_INVALIDDOMAIN DVD Navigator is not in a valid domain.
See Also
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER The pLanguage parameter is NULL. E_UNEXPECTED The DVD Navigator is not initialized. VFW_E_DVD_INVALIDDOMAIN DVD Navigator is not in a valid domain.
See Also
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_OK Success. E_INVALIDARG Invalid 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.
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_OK Success. E_INVALIDARG The buffer is not large enough to hold the string. VFW_E_DVD_INVALIDDOMAIN The DVD Navigator is not in a valid domain.
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_OK Success. E_POINTER Invalid argument. E_UNEXPECTED The 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_STREAM to query the default audio stream.
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_OK Success. E_FAIL No subpicture streams were found. E_POINTER Invalid 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
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_OK Success. E_POINTER pulUOPs 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
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_OK Success. E_POINTER Invalid 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.
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_OK Success. E_POINTER Invalid argument. E_UNEXPECTED An 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
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_OK Success. E_POINTER Invalid 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
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_OK Success. E_POINTER Invalid 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
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_OK Success. E_POINTER Invalid 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
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_OK Success. E_INVALIDARG Invalid argument. E_UNEXPECTED The DVD Navigator is not initialized.
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_OK Success. E_INVALIDARG Invalid argument. E_POINTER A parameter is invalid. E_UNEXPECTED The 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.
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_OK Success. E_POINTER A 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
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_OK Success. E_INVALIDARG Invalid argument. E_UNEXPECTED DVD 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.
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_OK Success. E_INVALIDARG Invalid argument. VFW_E_DVD_INVALIDDOMAIN The 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);
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_OK Success. E_INVALIDARG The nTitle parameter is invalid. E_INVALIDDOMAIN The DVD Navigator is not in the title domain. E_POINTER The pMenu or pTitle parameter is invalid. E_UNEXPECTED DVD Navigator is not initialized or some other internal error occurred.
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_OK Success. E_INVALIDARG Invalid argument. E_UNEXPECTED The DVD Navigator is not initialized.
Remarks
A title can contain different parental levels for different sections.
See Also
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_OK Success. E_POINTER Invalid argument. VFW_E_DVD_INVALIDDOMAIN The DVD Navigator is not in the title domain. VFW_S_DVD_NON_ONE_SEQUENTIAL The 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.
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_OK Success. E_POINTER Invalid argument. E_UNEXPECTED The DVD Navigator is not initialized.
Remarks
The Video Manager Menu is not associated with any particular title number.
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_OK Success. E_INVALIDARG Invalid argument. E_UNEXPECTED The 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.
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_OK Success. E_INVALIDARG Invalid argument. E_UNEXPECTED The 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.