com.izforge.izpack.util.os
Class ShellLink

java.lang.Object
  extended by com.izforge.izpack.util.os.ShellLink
All Implemented Interfaces:
NativeLibraryClient

public class ShellLink
extends java.lang.Object
implements NativeLibraryClient

This class represents a MS-Windows shell link, aka shortcut. It supports creation, modification and deletion as well as reporting on details of shell links. This class uses a number of native methods to access the MS-Windows registry and load save and manipulate link data. The native code is contained in the file ShellLink.cpp.

For more detailed information on Windows shortcuts read the win32 documentation from Microsoft on the IShellLink interface. There are also useful articles on this topic on the MIcrosoft website.

Using Shell Links in Windows 95
The IShellLink interface
IShellLink

Version:
0.0.1 / 1/21/02
Author:
Elmar Grom

Field Summary
static int ALL_USERS
          ALL_USERS = 1; the constant to use for selecting the all users.
private  java.lang.String allUsersLinkPath
          Path to the location where links for all users are stored.
private  java.lang.String arguments
           
static int CURRENT_USER
          CURRENT_USER = 0; the constant to use for selecting the current user.
private  java.lang.String currentUserLinkPath
          Path to the location where links for the current user are stored.
private  java.lang.String description
           
static int DESKTOP
          This type of shortcut shows on the desktop
private  java.lang.String dummyString
          there seems to be an error in JNI that causes an access violation if a String that is accessed from native code borders on another type of variable.
private  java.lang.String groupName
           
static int HIDE
          Hide the window when starting.
private  int hotkey
           
private  int iconIndex
           
private  java.lang.String iconPath
           
private  boolean initializeSucceeded
           
private static java.lang.String LINK_EXTENSION
          the extension that must be used for link files
private  java.lang.String linkDirectory
          Contains the directory where the link file is stored after any save operation that needs to create that directory.
private  java.lang.String linkFileName
          this is the fully qualified name of the link on disk.
private  java.lang.String linkName
           
private  int linkType
           
private static int MAX_SHOW
           
private static int MAX_TYPE
           
static int MAXIMIZED
          Show the window maximized when starting.
private static int MIN_SHOW
           
private static int MIN_TYPE
           
static int MINIMIZED
          Show the window minimized when starting.
static int MINNOACTIVE
          Show the window minimized when starting.
private  int nativeHandle
          This handle links us to a specific native instance.
static int NORMAL
          Show the window 'normal' when starting.
static int PROGRAM_MENU
          This type of shortcut shows in the program menu
private  int showCommand
           
private static int SL_ERROR
          Unspecific return if a native call was not successful
private static int SL_INITIALIZED
          Return value from native initialization functions if already initialized
private static int SL_NO_IPERSIST
          Return value from native uninitialization functions if nohandle for the IPersist interface could be obtained
private static int SL_NO_SAVE
          Return value from native uninitialization functions if the save operation fort the link failed
private static int SL_NOT_INITIALIZED
          Return value from native uninitialization functions if never initialized
private static int SL_OK
          Returned from native calls if the call was successful
private static int SL_OUT_OF_HANDLES
          Return value from native uninitialization functions if there are no more interface handles available
private static int SL_WRONG_DATA_TYPE
          Return value if the function called had to deal with unexpected data types.
static int START_MENU
          This type of shortcut shows in the start menu
static int STARTUP
          This type of shortcut is executed at OS launch time
private  java.lang.String targetPath
           
private static int UNINITIALIZED
           
private  int userType
           
private  java.lang.String workingDirectory
           
 
Constructor Summary
ShellLink(int type, int userType, java.lang.String group, java.lang.String name)
          Creates an instance of ShellLink from an existing shell link on disk.
ShellLink(int type, java.lang.String name)
          Creates an instance of ShellLink of a specific type.
ShellLink(java.lang.String name, int userType)
          Creates an instance of ShellLink from an existing shell link on disk.
 
Method Summary
protected  void finalize()
          Destructor, releases COM and frees native resources.
 void freeLibrary(java.lang.String name)
          This method is used to free the library at the end of progam execution.
private  void FreeLibrary(java.lang.String name)
          This method is used to free the library at the end of progam execution.
private  java.lang.String fullLinkName(int userType)
          Constructs and returns the fully qualified name for the link file.
