PHPXRef 0.7.1 : Unnamed Project : Detail view of wpkg.js

Functions that are not part of a class:

Displays command usage.

Main execution method. Actually runs the script

addNode(XMLNode, subNode) X-Ref

Adds a sub-node for the given XML node entry.

param: XMLNode
param: subNode
return: Returns true in case of success, returns false if no node could be

addSettingsNode(packageNode, saveImmediately) X-Ref

Adds a package node to the settings XML node. In case a package with the same
ID already exists it will be replaced.

param: packageNode
param: saveImmediately
return: true in case of success, otherwise returns false

addSkippedRemoveNodes(packageNode) X-Ref

Adds a package node to the list of skipped packages during removal process.

param: packageNode

appendProfileDependencies(profileArray, profileNode) X-Ref

Appends dependent profile nodes of the specified profile to the specified
array. Recurses into self to get an entire dependency tree.

checkAll(checkNodes) X-Ref

Evaluates all checks in the check nodes array and returns its result.

returns: {Boolean} true if all checks are true. False if at least one failed.
param: checkNodes Array of XML <check /> nodes to be evaluated.

checkCondition(checkNode) X-Ref

Checks for the success of a check condition for a package.

param: checkNode

checkHostAttribute(attributeName, expression) X-Ref

Checks whether the specified host attribute matches the expression passed as
argument.

returns: {Boolean} True if attribute matches the expression.
param: attributeName
param: expression

createHosts() X-Ref

Creates a new hosts XML root-node and returns it

return: new hosts node

createPackages() X-Ref

Creates a new packages XML root-node and returns it

return: new profiles node

createProfiles() X-Ref

Creates a new profiles XML root-node and returns it

return: new profiles node

createSettings() X-Ref

Creates a new settings XML root-node and returns it

return: new settings node

createSettingsFromFile(fileName) X-Ref

Create a new settings XML root-node by reading a file and returns it

param: fileName String pointing to the settings file to be created
return: settings root node as stored within the file

download(downloadNode) X-Ref

Downloads a file as specified within a download node.

param: downloadNode
return: true in case of successful download, false in case of error

downloadAll(downloadNodes) X-Ref

Downloads all files from the given array of download XML nodes

param: downloadNodes
return: true in case of successful download, false in case of error

downloadClean(downloadNode) X-Ref

Removes eventually existing temporary downloads of the specified XML node

param: downloadNode

downloadsClean(downloadNodes) X-Ref

Cleans all temporary files belonging to the download XML nodes within the
passed array of download XML nodes

param: downloadNodes

fillSettingsWithInstalled() X-Ref

Builds settings document tree containing actually installed packages. Tests
all packages from given doc tree for "check" conditions. If given conditions
are positive, package is considered as installed.

getCommandCmd(cmdNode) X-Ref

Returns the command line argument for this command node. A command node can
be an <install/>, <upgrade/> or <remove/> node.

param: cmdNode
return: command defined within the given cmd XML node, returns null

getCommandExitCodeAction(cmdNode, exitCode) X-Ref

Returns the value of an exit code node within the given command node. A
command node can be an <install/>, <upgrade/> or <remove/> node. In case no
such exit code was defined null will be returned. In case the code is defined
the string "success" is returned. In case the exit code specifies an
immediate reboot then the string "reboot" is returned.

return: returns string "reboot" in case a reboot is required.

getCommandInclude(cmdNode) X-Ref

Return value of include attribute of the given cmd node.
Returns null if include attribute is not set.

returns: Value of include attribute, returns null if attribute is undefined.
param: cmdNode

getCommandTimeout(cmdNode) X-Ref

Returns the timeout value for this command node. A command node can be an
<install/>, <upgrade/> or <remove/> node.

param: cmdNode
return: the timeout for the given cmd XML node - returns 0 if no timeout is

getCommandWorkdir(cmdNode) X-Ref

Returns the value of the workdir attribute of the given cmd XML node.

param: cmdNode
return: the workdir attribute value. Returns null in case value is not

getConditions(xmlNode) X-Ref

Returns condition node of a given XML node. Returns null if there is no
condition node specified.

returns: Array of condition XML-nodes, might be null if no condition is specified
param: xmlNode XML node which is supposed to have a <condition /> sub-node.

getConfig() X-Ref

Returns XML node which contains the configuration

getConfigParamArray() X-Ref

Returns array of <param> nodes from the configuration. Returns array of size
0 in case no parameter is defined.

return: <param> nodes

getDownloads(xmlNode, downloadsArray) X-Ref

Returns download XML node array on a given XML node

param: xmlNode
param: downloadsArray
return: XML node array on a given package XML node containing all package

getDownloadTarget(downloadNode) X-Ref

Returns 'target' attribute from the given download XML node

param: downloadNode
return: value of 'target' attribute, null if attribute is not defined

getDownloadTimeout(downloadNode) X-Ref

Returns 'timeout' attribute from the given download XML node

param: downloadNode
return: {Number} Value of 'timeout' attribute, returns value of downloadTimeout if no

getDownloadExandURL(downloadNode) X-Ref

Returns value of expandURL attribute from a download node.

returns: true if variables shall be expanded in URL attribute,
param: downloadNode The download XML node.

getDownloadUrl(downloadNode) X-Ref

Returns 'url' attribute from the given download XML node

param: downloadNode
return: value of 'url' attribute, null if attribute is not defined

getFileSize(file) X-Ref

Gets the size of a file (in Bytes). The path is allowed to contain
environment variables like "%TEMP%\somefile.txt".

param: file
return: size of the file (in Bytes), returns -1 if file size could not be

getFileDateCreation(file) X-Ref

Gets the creation date of a file.

returns: Date when the file has been created.
param: file

getFileDateModification(file) X-Ref

Gets the last modified date of a file.

returns: Date when the file has been last modified.
param: file

getFileDateLastAccess(file) X-Ref

Gets the last access date of a file.

returns: Date when the file has been last accessed.
param: file

getFileVersion(file) X-Ref

Returns the version of a file.

return: string representation of version, null in case no version could be

getHostname() X-Ref

Returns the hostname of the machine running this script. The hostname might
be overwritten by the /host:<hostname> switch.

getHostNameAttribute(hostNode) X-Ref

