com.izforge.izpack.util.os
Class ShellLink

java.lang.Object
  com.izforge.izpack.util.os.ShellLink

All Implemented Interfaces:

NativeLibraryClient

public class ShellLink
extends 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.
static int	CURRENT_USER CURRENT_USER = 0; the constant to use for selecting the current user.
static int	DESKTOP This type of shortcut shows on the desktop
static int	HIDE Hide the window when starting.
static int	MAXIMIZED Show the window maximized when starting.
static int	MINIMIZED Show the window minimized when starting.
static int	MINNOACTIVE Show the window minimized when starting.
static int	NORMAL Show the window 'normal' when starting.
static int	PROGRAM_MENU This type of shortcut shows in the program menu
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

Constructor Summary

ShellLink(int linkType, int userType, String group, String name, Librarian librarian)
Creates an instance of ShellLink from an existing shell link on disk.

ShellLink(int type, String name, Librarian librarian)
Creates an instance of ShellLink of a specific type.

ShellLink(String name, int userType, Librarian librarian)
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(String name) This method is used to free the library at the end of progam execution.
String	getallUsersLinkPath() Returns the path for allusersLink
String	getArguments() Returns the command line that the link passes to the target.
String	getcurrentUserLinkPath() Returns the path for currentusersLink
String	getDescription() Returns the description for the link.
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.
String	getFileName() Returns the fully qualified file name under which the link is saved on disk.
int	getHotkey() Retruns the hotkey that can be used to activate the link.
int	getIconIndex() Returns the index of the icon with the icon or resource file
String	getIconLocation() Returns the path and file name of the file that contains the icon that is associated with the link.
String	getLinkName() Returns the name shown in a menu or on the desktop for the link.
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.
boolean	getRunAsAdministrator() Determines if the shortcut target should be run with administrator privileges.
int	getShowCommand() Returns the initial condition of the target window (HIDE, NORMAL, MINIMIZED, MAXIMIZED).
String	getTargetPath() Retruns the absolute path of the link target
int	getUserType() Returns the (ShellLink) user type for the link.
String	getWorkingDirectory() Retruns the working deirectory for the link target.
protected void	moveFileTo(File srcFileObj, File destFileObj) Moves a file to a given destination.
void	save() Saves this link.
void	save(String name) Saves this link to any desired location.
void	setArguments(String arguments) Sets the command line arguments that will be passed to the target when the link is activated.
void	setDescription(String description) Sets the description string that is used to identify the link in a menu or on the desktop.
void	setHotkey(int hotkey) Sets the hotkey that can be used to activate the link.
void	setIconLocation(String path, int index) Sets the location of the icon that is shown for the shortcut on the desktop.
void	setLinkName(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
void	setProgramGroup(String groupName) Sets the name of the program group this ShellLinbk should be placed in.
void	setRunAsAdministrator(boolean runAsAdministrator) Determines if the shortcut target should be run with administrator privileges.
void	setShowCommand(int show) Sets the show command that is passed to the target application when the link is activated.
void	setTargetPath(String path) Sets the absolute path to the shortcut target.
void	setUserType(int type) Sets the (ShellLink) user type for link
void	setWorkingDirectory(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

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

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

Constructor Detail

ShellLink

public ShellLink(int type,
                 String name,
                 Librarian librarian)
          throws Exception

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.

librarian - the librarian

Throws:

IllegalArgumentException - if any of the call parameters are incorrect, or if no linkPaths are returned.

Exception - if problems are encountered in initializing the native interface

ShellLink

public ShellLink(String name,
                 int userType,
                 Librarian librarian)
          throws Exception

Creates an instance of ShellLink from an existing shell link on disk.

Parameters:

name - the file name of the link. May be fully qualified or relative

userType - the type of user for the link path.

librarian - the librarian

Throws:

IllegalArgumentException - if the name was null

Exception - if problems are encountered in reading the file

See Also:

CURRENT_USER, ALL_USERS

ShellLink

public ShellLink(int linkType,
                 int userType,
                 String group,
                 String name,
                 Librarian librarian)
          throws Exception

Creates an instance of ShellLink from an existing shell link on disk.

Parameters:

linkType - 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.

librarian - the librarian

Throws:

IllegalArgumentException - if any of the call parameters are incorrect

Exception - if problems are encountered in initializing the native interface

See Also:

CURRENT_USER, ALL_USERS

Method Detail

finalize

protected void finalize()
                 throws Throwable

Destructor, releases COM and frees native resources.

Overrides:

finalize in class Object

Throws:

Throwable

freeLibrary

public void freeLibrary(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)

setProgramGroup

public void setProgramGroup(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(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(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(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(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(String dir)

Sets the working directory for the link target.

Parameters:

dir - the working directory

See Also:

getWorkingDirectory()

setLinkName

public void setLinkName(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 IllegalArgumentException,
                        UnsupportedEncodingException

Sets the type of link

Parameters:

type - The type of link desired. The following values can be set:

• DESKTOP
• PROGRAM_MENU
• START_MENU
• STARTUP

Throws:

IllegalArgumentException - if an an invalid type is passed

UnsupportedEncodingException

getLinkType

public int getLinkType()

Returns the user type for the link.

• DESKTOP
• PROGRAM_MENU
• START_MENU
• STARTUP

See Also:

setLinkType(int)

setUserType

public void setUserType(int type)
                 throws IllegalArgumentException

Sets the (ShellLink) user type for link

Parameters:

type - the type of user for the link.

Throws:

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 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 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 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 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 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 String getWorkingDirectory()

Retruns the working deirectory for the link target.

Returns:

the working directory

See Also:

setWorkingDirectory(java.lang.String)

getFileName

public 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 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 String getLinkName()

Returns the name shown in a menu or on the desktop for the link.

Returns:

the name

getcurrentUserLinkPath

public String getcurrentUserLinkPath()

Returns the path for currentusersLink

Returns:

currentUsersLinkPath

getallUsersLinkPath

public String getallUsersLinkPath()

Returns the path for allusersLink

Returns:

allusersLinkPath

save

public void save()
          throws Exception

Saves this link.

Throws:

Exception - if problems are encountered

setRunAsAdministrator

public void setRunAsAdministrator(boolean runAsAdministrator)

Determines if the shortcut target should be run with administrator privileges.

Parameters:

runAsAdministrator - if true, run the target with administrator privileges.

getRunAsAdministrator

public boolean getRunAsAdministrator()

Determines if the shortcut target should be run with administrator privileges.

Returns:

true, if the target will run with administrator privileges

save

public void save(String name)
          throws Exception

Saves this link to any desired location.

Parameters:

name - the fully qualified file name for the link

Throws:

IllegalArgumentException - if the parameter was null

Exception - if the save operation could not be carried out

moveFileTo

protected void moveFileTo(File srcFileObj,
                          File destFileObj)

Moves a file to a given destination. Works even if destination file exists and needs to be overwritten.

Parameters:

srcFileObj - source file to be moved.

destFileObj - destination file object.