Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 2 - Edition Manager / Subscribing to Non-Edition Files

Calling an Edition Opener

You use the CallEditionOpenerProc function to call an edition opener. Since the Edition Manager is a package that may move, a real pointer cannot be safely returned for the standard opener and I/O routines. The system opener and the
I/O routines are returned as a value that is not a valid address to a procedure. The CallEditionOpenerProc and CallFormatIOProc functions check for these values and call the system openers.

You should never assume that a value for a system opener is a fixed constant.

err := CallEditionOpenerProc (selector, PB, routine);

Set the selector parameter to one of the edition opener verbs. The edition opener verbs include

• eoCanSubscribe
• eoOpen
• eoClose
• eoOpenNew
• eoCloseNew

The PB parameter of the CallEditionOpenerProc function is an edition opener parameter block.

TYPE EditionOpenerParamBlock = 
   RECORD
      info:          EditionInfoRecord;   {edition container to }
                                          { be subscribed to}
      sectionH:      SectionHandle;       {publisher or }
                                          { subscriber }
                                          { requesting open}
      document:      FSSpecPtr;           {document passed}
      fdCreator:     OSType;              {Finder creator type}
      ioRefNum:      LongInt;             {reference number}
      ioProc:        FormatIOProcPtr;     {routine to read }
                                          { formats}
      success:       Boolean;             {reading or writing }
                                          { was successful}
      formatsMask:   SignedByte;          {formats required to }
                                          { subscribe}
   END;

The routine parameter of the CallEditionOpenerProc function is a pointer to an edition opener function.

The following list shows which fields of the edition opener parameter block are used by the edition opener verbs:

Opener verb		Field	Description	Called by
eoCanSubscribe	-->	info	Edition container to subscribe to.	NewSubscriberDialogfunction for a subscriber
	-->	formatsMask	Formats required to subscribe.
	<--	Return value	A noErr code indicates that an edition container can be subscribed to. A noTypeErr code indicates that an edition container cannot be subscribed to.
eoOpen	-->	info	Edition container to open for reading.	OpenEdition and GetStandardFormats functions for a subscriber
	-->	sectionH	Subscriber section requesting open or NIL.
	<--	ioRefNum	Reference number for use by I/O routine. Not the same as EditionRefNum.
	<--	ioProc	I/O routine to call to read formats.
	<--	Return value	A noErr code or appropriate error code.
eoClose	-->	info	Edition container to be closed for reading.	CloseEdition and GetStandardFormats functions for a subscriber
	-->	sectionH	Subscriber section requesting close or NIL.
	-->	ioRefNum	Value returned by eoOpen.
	-->	ioProc	Value returned by eoOpen.
	-->	success	Success value passed to the CloseEdition function.
	<--	Return value	A noErr code or appropriate error code.
eoOpenNew	-->	info	Edition container to open for writing.	OpenNewEdition function for a publisher
	-->	sectionH	Publisher section requesting open or NIL.
	-->	document	Document pointer passed into the OpenNewEdition function.
	-->	fdCreator	The fdCreator passed into the OpenNewEdition function.
	<--	ioRefNum	Reference number for use by I/O routine. Not the same as EditionRefNum.
	<--	ioProc	I/O routine to call to write formats.
	<--	Return value	A noErr code or appropriate error code.
eoCloseNew	-->	info	Edition container to be closed after writing.	CloseEdition function for a publisher
	-->	sectionH	Publisher section requesting close or NIL.
	-->	ioRefNum	Value returned by eoOpenNew.
	-->	ioProc	Value returned by eoOpenNew.
	-->	success	Success value passed to the CloseEdition function.
	<--	Return value	A noErr code or appropriate error code.

As Listing 2-9 demonstrates, you install your own edition opener function by first saving the current opener and then installing your own opener. The listing also shows an edition opener, the MyEditionOpener function. When it receives the eoCanSubscribe opener verb, the MyEditionOpener function calls another application-defined routine, MyCanSubscribe. The Edition Manager sends your edition opener this verb to help it build the list of files displayed by the NewSubscriber function. The MyCanSubscribe function returns noErr if it can subscribe to the file; otherwise, it calls the original edition opener to handle the request.

Listing 2-9 Using your own edition opener function

VAR
   gOriginalOpener: EditionOpenerProcPtr;{global variable}

PROCEDURE MyInstallMyOpener;
BEGIN
   FailOSErr(GetEditionOpenerProc(gOriginalOpener));
   FailOSErr(SetEditionOpenerProc(@MyEditionOpener));
END; {MyInstallMyOpener}

FUNCTION MyEditionOpener (selector: EditionOpenerVerb; 
                          VAR PB: EditionOpenerParamBlock) 
                           : OSErr; 
BEGIN
   WITH PB DO
   BEGIN
      CASE selector OF
         eoCanSubscribe:
            MyEditionOpener := MyCanSubscribe(PB);
         eoOpen:
            MyEditionOpener := MyEditionOpen(PB);
         eoClose:
            MyEditionOpener := MyEditionClose(PB);
         OTHERWISE
            {call the original edition opener}
            MyEditionOpener 
               := CallEditionOpenerProc(selector, PB,
                                       gOriginalOpener);
      END; {of CASE}
   END; {of WITH}
END; {MyEditionOpener}

FUNCTION MyCanSubscribe (VAR PB: EditionOpenerParamBlock): OSErr;
BEGIN
   {check file type to see if it is a file you can emulate as an }
   { edition}
   IF PB.info.fdType = {for example}'PICT' THEN
      MyCanSubscribe := noErr
   ELSE {otherwise, let the saved edition opener decide}
         MyCanSubscribe := CallEditionOpenerProc(eoCanSubscribe,
                                             PB, gOriginalOpener);
END; {MyCanSubscribe}