KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > izforge > izpack > util > os > ShellLink


1 /*
2  * IzPack - Copyright 2001-2007 Julien Ponge, All Rights Reserved.
3  *
4  * http://www.izforge.com/izpack/
5  * http://developer.berlios.de/projects/izpack/
6  *
7  * Copyright 2002 Elmar Grom
8  *
9  * Licensed under the Apache License, Version 2.0 (the "License");
10  * you may not use this file except in compliance with the License.
11  * You may obtain a copy of the License at
12  *
13  * http://www.apache.org/licenses/LICENSE-2.0
14  *
15  * Unless required by applicable law or agreed to in writing, software
16  * distributed under the License is distributed on an "AS IS" BASIS,
17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18  * See the License for the specific language governing permissions and
19  * limitations under the License.
20  */

21
22 package com.izforge.izpack.util.os;
23
24 import java.io.File JavaDoc;
25 import java.io.UnsupportedEncodingException JavaDoc;
26
27 import com.izforge.izpack.util.Librarian;
28 import com.izforge.izpack.util.NativeLibraryClient;
29
30 /*---------------------------------------------------------------------------*/
31 /**
32  * This class represents a MS-Windows shell link, aka shortcut. It supports creation, modification
33  * and deletion as well as reporting on details of shell links. This class uses a number of native
34  * methods to access the MS-Windows registry and load save and manipulate link data. The native code
35  * is contained in the file <code>ShellLink.cpp</code>. <br>
36  * <br>
37  * For more detailed information on Windows shortcuts read the win32 documentation from Microsoft on
38  * the IShellLink interface. There are also useful articles on this topic on the MIcrosoft website.
39  * <br>
40  * <br>
41  * <A
42  * HREF=http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnmgmt/html/msdn_shellnk1.asp>Using
43  * Shell Links in Windows 95</A><br>
44  * <A
45  * HREF=http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/ifaces/ishelllink/ishelllink.asp>The
46  * IShellLink interface</a><br>
47  * <A
48  * HREF=http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/Shell/IFaces/IShellLink/IShellLink.asp>IShellLink</A>
49  *
50  * @version 0.0.1 / 1/21/02
51  * @author Elmar Grom
52  */

