The IDvdControl interface controls the playback and search mechanisms of a digital versatile disc that contains one or more video movies.
The DVD file system is very different than a format such as CD-ROM, which contains a linear series of tracks not easily customizable by the author. The author of DVD-formatted media files can control track layout and navigation much more precisely; the media file itself comprises many parts and control mechanisms, which enables the author to arrange and rearrange the playback order as needed. You can locate a specific portion of a file by time (in hours, minutes, seconds, and frames) or by chapter value.
A media file is made up of a list of program chains (PGCs), each of which are made up of a list of programs, each of which is made up of a list of cells, each of which is made up of a list of video object units (VOBUs), each of which is made up of a list of packs, and each of which is made up of actual MPEG data.
To obtain a copy of the DVD-Video specification, "DVD Specifications for Read-Only Disc, Part 3, Video Specifications," contact Toshiba Corporation at 1-1, Shibaura 1-Chrome, Minato-ku, Tokyo 105-01, Japan, Tel. +81-3-5444-9580, Fax. +81-3-5444-9430.
When to Implement
Do not implement this interface. DirectShow implements it for you.
When to Use
Use this interface to control playback (set root drive, play, stop, and so forth) or use DVD-specific functionality such as menus and buttons when playing DVD-Video files.
Methods in Vtable Order
| IUnknown methods | Description |
| QueryInterface | Retrieves pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| IDvdControl methods | Description |
| TitlePlay | Finds the media file with the specified title index and plays it back. |
| ChapterPlay | Plays the media file with the specified title index and chapter value. |
| TimePlay | Plays the media file with the specified title index, starting at the specified time. |
| StopForResume | Transitions playback to the DVD_DOMAIN_Stop state after saving resume information. |
| GoUp | Halts playback of the current media file and starts playback of the designated previous program group chain (PGC). |
| TimeSearch | Halts playback of the current chapter and starts playback from the specified time in the same media file. |
| ChapterSearch | Halts playback of the current chapter and starts playback from the specified chapter value in the same media file. |
| PrevPGSearch | Halts playback of the current chapter and starts playback from the previous chapter in the same PGC. |
| TopPGSearch | Halts playback of the current chapter and starts playback from the first chapter within the title. |
| NextPGSearch | Halts playback of the current chapter and starts playback from the next chapter within the title. |
| ForwardScan | Search forward through the current disc at the specified speed. |
| BackwardScan | Search backward through the current disc at the specified speed. |
| MenuCall | Displays the specified menu on the screen. |
| Resume | Continues playback of a media file, if the file is paused. |
| UpperButtonSelect | Selects the upper directional button from the displayed menu. |
| LowerButtonSelect | Selects the lower directional button from the displayed menu. |
| LeftButtonSelect | Selects the left directional button from the displayed menu. |
| RightButtonSelect | Selects the right directional button from the displayed menu. |
| ButtonActivate | Activates the selected button. |
| ButtonSelectAndActivate | Selects and activates the specified button. |
| StillOff | Resumes updating the display, which stops still-store mode. |
| PauseOn | Pauses the current media file playback. |
| PauseOff | Unpauses the current media file playback. |
| MenuLanguageSelect | Sets the displayed language for navigation menus. |
| AudioStreamChange | Sets the current audio stream. |
| SubpictureStreamChange | Enables or disables picture-in-picture mode and sets the subpicture to the specified source. |
| AngleChange | Sets the new display angle. |
| ParentalLevelSelect | Sets the access level for the current media file. |
| ParentalCountrySelect | Sets the current country for controlling access levels. |
| KaraokeAudioPresentationModeChange | Sets the audio playback mode to karaoke. |
| VideoModePreferrence | Sets the video display mode the user prefers. |
| SetRoot | Sets the root directory containing the DVD-Video volume. |
| MouseActivate | Selects and activates a DVD button in response to a mouse click. |
| MouseSelect | Selects a DVD button in response to mouse movement. |
| ChapterPlayAutoStop | Start playing at the specified chapter within the specified title and play the number of chapters specified. |
Sets the new display angle.
HRESULT AngleChange(
ULONG ulAngle
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Sets the current audio stream.
HRESULT AudioStreamChange(
ULONG nAudio
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Search backward through the current disc at the specified speed.
HRESULT BackwardScan(
double dwSpeed
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Activates the selected button.
HRESULT ButtonActivate(void);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
"Selecting" a DVD button simply highlights the button but does not "activate" the button. Selecting is the Windows equivalent of tabbing to a button but not pressing the space bar or enter key. Activating is the Windows equivalent of pressing the space bar or enter key after tabbing to a button.
IDvdControl::ButtonSelectAndActivate
Selects and activates the specified button.
HRESULT ButtonSelectAndActivate(
ULONG uiButton
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Electronic remote control devices typically have a number of buttons that activate various functions of a DVD playback unit. Typically, you call this method when a user clicks a button on the control device; DirectShow then indicates that the button was selected (by playing a sound or changing a graphic, for example) and calls methods appropriate to which button was selected, such as ButtonActivate.
Plays the media file with the specified title index and chapter value.
HRESULT ChapterPlay(
ULONG uiTitle,
ULONG uiChapter
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Instructs the DVD player to start playing at the specified chapter within the specified title and play the number of chapters specified.
HRESULT ChapterPlayAutoStop(
ULONG ulTitle,
ULONG ulChapter,
ULONG ulChaptersToPlay
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Chapters range from 1 to 999.
Halts playback of the current chapter and starts playback from the specified chapter within the same title.
HRESULT ChapterSearch(
ULONG Chapter
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Search forward through the current disc at the specified speed.
HRESULT ForwardScan(
double dwSpeed
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Halts playback of the current media file and starts playback of the designated previous program group chain (PGC).
HRESULT GoUp(void);
Returns an HRESULT value.
Each PGC is associated with a previous PGC at authoring time, which this method sets as the new playback file.
Sets the audio playback mode to karaoke.
HRESULT KaraokeAudioPresentationModeChange(
ULONG ulMode
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Karaoke support is currently not implemented.
Selects the left directional button from the displayed menu.
HRESULT LeftButtonSelect(void);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). This method tells DirectShow that something (the user, probably) triggered the left directional button.
"Selecting" a DVD button simply highlights the button but does not "activate" the button. Selecting is the Windows equivalent of tabbing to a button but not pressing the space bar or enter key. Activating is the Windows equivalent of pressing the space bar or enter key after tabbing to a button.
Selects the lower directional button from the displayed menu.
HRESULT LowerButtonSelect(void);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). This method tells DirectShow that something (the user, probably) triggered the lower directional button.
"Selecting" a DVD button simply highlights the button but does not "activate" the button. Selecting is the Windows equivalent of tabbing to a button but not pressing the space bar or enter key. Activating is the Windows equivalent of pressing the space bar or enter key after tabbing to a button.
Displays the specified menu on the screen.
HRESULT MenuCall(
DVD_MENU_ID MenuID
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Sets the displayed language for navigation menus.
HRESULT MenuLanguageSelect(
LCID LanguageCode
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
This method selects the default language for menus. Call this method only from the DVD stop state (DVD_DOMAIN_Stop). Applications specify languages with Windows standard LCIDs. LCIDs can be created from ISO-639 codes with:
MAKELCID( MAKELANGID(wISO639LangID ,SUBLANG_DEFAULT ), SORT_DEFAULT )
You might have to use 'jp' instead of 'ja' for the ISO639 code for Japanese.
Selects and activates a DVD button in response to a mouse click.
HRESULT MouseActivate(
POINT point );
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
This method checks the specified point within the display window to see if it is within a current DVD button's highlight rectangle. If it is, this method selects and then activates the button.
DVD buttons do not all necessarily have highlight rectangles. Button rectangles can overlap, and the rectangles do not always correspond to the visual representation of DVD buttons.
Selects a DVD button in response to mouse movement.
HRESULT MouseSelect(
POINT point );
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
This method checks the specified point within the display window to see if it is within a current DVD button's highlight rectangle. If it is, this method selects the button.
DVD buttons do not all necessarily have highlight rectangles. Button rectangles can overlap, and the rectangles do not always correspond to the visual representation of DVD buttons.
Halts playback of the current chapter and starts playback from the next chapter within the title.
HRESULT NextPGSearch(void);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Sets the current country for controlling access levels.
HRESULT ParentalCountrySelect(
WORD wCountry
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Sets the access level for the current media file.
HRESULT ParentalLevelSelect(
ULONG ulParentalLevel
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
This method sets the current user's access level; this access level determines what media files the user can play back. Higher levels can play lower level content; lower levels can't play higher-level content. For example, adults can watch child-safe content, but children can't watch adult content.
The DVD Navigator filter provides no restriction on setting the parental level. DVD player applications can enforce restrictions on the parental level setting, such as providing password protection for raising the current parental level. The DVD Navigator is initialized by default to parental level 8 (no restriction).
To disable parental management, pass 0xffffffff for ulParentalLevel. If parental management is disabled, then the player will play the first program chain (PGC) in a parental block regardless of parental IDs.
Unpauses the current media file playback, which returns it to normal playback.
HRESULT PauseOff(void);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
If the media file wasn't paused in playback, this method does nothing.
Pauses the current media file playback.
HRESULT PauseOn( );
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
This method freezes playback and any internal timers, similar to IMediaControl::Pause.
If the media file wasn't running, this method does nothing.
Halts playback of the current chapter and starts playback from the previous chapter in the same PGC.
HRESULT PrevPGSearch(void);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Continues playback of a media file, if the file is paused.
HRESULT Resume( );
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
If the file is stopped or already running, this method does nothing.
This method returns to title playback in DVD_DOMAIN_Title. Applications typically call this method after MenuCall which puts the DVD Navigator in DVD_DOMAIN_VideoTitleSetMenu or DVD_DOMAIN_VideoManagerMenu.
Selects the right directional button from the displayed menu.
HRESULT RightButtonSelect( );
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_OUTOFMEMORY | Out of memory (insufficient buffer space). |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). This method tells DirectShow that something (the user, probably) triggered the right directional button.
"Selecting" a DVD button simply highlights the button but does not "activate" the button. Selecting is the Windows equivalent of tabbing to a button but not pressing the space bar or enter key. Activating is the Windows equivalent of pressing the space bar or enter key after tabbing to a button.
Sets the root directory containing the DVD-Video volume.
HRESULT SetRoot(
LPCWSTR pszPath );
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_POINTER | NULL pointer argument. |
| S_OK | Success. |
The current state must be DVD_DOMAIN_Stop when you call this method.
If you haven't set the root directory before calling IDvdControl::TitlePlay, the first drive starting from C: that contains a VIDEO_TS directory in the top level directory will be used as the root.
Resumes updating the display, which stops still-store mode.
HRESULT StillOff( );
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
If the display image wasn't in still-store mode, this method does nothing.
Transitions playback to the DVD_DOMAIN_Stop state after saving resume information.
HRESULT StopForResume(void);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
If no file is playing or paused, this method does nothing.
The DVD Navigator filter transfers to the stopped state, but the filter graph remains in DirectShow's Run state.
Enables or disables picture-in-picture mode and sets the subpicture to the specified source.
HRESULT SubpictureStreamChange(
ULONG nSubPicture,
BOOL bDisplay
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Plays the media file with the specified title index, starting at the specified time.
HRESULT TimePlay(
ULONG uiTitle,
ULONG bcdTime
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Halts playback of the current chapter and starts playback from the specified time in the same media file.
HRESULT TimeSearch(
ULONG bcdTime
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Finds the media file with the specified title index and plays it back.
HRESULT TitlePlay(
ULONG uiTitle
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Halts playback of the current chapter and starts playback from the first chapter within the title.
HRESULT TopPGSearch( );
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| E_UNEXPECTED | DVD is not initialized. |
| S_OK | Success. |
Selects the upper directional button from the displayed menu.
HRESULT UpperButtonSelect( );
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_NOTIMPL | Method is not supported. |
| S_OK | Success. |
On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). This method tells DirectShow that something (the user, probably) triggered the upper directional button.
"Selecting" a DVD button simply highlights the button but does not "activate" the button. Selecting is the Windows equivalent of tabbing to a button but not pressing the space bar or enter key. Activating is the Windows equivalent of pressing the space bar or enter key after tabbing to a button.
Sets the video display mode the user prefers.
HRESULT VideoModePreferrence(
ULONG ulPreferredDisplayMode
);
Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
| Value | Meaning |
| E_FAIL | Failure. |
| E_INVALIDARG | Input argument is invalid. |
| E_NOTIMPL | Method is not supported. |
| S_OK | Success. |
This method changes the default video window's aspect ratio, and may also specify a default aspect ratio conversion mechanism.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.