IShellLink
Interfaces

IShellLink


The IShellLink interface allows shell links to be created, modified, and resolved.

IShellLink Methods Description
GetArguments Retrieves the command-line arguments associated with a shell link object.
GetDescription Retrieves the description string for a shell link object.
GetHotkey Retrieves the hot key for a shell link object.
GetIconLocation Retrieves the location (path and index) of the icon for a shell link object.
GetIDList Retrieves the list of item identifiers for a shell link object.
GetPath Retrieves the path and file name of a shell link object.
GetShowCmd Retrieves the show (SW_) command for a shell link object.
GetWorkingDirectory Retrieves the name of the working directory for a shell link object.
Resolve Resolves a shell link by searching for the shell link object and updating the shell link path and its list of identifiers (if necessary).
SetArguments Sets the command-line arguments associated with a shell link object.
SetDescription Sets the description string for a shell link object.
SetHotkey Sets the hot key for a shell link object.
SetIconLocation Sets the location (path and index) of the icon for a shell link object.
SetIDList Sets the list of item identifiers for a shell link object.
SetPath Sets the path and file name of a shell link object.
SetRelativePath Sets the relative path for a shell link object.
SetShowCmd Sets the show (SW_) command for a shell link object.
SetWorkingDirectory Sets the name of the working directory for a shell link object.

IShellLink::GetArguments

HRESULT STDMETHODCALLTYPE GetArguments(
    LPSTR pszArgs,	
    int cchMaxPath	
   );	

Retrieves the command-line arguments associated with a shell link object.

pszArgs
Address of a buffer that receives the command-line arguments.
cchMaxPath
Maximum number of characters to copy to the buffer pointed to by the pszArgs parameter.

See also IShellLink

IShellLink::GetDescription

RESULT STDMETHODCALLTYPE GetDescription(
    LPSTR pszName,	
    int cchMaxName	
   );	

Retrieves the description string for a shell link object.

pszName
Address of a buffer that receives the description string.
cchMaxName
Maximum number of characters to copy to the buffer pointed to by the pszName parameter.

See also IShellLink

IShellLink::GetHotkey

HRESULT STDMETHODCALLTYPE GetHotkey(
    WORD *pwHotkey	
   );	

Retrieves the hot key for a shell link object.

pwHotkey
Address of the hot key. The virtual key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the following values:
HOTKEYF_ALT ALT key
HOTKEYF_CONTROL CTRL key
HOTKEYF_EXT Extended key
HOTKEYF_SHIFT SHIFT key

See also IShellLink

IShellLink::GetIconLocation

HRESULT STDMETHODCALLTYPE GetIconLocation(
    LPSTR pszIconPath,	
    int cchIconPath,	
    int *piIcon	
   );	

Retrieves the location (path and index) of the icon for a shell link object.

pszIconPath
Address of a buffer that receives the path of the file containing the icon.
cchIconPath
Maximum number of characters to copy to the buffer pointed to by the pszIconPath parameter.
piIcon
Address of a value that receives the index of the icon.

See also IShellLink

IShellLink::GetIDList

HRESULT STDMETHODCALLTYPE GetIDList(
    LPITEMIDLIST *ppidl	
   );	

Retrieves the list of item identifiers for a shell link object.

ppidl
Address of a pointer to a list of item identifiers.

See also IShellLink

IShellLink::GetPath

HRESULT STDMETHODCALLTYPE GetPath(
    LPSTR pszFile,	
    int cchMaxPath,	
    WIN32_FIND_DATA *pfd,	
    DWORD fFlags	
   );	

Retrieves the path and file name of a shell link object.

pszFile
Address of a buffer that receives the path and file name of the shell link object.
cchMaxPath
Maximum number of bytes to copy to the buffer pointed to by the pszFile parameter.
pfd
Address of a WIN32_FIND_DATA structure that contains information about the shell link object.
fFlags
Flags that specify the type of path information to retrieve. This parameter can be a combination of the following values:
SLGP_SHORTPATH Retrieves the standard short (8.3 format) file name.
SLGP_UNCPRIORITY Retrieves the Universal Naming Convention (UNC) path name of the file.

See also IShellLink

