Interfaces

Interfaces


This section describes the Microsoft® Windows® shell interfaces.

ICommDlgBrowser
IContextMenu
IContextMenu2
IContextMenu3
ICopyHook
IDeskBand
IDockingWindow
IDockingWindowFrame
IDockingWindowSite
IEnumIDList
IExtractIcon
IFileViewer
IFileViewerSite
IInputObject
IInputObjectSite
INewShortcutHook
INotifyReplica
IPersistFolder
IQueryInfo
IReconcilableObject
IReconcileInitiator
IShellBrowser
IShellChangeNotify (No documentation available at this time)
IShellExecuteHook
IShellExtInit
IShellFolder
IShellIcon
IShellIconOverlay (No documentation available at this time)
IShellIconOverlayIdentifier (No documentation available at this time)
IShellLink
IShellPropSheetExt
IShellView
IShellView2 (No documentation available at this time)
ITaskbarList
IURLSearchHook

ICommDlgBrowser

The ICommDlgBrowser interface is used by the common file dialog boxes to extend the behavior of the shell browser. This interface is obtained by calling QueryInterface on the IShellBrowser object.

When to Implement

This interface is implemented only by the common file dialog boxes.

When to Use

Use ICommDlgBrowser when you need to provide special behavior while hosted inside the common dialog boxes.
ICommDlgBrowser Methods Description
IncludeObject Allows the common dialog to filter objects that the view displays.
OnDefaultCommand Called when a user double-clicks in the view or presses the ENTER key.
OnStateChange Called after a change of state has occurred in a common dialog box.

ICommDlgBrowser::IncludeObject

HRESULT IncludeObject(
    IShellView * ppshv,
    LPCITEMIDLIST pidl
   );

Allows the common dialog to filter objects that the view displays.

ppshv
IShellFolder interface address of the view.
pidl
Address of an identifier list (IDLIST) that is relative to the folder.

This method is called by the IEnumIDList implementation when hosted in the file dialogs. The enumerator should call this method to let the common dialog filter out objects that should not be displayed. Typically, the file dialogs will get the display text of the item, and filter by the extension.

Notes to Callers

Call before returning an object in the shell folder's IDLIST enumerator.

See also ICommDlgBrowser

ICommDlgBrowser::OnDefaultCommand

HRESULT OnDefaultCommand(
    IShellView * ppshv
   );

Called when a user double-clicks in the view or presses the ENTER key.

ppshv
IShellFolder interface address of the view.

The browser should return S_OK if it has processed the action or S_FALSE to let the view perform the default action.

Note to Callers

This method allows the default command to be handled by the common dialog box instead of the view.

See also ICommDlgBrowser

ICommDlgBrowser::OnStateChange

HRESULT OnStateChange(
    IShellView * ppshv,
    ULONG uChange
   );

Called after a state, identified by the uChange parameter, has changed in the IShellView interface.

ppshv
IShellFolder interface address of the view.
uChange
Specifies the change in the selection state. This parameter can be one of the following values:
CDBOSC_SETFOCUS The focus has been set to the view.
CDBOSC_KILLFOCUS The view has lost the focus.
CDBOSC_SELCHANGE The selection has changed.
CDBOSC_RENAME An item has been renamed.

This method is used to let the common file dialogs track the state of the view and change its user interface as needed.

Notes to Callers

When items in the view are selected, or when the view loses the focus, it needs to call this method to notify the common dialog that either the view state or selection state is changing.

See also ICommDlgBrowser

IContextMenu

The IContextMenu interface is used to either create or merge a context menu associated with a certain object.

Default context menus are available for most objects that are visible within Windows Explorer's namespace, such as files, folders, and printer objects. System-provided context menus are adaptable to file objects of any type, provided you have made the appropriate registry entries.

When to Implement

Implement IContextMenu in the following situations:

Shell extensions based on this interface must be initialized by using the IShellExtInit interface.

Also note that shell extensions do not work unless all appropriate registry entries are made.

When to Use

