TechNote (Archived)

Information about Authorware Web Player version 2004

Introduction

Macromedia Authorware Web Player version 2004 is significantly different than previous versions of the web player. This TechNote details the changes to the Authorware Web Player, and in doing so also describes how older versions of the Authorware Web Player work.

If you're looking for instructions about hosting the Macromedia Authorware Web Player 2004. Please seeInstructions for hosting the Macromedia Authorware Web Player 2004 (TechNote 19519)

Users of the Authorware Web Player may find this TechNote useful, but there are other TechNotes which may better help them if they are encountering problems installing the web player. Please see Troubleshooting Authorware Web Player for Windows (TechNote 14720). Once the web player plugin is installed, it will automatically handle downloading of required files to run any Authorware web packaged piece. The information in this document is not necessary to know before using the Authorware web player.

The information in this document will be useful for those developers who would like a better understanding of how the web player works, and those developers who want or need to customize the setup.

Background and past web player setup
What's new with Authorware Web player 2004
How the new Authorware web player works
Support for older versions of Authorware
Manifest file
Specifying the Manifest file
On First run
Specifications

Background and past web player setup:

The Authorware Web Player consists of several files:

The plugin, which is the np32asw.dll file
The ActiveX control, which is the awswax.ocx file (used to register the plugin in Microsoft Internet Explorer only)
A web player runtime application, such asruna7w32.exe for Authorware 7
Supporting files, such as .x32s (Xtras), .u32s, and .xmos

In all previous releases of the Authorware Web Player, thesefiles are installed in the following locations:

Internet Explorer: the player files are installed in C:\Windows (or WinNT)\System32\Macromed\Authorwa\
Netscape: the player files are installed in the plugins folder within the Netscape application directory

The directory structure for the Authorware Web Player files is as follows: within the Authorwa or the plugins folder is a file called Np32asw.dll and a NP32ASW folder. Within that folder are subfolders, one for each version of Authorware. Within each subfolder is the web player runtime application with all of its supporting files.

For example: the Authorware Web Player version 7 has a AW70 subfolder, and version 6.5 has a AW65 subfolder. The directory structure for the Authorware Web Player version 7 for Internet Explorer would look something like this:

 \Authorwa np32asw.dll awswax.ocx \NP32ASW \AW70 runa7w32.exe js32.dll ftp.u32 \XTRAS A3sread.x32

While there are likely many more files in the AW70 folder, this is the general file and folder structure. The subfolders for each version of Authorware are the main working directories when an Authorware piece is being played in a browser. Any external files that are needed by the piece, like media files or third party Xtras, are downloaded and run from this directory.

Note: There is one other file stored in a different location. The Awshkwv.ini file is the security preferences file for the Authorware Web Player. It keeps a record of the URLs that have been specified as trusted or non-trusted. The location for this file in previous player versions is C:\Windows\.

While this directory structure works well enough for Microsoft Windows 95 and Windows 98, users on secure operating systems may have problems installing the player. Operating systems such as Microsoft Windows NT4, 2000 and XP restrict access to specific directories, so a typical user may be unable to install the player.

What's new with Authorware Web Player version 2004

The new player is designed to solve the above problem in a couple of ways.

The plugin and OCX files are now designed to be universal across all versions of Authorware: past, present and future. Therefore, users will only need to install the plugin and OCX once and will not have to reinstall them with each new release of Authorware.
The location of the NP32ASW folder now allows all users full access to the directory, which means users can modify the player without administrative access. The new location for the folder is in the C:\Documents and Settings\{Users}\ directory.

How the new Authorware Web Player works

There will no longer be a Compact, Complete or Full installer. Only one installer is needed. The installer will only install the plugin (and the OCX if the player is being installed in Microsoft Internet Explorer). These files will be installed in the same location as they are now: C:\Windows (WinNT)\System32\Macromed\Authorwa\ for Internet Explorer or in the plugins folder within the Netscape Application directory for Netscape. Therefore, the initial installation will still require administrative access on secure operating systems.

Once these files are installed, the Authorware Web Player runtime files (the files in the NP32ASW folder) will be downloaded to the following directory: C:\Documents and Settings\{Users}\.

When a browser opens an Authorware web packaged piece it launches the Authorware plugin (np32asw.dll) which reads the Authorware map (*.aam) file. The first line of every map file has a version line (VER). The version in a map file corresponds to a specific release of Authorware. From this version information the plugin looks for the corresponding web player runtime. If it finds the correct runtime, it launches it and plays the piece.

Note: In the past if it did not find the web player runtime, an error message would appear and the users would need to get an installer for the correct version.

Support for older versions of Authorware

As mentioned above, the version in the map file corresponds to a specific version of an Authorware release. The following table shows this relationship:

Authorware release	Map file version line
3.5x	`VER 0 3`
4.0x	`VER 0 4`
5.x	`VER 0 5`
6.0	`VER 0 6`
6.5	`VER 0 7`
7.0	`VER 0 8`