private  java.lang.String fullLinkPath(int userType)
          Constructs and returns the full path for the link file.
private  void get()
          Gets all members from the native side.
 java.lang.String getallUsersLinkPath()
          Returns the path for allusersLink
 java.lang.String getArguments()
          Returns the command line that the link passes to the target.
private  int GetArguments()
           
 java.lang.String getcurrentUserLinkPath()
          Returns the path for currentusersLink
 java.lang.String getDescription()
          Returns the description for the link.
private  int GetDescription()
           
 java.lang.String getDirectoryCreated()
          Returns the path of the directory where the link file is stored, if it was necessary during the previous save operation to create the directory.
 java.lang.String getFileName()
          Returns the fully qualified file name under which the link is saved on disk.
private  int GetFullLinkPath(int usertype, int linktype)
           
 int getHotkey()
          Retruns the hotkey that can be used to activate the link.
private  int GetHotkey()
           
 int getIconIndex()
          Returns the index of the icon with the icon or resource file
 java.lang.String getIconLocation()
          Returns the path and file name of the file that contains the icon that is associated with the link.
private  int GetIconLocation()
           
private  int getInterface()
           
 java.lang.String getLinkName()
          Returns the name shown in a menu or on the desktop for the link.
 java.lang.String getLinkPath(int userType)
          Returns the path where the links of the selected type are stroed.
 int getLinkType()
          Returns the user type for the link.
private  int GetPath()
           
 int getShowCommand()
          Returns the initial condition of the target window (HIDE, NORMAL, MINIMIZED, MAXIMIZED).
private  int GetShowCommand()
           
 java.lang.String getTargetPath()
          Retruns the absolute path of the link target
 int getUserType()
          Returns the (ShellLink) user type for the link.
 java.lang.String getWorkingDirectory()
          Retruns the working deirectory for the link target.
private  int GetWorkingDirectory()
           
private  void initialize()
          Initializes COM and gets an instance of the IShellLink interface.
private  int initializeCOM()
           
private  int loadLink(java.lang.String name)
           
private  int releaseCOM()
           
private  int releaseInterface()
           
private  int Resolve()
           
 void save()
          Saves this link.
 void save(java.lang.String name)
          Saves this link to any desired location.
private  int saveLink(java.lang.String name)
           
private  void set()
          Sets all members on the native side.
private  void setAllLinkPaths()
          sets currentUsersLinkPath and allUsersLinkPath.
private  int SetArguments()
           
 void setArguments(java.lang.String arguments)
          Sets the command line arguments that will be passed to the target when the link is activated.
private  int SetDescription()
           
 void setDescription(java.lang.String description)
          Sets the description string that is used to identify the link in a menu or on the desktop.
private  int SetHotkey()
           
 void setHotkey(int hotkey)
          Sets the hotkey that can be used to activate the link.
private  int SetIconLocation()
           
 void setIconLocation(java.lang.String path, int index)
          Sets the location of the icon that is shown for the shortcut on the desktop.
 void setLinkName(java.lang.String name)
          Sets the name shown in a menu or on the desktop for the link.
 void setLinkType(int type)
          Sets the type of link
private  int SetPath()
           
 void setProgramGroup(java.lang.String groupName)
          Sets the name of the program group this ShellLinbk should be placed in.
private  int SetShowCommand()
           
 void setShowCommand(int show)
          Sets the show command that is passed to the target application when the link is activated.
 void setTargetPath(java.lang.String path)
          Sets the absolute path to the shortcut target.
 void setUserType(int type)
          Sets the (ShellLink) user type for link
private  int SetWorkingDirectory()
           
 void setWorkingDirectory(java.lang.String dir)
          Sets the working directory for the link target.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

HIDE

public static final int HIDE
Hide the window when starting. This is particularly useful when launching from a *.bat file, because no DOS window and no button for the DOS window on the task bar will show!

Note: this option is not available through the Windows 98+ UI!

See Also:
Constant Field Values

NORMAL

public static final int NORMAL
Show the window 'normal' when starting. Restores the window properties at the last shut-down.

See Also:
Constant Field Values

MINIMIZED

public static final int MINIMIZED
Show the window minimized when starting. The window will not show but a corresponding button in the task bar will.