You do not call this interface directly. It is called by the shell when a user chooses a context menu item that has been added by a handler registered under the appropriate registry keys or when an application includes it as the riid parameter in a call to IShellFolder::GetUIObjectOf.

IContextMenu Methods Description
GetCommandString Retrieves the language-independent name of a menu command or the Help text for a menu command.
InvokeCommand Carries out a menu command. For an example, see the IExtractIcon interface.
QueryContextMenu Adds commands to a context menu.

IContextMenu::GetCommandString

HRESULT GetCommandString(
    UINT idCmd,
    UINT uFlags,
    UINT *pwReserved,
    LPSTR pszName,
    UINT cchMax
   );

Retrieves the language-independent command string or the Help text for a context menu item.

idCmd
Menu item identifier offset.
uFlags
Flags specifying the information to retrieve. This can be one of the following values:
GCS_HELPTEXT Returns the Help text for the menu item.
GCS_VALIDATE Validates that the menu item exists.
GCS_VERB Returns the language-independent command name for the menu item.
pwReserved
Reserved. Applications must specify NULL when calling this method, and handlers must ignore this parameter when called.
pszName
Address of the buffer to receive the null-terminated string being retrieved.
cchMax
Size of the buffer to receive the null-terminated string.

The language-independent command name can be passed to the IContextMenu::InvokeCommand method to activate a command by an application. The Help text is a description that Windows Explorer displays in its status bar; it should be reasonably short (under 40 characters).

See also IContextMenu

IContextMenu::InvokeCommand

HRESULT InvokeCommand(
    LPCMINVOKECOMMANDINFO lpici
   );

Carries out the command associated with a context menu item.

lpici
Address of a CMINVOKECOMMANDINFO structure containing information about the command.

The shell calls this method when the user chooses a command that the handler added to a context menu. This method may also be called by an application without any corresponding user action.

See also IContextMenu

IContextMenu::QueryContextMenu

HRESULT QueryContextMenu(
    HMENU hmenu,
    UINT indexMenu,
    UINT idCmdFirst,
    UINT idCmdLast,
    UINT uFlags
   );

Adds menu items to the specified menu. The menu items should be inserted in the menu at the position specified by indexMenu, and their menu item identifiers must be between the idCmdFirst and idCmdLast parameter values.

hmenu
Handle to the menu. The handler should specify this handle when adding menu items.
indexMenu
Zero-based position at which to insert the first menu item.
idCmdFirst
Minimum value that the handler can specify for a menu item identifier.
idCmdLast
Maximum value that the handler can specify for a menu item identifier.
uFlags
Optional flags specifying how the context menu can be changed. Can be any combination of the following values:
CMF_CANRENAME This flag is set if the calling application supports renaming of items. A context menu extension or drag-and-drop handler should ignore this flag. A namespace extension should add a rename item to the menu if applicable.
CMF_DEFAULTONLY This flag is set when the user is activating the default action, typically by double-clicking. This flag provides a hint for the context menu extension to add nothing if it does not modify the default item in the menu. A context menu extension or drag-and-drop handler should not add any menu items if this value is specified. A namespace extension should add only the default item (if any).
CMF_EXPLORE This flag is set when Windows Explorer's tree window is present. Context menu handlers should ignore this value.
CMF_INCLUDESTATIC This flag is set when a static menu is being constructed. Only the browser should use this flag. All other context menu extensions should ignore this flag.
CMF_NODEFAULT This flag is set if no item in the menu should be the default item. A context menu extension or drag-and-drop handler should ignore this flag. A namespace extension should not set any of the menu items to the default.
CMF_NORMAL Indicates normal operation. A context menu extension, namespace extension, or drag-and-drop handler can add all menu items.
CMF_NOVERBS This flag is set for items displayed in the "Send To:" menu. Context menu handlers should ignore this value.
CMF_VERBSONLY This flag is set if the context menu is for a shortcut object. Context menu handlers should ignore this value.

The remaining bits of the low-order word are reserved by the system. The high-order word may be used for context-specific communications. The CMF_RESERVED value can be used to mask out the low-order word.

