Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Interapplication Communication /: Chapter 2 - Edition Manager / Using the Edition Manager

Reading and Writing a Section
Your application writes publisher data to an edition. New publisher data replaces the previous contents of the edition, making the previous edition information irretrievable. Your application reads data from an edition for each subscriber within a document.
The following sections describe how to

use different formats to write to or read from an edition
open an edition to initiate writing or reading
set a format mark
write to or read from an edition
close an edition after successfully writing or reading data

Formats in an Edition
You can write data to an edition in several different formats. These formats are the same as scrap format types. Scrap format types are indicated by a four-character tag.
Typically, when a user copies data, you identify the scrap format types and then write the data to the scrap. With the Edition Manager, when a user decides to publish data, you identify the format types and then write the data to an edition. You can write multiple formats of the same data.
For an edition, you should write your preferred formats first. In general, to write data to an edition, your application should use either 'TEXT' format or 'PICT' format. This allows your application to share data with most other applications. To subscribe to an edition, your application should be able to read both 'TEXT' and 'PICT' files. In addition, your application can write any other private formats that you want to support.
Scrap format types are described in the chapter "Scrap Manager" in Inside Macintosh: More Macintosh Toolbox.
A few special formats are defined as constants.
CONST kPublisherDocAliasFormat   = 'alis';{alias record from the }
                                          { edition to publisher}
      kPreviewFormat             = 'prvw';{'PICT' thumbnail }
                                          { sketch}
      kFormatListFormat          = 'fmts';{lists all available }
                                          { formats}
The kPublisherDocAliasFormat ('alis') format is written by the Edition Manager. It is an alias record from the edition to the publisher's document. Appended to the end of the alias is the section ID of the publisher, which the Edition Manager uses to distinguish between multiple publishers to a single edition. You should discourage users from making multiple copies of the same publisher. See "Duplicating Publishers and Subscribers" on page 2-58 for detailed information.
In addition to writing a publisher's data to an edition in the 'TEXT' format or 'PICT' format, your application can also write data to an edition in the kPreviewFormat ('prvw') format. If you provide a 'prvw' format in an edition, the Edition Manager uses it to display a preview of the edition data in the preview area of the subscriber dialog box. The 'prvw' format has the same format as a 'PICT' file. To draw a preview in the 'prvw' format, the Edition Manager calls DrawPicture with a rectangle of 120 by 120 pixels. (See Inside Macintosh: Imaging for more information about DrawPicture.) Your application should provide data in a 'prvw' format so that the data displays well in a rectangle of this size. Your application can also use this preview to display subscriber data within a document (to save space).
If your application does not provide a preview in the 'prvw' format for an edition, the Edition Manager attempts to provide a preview by using the edition's 'PICT' format. To draw a preview in the 'PICT' format, the Edition Manager examines the picture's bounding rectangle and calls DrawPicture with a rectangle that scales the picture proportionally and centers it in a 120-by-12-pixel area.
The kFormatListFormat ('fmts') format is a virtual format that is read but never written. It is a list of all the formats and their lengths. Applications can use this format in place of the EditionHasFormat function (described in "Choosing Which Edition Format to Read" on page 2-41), which provides a procedural interface to determine which formats are available.
If your application can read two or more of the available formats, use 'fmts' to determine the priority of these formats for a particular edition. The order of 'fmts' reflects the order in which the formats were written.
The FormatsAvailable data type defines a record for the 'fmts' format.
TYPE FormatsAvailable = ARRAY[0..0] OF
   RECORD
      theType:    FormatType;    {format type for an edition}
      theLength:  LongInt;       {length of edition format }
                                 { type}
   END;
For example, an edition container may have a format type 'TEXT' of length 100, and a format type 'styl' of length 32. A subscriber to this edition can open it and then read the format type 'fmts' to list all available formats. In this example, it returns 16 bytes: 'TEXT' $00000064 'styl' $00000020.

Opening an Edition
For a publisher, use the OpenNewEdition function to initiate the writing of data to an edition. (Note that the edition container must already exist before you initiate writing; see "Creating the Edition Container" beginning on page 2-32.)
err := OpenNewEdition(publisherSectionH, fdCreator,
                      publisherSectionDocument, refNum);