Previously, with each release, a new working directory was added to the NP32ASW folder for that versions web player runtime files. These directories were named after the Authorware release as follows:

Authorware release	Directory name in NP32ASW folder
3.5.x	n/a
4.0.x	AW40
5.x	AW50
6.0	AW60
6.5	AW65
7.0	AW70

This information also needed to be added to the plugin for each release so it knew where to find the corresponding web runtime. For instance, for Authorware 7, the plugin needed to be programmed to look for and launch the runa7w32.exe web player runtime in the AW70 directory when it opened a map file with a version line of0 8.

With the new player, the folder name for the web player runtime and supporting files will be calculated based on the version of the map file, instead of hard coded like in the past. In order to accomplish this, the names of the working directories have been changed to correspond to the map version, and the web player runtime was given a generic name of webplr.exe. These directory names will now be webplr{map version}. For example if the new plugin opens a map with a version of 0 8, it will look in the \np32asw\webplr08\ directory for the webplr.exe file. If the plugin finds this file in this location, it will launch the file to play the piece. If the plugin does not find the file in this location, the plugin will create this directory, if necessary, and download the web player runtime and supporting files before finally playing the piece. The map version is used because that is the only version string the plugin sees.

Manifest File

As described above, the new plugin downloads the web runtime files to the appropriate working directory. The files to be downloaded are specified in a new file called the manifest file. This is a text file with similar formatting as an Authorware map file but with an INF extension. One difference in the manifest file is that a new site tag can be used. This is to specify the root URL of the files to be downloaded. Any valid URL can be used. Multiple site tags can be used so that files can be downloaded from multiple locations if necessary.

The manifest file is used to list the webplr.exe file and any supporting files that are needed. The idea is to use the manifest file to list files that are generally needed and continue to use the map file for media and third party files specific to the piece. If a file is listed in both the manifest file and the map file, the file listed in the map file will be the one downloaded.

For example: If a developer has several pieces that only use four of the Xtras and the ftp.u32 file, then a manifest file could be created that would only list the webplr.exe, the ftp.u32 and the four Xtras. The target users will then only get the files they need and do not have to wait for a download of all files, most of which they do not use.

Like a map file, the files in the manifest file are downloaded individually. So if a developer needs to add an Xtra or update one of the existing files, he can edit the manifest file. The next time a user launches the piece, the missing files or updated files will be downloaded, and the user will be able to play the piece with the new files without the need of an installer.

Specifying the Manifest file

The manifest file to be used is specified in the map file. This is done with the new tag PLR (standing for Player). The format is as follows:

PLR (URL to manifest file)

An example would be:

PLR http://myserver/mydirectory/mywebplayerfiles/mycustommanifest.inf

This is generally added as the second line of the map file. If no PLR tag is found, a default manifest file is used from the Macromedia web site;which lists all the files found in a complete install for that version;and the files are downloaded.

On First Run

Since this plugin works with all versions of Authorware, there is a possibility that the old np32asw directory contains a large amount of files that might still be needed or used. Rather than requiring the user to redownload all of these files to the new np32asw location. When the new plugin is first run it will copy all these file, from the old working directories to the corresponding directories in the new location. It will also copy theawshkwv.ini from the old location to the new location.

Specifications

np32asw.dll and awswax.ocx

For Internet Explorer, the np32asw.dll and awswax.ocx will be installed in the C:\Windows (WinNT)\System32\macromed\authorwa\ directory via either an EXE installer or a CAB file. For details about the ActiveX control, see Methods added to Methods added to awswax.ocx.

For Netscape (or compatible browser), the np32asw.dll file will be installed in the plugins directory in the applications directory via an EXE installer.

Both of these files will work with all versions of Authorware files: past, present and future releases.

Web Player runtime files

These include the web player runtime EXE and supporting files (webplr.exe, u32s, xmos, xtras, external media, etc...). These files are downloaded to and run from the location specified in the following registry keys in the following order of priority.

A custom location can be set in the following registry key
HKEY_LOCAL_MACHINE\Software\Macromedia\Authorware\WebPlayer\PlayerPath
If the above is not specified, the default location is used, which is determined from the following registry key
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\AppData\ and adding "Macromedia\Authorware Web Player\"
Generally this will be:
C:\Documents and Settings\{user}\Application Data\Macromedia\Authorware Player\

awshkwv.ini file

The location is now determined by the following registry keys in the following order of priority

If all users on the the machine will use the same file
HKEY_LOCAL_MACHINE\Software\Macromedia\Authorware\WebPlayer\IniPath
This location is used if the first one is not specified (this is also the same location as the custom location of the web player runtime files)
HKEY_LOCAL_MACHINE\Software\Macromedia\Authorware\WebPlayer\PlayerPath
This location is used if neither of the above keys are specified (this is also the same as the default location for the Web player runtime files)
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\AppData\ and adding "Macromedia\Authorware Web Player"

Map file

The Map file is the same except for the addition of aPLR line, used to specify the location of the manifest file.

