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

Chapter 7 - Classes and Methods

CyberStream

Superclasses

ODObject

Subclasses

none

An object of class CyberStream downloads the data referenced by a CyberItem object.

Description

The CyberStream class is an abstract class that you can subclass and implement to provide downloading support for a particular service. A stream object interacts with a server to download the data referenced by a Cyberdog item, given its location. A Cyberdog display part uses a stream object to download the data referenced by its Cyberdog item.

Cyberdog provides implemented CyberStream subclasses for some common protocols: HTTP, Gopher, and FTP. You can use any of these existing CyberStream subclasses or create a new CyberStream subclass to support a new network protocol.

A stream subclass usually has a companion Cyberdog item subclass that references data on that type of server. For example, an object of the WebItem class (an implemented CyberItem subclass supplied with Cyberdog) references data located on a web (HTTP) server. An object of the companion WebStream class (an implemented CyberStream subclass supplied with Cyberdog) interacts with the web server to download the data.

If a stream is to be used to download the data referenced by a Cyberdog item, the Cyberdog item is responsible for creating a stream. A Cyberdog display part calls the CyberItem::CreateCyberStream method to create a new stream object initialized to download the data referenced by the Cyberdog item. The Cyberdog item performs any initialization necessary to communicate the address of its resources to the stream object.

When a Cyberdog display part is ready to download the data referenced by its Cyberdog item, it calls the stream's Open method, which always returns immediately; however, a stream object may download data either asynchronously or synchronously. In either case, the display part checks the status of the download operation periodically by calling the GetStreamStatus method, which returns a set of flags indicating the current status.

A stream object allocates memory buffers to hold incoming data. If the stream has data (if the kCDDataAvailable flag is set to true), the display part can call the stream's GetBuffer method to retrieve a buffer. This scheme minimizes the repeated copying of data during the download process and allows the stream to proceed with the download operation instead of waiting for the first call to GetBuffer. When it has finished using a buffer, the display part should call the ReleaseBuffer method to return the buffer to the stream object.

There is no Close method in the stream interface; when the stream object detects that the download operation is complete (when the kCDDownloadComplete flag is set to true), it closes the connection on its own.

GetStreamStatus, GetBuffer, and ReleaseBuffer are all synchronous methods; they return immediately no matter whether the stream object is downloading asynchronously or synchronously. For this reason, a stream object should not postpone the reading of data until the display part calls the GetBuffer method. The stream should read the data on its own time and set the kCDDataAvailable flag to true when data has been read successfully. A simple stream implementation might read data until its buffers are full when Open is called, and then whenever ReleaseBuffer is called.

A simple stream implementation might also keep the kCDBuffersAreLow flag set to true at all times. To proceed with asynchronous downloading, the stream object needs memory to store the incoming data. To maximize stream performance, make sure that the stream always has memory available to store data as it comes in.

Methods

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

Controlling a Stream

Open

Opens this Cyberdog stream and initiates the downloading process.

Abort

Terminates a download operation being performed by this Cyberdog stream.

Managing Buffers

GetBuffer

Retrieves a buffer from this Cyberdog stream.

ReleaseBuffer

Releases a buffer to this Cyberdog stream.

Retrieving Stream Information

GetLastModTime

Retrieves the last modification time for the data in this Cyberdog stream.

GetStatusString

Retrieves a string describing the current status of this Cyberdog stream.

GetStreamError

Retrieves the first nontrivial error encountered by this Cyberdog stream.

GetStreamStatus

Retrieves the current status flags for this Cyberdog stream.

GetTotalDataSize

Retrieves the total size, in bytes, of the data available to be downloaded by this Cyberdog stream.

IsLastModTimeAvailable

Tests whether the last modification time is available for data in this Cyberdog stream.

IsTotalDataSizeAvailable

Tests whether the total size of this Cyberdog stream is available.

---

Methods

Abort

GetBuffer

GetLastModTime

GetStatusString

GetStreamError

GetStreamStatus

GetTotalDataSize

IsLastModTimeAvailable

IsTotalDataSizeAvailable

Open

ReleaseBuffer