The actual identifier of each menu item should be idCmdFirst plus a menu identifier offset in the range zero through (idCmdLastidCmdFirst).

See also IContextMenu

IContextMenu2

The IContextMenu2 interface is used to either create or merge a context menu associated with a certain object when the menu involves owner-drawn menu items.

When to Implement

Implement IContextMenu2 if your context menu extension needs to process one or more of the following messages:
WM_INITMENUPOPUP
WM_DRAWITEM
WM_MEASUREITEM

These messages are forwarded to IContextMenu2—through the HandleMenuMsg method—only if a QueryInterface call for an IContextMenu2 interface pointer is successful, indicating that the object supports this interface.

When to Use

You do not call this interface directly. IContextMenu2 is used by the operating system only when it has confirmed that your application is aware of this interface.

IContextMenu2 is derived from IUnknown. The following methods are specific to IContextMenu2.

IContextMenu2 Methods Description
GetCommandString Retrieves the language-independent name of a menu command or the Help text for a menu command.
HandleMenuMsg Handles messages related to drawing owner-drawn menu items.
InvokeCommand Carries out a menu command. For an example, see the IExtractIcon interface.
QueryContextMenu Adds commands to a context menu.

IContextMenu2::GetCommandString

HRESULT GetCommandString(
    UINT idCmd,
    UINT uFlags,
    UINT *pwReserved,
    LPSTR pszName,
    UINT cchMax
   );

Retrieves the language-independent command string or the Help text for a context menu item.

idCmd
Menu item identifier offset.
uFlags
Flag specifying the information to retrieve. This parameter can be one of the following values:
GCS_HELPTEXT Returns the Help text for the menu item.
GCS_VALIDATE Validates that the menu item exists.
GCS_VERB Returns the language-independent command name for the menu item.
pwReserved
Reserved. Applications must specify NULL when calling this method, and handles must ignore this parameter when called.
pszName
Address of the buffer to receive the null-terminated string being retrieved.
cchMax
Size of the buffer to receive the null-terminated string.

The language-independent command name is a name that can be passed to the IContextMenu::InvokeCommand method to activate a command by an application. The Help text is a description that Windows Explorer displays in its status bar; it should be reasonably short (under 40 characters).

See also IContextMenu2, IContextMenu

IContextMenu2::HandleMenuMsg

HRESULT HandleMenuMsg(
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam
   );

Allows client objects of the IContextMenu interface to handle messages associated with owner-drawn menu items.

uMsg
Message to be processed. If it is WM_INITPOPUP, WM_DRAWITEM, or WM_MEASUREITEM, the client object being called may provide owner-drawn menu items.
wParam
Additional message information. The value of this parameter depends on the value of the uMsg parameter.
lParam
Additional message information. The value of this parameter depends on the value of the uMsg parameter.

HandleMenuMsg is called when a client of IContextMenu determines that the IContextMenu2 interface is supported and receives one of the messages specified in the description of the uMsg parameter.

IContextMenu2::InvokeCommand

HRESULT InvokeCommand(
    LPCMINVOKECOMMANDINFO lpici
   );

Carries out the command associated with a context menu item.

lpici
Address of a CMINVOKECOMMANDINFO structure containing information about the command.

See also IContextMenu2, IContextMenu

IContextMenu2::QueryContextMenu

HRESULT QueryContextMenu(
    HMENU hmenu,
    UINT indexMenu,
    UINT idCmdFirst,
    UINT idCmdLast,
    UINT uFlags
   );

Adds menu items to the specified menu. The menu items should be inserted at a specified position in the menu, and their menu item identifiers must be in a given range.

