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