Cyberdog, the OpenDoc

Internet Components

The future of Internet surfing is OpenDoc

by Stephen Humphrey, VP Engineering, Acorde Corporation

Cyberdog is the code name for Apple Computer’s OpenDoc-based Internet components. This article provides a 10,000-foot view of the Cyberdog architecture and a cursory introduction to the most important parts of its API.

Cyberdog will include components which provide Web browsing, SMTP and POP mail, Usenet News, FTP, Gopher, and Telnet. These components provide the sort of functionality one expects from Internet apps today, plus strong mutual integration with one another, and with a universal log, which keeps a historical record of the user’s actions, and a notebook, which stores pointers to the user’s favorite places and people. For instance, Cyberdog’s integrated SMTP and POP mail system (see Figure 1) is fully MIME-capable; addresses may be stored in the notebook for easy access; and any CyberItem may be sent as an enclosure. The News reader shows the familiar display of newsgroups and messages (see Figure 2), and any icon can be dragged to the notebook. Cyberdog is designed to improve the Internet experience for MacOS users by closely integrating the various

Figure 1. A Mail window

Figure 2. The News reader

components with each other, with other applications, and with the desktop. Apple will encourage third-party developers to extend and replace the base Cyberdog components by fully documenting the Cyberdog API and architecture.

As I write this article, Apple plans to distribute a sneak preview of the shared libraries which make up Cyberdog on the OpenDoc Developer Release 4 CD [in this issue]; the end-user release of the Cyberdog components is currently scheduled for May 1996.

The Cyberdog components factor their Internet responsi-bilities into three major areas: Viewers, Services, and Context facilities. Viewers are responsible for displaying the myriad data types commonly found on the Net, like JPEG and HTML. Services manage the protocols used for transporting the data types. Context facilities hold the history of the user’s interaction and help the users keep track of their favorite sites, newsgroups, and mail addresses.

Viewers are OpenDoc Part Editors

One of the most exciting aspects of Cyberdog is its extensive use of OpenDoc. Cyberdog depends fully on the OpenDoc architecture for displaying and interacting with Net-borne data. In fact, every part of Cyberdog that has a user interface(UI) is implemented as an OpenDoc part. Even those components which do not have a UI are implemented as SOM objects, so again they behave similarly to OpenDoc components. This dependence on OpenDoc means that a Cyber-aware Viewer you write will automatically benefit from the strengths of the OpenDoc architecture. So, for example, if you write a Cyberdog-savvy Stock Ticker, your users will be able to display dynamically-updating information about their portfolios in any OpenDoc container.

Cyberdog viewers are first and foremost OpenDoc viewers. To show a data type in Cyberdog, you first implement an editor based on ODPart. All of a regular OpenDoc part’s methods are required, and the part editor uses the standard OpenDoc event, layout, and storage facilities. To add the functionality of Cyberdog, you add an extension to your editor which inherits from CyberPartExtension.

CyberPartExtension is a virtual class which provides the methods with which the other Cyberdog components will interact with your viewer. You will write an extension which inherits the base functionality of CyberPartExtension but which also knows about the particular details of interacting with your editor. So for example, if you have already written a JPEG display part using OpenDoc, you will write a CyberJPEGExtension which provides your part with the additional capabilities of retrieving the JPEG data from the Net instead of just from your OpenDoc StorageUnit. CyberPartExtension is a standard ODExtension, so you will provide your extension to Cyberdog via the standard ODPart::HasExtension() and ODPart::GetExtension() mechanisms. After your part is initialized but before you create your first display frame, Cyberdog will tell your editor to use a CyberService to retrieve its data.

CyberServices Encapsulate Internet Protocols

A CyberService is the base class which manages a single Internet protocol. The basic Cyberdog components include CyberService implementations for HTTP, FTP, Gopher, Telnet, and the local file system. Notice that CyberServices represent transport protocols and not data types, so there is an FTPService, not a JPEGService. A CyberService’s most important role is as a manager of a few other classes of objects which actually implement a full Internet protocol, particularly the CyberItem and the CyberStream.

