Inside Macintosh: Cyberdog Programmer's Kit / Part 3 - Cyberdog Reference

Chapter 7 - Classes and Methods

CyberItem

Superclasses

ODRefCntObject --> ODObject

Subclasses

none

An object of the CyberItem class is a portable reference to data located on a network.

Description

A Cyberdog item is a reference to a remote location. Usually, a Cyberdog item refers to remotely located data. However, a Cyberdog item may simply describe a location; for example, an e-mail address is represented using a Cyberdog item. A Cyberdog item does not store actual data. Instead, it stores enough information about the location and network protocol of the data so that it can be retrieved when it is needed.

The CyberItem class is an abstract superclass that you can subclass and implement to reference data using a particular network protocol. The subclass encapsulates the specifics of addressing data using that protocol.

The type of Cyberdog item used in a particular situation depends on the location of the data you want to access, not the type of the data. For example, Cyberdog uses an FTPItem object (FTPItem is an implemented subclass of CyberItem supplied with Cyberdog) to reference data stored on an FTP server, whether the data is text, image, or audio. Cyberdog includes Cyberdog item subclasses to support common services, such as HTTP, Gopher, and FTP. You can use any of the existing Cyberdog item subclasses or create a new subclass to support a new service.

A CyberItem subclass usually has a companion CyberStream subclass (page 379). A Cyberdog stream downloads the data referenced by a Cyberdog item. For example, a WebItem object references data located on an HTTP server. A companion WebStream object interacts with the HTTP server to download the data.

A Cyberdog item is resolved if it can identify the kind of data to which it refers. When a Cyberdog item is opened, if it is resolved, the item creates a display part appropriate for displaying the type of data that the Cyberdog item references. Usually, the Cyberdog display part calls the Cyberdog item's CreateCyberStream method to retrieve a stream object initialized to download the Cyberdog item's data. The display part interacts with the stream object to download and display the data.

Some types of Cyberdog items (HTTP items, for example), do not inherently know the kind of data they refer to. Such Cyberdog items must override and implement the Resolve method to initiate whatever action is necessary to resolve the Cyberdog item.

Cyberdog items are not changeable. Once a Cyberdog item has been initialized, you should not change its attributes.

Cyberdog items are persistent and can be stored in storage units. If you are developing a Cyberdog item, you should store your Cyberdog items as kind kCyberItemKind.

There are two methods for storing a Cyberdog item in a storage unit. ExternalizeContent writes a Cyberdog item to a storage unit in multiple representations, in decreasing order of fidelity. You call this method to store a Cyberdog item for data interchange operations such as drag and drop.

StreamToStorageUnit flattens a Cyberdog item in the format shown in Table 7-1, writes it to a data buffer and then writes the buffer to a storage unit. You can use StreamToStorageUnit to store Cyberdog items that will not be used for data interchange. For example, a notebook calls StreamToStorageUnit to store its Cyberdog items.

You read Cyberdog items stored using either ExternalizeContent or StreamToStorageUnit by calling the CyberSession::CreateCyberItemFromSU method.

Table 7-1 Format of a flattened Cyberdog item (continued)

Length	Data item
4 bytes	The total length of flattened item, including length
2 bytes	The Cyberdog item signature (kCyberItemSignature)
2 bytes	The Cyberdog item version (kCyberItemVersionNum)
4 bytes	The length of the class ID
n bytes	The class ID
2 bytes	The script code for the display name
4 bytes	The length of the display name
n bytes	The display name
4 bytes	The length of the URL
n bytes	The URL
4 bytes	The length of private data required for this class
n bytes	The private data

Gopher and FTP Cyberdog items are capable of accessing data located on a proxy server. When a Gopher or FTP Cyberdog item is opened, it checks the user's preferences to see whether proxy server access is enabled. If so, the Cyberdog item calls CyberSession::CreateProxyItemFromURL (page 358) to create a proxy Cyberdog item capable of connecting to and accessing data through a proxy server.

Methods

This section presents summary descriptions of the Cybertem methods grouped according to purpose, followed by detailed descriptions.

Initialization and Cleanup

ICyberItem

Initializes this Cyberdog item.

SetUpFromURL

Initializes this Cyberdog item from a URL.

Opening Cyberdog Items

CreateCyberStream

Retrieves a Cyberdog stream that can be used to download the data referenced by this Cyberdog item.

Open

Initiates the opening of this Cyberdog item.

Testing and Resolving Cyberdog Items

Compare

Compares this Cyberdog item with another Cyberdog item for equality.

IsDownloadable

Tests whether the data referenced by this Cyberdog item is a file that can be downloaded.

IsResolved

Tests whether this Cyberdog item is resolved.

IsSecure

Tests whether this Cyberdog item references a secure site.

Resolve

Attempts to resolve this Cyberdog item.

Accessing Cyberdog Item Information

GetContentKind

Retrieves the part kind of the data referenced by this Cyberdog item.

GetFileInfo

Retrieves the file creator and file type of the data referenced by this Cyberdog item.

GetFlags

Retrieves flags for this Cyberdog item.

GetIconSuite

Retrieves an icon suite for this Cyberdog item.

GetStringProperty

Retrieves a string property for this Cyberdog item.

GetURL

Retrieves this Cyberdog item's URL.

SetDefaultName

Sets the default display name for this Cyberdog item.

Displaying Cyberdog Item Information

ShowInfoPart

Displays the Item Info window for this Cyberdog item.

ShowSecurityInfo

Displays the Security Info window for this Cyberdog item.

Copying and Storing Cyberdog Items

Clone

Returns a copy of this Cyberdog item.

ExternalizeContent

Writes this Cyberdog item to storage in multiple representations.

Flatten

Flattens this Cyberdog item and writes it to a buffer.

GetFlatSize

Retrieves the length of this Cyberdog item's flattened representation.

StreamToStorageUnit

Writes this Cyberdog item to a storage unit.

Unflatten

Reads this Cyberdog item from a buffer.

---

Methods

Clone

Compare

CreateCyberStream

ExternalizeContent

Flatten

GetContentKind

GetFileInfo

GetFlags

GetFlatSize

GetIconSuite

GetStringProperty

GetURL

ICyberItem

IsDownloadable

IsResolved

IsSecure

Open

Resolve

SetDefaultName

SetUpFromURL

ShowInfoPart

ShowSecurityInfo

StreamToStorageUnit

Unflatten