System.Win32.Shortcut

Working with .lnk format should be a matter of serializing. This library takes simpler approach, utilizing Component Object Model (COM) library. Even though COM provides some means of serialization, they cannot be used in a pure fashion - the library needs to be initialized and some COM functions still query the system for data. For this reason this library sticks to IO.

Before calling writeShortcut or readShortcut, COM library must be initialized with initialize.

Library does not support shortcut's IDLists, so creating or reading links to devices or network connections is not possible.

Example

import Control.Monad.Except

main = print . runExceptT $ do
  let link = empty { targetPath = "notepad.exe" }

  ExceptT initialize
  ExceptT $ writeShortcut link "c:\\link.lnk"
  ret <- ExceptT $ readShortcut "c:\\link.lnk"
  liftIO $ uninitialize

  return ret

>>> main
Right (Shortcut {targetPath = "C:\\Windows\\system32\\notepad.exe",
arguments = "", workingDirectory = "", showCmd = ShowNormal,
description = "", iconLocation = ("",0), hotkey = 0})

Documentation

data Shortcut

A shell link.

It seems that .lnk format permits up to 32767 characters in text fields (259 for targetPath), however if workingDirectory, description or iconLocation is longer then 259 characters COM won't be able to read the shortcut corectly (readShortcut will return faulty link without raising any error, and explorer.exe may not interpret it properly). For this reason two write functions are provided. unsafeWriteShortcut will allow long fields and writeShortcut which will raise error if workingDirectory, description or iconLocation is longer then 259 characters.

Constructors

Shortcut

Fields

• targetPath :: FilePath

  Path to target.

• arguments :: String

  Arguments for target.

• workingDirectory :: FilePath

  Path to working directory.

• showCmd :: ShowCmd
• description :: String
• iconLocation :: (FilePath, Int)

  Path to icon container (e.g. .exe, .dll, or .ico file) and icon index.

• hotkey :: WORD

  The virtual key code is in the low-order byte, and the modifier flags are in the high-order byte. hotkey == 0 means no hotkey will be used.

Instances

Show Shortcut

Methods

showsPrec :: Int -> Shortcut -> ShowS

show :: Shortcut -> String

showList :: [Shortcut] -> ShowS

empty :: Shortcut

An empty link. All fields are set to empty/default values.

data ShowCmd

Defines how a window will be opened when a link is executed.

Constructors

ShowNormal

Start normally.

ShowMaximized

Start maximized.

ShowMinimized

Start minimized.

Instances

Show ShowCmd

Methods

showsPrec :: Int -> ShowCmd -> ShowS

show :: ShowCmd -> String

showList :: [ShowCmd] -> ShowS

Basic operations

writeShortcut :: Shortcut -> FilePath -> IO (Either ShortcutError ())

Create a shortcut under specified location. initialize must be called beforehand. targetPath will be resolved with respect to whatever is found in PATH variable or desktop if saved path is not absolute.

unsafeWriteShortcut :: Shortcut -> FilePath -> IO (Either ShortcutError ())

Same as writeShortcut, but allows long description, workingDirectory and iconLocation fields. COM and explorer.exe may not interpret created link correctly.

readShortcut :: FilePath -> IO (Either ShortcutError Shortcut)

Read a shortcut from the supplied location. initialize must be called beforehand.

COM initialization

initialize :: IO (Either ShortcutError ())

Initialize COM library for current thread. Wraps CoInitializeEx function.

uninitialize :: IO ()

Uninitialize COM library for current thread.

Errors

data ShortcutError

Catch-all type for errors.

Constructors

InitializationError (OrHRESULTError CoInitializeError)

CreateIShellLinkInterfaceError (OrHRESULTError CoCreateInstanceError)

CreateIPersistFileInterfaceError (OrHRESULTError CoCreateInstanceError)

LoadError (OrHRESULTError LoadError)

SaveError (OrHRESULTError SaveError)

InvalidPath (OrHRESULTError PathError)

InvalidArguments (OrHRESULTError ArgumentsError)

InvalidWorkingDirectory (OrHRESULTError WorkingDirectoryError)

InvalidDescription (OrHRESULTError DescriptionError)

InvalidIconLocation (OrHRESULTError IconLocationError)

InvalidHotkey HRESULTError

InvalidShowCmd HRESULTError

Instances

Show ShortcutError

Methods

showsPrec :: Int -> ShortcutError -> ShowS

show :: ShortcutError -> String

showList :: [ShortcutError] -> ShowS

File IO Errors

data LoadError

IPersistFile interface failed to load a file.

Constructors

LE_E_OUTOFMEMORY

The object could not be loaded due to a lack of memory.

LE_E_FAIL

The object could not be loaded for some reason other than a lack of memory.