A CyberItem represents the address of a piece of data on the Net. In its simplest form, it can be thought of as an objected-oriented wrapper for a URL. In practice, there is nothing to stop much more advanced capabilities in a CyberItem, such as complete database queries. CyberItems are portable; they can be saved in your StorageUnit and reinstantiated later. If you are implementing a viewer which can contain one or more links to outside data, such as an HTML viewer, you will save CyberItems in your StorageUnit as part of your own content model, retrieving them when necessary based on action from the user. CyberItems have no inherent UI, so they inherit from SOMObject instead of ODPart.

A simple example of a CyberItem’s behavior is shown by a CyberButton, a simple Cyber-savvy viewer which comes with Cyberdog. A CyberButton is an OpenDoc part which behaves as a button (surprise!); it can be displayed in any OpenDoc container, can display a title or a picture on its face, and can be clicked on by the user. Internally, a CyberButton holds one CyberItem. When the user clicks on the CyberButton, the button calls the CyberItem’s Open() method. This is a fire-and-forget call; the CyberButton is not responsible for any additional interaction with the CyberItem. The CyberItem is free to take any appropriate action, the most common of which is to open a viewer to display the data pointed to by the CyberItem.

As a Cyber-savvy viewer, you become interested when the SetCyberItem() method of your CyberPartExtension is called. This tells you that you are being opened because the user fired a CyberItem, and you are provided a reference to that CyberItem. Your most common action then will be to ask the CyberItem to create a CyberStream through which you will get the data to display; to do this, call the CyberItem’s CreateCyberStream() method, and it will return a CyberStream.

CyberStreams Provide Clean Data to Viewers

A CyberStream implements the actual passing of data from a protocol to a viewer. After receiving a CyberStream from a CyberItem, you will tell the CyberStream to either Open() or OpenWithCallback(). This call tells the CyberStream that it should immediately begin downloading the data. It is the CyberStream’s responsibility to begin retrieving the data asynchronously and to store it until you ask for it.

If you opened the CyberStream by calling Open(), you will poll it for data by calling its GetStreamStatus() method. The most interesting replies are kDataAvailable and kDownloadComplete. If you opened the CyberStream by calling its OpenWithCallback() method, then the CyberStream will notify you whenever data is available by calling the notification method you register.

Any time the CyberStream has data available, you can request a chunk of data from the stream with the call GetBuffer(). When you are finished processing the data, you must call ReleaseBuffer(). If you are using a callback method to notify you when data is available, you must remember that this notification may happen at interrupt time; you will not be able to allocate memory, draw to the screen, or perform any other action which is not interrupt-safe. However, it is okay to set an internal state which will get and process the data later, such as at idle time. The CyberStream may only have a limited number of buffers, so it is a good idea to release them as soon as you are able to. You will continue calling GetBuffer() and ReleaseBuffer() until the CyberStream reports it is finished downloading.

CyberStreams are responsible for parsing the data stream and removing any protocol-specific headers or similar data blocks in the stream. This has the advantage of providing the viewer with a consistent stream of data regardless of the data’s transfer protocol on the Net. So for example, your JPEGViewer need not care whether the CyberItem it receives is really a GopherItem, an FTPItem, or a FileItem; regardless of the protocol the user chose, the JPEG stream you receive will be the same.

One limitation of the method described above is that sometimes a CyberItem doesn’t know what kind of viewer it should open. For example, a WebItem cannot open an appropriate viewer until it knows the kind of data at which it is pointing, that is, until it parses the HTML and finds an appropriate data-type tag. In this case, the CyberItem will actually open the CyberStream and start it downloading even before the real viewer is opened. The CyberItem will also open a special OpenerPart that will display the download status until the real viewer can be determined and opened. However, as a viewer you will not know or care that the stream has already been opened; you will ask the CyberItem to create a CyberStream, ask the CyberStream to open, and begin polling as usual.

