Distributing Your Application

Once you've finished coding and testing your application, you'll want to distribute it to users. You'll need to take some time to figure out exactly what files make up your package--what files does the user need to use your product? Is it just an application geode? Perhaps an application geode plus a data file? If one or more of the files is an application, make sure it's really ready for distribution. The files that make up your software are known as a software package.

Once you've figured out what files make up your software package, there are two approaches to making your package available:

PC Download

If all users will have access to a 486 (or better) PC running MS Windows 3.1 or MS Windows 95 and a serial or IR connection, and if you have some way to get files onto that PC, you can have users install your software with the built-in Install/Remove software application.
You will provide a package description file (described in the Package Description File section, below), and will need to set up server software on the PC (described in Setting Up a PC Server ).

Web Site

You can make the files available on a web site. Users with the ability to browse the web can download your program easily, thanks to installation savvy in the built-in WWW application.
You will need to provide a package description file (described in the Package Description File section, below), and a bit more to get your server and files ready (described in Setting Up a Web Server ). You will bundle each software package into an Add-On Software file (a specially tagged archive).

No matter how you're making your software available, you'll need to create its Package Description File.

  1 Preparing Your Application
  2 Package Description File
  3 Setting Up a PC Server
  4 Setting Up a Web Server

Distributing Your Application: 1 Preparing Your Application

Before you package your files up for distribution, first make sure that any applications in the package are ready.

The applications must be ready to shut down when prompted by the system. If the application is running on the device, the user won't be able to un-install the application or to install a newer version. To make your application shut down as necessary, make sure that its FoamSubApplication object has HINT_APPLICATION_QUIT_ON_IACP_ALLOW_FILE_ACCESS in its declaration.

Distributing Your Application: 2 Package Description File

No matter how you're making your program available, you'll need to provide a "package description file," sometimes known as the . INS file. This is an ASCII text file which specifies important information about the files that make up your program:

• Name of the package, which the Install/Remove software application displays to the user
• Description of the package, which the Install/Remove software application displays to the user
• Order in which files should be installed.
• Names and locations of the files on the host machine
• Where the files should be copied to on the client phone

This installation order is important in case of interrupted installation--if file A depends upon file B , but installation was interrupted after file A was brought over, but before file B was, then file A won't work, since it depends on an absent file. If another package is relying upon an older, successfully installed version of file A , then you've just broken that other file.

Use the following format when creating the package description file:

• The file name must have a . INS suffix.
• Whitespace at the end of a line is ignored; blank lines are ignored.
• The first line must say "GEOS Package Description File v1.0"
• The second line must contain the package name. This is the name by which the package will be identified to the user in the Install/Remove software application. The application doesn't have space for a long description, though--about 20 characters.
• The third line must contain a description of the package. When the user views the package in the Install/Remove software application, they may read this description before deciding whether to download/install the package. The application doesn't have space for a long description, though--about 16 characters.
• The fourth line must contain the size of the package, (in bytes). This is the combined size of all files in the package. This string must be at most 14 characters long. (Hopefully, this will be sufficient!) When computing the size, don't forget to include the size of the package description file itself. It's all right to over-estimate the size.
• The fifth line must consist of a period (.). (This delimiter separates information about the package as a whole from information about the individual files.)
• The rest of the file consists of pairs of lines:
  The first line of each pair contains the path of a file on the host machine (or within the Add-On Software file, which will be described later);
  The second line of each pair contains the destination of the file on the client phone.
  
  The host-machine location is relative to the location of the package description file. The destination location is relative to the base of the GEOS tree.

The line-pairs describing file locations must be ordered based upon the order in which the files should be installed. Libraries, fonts, etc. must be listed before the applications that depend on them.

Sample Package Description File

This example shows a package description file for the Santa package. On the host machine, the package description file is in the C:\NSERVER directory, and the files making up the package are in the C:\NSERVER\SANTA directory. The Santa application depends on the Sleigh library, and the Rudy font; the Sleigh library depends on the Donner and Blitzen libraries.

GEOS Package Description File v1.0

Santa v1.0
Gives gifts.
15769
.

santa\rudy.fnt
userdata\font\rudy.fnt

santa\donner.geo
system\donner.geo

santa\blitzen.geo
system\blitzen.geo

santa\sleigh.geo
system\sleigh.geo

santa\santa.geo
world\extrapps\santa.geo

Distributing Your Application: 3 Setting Up a PC Server

The Nokia 9000i Communicator comes with a disk containing the software by which a PC may be made to act as a server machine for the Install/Remove software application. The phone can make either a serial or IR connection with the PC. (For an IR connection, the PC must be running MS Windows 95 and the IR monitoring software which comes with it.)

1. From MS Windows 3.1 or Windows 95, run the program called server on the floppy disk to install a program called NServer onto the PC.
2. Run NServer to turn your PC into a server for the Nokia 9000i Communicator. This program monitors one of the PC's COM ports.
3. Make sure that the NServer program is monitoring the right COM port--check its Settings.

If the user makes a serial or IR connection between a Nokia 9000i Communicator and a PC running the NServer, then runs the Install/Remove software application on the phone, they can install packages from the PC to their phone.

The Install/Remove software application needs to know which directory to scan for Package Definition files. By default, the Install/Remove software application will look in the PC's A:\NSERVER directory--allowing for easy installation directly from floppy. If the files reside on the PC's hard drive, they should probably reside in C:\NSERVER; if they don't, make sure that the user knows where to look for them. To avoid clutter, you might want to put each "package" of files into its own directory under the directory containing the package description files.

Distributing Your Application: 4 Setting Up a Web Server

To make Nokia 9000i Communicator software packages available on a web site, the web site administrator will do some set-up work so that the server knows how to tag Add-On Software files. Each software package must be bundled up into an Add-On Software file--a special kind of archive.

Standard Add-On Software files will have a . AOS suffix, and should be identified by the MIME-type application/x-nokia-9000-communicator-add-on-software . Exactly how this is set up depends upon your server software. NCSA's httpd daemon may use a file called mime.types , to which you would add a line reading

			application/x-nokia-9000-communicator-add-on-software 							aos

Once the server has been set up correctly, each software package needs to be bundled up into an Add-On Software file.

1. Pack the package descriptor file and all files in the software package into one tar archive file. (This is done using the tar program. Tar is a standard Unix program; there is a public domain DOS tar program. The host-file-location lines in the package description file should describe locations within the tar file's directory structure.) The . INS file must be in the top level directory of the tar file so that it may be found. Read your tar documentation to find out how to create the archive. An appropriate invocation for one version of tar might be:

tar cvf santa2.aos santa2.ins santa2/santa2.geo 

2. Give the tar file's filename the suffix . AOS so that it will be recognized as an Add-On Software file.
3. Put the file up on your web server.

Users of the Nokia 9000i Communicator using the WWW built-in application will be able to use WWW to install the software package from your site. The WWW program will download the Add-On Software file, extract the files from the archive, and put them into the proper directories as directed by the package description file.