hmenu
Handle to the menu. The handler should specify this handle when adding menu items.
indexMenu
Zero-based position at which to insert the first menu item.
idCmdFirst
Minimum value that the handler can specify for a menu item identifier.
idCmdLast
Maximum value that the handler can specify for menu item identifiers.
uFlags
Optional flags specifying how the context menu can be changed. Can be any combination of the following values:
CMF_DEFAULTONLY The user activates the default action, typically by double-clicking. This value provides a hint for the context menu to add nothing if it does not modify the default item in the menu. A context menu extension or drag-and-drop handler should not add any menu items if this value is specified. A namespace extension should add only the default item (if any).
CMF_EXPLORE Context menu handlers should ignore this value. It is specified when the context menu is for an object in Windows Explorer.
CMF_NORMAL Indicates normal operation. A context menu extension, namespace extension, or drag-and-drop handler can add any menu items.
CMF_VERBSONLY Context menu handlers should ignore this value. This value is specified if the context menu is for a shortcut object.

The remaining bits of the low-order word are reserved by the system. The high-order word may be used for context-specific communications.

The actual identifier of each menu item should be idCmdFirst plus a menu identifier offset in the range zero through (idCmdLastidCmdFirst).

See also IContextMenu2, IContextMenu

IContextMenu3

The IContextMenu3 interface is used to create or merge a context menu associated with a certain object when the menu implementation needs to process the WM_MENUCHAR message.

When to Implement

Implement IContextMenu3 if your context menu extension needs to process the WM_MENUCHAR message.

These messages are forwarded to IContextMenu3—through the HandleMenuMsg2 method—only if a QueryInterface call for an IContextMenu3 interface pointer is successful, indicating that the object supports this interface.

When to Use

You do not call this interface directly. IContextMenu3 is used by the operating system only when it has confirmed that your application is aware of this interface.

IContextMenu3 is derived from IContextMenu2. The following method is specific to IContextMenu3:

IContextMenu3 Method Description
HandleMenuMsg2 Called when the window that owns the menu receives a WM_MENUCHAR message.

Note This interface is only supported in shell versions 4.71 and later.

IContextMenu3::HandleMenuMsg2

HRESULT HandleMenuMsg2(
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam,
    LRESULT *plResult
);

Allows context menu handlers to process the WM_MENUCHAR message.

uMsg
Message to be processed. At the present time, this method is only called for WM_MENUCHAR.
wParam
Additional message information. The value of this parameter depends on the value of the uMsg parameter.
lParam
Additional message information. The value of this parameter depends on the value of the uMsg parameter.
plResult
Address of an LRESULT value that the owner of the menu will return from the message.

HandleMenuMsg2 is called when a client of IContextMenu determines that the IContextMenu3 interface is supported and receives one of the messages specified in the description of the uMsg parameter.

Version 4.71

See also IContextMenu2

ICopyHook

ICopyHook is a COM-based interface used to create a copy hook handler. A copy hook handler is a shell extension that determines if a shell folder or printer object can be moved, copied, renamed, or deleted. The shell calls the ICopyHook::CopyCallback method prior to performing one of these operations.

The copy hook handler, which is an OLE in-process server (a DLL), does not perform the task itself, but it does approve or disapprove the action. If the shell receives approval from the copy hook handler, it performs the file system operation. Copy hook handlers are not informed about the success of an operation, so they cannot monitor actions taken on folder objects unless FindFirstChangeNotification is used.

A folder object can have multiple copy hook handlers. For example, even if the shell already has a copy hook handler registered for a particular folder object, you can still register one of your own. If two or more copy hook handlers are registered for an object, the shell simply calls each of them before performing one of the specified file system operations.

The shell initializes ICopyHook directly, without using the IShellExtInit interface first.

CopyCallback returns an integer value that indicates whether or not the shell should perform the operation. The shell will call each copy hook handler registered for a folder object until all the handlers have been called or until one of them has returned a value other than IDYES. The handler returns IDYES to specify that the operation should be performed, or IDNO or IDCANCEL to specify that the operation should be discontinued.

When to Implement

Implement a copy hook handler when you want to be able to control when, or if, these file system operations are performed on a given object. You might want to use a copy hook handler on shared folders, for example.

When to Use

You do not call this shell extension directly. ICopyHook::CopyCallback is called by the shell prior to moving, copying, deleting, or renaming a shell folder object.
ICopyHook Method Description
CopyCallback Determines whether a move, copy, delete, or rename operation on a folder object should be allowed or disallowed.