IShellLink::GetShowCmd

HRESULT STDMETHODCALLTYPE GetShowCmd(
    int *piShowCmd	
   );	

Retrieves the show command for a shell link object.

piShowCmd
Address of the show command. For a list of show commands, see the ShowWindow function.

See also IShellLink

IShellLink::GetWorkingDirectory

HRESULT STDMETHODCALLTYPE GetWorkingDirectory(
    LPSTR pszDir,	
    int cchMaxPath	
   );	

Retrieves the name of the working directory for a shell link object.

pszDir
Address of a buffer that receives the name of the working directory.
cchMaxPath
Maximum number of characters to copy to the buffer pointed to by the pszDir parameter. The name of the working directory is truncated if it is longer than the maximum specified by this parameter.

See also IShellLink

IShellLink::Resolve

HRESULT STDMETHODCALLTYPE Resolve(
    HWND hwnd,	
    DWORD fFlags	
   );	

Resolves a shell link. The system searches for the shell link object and updates the shell link path and its list of identifiers, if necessary.

hwnd
Handle to the window that the shell will use as the parent for a dialog box. The shell displays the dialog box if it needs to prompt the user for more information while resolving a shell link.
fFlags
Action flags. This parameter can be a combination of the following values:
SLR_ANY_MATCH Resolves the link, displaying a dialog box if the system needs information from the user.
SLR_NO_UI Prevents the shell from displaying a dialog box if it cannot resolve the shell link. When this flag is specified, the high-order word of fFlags specifies a time-out duration, in milliseconds. The function returns if the link cannot be resolved within the time-out duration. If the high-order word is set to zero, the time-out duration defaults to 3000 milliseconds (3 seconds).
SLR_UPDATE Directs the shell to update the path to the link and the list of identifiers if the link object has been changed. If this value is used, it is not necessary to call the IPersistFile::IsDirty method to determine whether the link object has changed.

If the system cannot find the object, it looks in the current directory for an object that has the same attributes and file creation time but has a different name. This type of search resolves a link to an object that has been renamed.

If the system still cannot find the link object, it does a recursive search of the subdirectories of the current directory, looking for a match with either the same name or creation time. If it does not find a match, the shell displays a dialog box prompting the user for a location. An application can suppress the dialog box by specifying the SLR_NO_UI value in a call to this method.

See also IShellLink

IShellLink::SetArguments

HRESULT STDMETHODCALLTYPE SetArguments(
    LPCSTR pszArgs	
   );	

Sets the command-line arguments for a shell link object.

pszArgs
Address of a buffer that contains the new command-line arguments.

See also IShellLink

IShellLink::SetDescription

HRESULT STDMETHODCALLTYPE SetDescription(
    LPCSTR pszName	
   );	

Sets the description for a shell link object. The description can be any application-defined string.

pszName
Address of a buffer containing the new description string.

See also IShellLink

IShellLink::SetHotkey

HRESULT STDMETHODCALLTYPE SetHotkey(
    WORD wHotkey	
   );	

Sets a hot key for a shell link object.

wHotkey
Specifies the new hot key. The virtual key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the values specified in the description of the IShellLink::GetHotkey method.

Setting a hot key allows the user to activate the object by pressing a particular combination of keys.

See also IShellLink

IShellLink::SetIconLocation

HRESULT STDMETHODCALLTYPE SetIconLocation(
    LPCSTR pszIconPath,	
    int iIcon	
   );	

Sets the location (path and index) of the icon for a shell link object.

pszIconPath
Address of a buffer to contain the path of the file containing the icon.
iIcon
Index of the icon.

See also IShellLink

IShellLink::SetIDList

HRESULT STDMETHODCALLTYPE SetIDList(
    LPCITEMIDLIST pidl	
   );	

Sets the list of item identifiers for a shell link object.

pidl
Address of a list of item identifiers.

This method is useful when an application needs to set a shell link to an object that is not a file, such as a Control Panel application, a printer, or another computer.

See also IShellLink

IShellLink::SetPath

HRESULT STDMETHODCALLTYPE SetPath(
    LPCSTR pszFile	
   );	

Sets the path and file name of a shell link object.

