You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

Internet Setup Wizard Design

Table of  Contents

Target Audience
Internet Setup Components
Design of Internet Setup Wizard
Internet Setup Manifest
Coding for Testing
i18n issues
Open Issues


 
Target Audience
All groups involved in developing and supporting Netscape's Client Customization Kit.
 
Internet Setup Components
In the 4.x series of Communicator, the Internet Setup application was built atop HTML, Style Sheets, Layers, Javascript, LiveConnect, Java, Java Native Methods, Plugins, Signing, and the Security Model.  Since each of these was a brand new, untried technology, the project was fraught with development and debugging problems that mushroomed this small project into a very lengthy project.  Even in later versions of 4.x, these technologies continued to evolve and present major development obstacles.

In the new 5.x series, the Internet Setup application will be built in a native wizard style.  By taking advantage of the WizardMachine, development of Internet Setup will be vastly simplified.  The WizardMachine provides a single browser like platform for the subset of features required by any wizard application.

The offline Internet Setup application will consist of these components:

  • UI in the form of a set of WizardMachine .ini files
  • DUN detection and installation (Win95, Win98 only)
  • (URL.DLL problems will be handled by minimum system requirements)
  • Modem detection and setup (including selection of existing connectoid in UI)
  • Connectoid configuration
  • Dialing properties?  (Win98 has new panels to handle 10-digit dialing)
  • Modem dialing
  • Communicator profile detection, creation and configuration
Online account creation also requires these components:
  • Dial an account server
  • Launch Communicator into special page and/or mode
  • Initiate and complete Milan negotiation
  • Update profile with configuration information
  • Hang up the modem
Excluding the UI, each of the components is implemented in one or more DLLs that are included into the Internet Setup wizard by reference in the .ini files.  (The WizardMachine provides the ability to dynamically load libraries and call entry points in those libraries to get work done.)  Each component's handling will be consolidated into a single entry point in the AS DLL(s).

For Internet Setup to be a useful application, these additional components are necessary:

  • Communicator code to connect a profile to it's dialup connectoid and setup dial on demand
  • Communicator UI to enable users to change the dialup connectoid associated with a profile
  • (Together, these are currently known as "MUC.DLL")
If possible, Internet Setup should launch Communicator into a new online session dialed into the new ISP account once configuration is complete.

Component Descriptions

DUN

MS DialUp Networking is the component that manages the linkage between the application using the network and the modem that actually provides the service.  DUN is necessary to implement a dialup enabled browser in our model.  Therefore, detecting whether DUN is installed and installing it if not is an essential feature of the product.

We have an outstanding bug in our DUN handling that prevents us from detecting situations where DUN is not completely installed correctly.  This causes significant problems for our partners and should be corrected in the new release.

Modem

Detecting the modem and configuring it is primarily done by the OS.  Internet Setup shows the current settings and allows the user to launch the OS configuration interface to resolve any problems.  Exiting this phase in Internet Setup, we are assured that a modem exists and has been configured.

Connectoids

To dial the modem, a connection must be defined.  This is commonly referred to as a "connectoid."  Internet Setup accomplishes this through the RAS API which is based on TAPI (Telephony API).  The OS presents different features in different versions and upgrade revisions.  In general, it includes information such as phone number, DNS settings, IP address and other link level information in the network protocols.

Dialing

Dialing is accomplished by referencing an existing connectoid and using the TAPI interfaces to cause the modem to do work.  Once the connection is established, Internet Setup is no longer directly involved other than to hang up the phone whenever a transaction is completed.  Internet Setup will only support dialing if online account creation is supported.

Create Profiles

Communicator stores all preferences for a particular "user" or "identity" in a thing called a profile.  Profiles are implemented as a directory structure that contains all the files with particular settings or contents that make up the profile.  Typically, these profiles are stored under Netscape/Users, but users may choose to place them anywhere.

Internet Setup's main task is to create and populate profiles with values determined during the account creation process.  To do this, it must be able to create profiles.  In the 4.x versions of Internet Setup, this was handled automatically inside Communicator.  In the 5.x+ releases, we need to be able to create a profile under external control.  The implementation of this component is currently planned to be a special command line option to Communicator itself which causes Communicator to create a profile with the given name and then exit.  The syntax is "netscape -CreateProfile <profile_name>".

Online Internet Setup

Launch Communicator

Online account creation depends on an HTTP client/server connection having been established.  The preferred method for creating this connection is to launch Communicator and post a form to the http server.  Launching Communicator to a specified URL is a base capability of Communicator.  Internet Setup merely needs to include an entry point to initiate it.

Milan

