CShellLink & CUrlShellLink v1.1

Introduction

Features

• Simple and clean C++ interface.
• Uses standard MFC classes in the interface.
• Simple console app is provided which tests all of the class methods.

Usage

• To use the class in your code simple include ShellLink.cpp in your project and #include ShellLink.h in which ever of your modules needs to make calls to the classes.
• To see the classes in action, have a look at the code in main() in the module main.cpp.
• Your code will need to include MFC either statically or dynamically.

History

• Initial public release.

V1.1 (12th December 1998)

• Updated sample program to be called ShelLink.
• Fixed a bug in CUrlShellLink::Save() where m_sTarget was not being set.
• Updated the trace comments in the code to include the function from which the function fails.
• Demo program now displays some info about what it is doing to the console window.
• Default build configuration is now ASCII Debug instead of Unicode Debug.

API Reference

CShellLinkInfo::m_sTarget
CShellLinkInfo::m_pidl
CShellLinkInfo::m_sArguments
CShellLinkInfo::m_sDescription
CShellLinkInfo::m_wHotkey
CShellLinkInfo::m_sIconLocation
CShellLinkInfo::m_nIconIndex
CShellLinkInfo::m_nShowCmd
CShellLinkInfo::m_sWorkingDirectory
CShellLink::Create
CShellLink::Load
CShellLink::Save
CShellLink::Resolve
CUrlShellLink::Create
CUrlShellLink::Load
CUrlShellLink::Save
CUrlShellLink::Invoke

Notes:

• The CShellLink class also includes simple Set and Get functions which modify the CShellLinkInfo data which the class contains.
• Since CUrlShellLink is derived from CShellLink, you can call all of the standard Get and Set functions which it inherits from CShellLink.

CShellLinkInfo::m_sTarget

Remarks:
This value stores the target of the shortcut. In the case of an ordinary shortcut, this will normally point to an executable or a document. In the case of an internet shortcut this will be a URL. m_sTarget is of type CString.

CShellLinkInfo::m_pidl

Remarks:
Contains a pointer to the item identifier for the shortcut. m_pidl is of type LPITEMIDLIST. This value is not valid In the case of an internet shortcut.

CShellLinkInfo::m_sArguments

Remarks:
Contains the command line arguments which are passed to the target when invoking the shortcut. This value is not valid In the case of an internet shortcut. m_sArguments is of type CString.

CShellLinkInfo::m_sDescription

Remarks:
Contains the description for the shortcut. m_sDescription is of type CString.

CShellLinkInfo::m_wHotkey

Remarks:
Contains the hotkey associated with the shortcut. m_wHotkey is of type WORD. 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

CShellLinkInfo::m_sIconLocation

Remarks:
Contains the filename where the icon for the shortcut is located. m_sIconLocation is of type CString.

CShellLinkInfo::m_nIconIndex

Remarks:
Contains the index in m_sIconLocation of the icon for the shortcut. m_sIconLocation is of type int.

CShellLinkInfo::m_nShowCmd

Remarks:
Contains the show command which is used when invoking the shortcut. m_nShowCmd is of type int. For a list of the show commands, see the description of the ShowWindow() function in books online.

CShellLinkInfo::m_sWorkingDirectory

Remarks:
Contains the working directory which the shortcut will use when invoked. m_sWorkingDirectory is of type CString.

CShellLink::Create

BOOL CShellLink::Create(const CShellLinkInfo& sli);

Return Value:
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Parameters:

• sli -- The structure which contains all the parameters to use in the shortcut. They will be updated on disk following a call to CShellLink::Save().

Remarks:
Call this member function to initialise the shortcut with initial values.

CShellLink::Load

BOOL CShellLink::Load(const CString& sFilename);

Return Value:
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Parameters:

• sFilename -- The filename from which to load the shortcut information. Normally this will have the extension ".lnk".

Remarks:
Call this member function to load up a shortcut from disk.

CShellLink::Save

BOOL CShellLink::Save(const CString& sFilename);

Return Value:
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Parameters:

• sFilename -- The filename to save this shortcut to. Normally this will have the extension ".lnk".

Remarks:
Call this member function to save a shortcut to disk. Prior to calling this function you would normally call CShellLink::Create() method.

CShellLink::Resolve

BOOL CShellLink::Resolve(CWnd* pParentWnd, DWORD dwFlags);

Return Value:
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Parameters:

• pParentWnd -- The parent window of a window that the shell uses as the parent window 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 timeout duration, in milliseconds. The function returns if the link cannot be resolved within the timeout duration. If the high-order word is set to zero, the timeout 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.

Remarks:
Call this member function to ensure that a shortcut is pointing to valid data. This is known as "resolving" a shortcut. For those who frequently move files from volume to volume, the Searching for Shortcut dialog should be familiar.

CUrlShellLink::Create

BOOL CUrlShellLink::Create(const CShellLinkInfo& sli);

Return Value:
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Parameters:

• sli -- The structure which contains all the parameters to use in the shortcut. They will be updated on disk following a call to CUrlShellLink::Save().

Remarks:
Call this member function to initialise the shortcut with initial values.

CUrlShellLink::Load

BOOL CUrlShellLink::Load(const CString& sFilename);

Return Value:
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Parameters:

• sFilename -- The filename from which to load the shortcut information. Normally this will have the extension ".url".

Remarks:
Call this member function to load up a shortcut from disk.

CUrlShellLink::Save

BOOL CUrlShellLink::Save(const CString& sFilename);

Return Value:
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Parameters:

• sFilename -- The filename to save this shortcut to. Normally this will have the extension ".url".

Remarks:
Call this member function to save a shortcut to disk. Priot to calling this function you would normally call the CUrlShellLink::Create() method.

CUrlShellLink::Invoke

BOOL CUrlShellLink::Invoke(CWnd* pParentWnd, DWORD dwFlags, const CString& sVerb);

Return Value:
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Parameters:

• pParentWnd -- Handle to the parent window. If dwFlags is set to IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB, this member is ignored.
• dwFlags -- Flag value that specifies how the IUniformResourceLocator::InvokeCommand() method will execute. This value can be a combination of the following:

  IURL_INVOKECOMMAND_FL_ALLOW_UI	Interaction with the user is allowed and the pParentWnd parameter is valid. If this is not set, interaction with the user is not allowed and the pParentWnd member is ignored.
  IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB	Default verb for the Internet Shortcut's protocol is to be used and the sVerb parameter is ignored. If this bit is not set, the verb is specified by sVerb.

• sVerb -- string that contains the verb to be invoked by IUniformResourceLocator::InvokeCommand(). If dwFlags is set to IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB, this parameter is ignored.

Remarks:
Call this member function to perform an action on a URL. The most common action would be to open it, which will open it up in your default web browser. You could also use the "edit" verb assuming you had a HTML editor open.

Contacting the Author

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here