Newer IShellLink only allows Normal, MinNoActive, Maximized.

See Also:
Constant Field Values

MAXIMIZED

public static final int MAXIMIZED
Show the window maximized when starting.

See Also:
Constant Field Values

MINNOACTIVE

public static final int MINNOACTIVE
Show the window minimized when starting. Note: for win98 and newer, use MINNOACTIVE instead of MINIMIZED.

See Also:
Constant Field Values

MIN_SHOW

private static final int MIN_SHOW
See Also:
Constant Field Values

MAX_SHOW

private static final int MAX_SHOW
See Also:
Constant Field Values

DESKTOP

public static final int DESKTOP
This type of shortcut shows on the desktop

See Also:
Constant Field Values

PROGRAM_MENU

public static final int PROGRAM_MENU
This type of shortcut shows in the program menu

See Also:
Constant Field Values

START_MENU

public static final int START_MENU
This type of shortcut shows in the start menu

See Also:
Constant Field Values

STARTUP

public static final int STARTUP
This type of shortcut is executed at OS launch time

See Also:
Constant Field Values

MIN_TYPE

private static final int MIN_TYPE
See Also:
Constant Field Values

MAX_TYPE

private static final int MAX_TYPE
See Also:
Constant Field Values

SL_OK

private static final int SL_OK
Returned from native calls if the call was successful

See Also:
Constant Field Values

SL_ERROR

private static final int SL_ERROR
Unspecific return if a native call was not successful

See Also:
Constant Field Values

SL_INITIALIZED

private static final int SL_INITIALIZED
Return value from native initialization functions if already initialized

See Also:
Constant Field Values

SL_NOT_INITIALIZED

private static final int SL_NOT_INITIALIZED
Return value from native uninitialization functions if never initialized

See Also:
Constant Field Values

SL_OUT_OF_HANDLES

private static final int SL_OUT_OF_HANDLES
Return value from native uninitialization functions if there are no more interface handles available

See Also:
Constant Field Values

SL_NO_IPERSIST

private static final int SL_NO_IPERSIST
Return value from native uninitialization functions if nohandle for the IPersist interface could be obtained

See Also:
Constant Field Values

SL_NO_SAVE

private static final int SL_NO_SAVE
Return value from native uninitialization functions if the save operation fort the link failed

See Also:
Constant Field Values

SL_WRONG_DATA_TYPE

private static final int SL_WRONG_DATA_TYPE
Return value if the function called had to deal with unexpected data types. This might be returned by registry functions if they receive an unexpected data type from the registry.

See Also:
Constant Field Values

UNINITIALIZED

private static final int UNINITIALIZED
See Also:
Constant Field Values

LINK_EXTENSION

private static final java.lang.String LINK_EXTENSION
the extension that must be used for link files

See Also:
Constant Field Values

CURRENT_USER

public static final int CURRENT_USER
CURRENT_USER = 0; the constant to use for selecting the current user.

See Also:
Constant Field Values

ALL_USERS

public static final int ALL_USERS
ALL_USERS = 1; the constant to use for selecting the all users.

See Also:
Constant Field Values

nativeHandle

private int nativeHandle
This handle links us to a specific native instance. Do not use or modify, the variable is for exclusive use by the native side.


currentUserLinkPath

private java.lang.String currentUserLinkPath
Path to the location where links for the current user are stored. The exact content depends on the circumstances. It can be set during object construction or from native code. It will point to the location where links of the most recently requested type are stored.


allUsersLinkPath

private java.lang.String allUsersLinkPath
Path to the location where links for all users are stored. The exact content depends on the circumstances. It can be set during object construction or from native code. It will point to the location where links of the most recently requested type are stored.


groupName

private java.lang.String groupName

linkName

private java.lang.String linkName

linkFileName

private java.lang.String linkFileName
this is the fully qualified name of the link on disk. Note that this variable contains only valid data if the link was created from a disk file or after a successful save operation. At other times the content is upredicatable.


linkDirectory

private java.lang.String linkDirectory
Contains the directory where the link file is stored after any save operation that needs to create that directory. Otherwise it contains null.


arguments

private java.lang.String arguments

description

private java.lang.String description

iconPath

private java.lang.String iconPath

