Path: news.weeg.uiowa.edu!news.uiowa.edu!uunet!wupost!waikato.ac.nz!comp.vuw.ac.nz!actrix.gen.nz!dempson
Newsgroups: comp.sys.apple2.programmer
Subject: Re: MessageCenter
Message-ID: <1993Jul11.131330.4950@actrix.gen.nz>
From: dempson@swell.actrix.gen.nz (David Empson)
Date: Sun, 11 Jul 1993 13:13:30 GMT
Sender: dempson@actrix.gen.nz (David Empson)
References: <1993Jul10.220740.134@pro-palmtree.socal.com>
Organization: Actrix Information Exchange
Lines: 131

In article <1993Jul10.220740.134@pro-palmtree.socal.com> bkogawa@pro-palmtree.socal.com (Bryan Ogawa) writes:
> Hm...I've been reading about this in David Empson's message, and from my
> understanding of how the Finder works, this is the way that documents are
> opened by application programs when they (the documents) are double-clicked
> by the finder. Could anyone explain either:
> (a) Where to get information of getting and receiving messagecenter
> messages?

The MessageCenter tool call is documented in Toolbox Reference Volume
2, in the Tool Locator chapter (page 24-14).

There is also further information in Toolbox Reference Volume 3, on
the "MessageByName" call (page 51-13), with further notes in IIgs
Technical note #89 (MessageByName--Catchy Messages).

Programmer's Reference for System 6.0 documents an additional message
type (page 232) for passing full GS/OS pathnames to a program, and a
new call (GetMsgHandle) to get the actual handle of a message (instead
of a copy of the message)


You can imagine the message centre as a big mail box: any program can
leave a message, with an ID number or name attached to it, and another
program (or the same program) can ask for a message by number or name
and be given the contents of the message.

The original call (MessageCenter) is available in all versions of IIgs
system software (back to about System 2.0).  You can perform three
operations: add a message, get a message, or delete a message.

The parameters are as follows:

| previous contents |
|-------------------|
|      action       |  Word: 1 = add, 2 = get, 3 = delete
|-------------------|
|       type        |  Word: message ID number
|-------------------|
|                   |
|-  messageHandle  -|  Long: handle to message
|                   |
|-------------------|


Message types are defined by the system software.  You can't pick any
old number and decide to put a message of that type in there.  If you
want to leave a message for your own software, use the MessageByName
call (which I won't cover here, because it is not used for passing
files from Finder).  It is only available in System 5.0 and later.

All messages have the following header:

MessNext     LONG      Handle of next message
MessType     WORD      Type of this message
MessDate     variable  Message-specific data

When you want to add a message, you set up your message in a handle
(with the first six bytes of your handle unused), then make the 'add'
call.  You can discard the handle after calling 'add' - MessageCenter
takes a copy of your handle.

To get a message, allocate a new handle (unlocked, not fixed, not
purgeable) of any size, make the 'get' call, and your handle will be
changed to contain the appropriate message.

For the delete call, the messageHandle parameter is not used.


Message type $0001 is used by Finder (and other programs) to pass an
application a list of files to open or print.

The data is organised as follows:

MessNext     LONG
MessType     WORD
Action       BYTE        0 = open files, 1 = print files
File1        STR 'full pathname 1'
File2        STR 'full pathname 2'
             ...
             BYTE 0      End marker

Each of the 'str' entries is a "pascal" string (leading length byte).
There may be no strings in the message (first length byte is zero).


System 6 defines an additional message type, which passes the
pathnames as GS/OS strings rather than Pascal strings.  The message
type is $0011.  The contents are the same as type $0001, except the
'action' field is a word instead of a byte, each of the 'str' entries
is a GS/OS input string (length word), and the end marker is a zero
word.  If you delete message type $0001, then message type $0011 is
also deleted.


The normal way to use the MessageCenter to get files from Finder is as
follows (in C pseudo-code):

    Handle msgHand;
    Pointer msgPtr;

    msgHand = NewHandle(0L, myID, 0x0000, 0L);  /* Empty handle */
    /* check for error */
    MessageCenter(getMessage, 0x0001, msgHand);
    if (_toolErr)
        /* message wasn't found, or out of memory - no files to load */
    else
        MessageCenter(deleteMessage, 0x0001, NULL);
    HLock(myMessage);
    msgPtr = *msgHand;
    /* do something with the list of files in the handle */
    DisposeHandle(msgHand);

Note: you should check the 'action' byte - if the user choses the
Print command from the File menu in Finder, then the application is
launched with the selected files in the message handle.  You should
immediately open and print these files.

If your application only supports one file, take the first one in the
list and ignore the rest.


If you want to support the GS/OS paths message, then change the code
to try a getMessage on type 0x0011.  If that fails, try 0x0001.  If
either case succeeds, delete type 0x0001.

You may wish to allocate the message handle using the 'no special
memory' attribute, but no other attributes should be used.
-- 
David Empson                                                               
dempson@swell.actrix.gen.nz                                                
Snail mail: P.O. Box 27-103, Wellington, New Zealand