pszFile
Address of a buffer that contains the new path.

See also IShellLink

IShellLink::SetRelativePath

HRESULT STDMETHODCALLTYPE SetRelativePath(
    LPCSTR pszPathRel,	
    LPCITEMIDLIST pidlRel	
   );	

Sets the relative path to the shell link object.

pszPathRel
Address of a buffer that contains the new relative path.
pidlRel
Address of a list of item identifiers that identify the object.

See also IShellLink

IShellLink::SetShowCmd

HRESULT STDMETHODCALLTYPE SetShowCmd(
    int iShowCmd	
   );	

Sets the show command for a shell link object. The show command sets the initial show state of the window.

iShowCmd
Show command. For a list of these commands, see the description of the ShowWindow function.

See also IShellLink

IShellLink::SetWorkingDirectory

HRESULT STDMETHODCALLTYPE SetWorkingDirectory(
    LPCSTR pszDir	
   );	

Sets the name of the working directory for a shell link object.

pszDir
Address of a buffer that contains the name of the new working directory.

The working directory is optional unless the target requires a working directory. For example, if an application creates a shell link to a Microsoft® Word document that uses a template residing in a different directory, the application would use this method to set the working directory.

See also IShellLink

IShellPropSheetExt

The IShellPropSheetExt interface allows a property sheet handler to add or replace pages in the property sheet displayed for a file object.

IShellPropSheetExt Methods Description
AddPages Adds one or more pages to a property sheet for a file object.
ReplacePage Replaces a page in a property sheet for a Control Panel object.

IShellPropSheetExt::AddPages

HRESULT STDMETHODCALLTYPE AddPages(
    LPFNADDPROPSHEETPAGE lpfnAddPage,	
    LPARAM lParam	
   );	

Adds one or more pages to a property sheet that the shell displays for a file object. When it is about to display the property sheet, the shell calls this method for each property sheet handler registered to the file type.

lpfnAddPage
Address of a function that the property sheet handler calls to add a page to the property sheet. The function takes a property sheet handle returned by the CreatePropertySheetPage function and the lParam parameter passed to the AddPages method.
lParam d>Parameter to pass to the function specified by the lpfnAddPage method.

See also IShellPropSheetExt

IShellPropSheetExt::ReplacePage

HRESULT STDMETHODCALLTYPE ReplacePage(
    UINT uPageID,	
    LPFNADDPROPSHEETPAGE lpfnReplacePage,	
    LPARAM lParam	
   );	

Replaces a page in a property sheet for a Control Panel object.

uPageID
Identifier of the page to replace. The values for this parameter for Control Panels can be found in the Cplext.h header file.
lpfnReplacePage
Address of a function that the property sheet handler calls to replace a page to the property sheet. The function takes a property sheet handle returned by the CreatePropertySheetPage function and the lParam parameter passed to the ReplacePage method.
lParam
Parameter to pass to the function specified by the lpfnReplacePage parameter.

See also IShellPropSheetExt

IShellView

The IShellView interface is implemented to present a view in the Windows Explorer or folder windows. The object that exposes IShellView is created by a call to the IShellFolder::CreateViewObject method. This provides the channel of communication between a view object and Windows Explorer's outermost frame window. The communication involves the translation of messages, the state of the frame window (activated or deactivated), the state of the document window (activated or deactivated), and the merging of menus and toolbar items.

When to Implement

This interface is implemented by namespace extensions that display themselves in Windows Explorer's namespace. This object is created by the IShellFolder object that hosts the view.

When to Use

These methods are used by the shell view's Windows Explorer window to manipulate objects while they are active.

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

IShellView Methods Description
AddPropertySheetPages Allows the view to add pages to the Options property sheet.
CreateViewWindow Creates the view window.
DestroyViewWindow Destroys the view window.
EnableModeless Enables or disables modeless dialog boxes. Not in use by Windows Explorer at this time.
EnableModelessSV Not currently in use.
GetCurrentInfo Returns the current folder settings.
GetItemObject Allows callers to get an object that represents something in the view.
Refresh Refreshes the display in response to user input.
SaveViewState Saves the shell's view settings so the current state can be restored during a subsequent browsing session.
SelectItem Changes the state of items within the shell view window.
TranslateAccelerator Translates accelerator key strokes when a namespace extension's view has the focus.
UIActivate Called whenever the activation state of the view window is changed by an event not caused by the shell view itself.