Returns a string representing the regular expression associated to the host
definition in hosts.xml.

getHostOS() X-Ref

Returns the operating system of the machine running this script. The return
format is:

<pre>
<OS-caption>, <OS-description>, <CSD-version>, <OS-version>
example output:
microsoft windows 7 professional, , sp1, 6.1.7601
</pre>

It might be overwritten by the /os:<hostos> switch.

Note: Some values might be empty.

returns: Host operating system specification as a plain string converted to

getDomainName() X-Ref

Returns name of domain on which the executing host is member of.

returns: Returns domain name string.

getHostGroups() X-Ref

Returns array of group names where the executing host is member of.

returns: Returns list of membership groups.

getHostAttributes(hostNode) X-Ref

Returns a list of attribute/value pair associated to the host
definition in hosts.xml.

param: hostNode XML node of the host definition
return: dictionary of attribute/value pair.

getHostNodeDescription(hostNode) X-Ref

Returns a string identifying a host node including all attributes.

param: hostNode
return: a string of concatenate 'attribute=value'

getHostInformation() X-Ref

Collects information from local host and stores it into a scripting
dictionary object.

returns: host attributes stored within a dictionary object. This currently

filterConditionalNodes(xmlNodes, getAllMatches) X-Ref

Accepts a list of XML nodes (Array of XML nodes) which is then filtered for
XML nodes which either do not specify specific host matches or all specified
attributes match the current host. For example the following XML nodes would
match:

E.g.

<pre>
<host name="nodename"; os="windows"; attributeX="value" profile-id="default" />
<host name="nodename" profile-id="default" />
<package os="windows" package-id="value" ipaddresses="192\.168\.1\..*" />
<package package-id="value" />
</pre>

The last example matches since there is no limitation to host attributes in the definition.

The return value will be an Array object listing only the XML nodes which
match.

returns: Array of XML nodes which match the current host.
param: xmlNodes
param: getAllMatches

getHostsApplying() X-Ref

Retrieves host nodes from given "hosts" XML documents. Searches for nodes
having matching attributes and returns their array.

First matching host node is returned by default. If switch /applymultiple is
used all matching host nodes are returned.

return: returns the first matching host XML node or the list of all matching

getHostNodes() X-Ref

Returns an array of host nodes which specify the host regular expression and
the corresponding profile

getHostProfiles(hostNode) X-Ref

Returns the profile-id associated with the given host node.
The node structure is defined as follows:

The profile-id or the enclosed <profile... /> nodes might be omitted but not
both!

param: hostNode XML node of the host definition
return: array of strings with referenced profiles

getHosts() X-Ref

Returns XML node which contains all host configurations

getHostsVariables(array) X-Ref

Returns a list of variables from the applying hosts definition.

param: array
return: Object of type Scripting.Dictionary which contains all key/value

getLocalizedString(stringID) X-Ref

Returns the corresponding string defined within the configuration.

param: stringID
return: returns the string as it appears within the configuration. Returns

getPackageChained(packageNode, packageList) X-Ref

Returns array of package IDs which includes package IDs of chained packages.
Returns empty array in case the package does not have any chained packages.

param: packageNode
param: packageList
return: Array specified in packageList parameter extended by package IDs

getPackagePrecheckPolicyInstall(packageNode) X-Ref

Defines how package checks are used during package installation.

Currently supported values:

"always" (default):
When a package is new to the host then first the checks are run in order to
verify whether the package is already installed. If the checks succeed then
it is assumed that no further installation is needed. The package is silently
added to the host without executing any commands.

"never":
When a package is new to the host then the install commands are run in any
case (without doing checks first). Note: Checks will still be done after
package installation to verify whether installation was successful.

returns: "always" or "never" according to precheck-install attribute of
param: packageNode Package XML node to read attribute from.

getPackagePrecheckPolicyRemove(packageNode) X-Ref

Defines how package checks are used during package removal.

Currently supported values:

"always":
When a package is removed from a host then the checks will be executed
before removal is processes. If the checks fail this potentially means that
the package has been removed already. In such case the package remove
commands will be skipped.

"never" (default):
When a package is about to be removed from the host then WPKG will execute
the remove commands in any case without executing the checks first.
Note: Checks will still be done after package removal to verify whether the
removal was successful.

returns: "always" or "never" according to precheck-remove attribute of
param: packageNode Package XML node to read attribute from.

getPackagePrecheckPolicyUpgrade(packageNode) X-Ref

Defines how package checks are used during package upgrade.

Currently supported values:

"always":
When a package is upgraded the checks specified will be be executed before
the upgrade takes place. If checks succeed, then the upgrade will not be
performed (WPKG just assumes that the new version is already applied
correctly.
Please note that your checks shall verify a specific software version and
not just a generic check which is true for all versions. If your checks
are true for the old version too then WPKG would never perform the upgrade
in this mode.

"never" (default):
When a package is about to be upgraded then WPKG will execute the upgrade
commands in any case without executing the checks first. This is the
recommended behavior.
Note: Checks will still be done after package upgrade to verify whether the
upgrade was successful.

returns: "always" or "never" according to precheck-upgrade attribute of
param: packageNode Package XML node to read attribute from.

getPackagePrecheckPolicyDowngrade(packageNode) X-Ref

Defines how package checks are used during package downgrade.

Currently supported values:

"always":
When a package is downgraded the checks specified will be be executed before
the downgrade takes place. If checks succeed, then the downgrade will not be
performed (WPKG just assumes that the old version is already applied
correctly.
Please note that your checks shall verify a specific software version and
not just a generic check which is true for all versions. If your checks
are true for the new/current version too then WPKG would never perform the
downgrade in this mode.

"never" (default):
When a package is about to be downgraded then WPKG will execute the
downgrade commands in any case without executing the checks first. This is
the recommended behavior.
Note: Checks will still be done after package downgrade to verify whether
the downgrade was successful.

returns: "always" or "never" according to precheck-downgrade attribute of
param: packageNode Package XML node to read attribute from.

getChecks(xmlNode) X-Ref

Returns an array of <check /> XML sub-nodes on a given XML node.
In case extended host matching attributes are used only the checks which match the
current host are returned.

param: xmlNode The XML node from which all 'check' sub-nodes are read
return: Array of XML nodes containing all 'check'-nodes which match to the current host.

getPackageCmdDowngrade(packageNode, includeChain) X-Ref

This is a convenience-method to get all downgrade commands.

param: packageNode
return: Array of 'downgrade' XML nodes, returns empty array if no nodes are

getPackageCmdInstall(packageNode, includeChain) X-Ref

This is a convenience-method to get all install commands.

param: packageNode
return: Array of 'install' XML nodes, returns empty array if no nodes are

getPackageCmdRemove(packageNode, includeChain) X-Ref

This is a convenience-method to get all remove commands.

param: packageNode
return: Array of 'remove' XML nodes, returns empty array if no nodes are

getPackageCmdUpgrade(packageNode, includeChain) X-Ref

This is a convenience-method to get all upgrade commands.

param: packageNode
return: Array of 'upgrade' XML nodes, returns empty array if no nodes are

getPackageCmd(packageNode, type, includeChain) X-Ref

Returns a list of commands which apply to the given command type.
Common types are 'install', 'upgrade', 'downgrade' or 'remove' but WPKG
allows any custom type definition within the commands/command XML structure.
For example it is possible to specify <command type="test-type" /> and then
receive all "test-type" commands using this method.

param: packageNode
param: type
param: includeChain
return: Array of command XML nodes, returns empty array if no nodes are

getPackageDependencies(packageNode, packageList) X-Ref

Returns array of package IDs which represent the package dependencies.
Returns empty array in case the package does not have any dependency.

param: packageNode
param: packageList
return: Array specified in packageList parameter extended by package IDs

getPackageExecute(packageNode) X-Ref

Returns the package execute attribute value (String)

param: packageNode
return: package execute attribute value, empty string if undefined

getPackageID(packageNode) X-Ref

Returns the package ID string from the given package XML node.

return: package ID

getPackageIncludes(packageNode, packageList) X-Ref

Returns array of package IDs which represent the package includes. Returns
empty array in case the package does not have any dependency.

param: packageNode
param: packageList
return: Array specified in packageList parameter extended by package IDs

getPackageManualInstallation(packageNode) X-Ref

Reads the "manualInstall" attribute from a package node.
This attribute is true only if the package as installed manually via
command line. It is false for packages which are initially installed by
package synchronization.

returns: {Boolean} True if package was installed manually, false if it is
param: packageNode the package from which the attribute is read.

getPackageName(packageNode) X-Ref

Returns the package name from the given package XML node

return: returns the package name attribute - empty string if no name is

getPackageNode(packageID) X-Ref

Returns the corresponding package XML node from the package database
(packages.xml). Returns null in case no such package exists.

getPackageNodeFromAnywhere(packageID) X-Ref

Returns the corresponding package XML node to the requested package ID by
searching the packages database first. If the package cannot be located
within the package database it prints an error and looks for the node within
the local settings database.
If even the local database does not contain such a package entry then it
prints an error about missing package definition. In case '/quitonerror' is
set it exits.

If the package could be located within the local package database it prints
a warning and returns the local package node.

Algorithmic description:

<pre>
search package node within local package database
if found
return it
else
print warning
look for package within local settings
if found
print warning
return it
else
print error (or exit by throwing error in case of /quitonerror)
return null
fi
fi
</pre>

getPackageNodes() X-Ref

Returns an array of all package nodes that can be installed. This list
includes all packages found in the package database. It does not include
local packages from the settings file (currently installed ones).

return: Array containing XML nodes (package nodes). Array might be of size 0

getPackageNotify(packageNode) X-Ref

Returns the package notify attribute value

param: packageNode
return: Notify attribute value (true in case of String "true" false

getPackagePriority(packageNode) X-Ref

Returns the package priority from the given package XML node

return: package priority - returns 0 if no priority is defined

getPackageReboot(packageNode) X-Ref

Returns the package reboot attribute value. This attribute can add
additional reboots but not limit or invalidate reboot flags set on the
command-level.

This value can have three states:

<pre>
"true" Immediate reboot after package installation.
This will take precedence of any command-level reboot="postponed"
attribute if present and reboot immediately after package
installation.
A reboot="true" attribute on command-level will still result in
an immediate reboot.
Resulting status depending on command-level reboot flag:
"true" immediate reboot after command execution
"delayed" reboot after package installation
"postponed" reboot after package installation
"false" reboot after package installation
"postponed" Schedule reboot after installing all packages within this
session, for example after synchronizing.
Resulting status depending on command-level reboot flag:
"true" immediate reboot after command execution
"delayed" reboot after package installation
"postponed" reboot after all actions are completed
"false" reboot after all actions are completed
"false" No reboot unless one is defined at command-level.
or not set Resulting status depending on command-level reboot flag:
"true" immediate reboot after command execution
"delayed" reboot after package installation
"postponed" reboot after all actions are completed
"false" no reboot
</pre>

As a result there are four possibilities to schedule a reboot in order of
precedence:

<pre>
immediate Command node specified reboot=true, immediate reboot takes place.
package Reboot is issued right after installing:
- package specifies reboot="true"
OR
- any command node specified reboot="delayed"
postponed Reboot will take place after all packages have been applied.
- package specifies reboot="postponed"
OR
- any command node specified reboot="postponed"
none No reboot is issued by this package:
- package does not specify reboot or specifies reboot="false"
AND
- no command node specified any form of reboot reboot
</pre>

This means that an immediate reboot always has the highest priority. You
can just set "reboot markers" on a "timeline" on package and command level
where the closest reboot marker will be executed:
immediate => package => postponed => none

return: one of the states (string values):

getPackageReferences(packageNode, packageArray) X-Ref

Adds all packages referenced by the specified package node to the given
array. In other words all dependencies, chained packages and includes of the
given node will be appended to the array. If you specify null or an empty
array the array returned will contain all packages from the dependency tree
of the given package node.

param: packageNode
param: packageArray
return: array containing all referenced packages (full package nodes). NOTE:

getPackageRevision(packageNode) X-Ref

Returns the package version string from the given package XML node. Returns 0
if package has no revision specified.

return: String representing the package revision (might be a dot-separated

getPackages() X-Ref

Returns XML node which contains all packages (package database).

getPackageInstallAction(packageNode) X-Ref

Returns the action to be performed on a given package if the package is
applied to the current host.
Valid actions are:
"none"      No action; package installed already
"install"   Installation, package is new on the host
"upgrade"   Upgrade package which already exists on the system
New version higher than installed version
"downgrade" Downgrade package which already exists on the system
New version lower than installed version

returns: Action to be performed. Can be 0=nothing, 1=install, 2=upgrade, 3=downgrade.
param: packageNode

getPackagesManuallyInstalled() X-Ref

Returns list of packages which have been manually installed.

returns: List of packages manually installed in local settings database.

getPackagesRemoved() X-Ref

Returns an array of packages which are not assigned to the current host any more.

Packages which are manually installed are not included in the list of packages
to be removed. Except if the package does not exist on server side any more.
Therefore in case a package is removed from the server it is removed from
clients as well even if the package was installed manually because it is to be
assumed tha the administrator no longer wants to support this type of software.

return: Array of packages which will be removed during synchronization.

getPackageVariables(packageNode, array) X-Ref

Returns a list of variables for the given package.

param: packageNode
param: array
return: Object of type Scripting.Dictionary which contains all key/value

getProfileDependencies(profileNode) X-Ref

Returns array of profile nodes which represent the profile dependencies.
Returns empty array in case the profile does not have any dependency.

return: Array of strings representing the references to dependent profiles

getProfileID(profileNode) X-Ref

Returns the corresponding profile ID stored within the given profile XML
node.

return: String representing the ID of the supplied profile node.

getProfileList() X-Ref

Returns an array of strings which represents the profiles directly referenced
by the applying host node. The profiles are evaluated as follows:
<pre>
- /profile:<profile> parameter
- /host:<hostname> parameter matching within hosts.xml
- profiles defined within host.xml which are assigned to the matching hosts entry
</pre>

return: array of strings representing the referenced profiles

getProfileNode(profileID) X-Ref

Returns the corresponding profile XML node from the profile database
(profile.xml). Returns null in case no such profile exists.

param: profileID

getProfileNodes() X-Ref

Returns an array of all profile nodes available.

return: array of profile XML nodes.

getProfilePackageIDs() X-Ref

Returns an array of strings which contains a list of package IDs referenced
by the currently applied profile(s).

The list will contain all referenced IDs within profile.xml which apply to
the current profile(s) (including profile dependencies). Packages which are
referenced but do not exist within the package database (packages.xml) are
included as well. So be aware that in case of inconsistency between
profiles.xml and packages.xml it might be possible that the returned list
refers to packages not available within packages.xml.

NOTE: The list does NOT contain IDs of package dependencies. Just the list of
packages as referred in profiles.xml. Dependency information is only available
within the concrete package nodes within packages.xml. Refer to
getProfilePackageNodes() to get packages including dependencies.

If you like to get a list of full package nodes have a look at
getProfilePackageNodes() but note that it cannot return full nodes for
packages referenced within profiles.xml but missing in the package database.

return: array of package IDs applying to this profile (empty array if no

getProfilePackageInstallDate(packageNode) X-Ref

Returns date object reflecting installation date defined in given node

param: packageNode
return: date object representing installation date. Null if date is undefined.

getProfilePackageNodes() X-Ref

Returns an array of package nodes that should be applied to the current
profile. This function returns full package nodes.

NOTE: Since the profile
just contains the package IDs referenced within profiles.xml but not
existing within the packages database (packages.xml) will not be part of the
list.

In case you like to get a list of package IDs referenced by the profile
(regardless if the package definition exists) have a look at
getProfilePackageIDs().

return: array of package nodes applying to the assigned profile(s)

getProfilePackageUninstallDate(packageNode) X-Ref

Returns Date representation of 'uninstalldate' attribute from the given
package definition as specified within the profile.

param: packageNode
return: Date object representing uninstall date of the given package. Returns

getProfiles() X-Ref

Returns XML node which contains all profiles (profile database).

getProfilesApplying() X-Ref

Returns an array of profile nodes that should be applied to the current
profile. This includes also all profile dependencies.

return: array of profiles (directly associated profiles and dependencies)

getProfilesLogLevel() X-Ref

Returns the log level associated with a given profile.

return: merged log levels from all applying profiles. For example if one

getProfileVariables(array) X-Ref

Returns a list of variables from the Profile.

param: array
return: Object of type Scripting.Dictionary which contains all key/value

getQueryMode() X-Ref

Returns current state of query mode.

returns: {String} Current query mode.

getSettingNode(packageID) X-Ref

Returns the corresponding package XML node from the settings database
(wpkg.xml). Returns null in case no such package is installed.

param: packageID
return: returns package XML node as stored within the settings. Returns null

getSettingHostAttributes() X-Ref

Tries to read host attributes from the settings database.
All host attributes found in the settings database will be used to override
attributes of the local host.

getSettingNodes() X-Ref

Returns an array of all installed packages from the local wpkg.xml

return: Array of installed packages (XML nodes)

getSettingsPath() X-Ref

Returns current path to settings file.

returns: Settings file FS object.

getSettings() X-Ref

Returns XML node which contains all settings (local package database).

getSettingsCheckResults() X-Ref

Returns the checkResults node of the settings database.

returns: checkResults node of currently loaded settings database.

addSettingsCheckResult(checkNode, result) X-Ref

Adds the given check node to the checkResults list in the settings database.

param: checkNode Check XML node to be inserted.
param: result Result of the check on current node.

getSettingsCheckResult(checkNode) X-Ref

Returns result of pre-evaluated check from settings node.

returns: result of already evaluated check. Returns null if the check has
param: checkNode the check node for which to look in the settings

getSettingsCheck(checkNode) X-Ref

Takes a check as a parameter and looks for the same check in the local
settings database. If an identical check with results is found, then this
check is returned in an array. Returns null if no identical check could be
found in the local settings database.

returns: Array of matching checks; returns null if no check match.
param: checkNode check to seek for in local settings databse.

getSkippedRemoveNodes() X-Ref

Returns a list of package nodes (Array object) which have been scheduled for
removal but are not removed due to the /noremove flag.

return: Array of package nodes which would have been removed during this

getVariables(XMLNode, array) X-Ref

Returns a list of key/value pairs representing all variable definitions from
the given XML node.

param: XMLNode
param: array
return: Object of type Scripting.Dictionary which contains all key/value

installPackage(packageNode) X-Ref

Installs the specified package node to the system. If an old package node is
supplied performs an upgrade. In case the old package node is null an
installation is performed.

installPackageReferences(packageNode, referenceType) X-Ref

Installs all packages references of the selected type. Returns true in
case all references could be installed. Returns false if at least one
reference failed.

param: packageNode
param: referenceType
return: true=all dependencies installed successful; false=at least one

installPackageName(name, manualInstall) X-Ref

Installs a package by name.

param: name Package ID of package to be installed.
param: manualInstall Boolean value specifying whether the package is

is64bit() X-Ref

Returns true if running on a 64-bit system. False if running on a 32-bit
system.

Please note that WPKG needs to be run from the local 64-bit cscript
instance in order to be able to access 64-bit directories and registry keys.
The 64-bit instance of cscript is located at %SystemRoot%\system32\. If
cscript from %SystemRoot%\SysWOW64\ is used (32-bit binary) then all reads to
%ProgramFiles% will be redirected to %ProgramFiles(x86). Hence it is not
possible for WPKG to access the "real" %ProgramFiles% folder with the 64-bit
binaries. The same applies for the registry. If 32-bit cscript is used all
reads to HKLM\Software\* are redirected to HKLM\Software\Wow6432Node\*.

WARNING: If cscript is invoked from a 32-bit application it is not possible
to run the 64-bit version of cscript since the real %SystemRoot%\System32
directory is not visible to 32-bit applications. So Windows will invoke the
32-bit version even if the full path is specified!

A work-around is to copy the 64-bit cmd.exe from %SystemRoot%\System32
manually to a temporary folder and invoke it by using
c:\path\to\64-bit\cmd.exe /c \\path\to\wpkg.js

return: true in case the system is running on a 64-bit Windows version.

isApplyMultiple() X-Ref

Returns the current setting of apply multiple configuration.

returns: Current state of apply multiple setting.

isCaseSensitive() X-Ref

returns current state of case sensitivity flag

return: true if case case sensitivity is enabled, false if it is disabled

isDebug() X-Ref

Returns current debug status.

return: true if debug state is on, false if debug is off

isDryRun() X-Ref

Returns current dry run status.

return: true if dry run state is on, false if dry run is off

isForce() X-Ref

Returns current value of the force flag.

return: true if force is enabled, false if it is disabled (boolean).

isForceInstall() X-Ref

Returns current value of the forceinstall flag.

return: true if forced installation is enabled, false if it is disabled

isLogAppend() X-Ref

Returns if log should be appended or overwritten

return: true in case log should be appended. false if it should be

isInstalled(packageNode) X-Ref

Check if package is installed.

return: returns true in case the package is installed, false otherwise

isNoDownload() X-Ref

Returns current status of /noDownload parameter

return: true in case downloads shall be disabled, false if downloads are enabled

isNoForcedRemove() X-Ref

Returns current status of /noforcedremove parameter

return: true in case forced remove is enabled, false if it is disabled

isNoNotify() X-Ref

Returns if the nonotify flag is set or not.

return: true if nonotify flag is set, false if nonotify is not set (boolean)

isNoReboot() X-Ref

Returns if the noreboot flag is set or not.

return: true if noreboot flag is set, false if noreboot is not set (boolean)

isNoRemove() X-Ref

Returns the current state (boolean) of the noremove flag.

return: true if noremove flag is set, false if noremove is not set (boolean)

isNoRunningState() X-Ref

Returns if the noRunningState flag is set or not.

return: true if noRunningState flag is set, false if noRunningState is not

isPostponedReboot() X-Ref

Returns the current state of postponed reboots. If it returns true a reboot
is scheduled when the script exits (after completing all actions).

return: current status of postponed reboot (boolean)

isSendStatus() X-Ref

Returns current value of the sendStatus flag

return: true in case status should be sent, otherwise returns false

isSystemChanged() X-Ref

Returns true in case a package has been processed yet. Returns false if no
package has been processed yet at all.

return: true in case a package has been processed, false otherwise.

isUpgradeBeforeRemove() X-Ref

Returns the current value of the upgrade-before-remove feature flag.

return: true in case upgrade-before-remove should be enabled, otherwise

isSkipEventLog() X-Ref

Returns current value of skip event log setting.

return: true in case event log logging is enabled, false if it is disabled

isEventLogFallback() X-Ref

Returns current state of event log fallback mode (logging to STDOUT instead
of event log.

returns: {Boolean} Current status of event log fallback mode.

isQuiet() X-Ref

Returns true if quiet mode is on. False otherwise.

return: true if quiet flag is set, false if it is unset (boolean)

isQuitOnError() X-Ref

Returns current value of quit on error setting (see '/quitonerror' parameter)

return: true in case quit on error is enabled, false if it is disabled

isZombie(packageNode) X-Ref

Checks if a package is a zombie package which means that it exists within the
locale package database (wpkg.xml) but not on server database (packages.xml).

return: true in case the package is a zombie, false otherwise

queryHostInformation() X-Ref

Query and print local host information (read from the host where wpkg.js is
executed).

queryHostInformationFromSettings() X-Ref

Query and print host information fread from settings file. This requires
that host information is available in settings file. You must have
settingsHostInfo enabled in your configuration.

queryAllPackages() X-Ref

Queries all available packages (from package database and local settings) and
prints a quick summary.

queryInstalledPackages() X-Ref

Show the user a list of packages that are currently installed.

queryPackage(packageNode, packageAction) X-Ref

Show the user information about a specific package.

param: packageNode
param: packageAction
return: string representing the package information

queryUninstalledPackages() X-Ref

Shows the user a list of packages that are currently not installed.

queryProfilePackages(listInstall, listUpgrade, listDowngrade, listRemove, listUnmodified) X-Ref

Query packages listed in the current profile.

param: listInstall List packages which are pending to be installed.
param: listUpgrade List packages which are pending to be upgraded.
param: listDowngrade List packages which are pending to be downgraded.
param: listRemove List packages which are pending to be removed.
param: listUnmodified List packages which are not modified during synchronization.

removePackage(packageNode) X-Ref

Removes the specified package node from the system. This function will remove
all packages which depend on the one to be removed prior to the package
itself. In case the /force parameter is set the function will even remove the
requested package if not all packages depending on it could be removed. Note
that these packages might probably not work any more in such case.

param: packageNode
return: True in case of successful remove of package and all packages

removePackageName(name) X-Ref

Removes a package by name.

param: name
return: True in case of successful remove of package and all packages

removePackagesDependent(packageNode) X-Ref

Removes all packages which depends on the given package. Returns true in case
all packages could be removed. Returns false if at least one dependent
package failed to remove.

param: packageNode
return: true=all dependencies installed successful; false=at least one

removeSettingsNode(packageNode, saveImmediately) X-Ref

Removes a package node from the settings XML node

param: packageNode
param: saveImmediately
return: Returns true in case of success, returns false if no node could be

resetHostInformationCache() X-Ref

Erases host information cache to enforce re-reading of host information when
getter methods like getHostInformation(), getHostOS(), getLocale() etc are
executed.

setApplyMultiple(newState) X-Ref

Sets state of multiple profile assignment.

param: newState

setArchitecture(newArchitecture) X-Ref

Set new architecture for this host.

param: newArchitecture Architecture to used for this host.

setCaseSensitivity(newSensitivity) X-Ref

Sets new status of the case-sensitive flag

param: newSensitivity

setDebug(newState) X-Ref

Sets debug value to the given state.

param: newState

setDomainName(newDomainName) X-Ref

Sets domain name used by the script.

param: newDomainName

setDryRun(newState) X-Ref

Sets dry run value to the given state.

param: newState

setForce(newState) X-Ref

Sets a new value for the forceinstall flag.

param: newState

setForceInstall(newState) X-Ref

Sets a new value for the forceinstall flag.

param: newState

setHostGroups(newGroupNames) X-Ref

Set new group names the host belongs to.

param: newGroupNames

setHostname(newHostname) X-Ref

Set a new host name which will be used by the script. This is useful for
debugging purposes.

param: newHostname

setHostOS(newHostOS) X-Ref

Set new host OS variable overwriting automatically-detected value.

param: newHostOS

setHostProfile(hostNode, profileID) X-Ref

Sets a new profile-id attribute to the given host XML node

param: hostNode
param: profileID

setHosts(newHosts) X-Ref

Set a new hosts node

param: newHosts

setIPAddresses(newIPAdresses) X-Ref

Set a new IP address list array.

param: newIPAdresses

setLogfilePattern(pattern) X-Ref

Set new value for log file pattern

param: pattern
return: returns the pattern with expanded environment variables

setNoDownload(newState) X-Ref

Sets new value for the no-download flag.

param: newState

setNoForcedRemove(newState) X-Ref

Sets new value for the noforcedremove flag.

param: newState

setNoReboot(newState) X-Ref

Sets new state for the noreboot flag.

param: newState

setNoRemove(newState) X-Ref

Sets new state for the noremove flag.

param: newState

setNoRunningState(newState) X-Ref

Sets new state for the noRunningState flag.

param: newState

setPackageID(packageNode, packageID) X-Ref

Sets a new package id-attribute to the given host XML node

param: packageNode
param: packageID

setPackageManualInstallation(packageNode, manualInstall) X-Ref

Set a new value for the manual installation flag of the given package.
Manual installations are flagged only for packages which are installed via
command line directly and not via synchronization.

param: packageNode package to be modified.
param: manualInstall {Boolean} new value of package installation flag.

setPackages(newPackages) X-Ref

Set a new packages node.

param: newPackages

setPostponedReboot(newState) X-Ref

Sets the status of postponed reboot. A postponed reboot schedules a system
reboot after finishing all actions (right before the script exits).

param: newState

setProfileID(profileNode, profileID) X-Ref

Sets a new profile id-attribute to the given profile XML node

param: profileNode
param: profileID

setProfiles(newProfiles) X-Ref

Set a new profiles node

param: newProfiles

setQueryMode(newState) X-Ref

Sets query mode to new state. Allowed states are "remote" and "local".

param: newState query mode value to be set.

setQuiet(newState) X-Ref

Sets new state of the quiet flag

param: newState

setQuitOnError(newState) X-Ref

Sets a new value for the quit on error flag.

param: newState

setRebootCmd(newCommand) X-Ref

Sets new value for the reboot command (rebootCmd).

param: newCommand

setRunningState(statename) X-Ref

Set state of application so other applications can see that it is running by
reading from the registry.

param: statename

setSendStatus(newStatus) X-Ref

Sets new value for the sendStatus flag which defines if status messages are
sent to the calling program using STDOUT

param: newStatus

setSettings(newSettings, saveImmediately) X-Ref

Set a new settings node

param: newSettings

setSettingsPath(path) X-Ref

Set path to local settings file (locak package database).
The path might contain environment variables as well as the following
expressions:
[HOSTNAME] Replaced by the executing hostname.
[PROFILE] Replaced by the concatenated list of profiles applied.

param: path path to settings XML file.

setSystemChanged() X-Ref

Sets the system changed attribute to true. Call this method to make WPKG
aware that a system change has been done.

return: returns current system change status (always true after this method

setSkipEventLog(newValue) X-Ref

Set new value for the boolean flag to disable/enable event log logging.

param: newValue

setEventLogFallback(newValue) X-Ref

Set event log fallback to new value (enabled/disabled).

param: newValue

sortPackageNodes(packageNodes, sortBy, sortOrder) X-Ref

Sorts package nodes by priority flag.

param: packageNodes
param: sortBy
param: sortOrder
return: new Array containing the same package nodes in sorted order (sorted

sortSettings() X-Ref

Sorts the settings file by package name. Returns sorted package XML node.

synchronizeProfile() X-Ref

Synchronizes the current package state to that of the specified profile,
adding, removing or upgrading packages.

saveXml(root, path) X-Ref

Saves the root element to the specified XML file.

createXml(root, rootNS) X-Ref

Creates a new root element of the specified name.

param: root
param: rootNS

loadXml(xmlPath, xmlDirectory, type) X-Ref

Loads XML from the given path and/or directory. Returns null in case XML
could not be loaded.

param: xmlPath
param: xmlDirectory
param: type
return: XML root node containing all nodes from the specified files.

removeNode(XMLNode, subNode) X-Ref

Removes a sub-node from the given XML node entry.

param: XMLNode
param: subNode
return: Returns true in case of success, returns false if no node could be

uniqueAttributeNodes(nodes, attribute) X-Ref

Returns a new array of XML nodes unique by the specified attribute.

cleanup() X-Ref

Clean up function called at the end. Writes all required files, closes
handlers and prints/writes log. Then exits with the given exit code.

exit(exitCode) X-Ref

Ends program execution with the specified exit code.

initialize() X-Ref

Initializes the system, all required variables...

initializeConfig() X-Ref

Initializes configuration file

initializeLog() X-Ref

Initializes log file depending on information available. If log file path is
not set or unavailable creates logfile within %TEMP%. Sets log file handler
to null in case logging is disabled (logLevel=0)

returns: log file handler; returns null if no logfile was initialized.

parseArguments(argv) X-Ref

Processes command line options and sets internal variables accordingly.

saveSettings(sort) X-Ref

Saves settings to file system. Optionally allows sorting of package nodes.

param: sort {Boolean} Set to true in order to sort package nodes.

alert(message) X-Ref

Echos text to the command line or a prompt depending on how the program is
run.

dinfo(stringInfo) X-Ref

Presents some debug output if debugging is enabled

error(message) X-Ref

Logs or presents an error message depending on interactivity.

getLogFile() X-Ref

Returns log file handler. If logfile has not been initialized yet, starts
initialization and returns new filehandler.

Returns null in case logLevel is set to 0.

return: log file handler (returns null if log level is 0)

getLogLine(severity, message) X-Ref

Creates a log line from a given string. The severity string is automatically
padded to a fixed length too to make the log entries easily readable.

param: severity
param: message
return: log entry in its default format: YYYY-MM-DD hh:mm:ss, SEVERITY:

getLogLevel() X-Ref

Returns the current log level:

return: Log level

info(message) X-Ref

Logs or presents an info message depending on interactivity.

log(type, description) X-Ref

Logs the specified event type and description in the Windows event log.

Log types:
<pre>
0 SUCCESS
1 ERROR
2 WARNING
4 INFORMATION
8 AUDIT_SUCCESS
16 AUDIT_FAILURE
</pre>

logStatus(message) X-Ref

Logs status message which can be read by WPKG client to display messages to
the user

param: message

notify(message) X-Ref

Notifies the user/computer with a pop up message.

notifyUserFail() X-Ref

Sends a message to the system console notifying the user that installation
failed.

notifyUserStart() X-Ref

Sends a message to the system console notifying of impending action.

notifyUserStop() X-Ref

Sends a message to the system console notifying them that all action is
complete.

setLocale(newLocale) X-Ref

Set new locale LCID for user.

param: newLocale new locale to be used starting from now.

setLocaleOS(newLocale) X-Ref

Set new locale LCID for OS.

param: newLocale new locale to be used starting from now.

setLogAppend(append) X-Ref

Sets new log append value.

param: append

setLogLevel(newLevel) X-Ref

Sets new logging level.

param: newLevel new log level to be used:

setNoNotify(newState) X-Ref

Sets new state for the nonotify flag.

param: newState

setUpgradeBeforeRemove(newState) X-Ref

Sets new state for the upgrade-before-remove flag.

param: newState

warning(message) X-Ref

Logs or presents a warning message depending on interactivity.

concatenateList(list1, list2) X-Ref

Combines one list and another list into a single array.

concatenateDictionary(dictionary1, dictionary2) X-Ref

Concatenates two Dictionary object and returns concatenated list.
Does not modify any of the dictionaries passed as paramters. Returns new
Dictionary object instead.
If an element is listed in both dictionaries, then the value of the second
Dictionary is applied (overwrite).
Throws error in case an error occurs during dictionary append.

returns: Dictionary object containing values of dicitonary1 and dictionary2.
param: dictionary1 Dictionary to be used as a base.
param: dictionary2 Dictionary to be appended to dictionary1.

downloadFile(url, target, timeout, expandURL) X-Ref

Downloads a file by url, target directory and timeout

param: url
param: target
param: timeout
return: true in case of successful download, false in case of error

createXmlHttp() X-Ref

This method is used to return an XMLHTTP object. Depending on the MSXML
version used the factory is different.

return: XMLHTTP object

exec(cmd, timeout, workdir) X-Ref

No description

getArgv() X-Ref

Returns script arguments

getArchitecture() X-Ref

Returns processor architecture as reported by Windows.
Currently returns the following architecture strings:
<pre>
String Description
x86 Intel x86 compatible 32-bit architecture
x64 AMD64 compatible 64-bit architecture
ia64 Itanium compatible 64-bit IA64 instruction set
</pre>

Other architectures are currently not supported.

returns: Processor architecture string.

getIPAddresses() X-Ref

This function retrieves the IP address from the registry.

return: array of IP address strings, array can be of length 0

getLocale() X-Ref

Returns the Windows LCID configured for the current user. 
NOTE: The LCID is read from "HKCU\Control Panel\International\Locale"
This is the locale of the user under which WPKG is run. In case WPKG GUI is
used this might probably differ from the real locale of the user but at
least it will match the system default locale. A user working on an English
installation will most probably be able to understand English messages even
if the users locale might be set to German. I was yet unable to find any
other reliable way to read the locale.

return: LCID value corresponding to current locale. See

getLocaleOS() X-Ref

Returns the Windows operating system install language LCID. 
NOTE: The LCID is read from the InstallLanguage value at
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\Language\.
This is the locale under which the OS has been initially installed
regardless of the user locale settings. 
For example on an English Windows installation with the locale settings set
to German it will still return 409.

returns: LCID value corresponding to system install language. See

getLogfilePattern() X-Ref

Returns the logfile pattern currently in use

return: current value of logfilePattern

getRebootCmd() X-Ref

Returns the current value of the rebootCmd variable.

return: current value of rebootCmd

getRegistrySubkeys(parentKey, subLevels) X-Ref

Returns a string array containing the names of the subkeys of the given
registry key. The parentKey parameter has to be specified without the leading
HKCU part.

param: parentKey
param: subLevels
return: array containing a list of strings representing the subkey names

getRegistryValue(registryPath) X-Ref

Returns value of given key in registry. If a key is specified instead of a
registry value returns its "(default)" value. In case no default value is
assigned returns an empty string ("").

In case no such key or value exists within the registry, returns null

return: registry value, key default value (or "") or null if path does not

hex(nmb) X-Ref

User-defined function to format error codes. VBScript has a Hex() function
but JScript does not.

isArgSet(argv, arg) X-Ref

Scans an argument vector for an argument "arg". Returns true if found, else
false.

loadPackageEnv(packageNode) X-Ref

Loads environment for the specified package (including applying hosts and
profile variables).

NOTE: You should invoke saveEnv() before loading the package environment.
This allows you to call loadEnv() after operations are done to restore
the previous environment.

<pre>
[...]
var previousEnv = getEnv();
loadPackageEnv(package);
// do some actions
loadEnv(previousEnv);
</pre>

param: packageNode The package definition to load the environment from

loadEnv(environment) X-Ref

Restores environment using the given dictionary object.
Variables which are not defined within the dictionary object are unset.
Variables which are defined within the dictionary object are set to the
value defined in the dictionary object.

param: environment
return: Always returns true.

parseISODate(dateString, ceil) X-Ref

Parses Date according to ISO 8601. See <http://www.w3.org/TR/NOTE-datetime>.

Generic format example:

<pre>
"YYYY-MM-DD hh:mm:ss"
Valid date examples:
(the following dates are all equal if ceil is set to false)
"2007-11-23 22:00" (22:00 local time)
"2007-11-23T22:00" (Both, "T" and space delimiter are allowed)
"2007-11-23 22:00:00" (specifies seconds which default to 0 above)
"2007-11-23 22:00:00.000" (specifies milliseconds which default to 0)
It is allowed to specify the timezone as well:
"2007-11-23 22:00+01:00" (22:00 CET)
"2007-11-23 21:00Z" (21:00 UTC/GMT = 22:00 CET)
"2007-11-23 22:00+00:00" (21:00 UTC/GMT = 22:00 CET)
</pre>

If 'ceil' is set to true then unspecified date components do not fall back
to "floor" (basically 0) but will be extended to the next value.
This allows easy comparison if the current date is within a parsed "!ceil"
date and a parsed "ceil" date.

Examples:
<pre>
ceil=false:
"2007-11-23" => "2007-11-23 00:00:00"
"2007-11" => "2007-11-01 00:00:00"
ceil=true:
"2007-11-23" => "2007-11-24 00:00:00"
"2007-11" => "2007-12-01 00:00:00"
</pre>

so you can specify a range in the following format
<pre>
if (parseISODate("2007-11", !ceil) >= currentDate &&
parseISODate("2007-11", ceil) <= currentDate) {
// this will be true for all dates within November 2007
...
}
</pre>

TIMEZONES:

As specified by ISO 8601 the date is parsed as local date in case no
time zone is specified. If you define a time zone then the specified time
is parsed as local time for the given time zone. So if you specify
"2007-11-23 22:00+05:00" this will be equal to "2007-11-23 18:00+01:00" while
"+01:00" is known as CET as well. The special identifier "Z" is equal to
"+00:00" time zone offset.

Specifying an empty string as dateString is allowed and will results in
returning the first of January 00:00 of the current year (ceil=false) or
first of January 0:00 of the next year (ceil=true).

param: dateString
param: ceil
return: Date object representing the specified date. Returns null if the

psreboot() X-Ref

Reboots the system using tools\psshutdown.exe from the script execution
directory.

reboot() X-Ref

Reboots the system.

getEnv() X-Ref

Fetches current environment and returns Scripting.Dictionary object
containing current environment.

returns: {ActiveXObject} Dictionary representing current environment.

setEnv(key, value) X-Ref

Set an environment variable in the current script environment.

param: key Environment variable name.
param: value Value to assign to the variable.

scanUninstallKeys(nameSearched) X-Ref

Scans uninstall list for given name. Uninstall list is placed in registry
under HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall Every
subkey represents package that can be uninstalled. Function checks each
subkey for containing value named DisplayName. If this value exists, function
returns true if nameSearched matches it.

param: nameSearched
return: returns an array of registry paths to the uninstall entries found. An

searchArray(array, element) X-Ref

Scans the specified array for the specified element and returns true if
found.

trim(string) X-Ref

Removes leading / trailing spaces.

trimLeadingZeroes(string) X-Ref

Removes leading zeroes from a string (does not touch trailing zeroes)

uniqueArray(array) X-Ref

Remove duplicate items from an array.

versionCompare(a, b) X-Ref

versionCompare - compare two version strings.

The algorithm is supposed to deliver "human" results. It's not just
comparing numbers but also allows versions with characters.

Some version number contain appendices to the version string indicating
"volatile" versions like "pre releases". For example some packages use
versions like "1.0RC1" or "1.0alpha2". Usually a version like "1.0RC1" would
be considered to be newer than "1.0" by the algorithm but in case of "RC"
versions this would be wrong. To handle such cases a number of strings are
defined in order to define such volatile releases.

The list of prefixes is defined in the global volatileReleaseMarker array.

Valid comparisons include:
<pre>
A B Result
"1" "2" B is newer
"1" "15" B is newer
"1.0" "1.2.b" B is newer
"1.35" "1.35-2" B is newer
"1.35-2" "1.36" B is newer
"1.35R3" "1.36" B is newer
"1" "1.0.00.0000" Versions are equal
"1" "1.0" Versions are equal
"1.35" "1.35-2" B is newer
"1.35-2" "1.35" A is newer
"1.35R3" "1.36R4" B is newer
"1.35-2" "1.35-2.0" Versions are equal
"1.35.1" "1.35.1.0" Versions are equal
"1.3RC2" "1.3" B is newer (special case where A is an "RC" version)
"1.5" "1.5I3656" A is newer (B is an "I"/integration version)
"1.5" "1.5M3656" A is newer (B is an "M"/milestone version)
"1.5" "1.5u3656" B is newer (B is an update version)
</pre>

return: 0 if equal,

File Size:	10676 lines (345 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	0 files

PHP Cross Reference of Unnamed Project

/se3-wpkg/sources/wpkg/ -> wpkg.js (summary)

Defines 247 functions