Instances

Show LoadError

Methods

showsPrec :: Int -> LoadError -> ShowS

show :: LoadError -> String

showList :: [LoadError] -> ShowS

data SaveError

IPersistFile interface failed to save a file.

Constructors

SE_S_FALSE

The object was not successfully saved.

Instances

Show SaveError

Methods

showsPrec :: Int -> SaveError -> ShowS

show :: SaveError -> String

showList :: [SaveError] -> ShowS

Argument errors

data PathError

Constructors

Path_S_FALSE

The operation is successful but no path is retrieved.

PathTooLong

Path length >= 260 characters.

Instances

Show PathError

Methods

showsPrec :: Int -> PathError -> ShowS

show :: PathError -> String

showList :: [PathError] -> ShowS

data ArgumentsError

Constructors

ArgumentsTooLong

Arguments length >= 32768 characters.

Instances

Show ArgumentsError

Methods

showsPrec :: Int -> ArgumentsError -> ShowS

show :: ArgumentsError -> String

showList :: [ArgumentsError] -> ShowS

data WorkingDirectoryError

Constructors

WorkingDirectoryTooLong

Instances

Show WorkingDirectoryError

Methods

showsPrec :: Int -> WorkingDirectoryError -> ShowS

show :: WorkingDirectoryError -> String

showList :: [WorkingDirectoryError] -> ShowS

data DescriptionError

Constructors

DescriptionTooLong

Instances

Show DescriptionError

Methods

showsPrec :: Int -> DescriptionError -> ShowS

show :: DescriptionError -> String

showList :: [DescriptionError] -> ShowS

data IconLocationError

Constructors

IconLocationTooLong

Instances

Show IconLocationError

Methods

showsPrec :: Int -> IconLocationError -> ShowS

show :: IconLocationError -> String

showList :: [IconLocationError] -> ShowS

Other errors

data CoCreateInstanceError

COM cannot create specified interface.

Constructors

CCI_REGDB_E_CLASSNOTREG

A specified class is not registered in the registration database. Also can indicate that the type of server you requested in the CLSCTX enumeration is not registered or the values for the server types in the registry are corrupt.

CCI_CLASS_E_NOAGGREGATION

This class cannot be created as part of an aggregate.

CCI_E_NOINTERFACE

The specified class does not implement the requested interface, or the controlling IUnknown does not expose the requested interface.

CCI_E_POINTER

The ppv parameter is NULL.

CCI_CO_E_NOTINITIALIZED

COM library was not initialized.

Instances

Show CoCreateInstanceError

Methods

showsPrec :: Int -> CoCreateInstanceError -> ShowS

show :: CoCreateInstanceError -> String

showList :: [CoCreateInstanceError] -> ShowS

data CoInitializeError

COM failed to initialize.

Constructors

CI_RPC_E_CHANGED_MODE

A previous call to CoInitializeEx specified the concurrency model for this thread as multithread apartment (MTA). This could also indicate that a change from neutral-threaded apartment to single-threaded apartment has occurred.

CI_CO_E_NOTINITIALIZED

You need to initialize the COM library on a thread before you call any of the library functions. Otherwise, the COM function will return CI_CO_E_NOTINITIALIZED.

Instances

Show CoInitializeError

Methods

showsPrec :: Int -> CoInitializeError -> ShowS

show :: CoInitializeError -> String

showList :: [CoInitializeError] -> ShowS

data HRESULTError

In Win32 API HRESULT is used to indicate error and warning conditions. HRESULTError wraps HRESULT to give it some meaning.

Constructors

E_ABORT

Operation aborted.

E_ACCESSDENIED

General access denied error.

E_FAIL

Unspecified failure.

E_HANDLE

Handle that is not valid.

E_INVALIDARG

One or more arguments are not valid.

E_NOINTERFACE

No such interface supported.

E_NOTIMPL

Not implemented.

E_OUTOFMEMORY

Failed to allocate necessary memory.

E_POINTER

Pointer that is not valid.

E_UNEXPECTED

Unexpected failure.

HRESULTUnknown HRESULT

Other, unknown HRESULT value.

Instances

Show HRESULTError

Methods

showsPrec :: Int -> HRESULTError -> ShowS

show :: HRESULTError -> String

showList :: [HRESULTError] -> ShowS

data OrHRESULTError err

Some error that comes from HRESULT.

Constructors

OtherError err

HRESULT value was expected and fits err.

HRESULTError HRESULTError

HRESULT did not fit err.

Instances

Show err => Show (OrHRESULTError err)

Methods

showsPrec :: Int -> OrHRESULTError err -> ShowS

show :: OrHRESULTError err -> String

showList :: [OrHRESULTError err] -> ShowS