targetPath

private java.lang.String targetPath

workingDirectory

private java.lang.String workingDirectory

dummyString

private java.lang.String dummyString
there seems to be an error in JNI that causes an access violation if a String that is accessed from native code borders on another type of variable. This caused problems in set() For this reason, the dummy string is placed here. Observed with version:

 

java version "1.3.0" Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.0-C) Java HotSpot(TM) Client VM (build 1.3.0-C, mixed mode)


hotkey

private int hotkey

iconIndex

private int iconIndex

showCommand

private int showCommand

linkType

private int linkType

userType

private int userType

initializeSucceeded

private boolean initializeSucceeded
Constructor Detail

ShellLink

public ShellLink(int type,
                 java.lang.String name)
          throws java.lang.Exception,
                 java.lang.IllegalArgumentException
Creates an instance of ShellLink of a specific type. Initializes currentUserLinkPath and allUsersLinkPath.

A LinkPath is empty if the combination of linkType and userType, are not valid.

Note: If a linkPath is empty, the userType is reset to the other userType.

If both linkPaths are empty, an IllegalArgumentException is thrown.

Parameters:
type - The type of link desired. The following values can be set:
  • ShellLink.DESKTOP
  • ShellLink.PROGRAM_MENU
  • ShellLink.START_MENU
  • ShellLink.STARTUP
name - The name that the link should display on a menu or on the desktop. Do not include a file extension.
Throws:
java.lang.IllegalArgumentException - if any of the call parameters are incorrect, or if no linkPaths are returned.
java.lang.Exception - if problems are encountered in initializing the native interface

ShellLink

public ShellLink(java.lang.String name,
                 int userType)
          throws java.lang.Exception,
                 java.lang.IllegalArgumentException
Creates an instance of ShellLink from an existing shell link on disk.

Parameters:
name - the fully qualified file name of the link.
userType - the type of user for the link path.
Throws:
java.lang.IllegalArgumentException - if the name was null
java.lang.Exception - if problems are encountered in reading the file
See Also:
CURRENT_USER, ALL_USERS

ShellLink

public ShellLink(int type,
                 int userType,
                 java.lang.String group,
                 java.lang.String name)
          throws java.lang.Exception,
                 java.lang.IllegalArgumentException
Creates an instance of ShellLink from an existing shell link on disk.

Parameters:
type - The type of link, one of the following values:
  • ShellLink.DESKTOP
  • ShellLink.PROGRAM_MENU
  • ShellLink.START_MENU
  • ShellLink.STARTUP
userType - the type of user for the link path.
group - The program group (directory) of this link. If the link is not part of a program group, pass an empty string or null for this parameter. (...\\Desktop\\group).
name - The file name of this link. Do not include a file extension.
Throws:
java.lang.IllegalArgumentException - if any of the call parameters are incorrect
java.lang.Exception - if problems are encountered in initializing the native interface
See Also:
CURRENT_USER, ALL_USERS
Method Detail

initializeCOM

private int initializeCOM()

releaseCOM

private int releaseCOM()

getInterface

private int getInterface()

releaseInterface

private int releaseInterface()

GetArguments

private int GetArguments()

GetDescription

private int GetDescription()

GetHotkey

private int GetHotkey()

GetIconLocation

private int GetIconLocation()

GetPath

private int GetPath()

GetShowCommand

private int GetShowCommand()

GetWorkingDirectory

private int GetWorkingDirectory()

Resolve

private int Resolve()

SetArguments

private int SetArguments()

SetDescription

private int SetDescription()

SetHotkey

private int SetHotkey()

SetIconLocation

private int SetIconLocation()

SetPath

private int SetPath()

SetShowCommand

private int SetShowCommand()

SetWorkingDirectory

private int SetWorkingDirectory()

saveLink

private int saveLink(java.lang.String name)

loadLink

private int loadLink(java.lang.String name)

GetFullLinkPath

private int GetFullLinkPath(int usertype,
                            int linktype)

FreeLibrary

private void FreeLibrary(java.lang.String name)
This method is used to free the library at the end of progam execution. After this call, any instance of this calss will not be usable any more!


initialize

private void initialize()
                 throws java.lang.Exception
Initializes COM and gets an instance of the IShellLink interface.