Having launched Communicator is not enough, by itself, to cause a Milan conversation to occur.  In addition to launching Communicator, we must cause a form to be posted to the target URL.  This should be possible using a simple form and some javascript to set the target URL and submit() the form.

At the completion of a Milan conversation, the server returns a MIME STREAM of type application/x-netscape-autoconfigure-dialer or application/x-netscape-autoconfigure-dialer-v2.  This stream of data contains all the configuration data necessary for access to the new ISP account.  To complete the loop, a plugin must be installed to handle the mime stream.  The plugin's task is to capture the data and store it for later processing.  (or maybe it's to actually do the processing itself, depends)

It may be necessary to use signed javascript for this component.  In this case, the impact should be minimal assuming the tools exist.  CCK customers should never need to customize this component since it really doesn't have any visible parts and should be very small.

Configure Profiles

Once the Milan conversation is complete, we have configuration data available.  Some information ends up in the connectoid, some ends up in the profile.  We need to separate them out and put them in the right places.  This entry point has typically been called with a bulk list of name=value pairs to be processed.  It might be that we continue to do it that way, it might not...
Design of Internet Setup Wizard

General Considerations


See the Internet Setup UI Spec for more details on how the flow of Internet Setup is going to be laid out.  One aspect of the UI is that it must contain and support CCK Wizard customizable items.  These include a logo graphic, distributor name, and support phone number.  In all liklihood, each of these items will appear on every page.  In addition, some elements of the wizard have traditionally been controlled by the acctset.ini file.  This likely needs to continue... Figure out how to deal with acctset.ini

The underlying features of Internet Setup are provided by the latest revision of the dialup code that was first written way back before the stock symbol NSCP existed.  This code was most recently updated by Tim McClarren before he left the company.  We have had plenty of feedback from our customers about flaws in this code.  One goal of this effort will be to simplify and correct the code wherever possible.  To this end, the code structure will be made more modular.  Each of the components will exist in its own C file and will be independently testable by QA.

Each of the components of Internet Setup will be exposed from a DLL called as.dll.  The only thing that may change this is if there is a sensible way to have multiple DLLs that are shared between Communicator itself and the Internet Setup wizard.  For the moment, I'm assuming that a single DLL is sufficient. Figure out if 1 DLL is the right answer or not

Offline Account Creation

 
 

Flow of Internet Setup


Offline account creation consists of the following steps:

  1. Collect a bunch of machine configuration data (automatically or via wizard screens)
  2. Correct any correctable configuration problems
  3. Collect a bunch of user data and preferences via wizard screens
  4. Collect a bunch of ISP account data via wizard screens
  5. Create a profile
  6. Create a connectoid
  7. Dump information into the profile and the connectoid
  8. Launch Communicator into the new profile to get the user started browsing
Most of these steps center around data collection and manipulation.

Collect a bunch of machine configuration data (automatically or via wizard screens)

DUN is absolutely required for correct operation of a dialup client.  We do not and will not provide actual dialer technology with Communicator.  To this end, the installer has traditionally launched a helper app that will examine the state of the user's system and recommend launching the DUN installer if necessary.  In addition, Internet Setup has traditionally made the same checks and also attempted to launch the DUN installer.  The installer helper app is not addressed by this document, go here for more information.

DUN handling in Internet Setup will be implemented in as.dll function DialerSetup().  This checking is done differently between the Win95/Win98 and WinNT platforms.  These differences will be hidden below this entry point.  The main gist of it is that DUN is on the 9x platforms and RAS is on the NT platform.  [In addition to checking for RAS on NT, the code will ensure that the RASMON process is running or will launch it if it's not running. is this true? ]  This code will reside in dun.c in the source directory.  As a special case, on Win95 DialerSetup() will also check DNS and provide a warning if there are DNS addresses set in the networking adapter (because dialup doesn't work on Win95 if they have their own settings in there.)

The modem is also absolutely required for correct operation of a dialup client.  Once we've proven DUN is installed, the next step is to make sure a modem is installed and configured.  This is currently handled on the modem setup screen and there is a button to invoke the native modem setup dialogs.  This button will be connected to the as.dll function ModemSetup().  Other functions required by the modem page will be implemented in the as.dll and may have separate entry points. This is an area to be defined by future progress in the implementation.

It is my intention to leverage native dialogs rather than implement or preserve local implementations of any setup dialogs I can find in the OSs.

Correct any correctable configuration problems

See previous section.

Collect a bunch of user data and preferences via wizard screens

This is the easy part.  This consists of creating and testing a number of WizardMachine INI files to collect said data.  This data will later be used by other components to do their jobs.  All collected data goes into a global area and is provided to all component functions when called by the WizardMachine.  The following information needs to be collected from user input:
  • TBD
