JSDrop Generic Drop HandlerInitial release: December, 2010. Version 1.10.1219.IntroductionJSDrop is an ActiveX DLL component that provides customized drop handling. A drop handler is a shell extension that gets informed by Explorer whenever anything is dropped onto a specific registered file type. For instance, Windows Script Host provides wshext.dll as a drop handler for .VBS files. When another file is dropped onto a VBS file, WSH runs the VBS file and provides the dropped file path in the WScript object's Arguments property.Any registered file type can have a drop handler. The inspiration for JSDrop was the fact that HTA files do not have a drop handler, even thought there is a commandLine property in an HTA. Providing a drop handler for HTAs means an HTA utility can be started with the path of a dropped file in the commandLine property. JSDrop is described as a generic drop handler because it can be used for any number of file extensions. Any extension that is registered on the system can have a drop handler. (No file type can have more than 1 drop handler.) JSDrop also provides different ways to access the drop information. One way is to assign an executable to handle the drop: When a file or folder is dropped onto a relevant file type, JSDrop will run a designated executable and send it both the target file path and the dropped file path in a command line. With HTA files, JSDrop can be configured to run mshta.exe whenever a file or folder is dropped onto an HTA file. The HTA commandLine property will then contain "[HTA file path]" "[Dropped file path]": <HTA:APPLICATION ID="ObjHTA"> <SCRIPT LANGUAGE="VBScript"> Sub LoadIt() sComLine = objHTA.commandLine End Sub </SCRIPT> <BODY onload="LoadIt()"> That method works well for file types that can process a command line. It could even work well for other types of files. For example, one could assign JSDrop as a drop handler for .LOG files and have a custom program assigned to be run whenever a file is dropped onto a LOG file. That custom program could then add the text in the dropped file to the LOG file automatically. In order to provide more options, especially to scripters, JSDrop also provides a second, entirely different kind of access. JSDrop puts an object in the Running Object Table (ROT) to be accessible by script or software. The ROT is a systemwide list of objects that are available to any COM-compatible process. The ROT is what makes it possible to get hold of a running instance of MS Word by using Set Ob = GetObject(, "Word.Application"). JSDrop adds the object JSDrop.DropInfo to the ROT. JSDrop.DropInfo provides a FileDrop event to any subscribing process. You can use Set Ob = GetObject(, "JSDrop.DropInfo") to receive drop events for any file extension you have registered with JSDrop. The event provides the target and dropped file paths. It also provides an option to programmatically cancel running the target file. See the topics below for a more detailed explanation of the ways that JSDrop can be used. Back to Index RequirementsVista/7 issues:JSDrop can be used on any Windows version. It was developed and tested on Windows XP. It should work fine on Vista/7, but as usual, there could be problems with some aspects if you do not give yourself sufficient permissions. (For instance, configuration requires writing to the Registry.) Windows32 vs Windows64: JSDrop is 32-bit software. As a shell extension it is loaded by Explorer. Therefore, it will not work on 64-bit Windows if you are using the 64-bit version of Explorer.exe. If you would like to use the 32-bit version of Explorer.exe you can use JSDrop. For more information about how to do that, see this link: http://support.microsoft.com/kb/895561 Registration: To use JSDrop, you first need to register the objects. To do that, copy JSDrop.dll to the System folder or some other safe place. Then drop it onto the RegSvr.vbs script to register the objects. After the objects are registered you can use the JSDrop.Setup object to configure the drop handling functionality. Datatype note: All methods on all JSDrop objects use variant data types. That means that all methods are VBScript-compatible. When using JSDrop from VB, C++, Delphi, etc. some translation may be required to translate parameters going in and out of method calls. Back to Index Handler ObjectThere are no public methods for the JSDrop.Handler object. JSDrop.Handler is the actual drop handler. It is called by Explorer when a relevant file drop occurs. It is not used programmatically.Back to Index DropInfo ObjectThe JSDrop.DropInfo has one main element. That is the FileDrop event. JSDrop.DropInfo is the object that gets put into the Running Object Table (ROT) so that any script or software can access it. See the hook demo.vbs script for an example of how to use JSDrop.DropInfo.Event FileDrop(TargetExtension, TargetFile, DropFile, CancelRun)FileDrop occurs whenever a file or folder is dropped onto a file (or its shortcut) that has an extension handled by JSDrop. For example, if you register the extensions .hta, .log and .gif with JSDrop then the FileDrop event will occur whenever a file or folder is dropped onto any of those file types.TargetExtension - Returns the file extension of the target file. TargetFile - Returns the full path of the target file. DropFile - Returns the full path of the dropped file. CancelRun - This is similar to the Cancel options when scripting the IE DOM. If CancelRun is set to True in the event handler the running of the target file will be cancelled. (See the hook demo.vbs script for an example of the usage.) Back to Index Properties TargetFile, DropFileTargetFile returns the path of the last file dropped onto. DropFile returns the path of the last file dropped. In general these properties are not likely to be useful. They are provided merely for thoroughness. For example, you may find it easier to monitor drop events by calling periodically to JSDrop.DropInfo rather than keeping an instance alive to receive events.Back to Index Setup ObjectJSDrop.Setup is not directly part of the drop target functionality. Rather, it provides methods to configure file extension settings, etc. The methods below provide the way to customize JSDrop functionality.Function RegisterExtension(Extension, HandlerEXE, RunFile)Registers a file extension to be handled by JSDrop.Ex.: Return = DH.RegisterExtension("hta", "C:\windows\system32\mshta.exe", True) Extension - Must be the registered file extension to be handled. HandlerEXE - Path to the executable file that is called to run the target file if RunFile is True. If RunFile is False then HandlerEXE should be "". RunFile - Boolean. True to run the HandlerEXE with the target file and dropped file paths in the command line. If RunFile is False, the JSDrop.DropInfo FileDrop event still occurs but no other action is taken by JSDrop. Return - Returns zero on success. For non-zero errors, the ErrorString property returns an error description. Notes: When JSDrop is assigned to handle a given file extension, a Handler EXE path is provided, and RunFile is set to true, it works as follows: When a file or folder is dropped onto a relevant file (or the link to such a file) the drop handler will run the handler EXE program and send both file paths in the command line. Example scenario: JSDrop is assigned as drop handler for HTA files. The handler EXE is c:\windows\system32\mshta.exe. A file C:\windows\desktop\file1.txt is dropped onto a file C:\windows\desktop\some.hta. JSDrop runs mshta and sends it the following command line: "C:\windows\desktop\some.hta" "C:\windows\desktop\file1.txt" Mshta.exe then loads C:\windows\desktop\some.hta and passes it the same command line that it received. So some.hta gets its own path plus the path of the dropped file. Back to Index Function UnRegisterExtension(Extension)Unregisters a file extension in relation to JSDrop, so that JSDrop will no longer act as drop handler for that file type.Ex.: Return = DH.UnregisterExtension("hta") UnRegisterExtension reverses RegisterExtension actions. It returns similar error codes. A return of zero indicates success. Back to Index Functions RegisterForROT(), RegisterForROTNT6()When the JSDrop handler is activated it makes sure that JSDrop.DropInfo is running in the ROT and is available using GetObject. But what about if you want to get hold of JSDrop.DropInfo and no files have been dropped since Windows started? RegisterForROT is a method to cause Explorer to load JSDrop.DropInfo at startup so that it is always available.There are two methods here because Microsoft broke the functionality with Windows Vista/7. RegisterForROT is for Windows 2000/XP. It lists JSDrop.DropInfo in the Registry key HKLM\Software\Microsoft\Windows\CurrentVersion\ShellServiceObjectDelayLoad causing it to be loaded by Explorer at boot, at which time it puts itself into the ROT and is then accessible with GetObject. That method is broken in Windows Vista/7 because Microsoft moved the Registry key! RegisterForROTNT6 is for use with Windows Vista/7. It puts an entry under the Registry key HKLM\Microsoft\Windows\CurrentVersion\Explorer\ShellServiceObjects Return is zero on success. For other returns use the ErrorString property to get an error description. Notes: As of this writing, RegisterForROTNT6 has not been tested in Windows Vista/7. Given the extreme and convoluted security issues in Vista/7, it's possible that the method will not work. In that case a file drop would be required to load JSDrop.DropInfo into the ROT after startup. Do not attempt to load the object into the ROT by creating the object. It must be loaded by Explorer to work (via Registry setting or file drop.) If you attempt to create the JSDrop.DropInfo object using CreateObject it will work, and the object will get loaded into the ROT, but that object will not fire events that can be received. Back to Index Functions UnregisterForROT(), UnregisterForROTNT6()These functions reverse the matching registration functions above.Back to Index Function GetDropExtensions()JSDrop stores a list of drop extensions that can be retrieved in order to make sure that all Registry settings are cleared when/if JSDrop is removed from the system. GetDropExtensions returns that list as a simple, comma-delimited string. For example, if you have assigned JSDrop as drop target for HTA, LOG and GIF files, GetDropExtensions will return something like: "hta,log,gif".Back to Index Sub CleanUpForRemoval()If you decide to remove JSDrop you need to clean up the changes you have made. Unregistering the component will not remove file extension settings and ROT settings. To be thorough, proceed as follows:1) Call UnregisterExtension for any file extension you have assigned to JSDrop. 2) Call CleanUpForRemoval to remove other settings. 3) Unregister JSDrop.dll. Back to Index Property ErrorString(Number)Ex.: Ret = DH.RegisterForROTDescription = DH.ErrorString(Ret) Returns an error description for errors returned by JSDrop functions. Ret should be the numeric value returned by the function call. Back to Index LicenseYou use all script code and components from JSWare at your own risk.The components (compiled DLL and EXE files) may be used for personal or commercial purposes. No payment or attribution is required for either use. The components may be redistributed if they are required as support files for scripts or software that you have written. Also, the script code may be used freely, in part or as whole scripts, for any purpose, personal or commercial, without payment or attribution. I ask only that you not redistribute these scripts and components, except as required for your direct use. Instead, please direct others to obtain copies of JSWare scripts and components directly from www.jsware.net. Also, none of the code here may be redistributed under another license. If a work using code from JSWare is distributed with restrictions of any kind the code from JSWare must be kept exempt from those restrictions. This includes, but is not limited to, code sold for profit, code with usage restrictions and code distributed as so-called "Open Source" with redistribution restrictions. Joe Priestley
JSWare • www.jsware.net • jsware@jsware.net Please note: JSWare does not accept "webmail" from hotmail, yahoo, facebook, or gmail. For further explanation see: www.jsware.net/jsware/contact.php5 |