The publisherSectionH parameter is the publisher section that you are writing to the edition. The fdCreator parameter is the Finder creator type of the new edition. (The edition container file already has a creator type; you can specify the same creator type or establish a new creator type for the edition.)
The publisherSectionDocument parameter specifies the document that contains the publisher. This parameter is used to create an alias from the edition to the publisher's document. If you pass NIL for publisherSectionDocument, an alias is not made in the edition file. The refNum parameter returns the reference number for the edition.
For a subscriber, use the OpenEdition function to initiate the reading of data from
an edition.
err := OpenEdition(subscriberSectionH, refNum);
The subscriberSectionH parameter is a handle to the section record for a given section. The refNum parameter returns the reference number for the edition.
The user may rename or move the edition in the Finder. Before writing to or reading data from an edition, the Edition Manager verifies the name of the edition. This process is referred to as synching or synchronization. Synching ensures that the Edition Manager's existing edition names correspond to the Finder's existing edition names by updating the control block.

Format Marks
Each format has its own mark. The mark indicates the next position of a read or write operation. Initially, a mark automatically defaults to 0. After reading or writing data, the format mark is set past the last position written to or read from. The mark is similar to the File Manager's current read or write position marker for a data fork. Any time that an edition is open (after calling the OpenEdition or the OpenNewEdition function), any of the marks for each format can be queried or set.
To set the current mark for a section format to a new location, use the SetEditionFormatMark function.
err := SetEditionFormatMark(whichEdition, whichFormat,
                            setMarkTo);
To get the current mark for a format in an edition file, use the GetEditionFormatMark function.
err := GetEditionFormatMark(whichEdition, whichFormat,
                            currentMark);
Reading and Writing Edition Data
The Edition Manager allows you to read or write data a few bytes at a time (as with a data fork of a Macintosh file) instead of in one block (as with the Scrap Manager). You can read sequentially by setting the mark to 0 and repeatedly calling read, or you can jump to a specific offset by setting the mark there. The Edition Manager also adds the capability to stream multiple formats by keeping a separate mark for each format. This allows you to write a few bytes of one format and then write a few bytes of another format, and so forth.
Once you have opened the edition container for a particular publisher, you can begin writing data to the edition. Use the WriteEdition function to write publisher data to an edition.
err := WriteEdition(whichEdition, whichFormat, buffPtr, buffLen);
The WriteEdition function writes the specified format (beginning at the current mark for that format type) from the buffer pointed to by the buffPtr parameter up to buffLen bytes.
After you open the edition container for a subscriber and determine which formats to read, use the ReadEdition function to read edition data.
err := ReadEdition(whichEdition, whichFormat, buffPtr, buffLen);
The ReadEdition function reads the data with the specified format (whichFormat) from the edition into the buffer. The ReadEdition function begins reading at the current mark for that format and continues to read up to buffLen bytes. The actual number of bytes read is returned in the buffLen parameter. Once the buffLen parameter returns a value smaller than the value you have specified, there is no additional data to read, and the ReadEdition function returns a noErr result code.

Note
The Translation Manager (if it is available) attempts implicit translation under certain circumstances. For instance, it does so when your application attempts to read from an edition a format type that is not in the edition. In this case, the Translation Manager attempts to translate the data into the requested format. For more information, see the chapter "Translation Manager" in Inside Macintosh: More Macintosh Toolbox.

Closing an Edition
When you are done writing to or reading data from an edition, call the CloseEdition function.
err := CloseEdition(whichEdition, successful);
Each time a user edits a publisher within a document, you must update the modification date in the section record (even if the data is not yet written). When the update mode is set to Manually, the user can compare the modification dates for a publisher and its edition in the publisher options dialog box. One modification date indicates when the publisher last wrote data to the edition, and the other modification date indicates when the publisher section was last edited.
If the successful parameter for a publisher is TRUE, the CloseEdition function makes the newly written data available to subscribers and sets the modification date in the mdDate field of the edition to correspond to the modification date of the publisher's section record. If the two dates differ, the Edition Manager sends a Section Read event to all current subscribers.
If the successful parameter for a subscriber is TRUE, the CloseEdition function sets the modification date of the subscriber's section record to correspond to the modification date of the edition.
If you cannot successfully read from or write data to an edition, set the successful parameter to FALSE. For a publisher, data is not written to the edition, but it should still be saved with the document that contains the section. When the document is next saved, data can then be written to the edition. See "Closing an Edition After Reading or Writing" on page 2-88 for additional information on the CloseEdition function.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.