PLR line

Format of the PLR line: PLR {URL}. The URL can be any valid URL.
Example: PLR http://myserver/mydirectory/mymanifest.inf
Special PLR lines
- PLR COMPACT: This will point to a Compact manifest file on the Macromedia site for the particular map file version.
- PLR COMPLETE: This will point to a Complete manifest file on the macromedia site for the particular map file version.
- # PLR: This will be treated the same as a PLR line with the new plugin. This format can be used so that the map file will still be compatible with previously released version of the plugin, as the line will be treated as a comment by old plugins.
  Example: # PLR http://myserver/mydirectory/mymanifest.inf
- If no PLR line specified, PLR COMPLETE will be used. This makes it possible to use this new plugin with all previous content.

Manifest file

This is a text file with an .inf extension. There are separate manifest files for each version of the web player. It is a list of the web player runtime files the Authorware Web Player plugin (np32asw.dll) will use to determine what files should be included on the clients machine. The location of this file is specified by a PLR line (describe above) in the map file.

Site line

The format of the manifest file is similar to map file formatting with the addition of a new Site line. This line is written as follows: site {URL}, where URL is any valid URL. Specifies the root location of the files listed in the manifest file. If no site line is found, it is assumed the root is the same as that of the manifest file location. Multiple site lines can be used.

Example: site http://myserver/mydirectory/

get

This line specifies the get location on the server relative to the root location

put

This line specifies the put location on the client machine relative to the webplr.exe file

bin

This line specifies a file, and includes the following information

name of file on server
name of file on client machine
length of file (which is used to confirm file on server is same as file on client machine: if the file lengths differ, the file on the server will be download and replace the file on the client machine)
Options
- preempt
- recycle
If the same file is specified in the map file and in the manifest file, the file listed in the map will be the one used.

Here is an example of the complete manifest file for a version 0 8 map file.

Security

A separate Security dialog box can appear for each URL files are to be downloaded from. The files from the Macromedia server are always considered trusted, so the security dialog is not needed when files from Macromedia are specified. All other URLs must be specified as trusted either by having the user click the OK buttonin the security dialog and/or by adding the URL as aTrustedSite to the awshkwv.ini file.

Methods added to awswax.ocx

`SetVariable`

Usage: Use SetVariable to change the value of a variable in the embedded Authorware piece running in the activeX control. Check the result value for possible errors. The return matches values in EvalStatus.

Arguments: The following are valid arguments for SetVariable

VariableName
@ icon name: Set to "" if not icon variable
@ icon ID: Set to 0 if not icon variable
Flag
- value = 0: does not create variable, variable is already created in piece
- value = 1: creates variable, the variable will be temporary and is discarded when the piece exits
variable type
- 0 = Text
- 1 = Long
- 2 = Real
- list types currently not supported
value: allows enclose in quotes

Sample Syntax:SetVariableResult: = CallSprite(@"ActiveX...", #SetVariable, "myVar", "", 0, 0, 0, "thirteen")

`GetVariable`

Usage: Use GetVariable to retrieve the value of a variable in the embedded Authorware piece running in the activeX control. The return value is always a string.

Arguments: The following are valid arguments for GetVariable

VariableName
@ icon name: Set to "" if not icon variable
@ icon ID: Set to 0 if not icon variable
Flag: must be 0
variable type to return
- 0 = text
- only text supported
Error value: The string to return ifGetVariable fails in the embedded piece

Sample Syntax:GetVariableResult := CallSprite(@"ActiveX...", #GetVariable, "myVar", "", 0, 0, 0, "ERROR calling GetVariable")

`EvalExpression`

Usage: Use EvalExpression to have the running piece evaluate an expression in its own context. Use this as you would use EvalAssign in the Authorware file. Check the result value against EvalStatus messages for error information.

Arguments: The following are valid arguments for EvalExpression

ExprString: the string to be evaluated. The string must be properly formatted as you would forEvalAssign(...), for example: exprString := "myVar := \"this was set with eval expression\""

Sample Syntax:EvalExpressionResult := CallSprite(@"ActiveX...", #EvalExpression, exprString)

`JumpFile`

Usage: This instructs the embedded Authorware piece to execute a JumpFile.

Arguments: The following are valid arguments for JumpFile

FileName: The name of the destination file to be loaded
VariableList
- Optional
- a single string listing the variables to be passed "var1, var2" or "*"
RecordsLocation
- Optional
- the name of the new RecordsLocation folder

Sample Syntax:CallSprite(@"ActiveX...", #JumpFile, "embedded2.aam", "myVar", "")

`JumpFileReturn`

Usage: This works the same way asJumpFile except that it will return to the original file when the destination file quits.

Arguments: The following are valid arguments for JumpFileReturn

FileName: The name of the destination file to be loaded
VariableList
- Optional
- A single string listing the variables to be passed "var1, var2" or "*"
RecordsLocation
- Optional
- The name of the new RecordsLocation folder