ICopyHook::CopyCallback

UINT CopyCallback(
    HWND hwnd,
    UINT wFunc,
    UINT wFlags,
    LPCSTR pszSrcFile,
    DWORD dwSrcAttribs,
    LPCSTR pszDestFile,
    DWORD dwDestAttribs
   );

Determines whether the shell will be allowed to move, copy, delete, or rename a folder or printer object. The shell calls each copy hook handler registered (see comments below) for a folder or printer object until all the handlers have been called or until one of them returns IDNO or IDCANCEL.

hwnd
Handle to the window that the copy hook handler should use as the parent for any user interface elements the handler may need to display. If FOF_SILENT is specified, the method should ignore this parameter.
wFunc
Operation to perform. This parameter can be one of the values listed under the wFunc member of the SHFILEOPSTRUCT structure.
wFlags
Flags that control the operation. This parameter can be one or more of the values listed under the fFlags member of the SHFILEOPSTRUCT structure.
pszSrcFile
Address of a string that contains the name of the source file.
dwSrcAttribs
Attributes of the source file. This parameter can be a combination of any of the file attribute flags (FILE_ATTRIBUTE_*) defined in the Windows header files.
pszDestFile
Address of a string that contains the name of the destination file.
dwDestAttribs
Attributes of the destination file. This parameter can be a combination of any of the file attribute flags (FILE_ATTRIBUTE_*) defined in the Windows header files.

You need to register your copy hook handler. For example, directory copy hook handlers are registered under HKEY_CLASSES_ROOT\directory\shellex\CopyHookHandlers\your_copyhook\{copyhook CLSID value}. Other registry keys associated with shell extensions are: *, Folder, Drives, Printers, Unknown, and AudioCD.

When this method is called, the shell initializes the ICopyHook interface directly without using an IShellExtInit interface first.

See also SHFileOperation

IDeskBand

IDeskBand is used to obtain information about a band object. See Band Objects for more information about band objects.

When to Implement

Implement IDeskBand if you are implementing a band object.

When to Use

You do not call this interface directly. IDeskBand is used by the shell or the browser to obtain display information for a band object.

IDeskBand is derived from IDockingWindow. The following method is specific to IDeskBand.

IDeskBand Method Description
GetBandInfo Retrieves the information for a band object.

Note This interface is only supported in shell versions 4.71 and later.

IDeskBand::GetBandInfo

HRESULT GetBandInfo(
    DWORD dwBandID, 
    DWORD dwViewMode, 
    DESKBANDINFO* pdbi
);

Retrieves the information for a band object.

dwBandID
Identifier of the band. The container assigns this identifier. The band object can keep this value if it is required.
dwViewMode
View mode of the band object. This will be one of the following values:
DBIF_VIEWMODE_NORMAL The band object is being displayed in a horizontal band.
DBIF_VIEWMODE_VERTICAL The band object is being displayed in a vertical band.
DBIF_VIEWMODE_FLOATING The band object is being displayed in a floating band.
DBIF_VIEWMODE_TRANSPARENT The band object is being displayed in a transparent band.
pdbi
Address of a DESKBANDINFO structure that receives the band information for the object. The dwMask member of this structure indicates what information is being requested.

Version 4.71

IDockingWindow

The IDockingWindow interface is implemented by window objects that can be docked within the border space of a Windows Explorer window.

When to Implement

You implement IDockingWindow when you want to display a window inside a browser frame. This is normally used for user interface windows, such as toolbars.

When to Use

You do not normally use the IDockingWindow interface. The shell browser uses this interface to support docked windows inside the browser frame.

IDockingWindow is derived from IOleWindow. The following are the methods specific to IDockingWindow.

IDockingWindow Method Description
CloseDW Notifies the docking window object that it is about to be removed.
ResizeBorderDW Notifies the docking window object that the frame's border space has changed.
ShowDW Instructs the docking window object to show or hide itself.

Note This interface is only supported in shell versions 4.71 and later.

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