The following information needs to be discerned from the OS and presented to the user for choosing:
  • TBD

Collect a bunch of ISP account data via wizard screens

Most of the ISP data should be specified in the NCI files that were included in the installer by the ISP that customized this browser.  Anything that's missing needs to be collected from a single wizard screen.  The relevant data are:
  • TBD

Create a profile

This component will actually be implemented in Communicator itself.  Using the 4.5 base, we have implemented a -CreateProfile flag that can call the internal routines necessary to accomplish all Communicator handling for a new profile.  This piece will depend on the outcome of the current profile manager backend discussion, but there has to be some equivalent function even if the 4.5 profile manager is scrapped completely.

See below for how this will be invoked.

Create a connectoid

Creating a connectoid is the one of the last steps of offline account creation.  In online account creation, it can happen multiple times.  This function will be implemented in as.dll as DialerConfig().  This function will rely extensively on the WizardMachine globals API to access values collected by the wizard screens that pertain to the connectoid required.

Populate a connectoid info goes here

Dump information into the profile and the connectoid

See previous section for connectoid information.

Although the act of creating a profile will be implemented in the Communicator, we still need a way to have the Internet Setup wizard invoke Communicator to create the profile.  Since profile creation and population are a single logical step to the wizard, it makes sense to have a single action do both jobs.  Therefore, the as.dll will have an entry point called CreateProfile() that will know how to launch Communicator with the right parameters to create a profile.  CreateProfile() will then do whatever is necessary to populate that profile with information from the wizard globals.

The following information needs to be collected and stored in the globals for profile creation:

  • TBD
Internet Setup needs to set preferences that describe the account just created.  The following preferences are modified by the 4.5 Internet Setup (and mostly need analogous coverage in 5.0):
  • browser.enable_style_sheets
  • browser.mac.show_tool_tips
  • browser.mac.use_internet_config
  • browser.startup.homepage (Milan only)
  • browser.startup.page
  • editor.author
  • editor.publish_browse_location
  • editor.publish_location
  • editor.publish_password
  • editor.publish_save_password
  • editor.publish_username
  • general.always_load_images
  • ldap_1.directoryN.description
  • ldap_1.directoryN.dirType
  • ldap_1.directoryN.filename
  • ldap_1.directoryN.isOffline
  • ldap_1.directoryN.isSecure
  • ldap_1.directoryN.port
  • ldap_1.directoryN.savePassword
  • ldap_1.directoryN.searchBase
  • ldap_1.directoryN.searchString
  • ldap_1.directoryN.serverName
  • ldap_1.number_of_directories
  • mail.check_new_mail
  • mail.identity.organization
  • mail.identity.reply_to (Milan only)
  • mail.identity.useremail
  • mail.identity.username
  • mail.imap.server_sub_directory (Milan only)
  • mail.leave_on_server
  • mail.pop_name
  • mail.pop_password
  • mail.remember_password
  • mail.server_type
  • network.cookie.warnAboutCookies
  • network.hosts.nntp_server
  • network.hosts.pop_server
  • network.hosts.smtp_server
  • network.online
  • offline.startup_mode
  • security.warn_entering_secure
  • security.warn_leaving_secure
  • security.warn_submit_insecure


Here are the details of how that information gets populated into a profile:
Populate a profile info goes here

Launch Communicator into the new profile to get the user started browsing

This is the last step in offline account creation.  Launching the user into the Communicator using their new connectoid closes the loop between installing and surfing.  In the past, we would simply tell people to launch Communicator themselves by finding and clicking on the desktop icon.  Unfortunately, we didn't bother to describe the icon to them and its a very tenuous connection.  There is no reason to avoid launching communicator at the end of Internet Setup in this new design, so we will do so.

In the preceding section, I described how launching an application is a necessary feature.  It is possible that the WizardMachine will expose an entry point to launch applications.  If so, it would be used to implement this.  If not, the application launcher used for CreateProfile() will be reused.
 

Online Account Creation

Online account creation is much more complex than offline account creation.  In addition to many of the tasks from offline, online must also handle the following:
  1. Dial the account creation server's modem
  2. Launch Communicator into a Milan conversation with some account creation server
  3. Catch the ISP account configuration information returned from the account server
  4. Use that information in place of the offline data collection wizard screens to create a connectoid and profile

Dial the account creation server's modem

Dialing the modem is pretty straightforward after all the other steps of configuration are done.  This component will be implemented inside as.dll as the DialModem() entry point.  It will need to be told which connectoid to use, so either some kludgy thing with the globals must be done, or the WizardMachine needs an enhancement to pass non-standard parameters to some DLL functions. Figure out how to pass connectoid parameter to DialModem()