IShellView::AddPropertySheetPages

HRESULT AddPropertySheetPages(
    DWORD dwReserved,
    LPFNADDPROPSHEETPAGE lpfn,
    LPARAM lparam
   );	

Allows the view to add pages to the Options property sheet from the View menu.

dwReserved
Reserved for future use.
lpfn
Address of the callback function used to add the pages.
lparam
Value that must be passed to the callback function in the lpfn parameter.

Notes to Implementers

Windows Explorer calls this method when it is opening the Options property sheet from the View menu. Views can add pages by creating them and calling the callback function with the page handles.

See also IShellView

IShellView::CreateViewWindow

RESULT CreateViewWindow(
    ISHELLLINK *lpPrevView,
    LPFOLDERSETTINGS lpfs,
    IShellBrowser *psb,
    RECT *prcView,
    HWND *phWnd
   );	

Creates a view window. This can be either the right pane of Windows Explorer or the client window of a folder window.

lpPrevView
Address of the view window being exited. Views can use this parameter to communicate with a previous view of the same implementation. This can be used to optimize browsing between like views. This pointer may be NULL.
lpfs
Address of a FOLDERSETTINGS structure. The view should use this when creating its view.
psb
Address of the current instance of the IShellBrowser interface. The view should call this interface's AddRef method and keep the interface pointer to allow communication with the Windows Explorer window.
prcView
Dimensions of the new view, in client coordinates.
phWnd
Address of the window handle being created.

Notes to Callers

Call this method when the view needs to be created.

Notes to Implementers

Create your view window and restore any persistent state by calling the IShellBrowser::GetViewStateStream method.

See also IShellView

IShellView::DestroyViewWindow

HRESULT DestroyViewWindow(void)

Destroys the view window.

Windows Explorer calls this method when a folder window or Explorer is being closed.

Notes to Implementers

Clean up all states that represent the view, including the window and any other associated resources.

See also IShellView

IShellView::EnableModeless

HRESULT EnableModeless(
    BOOL fEnable
   );	

Enables or disables modeless dialog boxes. This method is not currently implemented.

fEnable
Nonzero to enable modeless dialog box windows or zero to disable them.

See also IShellView

IShellView::EnableModelessSV

Not currently implemented.

IShellView::GetCurrentInfo

HRESULT GetCurrentInfo(
    LPFOLDERSETTINGS lpfs
   );	

Retrieves the current folder settings.

lpfs
Address of a FOLDERSETTINGS structure to receive the settings.

Windows Explorer uses this method to query the view for standard settings.

Notes to Callers

This method is used to get the current view settings of the view.

Notes to Implementers

Return as many of the settings as apply. This is intended to maintain the same basic settings when the user browses from view to view. For example, if the user sets the Details view, that view should be maintained as the user goes from one folder to the other in Windows Explorer mode.

See also IShellView

IShellView::GetItemObject

HRESULT GetItemObject(
    UINT uItem,
    REFIID riid,
    LPVOID *ppv
   );	

Retrieves an interface that refers to data presented in the view.

uItem
Constants that refer to an aspect of the view. This parameter can be any of the following values:
SVGIO_BACKGROUND Refers to the background of the view. It is used with IID_IContextMenu to get a context menu for the view background.
SVGIO_SELECTION Refers to the currently selected items. IID_IDataObject uses this constant to get a data object that represents the selected items.
SVGIO_ALLVIEW Same as SVGIO_SELECTION but refers to all items in the view.
riid
Identifier of the COM interface being requested.
ppv
Address that receives the interface pointer. If an error occurs, the pointer returned must be NULL.

Used by the common dialogs to get the selected items from the view.

See also IShellView

IShellView::Refresh

HRESULT Refresh(void)

Refreshes the view's contents in response to user input.

Tells the view to refresh its contents, revalidating any view information it has.

Notes to Callers

Windows Explorer calls this method when the F5 key is pressed on an already open view.

Notes to Implementers

