Subwoofer

Engineering Specifications

Last Modified: 1/23/1997

 

You may incorporate this sample code into your applications without restriction, though the sample code has been provided "AS IS" and the responsibility for its operation is 100% yours. However, what you are not permitted to do is to redistribute the source as "DSC Sample Code" after having made changes. If you're going to re-distribute the source, we require that you make it clear in the source that the code was descended from Apple Sample Code, but that you've made changes.


Table of Content

Introduction

Engineering Feature Set

Architecture

Implementation

Considerations, Risks, Assumptions

Design


Introduction (top of page)

Subwoofer is a project to provide high-level Internet APIs to developers. Specifically, an API like the Cyberdog CyberStreams API which let's a client download data from the Internet. With this API, all applications can become Internet-enabled with just a few additional calls.

Future versions will allow data to be uploaded to the Internet and will also provide lower-level access to protocol specific calls.


Engineering Feature Set (top of page)

The API will allow data to be downloaded directly to a file (the simple API) or downloaded with more control by the client to a place of their choice (the stream API). The source will be specified by a URL in both cases. Other capabilities include aborting the process, finding out status, and getting information about the data being downloaded.

Protocol Support (top of page)

Subwoofer will provide access to HTTP, FTP, and HFS through the URL schemes "http://", "ftp://", and "file://". The file URLs are provided to allow one code path for local vs. remote data.

Extensibility to other schemes is possible through a plug-in architecture.

Security and Firewalls (top of page)

Support for SSL, Cern Proxies, and SOCKS firewalls will be provided. SSL will be used when the "https://" scheme is recognized. In the future, a mechanism for registering a scheme as SSL-capable may be added. Proxies and SOCKS will be used if the Internet Config preference indicates that they should be.

Protocol Specific Issues (top of page)

FTP will support both passive and active connections. Any authentication will be handled by the Subwoofer API with the option for the client to provide the dialog.

Post-processing Issues (top of page)

When using the stream API the data will be delivered to the user in close to it's raw format. Exceptions include end-of-line translation and removal of protocol specific information.

When using the simple API, as much post-processing as possible will be done automatically. Subwoofer will include direct support for de-binhexing data and will use Internet Config to post-process beyond that unless the client flags indicate not to.

A mechanism for plugging in filters for post-processing the data may be included in future versions.


Addressing Product Criteria (top of page)

How to Meet Hardware Compatibility Requirements (top of page)

The API will run on both 68K and PowerPC using the Code Fragment Manager. Any restrictions will be imposed by CFM-68K.

How to Meet Software Compatibility Requirements (top of page)

The API will be OpenTransport native (where OT is needed).

The API will be a C API and will not require the installation of SOM or OpenDoc. Pascal headers will also be provided.

The API will run on all systems capable of running CFM.

The model used for API design is QuickTime. Progress, Status and Authenticate procs can be specified by the client if desired or the client can indicate to use the built-in progress and authenticate. The APIs will use Pascal calling conventions.

Installation Requirements (top of page)

Subwoofer will be provided as a single shared library. Installation is therfore not required. The user will just drag the shared library to the System Folder.

On the development system, headers will also be required, but will not be installed.

How to Meet Performance Targets (top of page)

Subwoofer will be as fast or faster than the existing Cyberdog implementation. The goal will be to download a file from HTTP and FTP as fast or faster than competing products.

RAM Footprint (top of page)

Footprint is currently unknown, but should be very small. Goal will be to keep it under 500K for the first release. Optimization may be possible for a subsequent release (since the current code base is Cyberdog).

Disk Footprint (top of page)

Small.

Physical Size (top of page)

Small

Internationalization/Localization Requirements (top of page)

The human interface is limited to a progress window, a username/password dialog, and status strings. All strings will be in resources to allow localization.


Architecture (top of page)

Overview (top of page)

This section documents the architecture of Subwoofer. The goal of the architecture is to use the existing Cyberdog code base and make it available to non-cyberdog applications.

Architecture Description (top of page)

Subwoofer will be a layer added underneath the Cyberdog CyberStreams layer. The current CyberStream code will be moved within Subwoofer. A universal CyberStream will be provided to access Subwoofer from Cyberdog.

Subwoofer will also use Internet Config to access necessary preferences. The APIs will map to the CyberStreams API wherever possible.

Additional scheme implementations will be possible using a plug-in architecture described in the next section.

Subwoofer Architecture

Plug-in Architecture (top of page)

A plug-in mechanism is provided to allow extensibility to other schemes.

Each module is provided as a shared library in the Shared Library Folder of the System folder. Its implementation is similar to the CyberStream implementation so that migration is simple. The only difference is that the Subwoofer module stream class does not inheret from ODObject.

When attempting to resolve a URL, Subwoofer will probe each module (starting by the internal ones) to find one that supports the specified scheme.


Implementation (top of page)

Integration Strategy (top of page)

The integration strategy in the short term mainly concerns Cyberdog. The goal will be to maintain one source base and modify existing Cyberdog code if necessary. If changes required become unwieldy, the integration process will be aborted.

Standards, Building Codes, and Guidelines (top of page)

The Architecture Review Board is being consulted to assure we meet required standards and guidelines. In addition, all protocols will be implemented to Internet standards.

Software Configuration and Code Management (top of page)

Source control system used is Projector. All other configuration and code management will be done by SCM.

Feature Control and Bug Review Process (top of page)

The feature set for this project will be subject to review by developers and may change accordingly. Several mailing lists and DTS will be used to gather this feedback with strict time limits imposed.

Any details not described in the design document (top of page)

N/A

Languages (top of page)

All code will be written in C++ with some C and Pascal interfaces. Metrowerks CodeWarrior will be the primary compiler with possible optimization done with MrC.

External Dependencies (top of page)

Major dependencies include:

Source Base (top of page)

Cyberdog 1.1 will be the source base for Subwoofer stream modules.

Build System/Environment (top of page)

The build environment will be Metrowerks CodeWarrior along with MPW for projector access.

Build strategy (top of page)

Given the projected short life-cycle, there will be only one alpha and one beta build. These builds will be distributed to developer's via the Internet.


Considerations, Risks, Assumptions (top of page)

Tradeoff Decisions (top of page)

We decided to use CFM due to the existing Cyberdog implementation and for extensibility.

Alternative Designs (top of page)

Feature Limitations (top of page)

Known Design and Implementation Limitations and Risks (top of page)

There are no known design or implemenation limitations or risks at this time.

OEM Impact and Considerations (top of page)

N/A. Currently there are no OEM's involved.

Performance (top of page)

The current expectation is that downloads will be as fast or faster than Cyberdog 1.1 downloads.

Ideas For Improvements (top of page)


Design (top of page)

API (top of page)

See Subwoofer APIs for a detailed description of the Subwoofer design.

Asynchronous vs Synchronous (top of page)

All (except one) calls of Subwoofer will be asynchronous. This means that they return immediately after being called. To get completion of the call, the client application needs to provide a stream status callback routine to the URLReferenceDownload or URLOpen routines.

The URLDownload call is synchronous. It will return only at completion of the download.