53 /*---------------------------------------------------------------------------*/
54 public class ShellLink implements NativeLibraryClient
55 {
56
57     // ------------------------------------------------------------------------
58
// Constant Definitions
59
// ------------------------------------------------------------------------
60
/**
61      * Note: each of the subclasses will convert these values as appropriate before calling the OS's
62      * routines. For example Win 98 & up will use SW_SNOWMINNOACTIVE (7) when passed HIDE (0) or
63      * MINIMIZED (2) <br>
64      * <br>
65      * and this conversion is done in Win_Shortcut.java
66      */

67     /**
68      * Hide the window when starting. This is particularly useful when launching from a *.bat file,
69      * because no DOS window and no button for the DOS window on the task bar will show! <br>
70      * <br>
71      * <b>Note:</b> this option is not available through the Windows 98+ UI!
72      */

73     public static final int HIDE = 0;
74
75     /**
76      * Show the window 'normal' when starting. Restores the window properties at the last shut-down.
77      */

78     public static final int NORMAL = 1;
79
80     /**
81      * Show the window minimized when starting. The window will not show but a corresponding button
82      * in the task bar will. <p>
83      *
84      * Newer IShellLink only allows Normal, MinNoActive, Maximized.
85      */

86     public static final int MINIMIZED = 2;
87
88     /** Show the window maximized when starting. */
89     public static final int MAXIMIZED = 3;
90
91     /**
92      * Show the window minimized when starting. Note: for win98 and newer, use MINNOACTIVE instead
93      * of MINIMIZED.
94      */

95     public static final int MINNOACTIVE = 7;
96
97     private static final int MIN_SHOW = 0;
98
99     private static final int MAX_SHOW = 7;
100
101     // ------------------------------------------------------
102
// Shortcut types
103
// specific to ShellLink (Shortcut has different numbers).
104
// ------------------------------------------------------
105
/** This type of shortcut shows on the desktop */
106     public static final int DESKTOP = 1;
107
108     /** This type of shortcut shows in the program menu */
109     public static final int PROGRAM_MENU = 2;
110
111     /** This type of shortcut shows in the start menu */
112     public static final int START_MENU = 3;
113
114     /** This type of shortcut is executed at OS launch time */
115     public static final int STARTUP = 4;
116
117     private static final int MIN_TYPE = 1;
118
119     private static final int MAX_TYPE = 4;
120
121     // ------------------------------------------------------
122
// Return values from nafive methods
123
// ------------------------------------------------------
124
/** Returned from native calls if the call was successful */
125     private static final int SL_OK = 1;
126
127     /** Unspecific return if a native call was not successful */
128     private static final int SL_ERROR = -1;
129
130     /**
131      * Return value from native initialization functions if already initialized
132      */

133     private static final int SL_INITIALIZED = -2;
134
135     /**
136      * Return value from native uninitialization functions if never initialized
137      */

138     private static final int SL_NOT_INITIALIZED = -3;
139
140     /**
141      * Return value from native uninitialization functions if there are no more interface handles
142      * available
143      */

144     private static final int SL_OUT_OF_HANDLES = -4;
145
146     /**
147      * Return value from native uninitialization functions if nohandle for the IPersist interface
148      * could be obtained
149      */

150     private static final int SL_NO_IPERSIST = -5;
151
152     /**
153      * Return value from native uninitialization functions if the save operation fort the link
154      * failed
155      */

156     private static final int SL_NO_SAVE = -6;
157
158     /**
159      * Return value if the function called had to deal with unexpected data types. This might be
160      * returned by registry functions if they receive an unexpected data type from the registry.
161      */

162     private static final int SL_WRONG_DATA_TYPE = -7;
163
164     // ------------------------------------------------------
165
// Miscellaneous constants
166
// ------------------------------------------------------
167
private static final int UNINITIALIZED = -1;
168
169     /** the extension that must be used for link files */
170     private static final String JavaDoc LINK_EXTENSION = ".lnk";
171
172     /** CURRENT_USER = 0; the constant to use for selecting the current user. */
173     public static final int CURRENT_USER = 0;
174
175     /** ALL_USERS = 1; the constant to use for selecting the all users. */
176     public static final int ALL_USERS = 1;
177
178     // ------------------------------------------------------------------------
179
// Variable Declarations
180
// ------------------------------------------------------------------------
181
/**
182      * This handle links us to a specific native instance. Do not use or modify, the variable is for
183      * exclusive use by the native side.
184      */

185     private int nativeHandle = UNINITIALIZED;
186
187     /**
188      * Path to the location where links for the current user are stored. The exact content depends
189      * on the circumstances. It can be set during object construction or from native code. It will
190      * point to the location where links of the most recently requested type are stored.
191      */

192     private String JavaDoc currentUserLinkPath;
193
194     /**
195      * Path to the location where links for all users are stored. The exact content depends on the
196      * circumstances. It can be set during object construction or from native code. It will point to
197      * the location where links of the most recently requested type are stored.
198      */

199     private String JavaDoc allUsersLinkPath;
200
201     private String JavaDoc groupName = "";
202
203     private String JavaDoc linkName = "";
204
205     /**
206      * this is the fully qualified name of the link on disk. Note that this variable contains only
207      * valid data if the link was created from a disk file or after a successful save operation. At
208      * other times the content is upredicatable.
209      */

210     private String JavaDoc linkFileName = "";
211
212     /**
213      * Contains the directory where the link file is stored after any save operation that needs to
214      * create that directory. Otherwise it contains <code>null</code>.
215      */

216     private String JavaDoc linkDirectory = "";
217
218     private String JavaDoc arguments = "";
219
220     private String JavaDoc description = "";
221
222     private String JavaDoc iconPath = "";
223
224     private String JavaDoc targetPath = "";
225
226     private String JavaDoc workingDirectory = "";
227
228     /**
229      * there seems to be an error in JNI that causes an access violation if a String that is
230      * accessed from native code borders on another type of variable. This caused problems in
231      * <code>set()</code> For this reason, the dummy string is placed here. Observed with version:
232      *
233      * <pre>
234      *
235      *
236      *
237      * java version &quot;1.3.0&quot;
238      * Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.0-C)
239      * Java HotSpot(TM) Client VM (build 1.3.0-C, mixed mode)
240      *
241      *
242      * </pre>
243      */

244     private String JavaDoc dummyString = "";
245
246     private int hotkey = 0;
247
248     private int iconIndex = 0;
249
250     private int showCommand = NORMAL;
251
252     private int linkType = DESKTOP;
253
254     private int userType = CURRENT_USER;
255
256     private boolean initializeSucceeded = false;
257
258     // ------------------------------------------------------------------------
259
// Native Methods
260
// ------------------------------------------------------------------------
261
// For documentation on these methods see ShellLink.cpp
262
// ------------------------------------------------------------------------
263
private native int initializeCOM();
264
265     private native int releaseCOM();
266
267     private native int getInterface();
268
269     private native int releaseInterface();
270
271     private native int GetArguments();
272
273     private native int GetDescription();
274
275     private native int GetHotkey();
276
277     private native int GetIconLocation();
278
279     private native int GetPath();
280
281     private native int GetShowCommand();
282
283     private native int GetWorkingDirectory();
284
285     private native int Resolve();
286
287     private native int SetArguments();
288
289     private native int SetDescription();
290
291     private native int SetHotkey();
292
293     private native int SetIconLocation();
294
295     private native int SetPath();
296
297     private native int SetShowCommand();
298
299     private native int SetWorkingDirectory();
300
301     private native int saveLink(String JavaDoc name);
302
303     private native int loadLink(String JavaDoc name);
304
305     private native int GetFullLinkPath(int usertype, int linktype);
306
307     /**
308      * This method is used to free the library at the end of progam execution. After this call, any
309      * instance of this calss will not be usable any more!
310      */

311     private native void FreeLibrary(String JavaDoc name);
312
313     /**
314      * Creates an instance of <code>ShellLink</code> of a specific type. Initializes
315      * currentUserLinkPath and allUsersLinkPath.
316      * <p>
317      *
318      * A LinkPath is empty if the combination of linkType and userType, are not valid.
319      * <p>
320      *
321      * Note: If a linkPath is empty, the userType is reset to the other userType.
322      * <p>
323      *
324      * If both linkPaths are empty, an IllegalArgumentException is thrown.
325      *
326      * @param type The type of link desired. The following values can be set:<br>
327      * <ul>
328      * <li><code>ShellLink.DESKTOP</code>
329      * <li><code>ShellLink.PROGRAM_MENU</code>
330      * <li><code>ShellLink.START_MENU</code>
331      * <li><code>ShellLink.STARTUP</code>
332      * </ul>
333      * @param name The name that the link should display on a menu or on the desktop. Do not include
334      * a file extension.
335      *
336      * @exception IllegalArgumentException if any of the call parameters are incorrect, or if no
337      * linkPaths are returned.
338      * @exception Exception if problems are encountered in initializing the native interface
339      */

340     public ShellLink(int type, String JavaDoc name) throws Exception JavaDoc, IllegalArgumentException JavaDoc
341     {
342         if ((type < MIN_TYPE) || (type > MAX_TYPE)) { throw (new IllegalArgumentException JavaDoc(
343                 "the type parameter used an illegal value")); }
344         if (name == null) { throw (new IllegalArgumentException JavaDoc("the name parameter was null")); }
345
346         linkName = name;
347         linkType = type;
348
349         initialize(); // com
350

351         // set curretnUsersLinkPath, allUsersLinkPath, sets userType to valid.
352
setAllLinkPaths();
353     }
354
355     /*--------------------------------------------------------------------------*/
356     /**
357      * Creates an instance of <code>ShellLink</code> from an existing shell link on disk.
358      *
359      * @param name the fully qualified file name of the link.
360      * @param userType the type of user for the link path.
361      *
362      * @see #CURRENT_USER
363      * @see #ALL_USERS
364      *
365      * @exception IllegalArgumentException if the name was null
366      * @exception Exception if problems are encountered in reading the file
367      */

368     public ShellLink(String JavaDoc name, int userType) throws Exception JavaDoc, IllegalArgumentException JavaDoc
369     {
370         if (name == null) { throw (new IllegalArgumentException JavaDoc("the name parameter was null")); }
371
372         this.userType = userType;
373
374         initialize(); // com
375

376         // store the individual parts of the path for later use
377
int pathEnd = name.lastIndexOf(File.separator);
378         int nameStart = pathEnd + 1;
379         int nameEnd = name.lastIndexOf('.');
380         if (nameEnd < 0) { throw (new Exception JavaDoc("illegal file name")); }
381         linkName = name.substring(nameStart, nameEnd);
382
383         if (userType == CURRENT_USER)
384         {
385             currentUserLinkPath = name.substring(0, pathEnd);
386         }
387         else
388         {
389             allUsersLinkPath = name.substring(0, pathEnd);
390         }
391
392         linkFileName = fullLinkName(userType);
393         if (loadLink(linkFileName) != SL_OK) { throw (new Exception JavaDoc(
394                 "reading of the file did not succeed")); }
395
396         // get all settings from the native side
397
get();
398     }
399
400     /*--------------------------------------------------------------------------*/
401     /**
402      * Creates an instance of <code>ShellLink</code> from an existing shell link on disk.
403      *
404      * @param type The type of link, one of the following values: <br>
405      * <ul>
406      * <li><code>ShellLink.DESKTOP</code>
407      * <li><code>ShellLink.PROGRAM_MENU</code>
408      * <li><code>ShellLink.START_MENU</code>
409      * <li><code>ShellLink.STARTUP</code>
410      * </ul>
411      * @param userType the type of user for the link path.
412      * @param group The program group (directory) of this link. If the link is not part of a program
413      * group, pass an empty string or null for this parameter. (...\\Desktop\\group).
414      * @param name The file name of this link. Do not include a file extension.
415      *
416      * @see #CURRENT_USER
417      * @see #ALL_USERS
418      *
419      * @exception IllegalArgumentException if any of the call parameters are incorrect
420      * @exception Exception if problems are encountered in initializing the native interface
421      */

422     public ShellLink(int type, int userType, String JavaDoc group, String JavaDoc name) throws Exception JavaDoc,
423             IllegalArgumentException JavaDoc
424     {
425         if ((type < MIN_TYPE) || (type > MAX_TYPE)) { throw (new IllegalArgumentException JavaDoc(
426                 "the type parameter used an illegal value")); }
427         if (name == null) { throw (new IllegalArgumentException JavaDoc("the name parameter was null")); }
428
429         this.userType = userType;
430
431         initialize(); // com
432

433         // set the variables for currentUserLinkPath and allUsersLinkPath
434
setAllLinkPaths();
435
436         if (group != null)
437         {
438             groupName = group;
439         }
440         linkName = name;
441
442         // load the link
443
linkFileName = fullLinkName(userType);
444         if (loadLink(linkFileName) != SL_OK) { throw (new Exception JavaDoc(
445                 "reading of the file did not succeed")); }
446
447         // get a settings from the native side
448
get();
449     }
450
451     /*--------------------------------------------------------------------------*/
452     /**
453      * Initializes COM and gets an instance of the IShellLink interface.
454      *
455      * @exception Exception if problems are encountered
456      */

457     private void initialize() throws Exception JavaDoc
458     {
459         try
460         {
461             Librarian.getInstance().loadLibrary("ShellLink", this);
462         }
463         catch (UnsatisfiedLinkError JavaDoc exception)
464         {
465             throw (new Exception JavaDoc("could not locate native library"));
466         }
467
468         try
469         {
470             if (initializeCOM() != SL_OK)
471             {
472                 throw (new Exception JavaDoc("could not initialize COM"));
473             }
474             else
475             {
476                 initializeSucceeded = true;
477             }
478         }
479         catch (Throwable JavaDoc exception)
480         {
481             throw (new Exception JavaDoc("unidentified problem initializing COM\n" + exception.toString()));
482         }
483
484         int successCode = getInterface();
485         if (successCode != SL_OK)
486         {
487             releaseCOM();
488             initializeSucceeded = false;
489
490             if (successCode == SL_OUT_OF_HANDLES)
491             {
492                 throw (new Exception JavaDoc(
493                         "could not get an instance of IShellLink, no more handles available"));
494             }
495             else
496             {
497                 throw (new Exception JavaDoc(
498                         "could not get an instance of IShellLink, failed to co-create instance"));
499             }
500         }
501     }
502
503     /*--------------------------------------------------------------------------*/
504     /**
505      * Destructor, releases COM and frees native resources.
506      */

507     protected void finalize() throws Throwable JavaDoc
508     {
509         releaseInterface();
510
511         if (initializeSucceeded)
512         {
513             releaseCOM();
514             initializeSucceeded = false;
515         }
516         super.finalize();
517     }
518
519     /*--------------------------------------------------------------------------*/
520     /**
521      * This method is used to free the library at the end of progam execution. After this call, any
522      * instance of this calss will not be usable any more! <b><i><u>Note that this method does NOT
523      * return!</u></i></b> <br>
524      * <br>
525      * <b>DO NOT CALL THIS METHOD DIRECTLY!</b><br>
526      * It is used by the librarian to free the native library before physically deleting it from its
527      * temporary loaction. A call to this method will freeze the application irrecoverably!
528      *
529      * @param name the name of the library to free. Use only the name and extension but not the
530      * path.
531      *
532      * @see com.izforge.izpack.util.NativeLibraryClient#freeLibrary
533      */

534     public void freeLibrary(String JavaDoc name)
535     {
536         int result = releaseInterface();
537
538         if (initializeSucceeded)
539         {
540             result = releaseCOM();
541             initializeSucceeded = false;
542         }
543
544         FreeLibrary(name);
545     }
546
547     /*--------------------------------------------------------------------------*/
548     /**
549      * Constructs and returns the full path for the link file.
550      *
551      * @param userType the type of user for the link path.
552      *
553      * @return the path to use for storing the link
554      *
555      * @see #CURRENT_USER
556      * @see #ALL_USERS
557      */

558     private String JavaDoc fullLinkPath(int userType)
559     {
560         StringBuffer JavaDoc path = new StringBuffer JavaDoc();
561
562         // ----------------------------------------------------
563
// build the complete name
564
// ----------------------------------------------------
565
if (userType == CURRENT_USER)
566         {
567             path.append(currentUserLinkPath);
568         }
569         else
570         {
571             path.append(allUsersLinkPath);
572         }
573
574         if ((groupName != null) && (groupName.length() > 0))
575         {
576             path.append(File.separator);
577             path.append(groupName);
578         }
579
580         return (path.toString());
581     }
582
583     /*--------------------------------------------------------------------------*/
584     /**
585      * Constructs and returns the fully qualified name for the link file.
586      *
587      * @param userType the type of user for the link path.
588      *
589      * @return the fully qualified file name to use for storing the link
590      *
591      * @see #CURRENT_USER
592      * @see #ALL_USERS
593      */

594     private String JavaDoc fullLinkName(int userType)
595     {
596         StringBuffer JavaDoc name = new StringBuffer JavaDoc();
597
598         name.append(fullLinkPath(userType));
599
600         name.append(File.separator);
601         name.append(linkName);
602         name.append(LINK_EXTENSION);
603
604         return (name.toString());
605     }
606
607     /*--------------------------------------------------------------------------*/
608     /**
609      * Sets all members on the native side.
610      *
611      * @exception Exception if any problem is encountered during this operation.
612      */

613     private void set() throws Exception JavaDoc
614     {
615         if (SetArguments() != SL_OK) { throw (new Exception JavaDoc("could not set arguments")); }
616         if (SetDescription() != SL_OK) { throw (new Exception JavaDoc("could not set description")); }
617         if (SetHotkey() != SL_OK) { throw (new Exception JavaDoc("could not set hotkey")); }
618         if (SetIconLocation() != SL_OK) { throw (new Exception JavaDoc("could not set icon location")); }
619         if (SetPath() != SL_OK) { throw (new Exception JavaDoc("could not set target path")); }
620         if (SetShowCommand() != SL_OK) { throw (new Exception JavaDoc("could not set show command")); }
621         if (SetWorkingDirectory() != SL_OK) { throw (new Exception JavaDoc(
622                 "could not set working directory")); }
623
624     }
625
626     /*--------------------------------------------------------------------------*/
627     /**
628      * Gets all members from the native side.
629      *
630      * @exception Exception if any problem is encountered during this operation.
631      *
632      */

633     private void get() throws Exception JavaDoc
634     {
635         if (GetArguments() != SL_OK) { throw (new Exception JavaDoc("could not get arguments")); }
636         if (GetDescription() != SL_OK) { throw (new Exception JavaDoc("could not get description")); }
637         if (GetHotkey() != SL_OK) { throw (new Exception JavaDoc("could not get hotkey")); }
638         if (GetIconLocation() != SL_OK) { throw (new Exception JavaDoc("could not get icon location")); }
639         if (GetPath() != SL_OK) { throw (new Exception JavaDoc("could not get target ath")); }
640         if (GetShowCommand() != SL_OK) { throw (new Exception JavaDoc("could not get show command")); }
641         if (GetWorkingDirectory() != SL_OK) { throw (new Exception JavaDoc(
642                 "could not get working directory")); }
643     }
644
645     /*--------------------------------------------------------------------------*/
646     /**
647      * Sets the name of the program group this ShellLinbk should be placed in.
648      *
649      * @param groupName the name of the program group
650      */

651     public void setProgramGroup(String JavaDoc groupName)
652     {
653         this.groupName = groupName;
654     }
655
656     /*--------------------------------------------------------------------------*/
657     /**
658      * Sets the command line arguments that will be passed to the target when the link is activated.
659      *
660      * @param arguments the command line arguments
661      *
662      * @see #getArguments
663      */

664     public void setArguments(String JavaDoc arguments)
665     {
666         this.arguments = arguments;
667     }
668
669     /*--------------------------------------------------------------------------*/
670     /**
671      * Sets the description string that is used to identify the link in a menu or on the desktop.
672      *
673      * @param description the descriptiojn string
674      *
675      * @see #getDescription
676      */

677     public void setDescription(String JavaDoc description)
678     {
679         this.description = description;
680     }
681
682     /*--------------------------------------------------------------------------*/
683     /**
684      * Sets the hotkey that can be used to activate the link.
685      *
686      * @param hotkey a valid Windows virtual key code. Modifiers (e.g. for alt or shift key) are
687      * added in the upper byte. Note that only the lower 16 bits for tis parameter are used.
688      *
689      * @see #getHotkey
690      */

691     public void setHotkey(int hotkey)
692     {
693         this.hotkey = hotkey;
694     }
695
696     /*--------------------------------------------------------------------------*/
697     /**
698      * Sets the location of the icon that is shown for the shortcut on the desktop.
699      *
700      * @param path a fully qualified file name of a file that contains the icon.
701      * @param index the index of the specific icon to use in the file. If there is only one icon in
702      * the file, use an index of 0.
703      *
704      * @see #getIconLocation
705      */

706     public void setIconLocation(String JavaDoc path, int index)
707     {
708         this.iconPath = path;
709         this.iconIndex = index;
710     }
711
712     /*--------------------------------------------------------------------------*/
713     /**
714      * Sets the absolute path to the shortcut target.
715      *
716      * @param path the fully qualified file name of the target
717      *
718      * @see #getTargetPath
719      */

720     public void setTargetPath(String JavaDoc path)
721     {
722         this.targetPath = path;
723     }
724
725     /*--------------------------------------------------------------------------*/
726     /**
727      * Sets the show command that is passed to the target application when the link is activated.
728      * The show command determines if the the window will be restored to the previous size,
729      * minimized, maximized or visible at all. <br>
730      * <br>
731      * <b>Note:</b><br>
732      * Using <code>HIDE</code> will cause the target window not to show at all. There is not even
733      * a button on the taskbar. This is a very useful setting when batch files are used to launch a
734      * Java application as it will then appear to run just like any native Windows application.<br>
735      * <b>Note1:</b><br>
736      * <code>HIDE</code> doesn't work in Win98 and newer systems.<br>
737      * use MINIMIZED (MINNOACTIVE), instead.<br>
738      *
739      * @param show the show command. Valid settings are: <br>
740      * <ul>
741      * <li><code>ShellLink.HIDE</code> (deprecated)
742      * <li><code>ShellLink.NORMAL</code>
743      * <li><code>ShellLink.MINNOACTIVE</code>
744      * <li><code>ShellLink.MAXIMIZED</code>
745      * </ul>
746      *
747      * @see #getShowCommand
748      */

749     public void setShowCommand(int show)
750     {
751         if ((show < MIN_SHOW) || (show > MAX_SHOW)) { throw (new IllegalArgumentException JavaDoc(
752                 "illegal value for show command " + show)); }
753
754         this.showCommand = show;
755     }
756
757     /*--------------------------------------------------------------------------*/
758     /**
759      * Sets the working directory for the link target.
760      *
761      * @param dir the working directory
762      *
763      * @see #getWorkingDirectory
764      */

765     public void setWorkingDirectory(String JavaDoc dir)
766     {
767         this.workingDirectory = dir;
768     }
769
770     /*--------------------------------------------------------------------------*/
771     /**
772      * Sets the name shown in a menu or on the desktop for the link.
773      *
774      * @param name The name that the link should display on a menu or on the desktop. Do not include
775      * a file extension.
776      */

777     public void setLinkName(String JavaDoc name)
778     {
779         linkName = name;
780     }
781
782     /*--------------------------------------------------------------------------*/
783     /**
784      * Sets the type of link
785      *
786      * @param type The type of link desired. The following values can be set:<br>
787      * <ul>
788      * <li>{@link #DESKTOP}
789      * <li>{@link #PROGRAM_MENU}
790      * <li>{@link #START_MENU}
791      * <li>{@link #STARTUP}
792      * </ul>
793      *
794      * @exception IllegalArgumentException if an an invalid type is passed
795      * @throws UnsupportedEncodingException
796      */

797     public void setLinkType(int type) throws IllegalArgumentException JavaDoc, UnsupportedEncodingException JavaDoc
798     {
799         if ((type < MIN_TYPE) || (type > MAX_TYPE)) { throw (new IllegalArgumentException JavaDoc(
800                 "illegal value for type")); }
801
802         linkType = type;
803
804         // set curretnUsersLinkPath, allUsersLinkPath, sets userType to valid.
805
setAllLinkPaths();
806     }
807
808     /**
809      * Returns the user type for the link. <br>
810      * <ul>
811      * <li>{@link #DESKTOP}
812      * <li>{@link #PROGRAM_MENU}
813      * <li>{@link #START_MENU}
814      * <li>{@link #STARTUP}
815      * </ul>
816      * <br>
817      *
818      * @see #setLinkType
819      */

820     public int getLinkType()
821     {
822         return linkType;
823     }
824
825     /*--------------------------------------------------------------------------*/
826     /**
827      * Sets the (ShellLink) user type for link
828      *
829      * @param type the type of user for the link.
830      *
831      * @see #CURRENT_USER
832      * @see #ALL_USERS
833      *
834      * @exception IllegalArgumentException if an an invalid type is passed
835      */

836     public void setUserType(int type) throws IllegalArgumentException JavaDoc
837     {
838         if ((type == CURRENT_USER) || (type == ALL_USERS))
839         {
840             userType = type;
841         }
842         else
843         {
844             throw (new IllegalArgumentException JavaDoc(type + " is not a recognized user type"));
845         }
846     }
847
848     /*--------------------------------------------------------------------------*/
849     /**
850      * Returns the (ShellLink) user type for the link. Either {@link #CURRENT_USER} or
851      * {@link #ALL_USERS}
852      *
853      * @see #setUserType
854      */

855     public int getUserType()
856     {
857         return userType;
858     }
859
860     /*--------------------------------------------------------------------------*/
861     /**
862      * Returns the path where the links of the selected type are stroed. This method is useful for
863      * discovering which program groups already exist.
864      *
865      * @param userType the type of user for the link path. One of {@link #CURRENT_USER} or
866      * {@link #ALL_USERS}
867      *
868      * @return the path to the type of link set for this instance.
869      */

870     public String JavaDoc getLinkPath(int userType)
871     {
872         String JavaDoc result = null;
873         if (userType == CURRENT_USER)
874         {
875           result = currentUserLinkPath;
876         }
877         else
878         {
879           result = allUsersLinkPath;
880         }
881         return result;
882     }
883
884     /*--------------------------------------------------------------------------*/
885     /**
886      * Returns the command line that the link passes to the target.
887      *
888      * @return the command line
889      *
890      * @see #setArguments
891      */

892     public String JavaDoc getArguments()
893     {
894         return (arguments);
895     }
896
897     /*--------------------------------------------------------------------------*/
898     /**
899      * Returns the description for the link.
900      *
901      * @return the description
902      *
903      * @see #setDescription
904      */

905     public String JavaDoc getDescription()
906     {
907         return (description);
908     }
909
910     /*--------------------------------------------------------------------------*/
911     /**
912      * Retruns the hotkey that can be used to activate the link.
913      *
914      * @return the virtual keycode for the hotkey
915      *
916      * @see #setHotkey
917      */

918     public int getHotkey()
919     {
920         return (hotkey);
921     }
922
923     /*--------------------------------------------------------------------------*/
924     /**
925      * Returns the path and file name of the file that contains the icon that is associated with the
926      * link.
927      *
928      * @return the path to the icon
929      *
930      * @see #setIconLocation
931      */

932     public String JavaDoc getIconLocation()
933     {
934         return (iconPath);
935     }
936
937     /*--------------------------------------------------------------------------*/
938     /**
939      * Returns the index of the icon with the icon or resource file
940      *
941      * @return the index
942      *
943      * @see #setIconLocation
944      */

945     public int getIconIndex()
946     {
947         return (iconIndex);
948     }
949
950     /*--------------------------------------------------------------------------*/
951     /**
952      * Retruns the absolute path of the link target
953      *
954      * @return the path
955      *
956      * @see #setTargetPath
957      */

958     public String JavaDoc getTargetPath()
959     {
960         return (targetPath);
961     }
962
963     /*--------------------------------------------------------------------------*/
964     /**
965      * Returns the initial condition of the target window (HIDE, NORMAL, MINIMIZED, MAXIMIZED).
966      *
967      * @return the target show command
968      *
969      * @see #setShowCommand
970      */

971     public int getShowCommand()
972     {
973         return (showCommand);
974     }
975
976     /*--------------------------------------------------------------------------*/
977     /**
978      * Retruns the working deirectory for the link target.
979      *
980      * @return the working directory
981      *
982      * @see #setWorkingDirectory
983      */

984     public String JavaDoc getWorkingDirectory()
985     {
986         return (workingDirectory);
987     }
988
989     /*--------------------------------------------------------------------------*/
990     /**
991      * Returns the fully qualified file name under which the link is saved on disk. <b>Note:</b>
992      * this method returns valid results only if the instance was created from a file on disk or
993      * after a successful save operation.
994      *
995      * @return the fully qualified file name for the shell link
996      */

997     public String JavaDoc getFileName()
998     {
999         return (linkFileName);
1000    }
1001
1002    /*--------------------------------------------------------------------------*/
1003    /**
1004     * Returns the path of the directory where the link file is stored, if it was necessary during
1005     * the previous save operation to create the directory. This method returns <code>null</code>
1006     * if no save operation was carried out or there was no need to create a directory during the
1007     * previous save operation.
1008     *
1009     * @return the path of the directory where the link file is stored or <code>null</code> if no
1010     * save operation was carried out or there was no need to create a directory during the previous
1011     * save operation.
1012     */

1013    public String JavaDoc getDirectoryCreated()
1014    {
1015        return (linkDirectory);
1016    }
1017
1018    /*--------------------------------------------------------------------------*/
1019    /**
1020     * Returns the name shown in a menu or on the desktop for the link.
1021     *
1022     * @return the name
1023     */

1024    public String JavaDoc getLinkName()
1025    {
1026        return (linkName);
1027    }
1028
1029    /*--------------------------------------------------------------------------*/
1030    /**
1031     * Returns the path for currentusersLink
1032     *
1033     * @return currentUsersLinkPath
1034     */

1035    public String JavaDoc getcurrentUserLinkPath()
1036    {
1037      return currentUserLinkPath;
1038    }
1039
1040    /*--------------------------------------------------------------------------*/
1041    /**
1042     * Returns the path for allusersLink
1043     *
1044     * @return allusersLinkPath
1045     */

1046    public String JavaDoc getallUsersLinkPath()
1047    {
1048       return allUsersLinkPath;
1049    }
1050
1051    /*--------------------------------------------------------------------------*/
1052    /**
1053     * Saves this link.
1054     *
1055     * @exception Exception if problems are encountered
1056     */

1057    public void save() throws Exception JavaDoc
1058    {
1059        // set all values on the native side
1060
set();
1061
1062        // make sure the target actually resolves
1063
int result = Resolve();
1064
1065        if (result != SL_OK) { throw (new Exception JavaDoc("cannot resolve target")); }
1066
1067        // make sure the directory exists
1068
File JavaDoc directory = new File JavaDoc(fullLinkPath(userType));
1069
1070        if (!directory.exists())
1071        {
1072            directory.mkdirs();
1073            linkDirectory = directory.getPath();
1074        }
1075        else
1076        {
1077            linkDirectory = "";
1078        }
1079
1080        // perform the save operation
1081
String JavaDoc saveTo = fullLinkName(userType);
1082
1083        result = saveLink(saveTo);
1084
1085        if (result == SL_NO_IPERSIST)
1086        {
1087            throw (new Exception JavaDoc("could not get handle for IPesist"));
1088        }
1089        else if (result == SL_NO_SAVE) { throw (new Exception JavaDoc("the save operation failed")); }
1090
1091        linkFileName = saveTo;
1092    }
1093
1094    /*--------------------------------------------------------------------------*/
1095    /**
1096     * Saves this link to any desired location.
1097     *
1098     * @param name the fully qualified file name for the link
1099     *
1100     * @exception IllegalArgumentException if the parameter was null
1101     * @exception Exception if the save operation could not be carried out
1102     */

1103    public void save(String JavaDoc name) throws Exception JavaDoc
1104    {
1105        if (name == null) { throw (new IllegalArgumentException JavaDoc("name was null")); }
1106
1107        // set all values on the native side
1108
set();
1109
1110        // make sure the target actually resolves
1111
if (Resolve() != SL_OK) { throw (new Exception JavaDoc("cannot resolve target")); }
1112
1113        // make sure the directory exists
1114
File JavaDoc directory = new File JavaDoc(name.substring(0, name.lastIndexOf(File.separatorChar)));
1115        if (!directory.exists())
1116        {
1117            directory.mkdirs();
1118            linkDirectory = directory.getPath();
1119        }
1120        else
1121        {
1122            linkDirectory = null;
1123        }
1124
1125        // perform the save operation
1126
if (saveLink(name) != SL_OK) { throw (new Exception JavaDoc("the save operation failed")); }
1127
1128        linkFileName = name;
1129    }
1130
1131    /*--------------------------------------------------------------------------*/
1132    /**
1133     * sets currentUsersLinkPath and allUsersLinkPath. If the path is empty, resets userType to a
1134     * valid userType for this type of link. If no linkPaths are valid, an IllegalArgumentException
1135     * is thrown.
1136     *
1137     * @throws IllegalArgumentException
1138     * @throws UnsupportedEncodingException
1139     */

1140    private void setAllLinkPaths() throws IllegalArgumentException JavaDoc
1141    {
1142        // sets currentUsersLinkPath and allUsersLinkPath
1143
GetFullLinkPath(CURRENT_USER, linkType);
1144        GetFullLinkPath(ALL_USERS, linkType);
1145
1146        // be sure userType is valid. Override initial choice if not.
1147
if (userType == CURRENT_USER && currentUserLinkPath.length() == 0)
1148        {
1149            userType = ALL_USERS;
1150        }
1151        else if (userType == ALL_USERS && allUsersLinkPath.length() == 0)
1152        {
1153            userType = CURRENT_USER;
1154        }
1155
1156        if ( allUsersLinkPath.length() == 0 && currentUserLinkPath.length() == 0) { throw (new IllegalArgumentException JavaDoc(
1157                "linkType " + linkType + " is invalid.")); }
1158    }
1159
1160}
1161/*---------------------------------------------------------------------------*/
1162
1163
Popular Tags