Throws:
java.lang.Exception - if problems are encountered

finalize

protected void finalize()
                 throws java.lang.Throwable
Destructor, releases COM and frees native resources.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable

freeLibrary

public void freeLibrary(java.lang.String name)
This method is used to free the library at the end of progam execution. After this call, any instance of this calss will not be usable any more! Note that this method does NOT return!

DO NOT CALL THIS METHOD DIRECTLY!
It is used by the librarian to free the native library before physically deleting it from its temporary loaction. A call to this method will freeze the application irrecoverably!

Specified by:
freeLibrary in interface NativeLibraryClient
Parameters:
name - the name of the library to free. Use only the name and extension but not the path.
See Also:
NativeLibraryClient.freeLibrary(java.lang.String)

fullLinkPath

private java.lang.String fullLinkPath(int userType)
Constructs and returns the full path for the link file.

Parameters:
userType - the type of user for the link path.
Returns:
the path to use for storing the link
See Also:
CURRENT_USER, ALL_USERS

fullLinkName

private java.lang.String fullLinkName(int userType)
Constructs and returns the fully qualified name for the link file.

Parameters:
userType - the type of user for the link path.
Returns:
the fully qualified file name to use for storing the link
See Also:
CURRENT_USER, ALL_USERS

set

private void set()
          throws java.lang.Exception
Sets all members on the native side.

Throws:
java.lang.Exception - if any problem is encountered during this operation.

get

private void get()
          throws java.lang.Exception
Gets all members from the native side.

Throws:
java.lang.Exception - if any problem is encountered during this operation.

setProgramGroup

public void setProgramGroup(java.lang.String groupName)
Sets the name of the program group this ShellLinbk should be placed in.

Parameters:
groupName - the name of the program group

setArguments

public void setArguments(java.lang.String arguments)
Sets the command line arguments that will be passed to the target when the link is activated.

Parameters:
arguments - the command line arguments
See Also:
getArguments()

setDescription

public void setDescription(java.lang.String description)
Sets the description string that is used to identify the link in a menu or on the desktop.

Parameters:
description - the descriptiojn string
See Also:
getDescription()

setHotkey

public void setHotkey(int hotkey)
Sets the hotkey that can be used to activate the link.

Parameters:
hotkey - a valid Windows virtual key code. Modifiers (e.g. for alt or shift key) are added in the upper byte. Note that only the lower 16 bits for tis parameter are used.
See Also:
getHotkey()

setIconLocation

public void setIconLocation(java.lang.String path,
                            int index)
Sets the location of the icon that is shown for the shortcut on the desktop.

Parameters:
path - a fully qualified file name of a file that contains the icon.
index - the index of the specific icon to use in the file. If there is only one icon in the file, use an index of 0.
See Also:
getIconLocation()

setTargetPath

public void setTargetPath(java.lang.String path)
Sets the absolute path to the shortcut target.

Parameters:
path - the fully qualified file name of the target
See Also:
getTargetPath()

setShowCommand

public void setShowCommand(int show)
Sets the show command that is passed to the target application when the link is activated. The show command determines if the the window will be restored to the previous size, minimized, maximized or visible at all.

Note:
Using HIDE will cause the target window not to show at all. There is not even a button on the taskbar. This is a very useful setting when batch files are used to launch a Java application as it will then appear to run just like any native Windows application.
Note1:
HIDE doesn't work in Win98 and newer systems.
use MINIMIZED (MINNOACTIVE), instead.

Parameters:
show - the show command. Valid settings are:
  • ShellLink.HIDE (deprecated)
  • ShellLink.NORMAL
  • ShellLink.MINNOACTIVE
  • ShellLink.MAXIMIZED
See Also:
getShowCommand()

setWorkingDirectory

public void setWorkingDirectory(java.lang.String dir)
Sets the working directory for the link target.

Parameters:
dir - the working directory
See Also:
getWorkingDirectory()

setLinkName

public void setLinkName(java.lang.String name)
Sets the name shown in a menu or on the desktop for the link.

Parameters:
name - The name that the link should display on a menu or on the desktop. Do not include a file extension.

setLinkType

public void setLinkType(int type)
                 throws java.lang.IllegalArgumentException,
                        java.io.UnsupportedEncodingException
Sets the type of link