Refill the view by going to any underlying storage for the contents.

See also IShellView

IShellView::SaveViewState

HRESULT SaveViewState(void)

Saves the shell's view settings so the current state can be restored during a subsequent browsing session.

The shell view obtains a view stream by calling the IShellBrowser::GetViewStateStream method and stores the current view state in that stream.

Notes to Callers

Windows Explorer calls this method when it wants to save the view state for a view.

Notes to Implementers

Be sure to make the format of the data stored in the stream robust enough that different versions of the implementation can read it without error.

See also IShellView

IShellView::SelectItem

HRESULT SelectItem(
    LPCITEMIDLIST pidlItem,
    UINT uFlags
   );	

Changes the selection state of one or more items within the shell view window.

pidlItem
Address of the ITEMIDLIST structure.
uFlags
Flag specifying what type of selection to apply. This parameter can be one of the following values:
SVSI_DESELECT Deselect the specified item.
SVSI_DESELECTOTHERS Deselect all but the specified item. If pidlItem is NULL, deselect all items.
SVSI_EDIT Put pidlItem in edit mode.
SVSI_ENSUREVISIBLE Ensure the item is displayed on the screen.
SVSI_FOCUSED The item should be given the focus.
SVSI_SELECT The item should be selected.

Notes to Implementers

This method is used to implement the Target command from the File menu of the shell shortcut property sheet.

See also IShellView

IShellView::TranslateAccelerator

HRESULT TranslateAccelerator(
    LPMSG lpmsg
   );	

Translates accelerator key strokes when a namespace extension's view has the focus.

lpmsg
Address of the message to be translated.

This method is called by Windows Explorer to let the view translate its accelerators.

Notes to Callers

Windows Explorer calls this method before any other translation if the view has the focus. If the view does not have the focus, it is called after Explorer translates its own accelerators.

Notes to Implementers

By default, the view should return S_FALSE so that Windows Explorer can either do its own accelerator translation or normal menu dispatching. The view should return S_OK only if it has processed the message as the accelerator and does not want Explorer to process it further.

See also IShellView

IShellView::UIActivate

HRESULT UIActivate(
    UINT uState
   );	

Called when the activation state of the view window is changed by an event that is not caused by the shell view itself. For example, if the TAB key is pressed when the tree has the focus, the view should be given the focus.

uState
Flag specifying the activation state of the window. This parameter can be one of the following values:
SVUIA_ACTIVATE_FOCUS Windows Explorer has just created the view window with the input focus. This means the shell view should be able to set menu items appropriate for the focused state.
SVUIA_ACTIVATE_NOFOCUS The shell view is losing the input focus, or it has just been created without the input focus. The shell view should be able to set menu items appropriate for the nonfocused state. This means no selection-specific items should be added.
SVUIA_DEACTIVATE Windows Explorer is about to destroy the shell view window. The shell view should remove all extended user interfaces. These are typically merged menus and merged modeless pop-up windows.
SVUIA_INPLACEACTIVATE Not used for this interface.

Before remerging menu items, the shell view typically hooks the WM_SETFOCUS message and calls the IShellView::OnViewWindowActive method. The shell view should not hook the WM_KILLFOCUS message to remerge menu items.

Notes to Callers

Call this method to inform the view of an activation state change.

Notes to Implementers

Use this method to track the activation state and change any behavior, as appropriate.

See also IShellView

ITaskbarList

The ITaskbarList interface is used to control the taskbar. It allows you to dynamically add items to the taskbar, remove items from the taskbar, and activate items on the taskbar. See Modifying the Contents of the Taskbar for more information about using this interface.

When to Implement

You do not implement ITaskbarList; it is implemented by the shell.

When to Use

You use ITaskbarList to add items to the taskbar, remove items from the taskbar, and activate items on the taskbar.

ITaskbarList is derived from IUnknown. The following methods are specific to ITaskbarList:

ITaskbarList Methods Description
ActivateTab Activates an item on the taskbar.
AddTab Adds an item to the taskbar.
DeleteTab Deletes an item from the taskbar.
HrInit Initializes the taskbar list object.
SetActiveAlt Marks a taskbar item as active but does not visually activate it.

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

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