Download source files - 12 Kb
Introduction
Welcome to
CShellLink and
CUrlShellLink, 2 freeware MFC wrapper classes
to encapsulate shell shortcuts.
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
v1.0 (10 December 1998)
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
The API consists of the following:
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
PJ Naughter
Email: pjn@indigo.ie
Web: http://www.naughter.com
12th December 1998