As of now, CyberStreams are designed primarily to pass data in one direction. This is decidedly unhelpful for some protocols which depend on more interactive communication between the viewer and the stream. For example, the telnet protocol cannot be implemented efficiently using CyberStreams. Thus, when a TelnetItem (a telnet CyberItem) asks a TelnetViewer to open, the TelnetViewer never requests a TelnetStream. Instead, it just fully implements the telnet protocol within the viewer by asking the TelnetItem for its connection information and creating the connection itself. Since no CyberConnection object exists, this means implementing these types of protocols is fairly tedious today. This is a great opportunity for either a future version of Cyberdog or for a smart third-party.

Context Facilities Tie the Parts Together

Cyberdog provides several built-in context facilities which unite the various components into a seamless Internet workspace. These include a common Connect dialog, a Preferences panel, the Log, and Notebooks. Each of these is managed through the single CyberSession object.

The CyberSession is responsible for the overall integration of the Cyberdog components. It is similar in purpose to the OpenDoc session object, ODSession, although it is different in the particular services it provides. There is at most one CyberSession for each ODSession. The CyberSession is the main facility through which Viewers will request various Cyberdog objects. It is also the facility through which standard OpenDoc containers will be able to add the Cyberdog menus to their menu bar. Among its responsibilities, the CyberSession checks the Cyberdog libraries folder to see which CyberServices are available. This is what allows the run-time addition of new services to Cyberdog’s repertoire.

CyberServices may provide a Connect panel. If provided, this part allows the Cyberdog Connect dialog to display protocol-specific fields for any service available to the user. In operation, the Connect dialog is reminiscent of the pre-System 7 Control Panel dialog, with scrolling icons on the left and individual panels on the right. Since the panels are implemented as regular OpenDoc parts, a service which implements a new protocol can easily provide a panel for the CyberSession to display to the user. Such a Connect panel is implemented by adding a CyberPanelExtension to a regular part subclassed from ODPart.

Similarly, any CyberService can provide a Preferences panel that the CyberSession will display in the Cyberdog Preferences Dialog. A Preferences panel, too, is implemented by adding a CyberPanelExtension to a regular part subclassed from ODPart. (This implementation of the Cyberdog dialog boxes provides one of the best non-document uses of OpenDoc to date; it validates OpenDoc as more than just a compound-document architecture.)

To provide an historical context for the user’s actions, Cyberdog provides a universal Log which tracks where the user has been on the Net. The user can show the log, display its items hierarchically, alphabetically, or historically, and return to places in it by simply clicking on the place’s icon (see Figure 3). A Viewer posts a new item on the log by providing a CyberItem (and optionally, its hierarchical parent) to the CyberSession’s AddCyberItemToLog() method.

Figure 3. The Log window

The user may also save one or more Cyberdog Notebooks (see Figure 4). These simple lists of CyberItems have a single-level folder system in which the user can organize favorite places and people. The user identifies a default notebook, and Viewers may add an item to this default notebook by simply telling the CyberSession to AddCyberItemToNotebook(). More typically, Viewers allow the user to drag CyberItems to a Notebook using the OpenDoc drag-and-drop facilities (so the user can drag e-mail addresses, newsgroups, Web sites, Gopher directories, and telnet connections right into a Notebook). Like other parts of Cyberdog, the Notebook is designed to implement the minimum functionality required by a beginning Internet user; it is ripe for replacement by an enterprising third-party.

Figure 4. The Notebook

Where To Go From Here

By the time you read this article, the Cyberdog components and SDK should be available on the OpenDoc DR4 CD. The SDK is quite preliminary, but should be sufficient to get started with developing for Cyberdog (especially if you’re not afraid to bleed a little). Various listservers have been established to facilitate Cyberdog discussion. Mail a message to cdog@apple.com with subject “DEV-INFO” for more information.

Apple has done a commendable job of designing Cyberdog. From its foundation, Cyberdog’s architecture permits and even encourages third-party developers to replace and extend it. Since it is still alpha-quality code, expect some pain. However, developers who learn to walk the ’dog now might discover opportunities and markets that will be harder to find later. If you start early, the ’dog will probably bite you occasionally; but once you’ve learned to handle it, you’ll be able to cuddle up close.