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.
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.
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.
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.
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.
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.
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.
The API will run on both 68K and PowerPC using the Code Fragment Manager. Any restrictions will be imposed by CFM-68K.
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.
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.
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.
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).
Small.
Small
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.
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.
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.
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.
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.
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.
Source control system used is Projector. All other configuration and code management will be done by SCM.
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.
N/A
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.
Major dependencies include:
Cyberdog 1.1 will be the source base for Subwoofer stream modules.
The build environment will be Metrowerks CodeWarrior along with MPW for projector access.
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.
We decided to use CFM due to the existing Cyberdog implementation and for extensibility.
There are no known design or implemenation limitations or risks at this time.
N/A. Currently there are no OEM's involved.
The current expectation is that downloads will be as fast or faster than Cyberdog 1.1 downloads.
See Subwoofer APIs for a detailed description of the Subwoofer design.
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.