LSMD Document

lsmd version:
0.3p
file version:
1.2.0
by RabidCow

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.

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 *NetLoadModule
You 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
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

Index

Configuration
*NetLoadModule
NetLoadModuleAliasFile
NetLoadModuleDocPath
*NetInstallModule
NetLoadModuleOnFail
NetLoadModuleOnLoad
order
NetLoadModulePath
*NetLoadModuleSite
NetLoadModuleTestMessage
weight
NetLoadModuleZipPath
Bang Commands
!NetInstallModule
!NetLoadModuleBatch
!NetReloadModule
!NetUninstallModule
!NetUnloadModule



Copyright © 2003 RabidCow