NetLoadModule 2.4.1
netloadmodule-2.4.1
by RabidCow
Category: network metamodule
NetLoadModule allows you to load modules that may not necessarily be
installed. If the module is not installed, it can be automatically
downloaded and installed before being loaded.
- home: NetLoadModule Home
- required: zlib.dll (included with .24.7)
Table of Contents
Operation
When NetLoadModule first starts, it loads the list of *NetLoadModule files and checks if all of the modules exist. If they do, they are then all loaded, in order, and LiteStep continues loading.
If
one or more of the modules does not exist, NetLoadModule will display a
dialog box containing a list of them. Any descriptions given will be
displayed next to the modules. The user can select the location of
modules that exist, but not where NetLoadModule expected through a
context menu (this is slightly hidden because it is an advanced
feature) and then has a choice as to whether or not to download and
install these modules.
NetLoadModule then downloads and installs the modules in order, first looking for the archive in the NetLoadModuleZipPath, then the *NetLoadModuleSite lines, then the primary site list with the module.
If
a module archive is found that contains more than one dll file and the
theme does not specify which to load, the user is presented a list of
the dlls and asked which is the module to load. There is a button to
open the documentation to make this decision easier. NetLoadModule
cannot decide automatically because there is no easy way to guess which
file is the module, and which other dll files are required.
If
any modules fail to install, the list is presented to the user again,
otherwise NetLoadModule loads all its modules in order and LiteStep
continues to load as normal.
Theme Specific
- *NetLoadModule STRING OPTION OPTION... URL STRING
-
This specifies a module to be loaded, instead of using a LoadModule line for that module. The module name should include the name and version number, but does not need to include a path or extension. This name uniquely identifies this version of this module and is used to determine if the correct version is installed, and where to get it if it is not.Three flags are allowed immediately after the module name: threaded, nopump, and load. threaded and nopump only work with litestep .24.7 beta 4 or newer and work the same as the respective flags with the LoadModule command, except that threaded will load the modules sequencially instead of in parallel.load will allow a theme to specify which dll file to load if there are more than one in the archive. (so the end user doesn't have to deal with the "Multiple DLL" dialog) This can also be used if a module doesn't like being renamed, as it will force the module to be installed in a subdirectory. load has no effect if the module is already installed.
*NetLoadModule ckhotspots-2.3 load ckhotspots.dll "http://site/file.zip" *NetLoadModule geekamp-1.9.666 threaded nopump "" Does it need a msg pump?
If the optional URL is given, this is tried AFTER any *NetLoadModuleSite sites, in this case nothing additional is appended, this is the complete URL to the archive.The description may be displayed to the user to describe what this module is used for, it doesn't affect how it is loaded in any way.The URL may be included in quotes, use "" if you want to leave it out and add a description. The description should not be in quotes unless you want them to show up.If you are loading RabidVWM v1.0 beta 3:LoadModule $ModuleDir$rabidvwm.dll
You can load it with NetLoadModule:*NetLoadModule rabidvwm-1.0-beta_3
or*NetLoadModule rabidvwm-1.0-beta_3 "" the box with stuff that you click on
- *NetInstallModule STRING OPTION OPTION... URL STRING
-
This will download and install a module but not load it. Syntax is the same as for *NetLoadModule.Use this to avoid extra download prompts while your theme is in use:
*NetInstallModule textedit-2.5 !NetReloadModule textedit-2.5
Without the *NetInstallModule line, the first use of !NetReloadModule would prompt the user for download.While the flags are the same as for *NetLoadModule, only load will do anything because the module is not actually loaded. - *NetLoadModuleSite URL STRING
-
This specifies a site to download any missing modules from. The module name will be appended to the end of the URL and the suffix will then be appended to the end of that. If no suffix is given, ".zip" is used.At least one download site should be specified by the theme itself, additional sites can be specified by the user. (In the case of a distro, one download site should be specified by the distro rather than each theme.)ShellFront's module archive would be:
*NetLoadModuleSite "http://www.shellfront.org/modules/"
or, if you wanted to include the suffix:*NetLoadModuleSite "http://www.shellfront.org/modules/" ".zip"
although that's not necessary in this case. - NetLoadModuleTestMessage BOOL
-
This tells NetLoadModule to always display the download module dialog, even if all the modules can be found. All *NetLoadModules will be listed, not just the modules that can't be found.This will also affect !NetReloadModule et al.
- NetLoadModuleOnLoad ACTION
-
The given action will be executed after NetLoadModule has completed loading all the modules listed by *NetLoadModule successfully.
NetLoadModuleOnLoad !alert "I'm so thrilled that this worked!"
If you never use NetLoadModule's bang commands, you can have it unload itself when it's done:NetLoadModuleOnLoad !NetUnloadModule .
But if you're using litestep .24.6, you'll have to use the longer:NetLoadModuleOnLoad !UnloadModule $path$NetLoadModule2.dll
- NetLoadModuleOnFail ACTION
-
The given action will be executed if any module specified by *NetLoadModule could not be installed, after all existing modules were loaded.The intended use is to load a theme switcher or something to provide the user with some sort of "emergency" interface to avoid getting stuck with a blank screen or otherwise partially functional theme.
NetLoadModuleOnFail !alert "Oops, something ain't right here..." "Sucker!"
User Specific
- *NetLoadModuleSite URL STRING
-
This specifies a site to download any missing modules from. The module name will be appended to the end of the URL and the suffix will then be appended to the end of that. If no suffix is given, ".zip" is used.At least one download site should be specified by the theme itself, additional sites can be specified by the user. (In the case of a distro, one download site should be specified by the distro rather than each theme.)ShellFront's module archive would be:
*NetLoadModuleSite "http://www.shellfront.org/modules/"
or, if you wanted to include the suffix:*NetLoadModuleSite "http://www.shellfront.org/modules/" ".zip"
although that's not necessary in this case. - NetLoadModulePath FOLDER
-
This sets the path where NetLoadModule looks for modules, and where it will install them to. This defaults to $LiteStepDir$modules\. This directory must already exist.If a module has an alias, NetLoadModule does not look for it in the module path, only at the location specified in the alias file.
- NetLoadModuleDocPath FOLDER
-
This sets the path where NetLoadModule will install any documentation included with modules that it installs. The default is $LiteStepDir$modules\docs\. If the folder does not exist, it will be created.
- NetLoadModuleZipPath FOLDER
-
This sets the path where NetLoadModule saves the zip files that it downloads. The default is to not save them. NetLoadModule will also look for archives here before downloading them, so if you just delete the module, it will be installed from the local copy. If the folder does not exist, it will be created.
- NetLoadModuleAliasFile FILE
-
This specifies the file where NetLoadModule loads/saves paths for modules that are not simply in the NetLoadModulePath. This file is formatted like an ini file, entries are of the form module-name=path\to.dll, which can include litestep $variables$, under a [NetLoadModule] section. The default is $LiteStepDir$modules.ini.Entries are automatically added when a module is installed in a subfolder because its archive contained multiple dlls.Entries can be added manually with "Select file..." in the module download context menu.You should never have to worry about lines in the alias file, I've documented this merely for completeness, and so you can easily correct things if something goes wrong. (I expect deleting improper lines will be enough.) DO NOT include your alias file with a theme, it will be specific to your system.Example entry added by NetLoadModule when installing ckHotspots 2.2:
ckhotspots-2.2=$litestepdir$modules\ckhotspots-2.2\ckHotspots.dll
Bang Commands
- !NetReloadModule STRING OPTION OPTION... URL STRING
-
This will load or reload a module after startup, downloading and installing if necessary. Syntax is the same as for *NetLoadModuleYou should use this instead of !ReloadModule so you don't have to worry about the path even if you know the module will be installed.Use *NetInstallModule if you want to install a module at startup but load load it later.!NetReloadModule . will reload NetLoadModule itself and, consequently, all modules with a *NetLoadModule line. This will only work with litestep .24.7 beta 4 and above. All flags and options are ignored.The module is guaranteed to be reloaded by the time the bang command is done unless it's used within a !NetLoadModuleBatch block.
- !NetUnloadModule STRING
-
This will unload a module given only the name-version string.You should use this instead of !UnloadModule so you don't have to worry about the path even if you know the module will be installed.!NetUnloadModule . will unload NetLoadModule itself. (That's a period for the module name.) This will only work for litestep .24.7 beta 4 and above.There is no guarantee that the module will be unloaded by the time the bang command is done.
- !NetInstallModule STRING OPTION OPTION... URL STRING
-
This will download and install a module after startup. It's exactly the same as *NetInstallModule.
- !NetUninstallModule STRING
-
This will unload and delete the specified module, its documentation, and any cached copy stored in the NetLoadModuleZipPath. The next load or install for this module will have to re-download it.This may not currently uninstall a loaded module completely.
- !NetLoadModuleBatch OPTION
-
This takes one parameter, which can be either begin or end. It allows you to batch up !NetReloadModules and !NetInstallModules so that you only get one download request for the entire group.
!NetLoadModuleBatch begin !NetReloadModule layercut-1.72 !NetReloadModule lsbox-2.95 !NetInstallModule lscolor-1.4 "" "We're not actually loading this." !NetLoadModuleBatch end
All modules will be installed and (re)loaded by the time !NetLoadModuleBatch end completes. (ie, you can use bang commands for a netloaded module on the same line immediately following !NetLoadModuleBatch end.)
Load Balancing
The *NetLoadModuleSite command now supports some load balancing options which may never be used.
You can't omit the suffix for sites if you use these.
- order INT
-
This enforces a strict order between sites. The order in which the actual *NetLoadModuleSite lines occur is completely ignored.The default order is 100, sites with a lower order will be tried before those with a higher order. Multiple sites may have the same order, such sites will have no enforced order between them.
*NetLoadModuleSite http://a.site/ .zip order 1 *NetLoadModuleSite http://b.site/ .zip order 2 weight 90 *NetLoadModuleSite http://c.site/ .zip order 2 weight 10 *NetLoadModuleSite http://d.site/ .zip order 3
One use for this might be if you have a server on a local network that you always want to check before going out to the internet. - weight INT
-
This sets a relative amount of traffic that a site should recieve. The default weight is 10000, sites with a lower weight will be chosen first less often than those with a higher weight.If you run a site that can only handle a small amount of traffic, you can recommend that people use:
*NetLoadModuleSite "http://whatever/" ".zip" weight 100
and get about 1/100th of the traffic that unweighted sites get. (unless you are the only site with the file, of course)
History
- 2003-09-26 version 2.4.1
- — recompiled hash tables with fixed makehash. Now threaded, nopump, load, weight, order, begin, end should actually be recognized.
- — added a few error messages for incorrect keywords
- — moved error messages from string table to message table so FormatMessage() can use them directly
- 2003-09-17 version 2.4.0
- — works with LiteStep .24.7 (but not beta 1, 2, or 3)
- — clicking "Download" again after the first try fails no longer causes NLM to crash
- — *NetInstallModule will install a module at startup but not load it
- — !NetReloadModule, !NetUnloadModule, !NetInstallModule, !NetLoadModuleBatch for loading/unloading after startup
- — NetLoadModuleOnLoad, NetLoadModuleOnFail so you can, eg, start a theme switcher if something fails to install
- — using external zlib.dll (shares lsapi's copy in .24.7)
- — "primary" site is now used LAST, so authors don't get tons of bandwidth usage
- — new site load balancing with weight and order
- — threaded, nopump, and load flags added to *NetLoadModule
- — fixed a small memory leak in the installer
- — !NetUninstallModule does the inverse of !NetInstallModule
- 2002-11-21 version 2.03
- — will now load with win95
- — added simple load balancing - will start with a site at random from those listed instead of the first one
- 2002-05-08 version 2.02
- — cleaned up the source for release
- — fixed some memory leaks
- — added progress bar during download
- 2002-04-27 version 2.01
- — fixed bug which caused all modules to be installed in a subdirectory, even if there was only one dll in the archive
- — fixed bug which prevented files in subdirectories in archives from being installed
- 2002-04-25 version 2.0
- initial release of NetLoadModule2
- — improved appearance
- — provided mechanism to properly install modules with multiple dlls in their archive
- — properly install html documentation and multiple doc files