Parameters:
type - The type of link desired. The following values can be set:
Throws:
java.lang.IllegalArgumentException - if an an invalid type is passed
java.io.UnsupportedEncodingException

getLinkType

public int getLinkType()
Returns the user type for the link.

See Also:
setLinkType(int)

setUserType

public void setUserType(int type)
                 throws java.lang.IllegalArgumentException
Sets the (ShellLink) user type for link

Parameters:
type - the type of user for the link.
Throws:
java.lang.IllegalArgumentException - if an an invalid type is passed
See Also:
CURRENT_USER, ALL_USERS

getUserType

public int getUserType()
Returns the (ShellLink) user type for the link. Either CURRENT_USER or ALL_USERS

See Also:
setUserType(int)

getLinkPath

public java.lang.String getLinkPath(int userType)
Returns the path where the links of the selected type are stroed. This method is useful for discovering which program groups already exist.

Parameters:
userType - the type of user for the link path. One of CURRENT_USER or ALL_USERS
Returns:
the path to the type of link set for this instance.

getArguments

public java.lang.String getArguments()
Returns the command line that the link passes to the target.

Returns:
the command line
See Also:
setArguments(java.lang.String)

getDescription

public java.lang.String getDescription()
Returns the description for the link.

Returns:
the description
See Also:
setDescription(java.lang.String)

getHotkey

public int getHotkey()
Retruns the hotkey that can be used to activate the link.

Returns:
the virtual keycode for the hotkey
See Also:
setHotkey(int)

getIconLocation

public java.lang.String getIconLocation()
Returns the path and file name of the file that contains the icon that is associated with the link.

Returns:
the path to the icon
See Also:
setIconLocation(java.lang.String, int)

getIconIndex

public int getIconIndex()
Returns the index of the icon with the icon or resource file

Returns:
the index
See Also:
setIconLocation(java.lang.String, int)

getTargetPath

public java.lang.String getTargetPath()
Retruns the absolute path of the link target

Returns:
the path
See Also:
setTargetPath(java.lang.String)

getShowCommand

public int getShowCommand()
Returns the initial condition of the target window (HIDE, NORMAL, MINIMIZED, MAXIMIZED).

Returns:
the target show command
See Also:
setShowCommand(int)

getWorkingDirectory

public java.lang.String getWorkingDirectory()
Retruns the working deirectory for the link target.

Returns:
the working directory
See Also:
setWorkingDirectory(java.lang.String)

getFileName

public java.lang.String getFileName()
Returns the fully qualified file name under which the link is saved on disk. Note: this method returns valid results only if the instance was created from a file on disk or after a successful save operation.

Returns:
the fully qualified file name for the shell link

getDirectoryCreated

public java.lang.String getDirectoryCreated()
Returns the path of the directory where the link file is stored, if it was necessary during the previous save operation to create the directory. This method returns null if no save operation was carried out or there was no need to create a directory during the previous save operation.

Returns:
the path of the directory where the link file is stored or null if no save operation was carried out or there was no need to create a directory during the previous save operation.

getLinkName

public java.lang.String getLinkName()
Returns the name shown in a menu or on the desktop for the link.

Returns:
the name

getcurrentUserLinkPath

public java.lang.String getcurrentUserLinkPath()
Returns the path for currentusersLink

Returns:
currentUsersLinkPath

getallUsersLinkPath

public java.lang.String getallUsersLinkPath()
Returns the path for allusersLink

Returns:
allusersLinkPath

save

public void save()
          throws java.lang.Exception
Saves this link.

Throws:
java.lang.Exception - if problems are encountered

save

public void save(java.lang.String name)
          throws java.lang.Exception
Saves this link to any desired location.

Parameters:
name - the fully qualified file name for the link
Throws:
java.lang.IllegalArgumentException - if the parameter was null
java.lang.Exception - if the save operation could not be carried out

setAllLinkPaths

private void setAllLinkPaths()
                      throws java.lang.IllegalArgumentException
sets currentUsersLinkPath and allUsersLinkPath. If the path is empty, resets userType to a valid userType for this type of link. If no linkPaths are valid, an IllegalArgumentException is thrown.

Throws:
java.lang.IllegalArgumentException
java.io.UnsupportedEncodingException