Launch Communicator into a Milan conversation with some account creation server

Launching Communicator has been mentioned several times previously.  Whatever is done for those instances will also be used here.  The one new thing is that a particular URL needs to be targeted.

The URL that gets loaded will be a page that is created by Internet Setup that contains all the information required by this particular instance of the Milan protocol.  It is probable that some form of template can be used to create this form.  That needs to be worked out yet. Figure out how to create the Milan launch page

The page must also be able to instantiate the mime stream plugins and submit itself to the server URL.  These pieces should basically be carried over from the 4.x implementation of Internet Setup.  It may be necessary to sign this page, this is a minor issue since there are no distributor customizations that would be necessary on this page.

This component will be implemented in as.dll as the MilanLaunch() entry point.

Catch the ISP account configuration information returned from the account server

This component is responsible for catching the mime stream from the Milan server and converting it into a new connectoid and profile.  It is possible to leverage some of the 4.x javascript/plugin stuff to make this work with the minimal investment of coding time.  The main drawback is that this would guarantee the need for signing of the Milan launch page.  A further complication is that this page may not be running in the context of the ultimate profile we want to create for the end user.  (In other words, we may need to create a temporary profile just for the Milan session and then create a new profile for the user data.) Figure out how the profile gets populated after Milan

The work of converting Milan information into a connectoid could equally easily be done by the plugin or by the wizard.  However, depending on the preceding profile decision, it may be substantially easier to populate the profile either in the plugin or in the wizard.  If the Milan profile actually is the final profile, then doing this in Communicator may be much easier than in the wizard.  Conversely, if the profiles are different then it's impossible to do it in Communicator.  To avoid the dogfood problems, this will be implemented in the wizard unless that has a terribly high cost.

OK, so all that smog clears up at some point and then there's an entry point in as.dll called MilanConfigure() that knows how to find the info saved by the plugin and turn it into a valid connectoid and profile.  By implication, there is a plugin the knows how to save that info.  The MilanConfigure() routine may be able to leverage the WizardMachine's globals handling routines to simplify this process. Be sure to find out

Use that information in place of the offline data collection wizard screens to create a connectoid and profile

See the above discussions.  If profile creation is done in a different way for online, then we have to not do it the same way as offline.  They can share underlying routines, but the data sources and flows are all different.  One way to unify them is to have the wizard always do the work.  This is the route that I'm aiming for first.

Combined Offline/Online Account Creation

We are not currently contemplating creating this.  This is the way the previous versions of Internet Setup worked, so we need to validate whether it's required by our market.  If it becomes required, minor adjustments to the UI will be required but no new basic components will be needed.


Internet Setup Manifest

TBD.  This requires information that is not yet available.



Coding for Testing
As with the other projects within CCK, this project is broken into a number of independent components.  Each component will be designed and built in a modular fashion.  This project will provide a command line interface such that each component can be easily exercised by automated tests.  The interfaces required will be negotiated between the development and QA engineer(s) assigned to each component.

In general, any entry point in the as.dll should have a corresponding command line to exercise it.

All code will be reviewed by at least two developers other than the author before being considered complete.  Similarly, all test cases must pass.

List of independently testable components and command lines to exercise them:

  • TB filled in


i18n issues
It is always important for us to develop our application in such way that it can be easily localized. Currently, we are discussing with i18n group in identifying the areas that need to be focussed in making localization an easy task with respect to the the new design proposed above.


Open Issues
 
  1. Identify any new WizardMachine dependencies
  2. DUN detection is not adequate in the existing code
  3. Need to create muc.htm document
  4. MUC and other core Communicator dependencies are not scoped or committed
  5. Need to create UI spec
  6. Need to decide if there will be more than one DLL for both AS and C5
  7. Need to create helper.htm document
  8. Need to determine all dependencies from the modem page in the UI
  9. Need to explicitly list the information collected by the wizard in several places in this document
  10. Need to determine the communication requirements and mechanism for online account creation
  11. Determine whether the WizardMachine globals API can be used for the online account creation communication mechanism
  12. Need to figure out what the Milan launch page looks like and how it works
  13. profiles may not exist or may work radically differently in 5.0 versus 4.5
  14. The exact mechanism for putting information into a profile may need serious research
  15. Determine whether the WizardMachine needs to expose more advanced parameter passing for entry points
  16. Review the bugs that have been found in the code this was all based on and figure out what to do with them
  17. Review the enhancement requests for AS and decide what to do with them
  18. Deal with acctset.ini
  19. Deal with dial 1 and dial area code vs 10-digit dialing
Author : Steve Elmer
Date :    1/14/99