BroadCast 0.5b3 =============== Copyright 1988 Joachim Lindenberg, University of Karlsruhe, Federal Republic of Germany. All rights reserved. BroadCast is a copyrighted procuct. Permission is granted to everybody not envolved in military projects to use it freely at no charge, as long as it is not repackaged or sold. BroadCast may not be used within other products without prior express permission in writing by University of Karlsruhe. Our licensing terms require you to grant a site license of your product at no charge to University of Karlsruhe, Joachim Lindenberg, Fakultaet fuer Informatik Postfach 6980, 7500 Karlsruhe 1 Federal Republic of Germany [ Include standard disclaimers - you know that it may habe bugs. Mail bug reports and/or other stuff to joachim@ira.uka.de. ] MenuIcons ========= BroadCast supports sending/receiving of any icon. Note that the icon is actually transmitted via the network. There is no need for the receiver to know the icons in advance. The 6 icons currently included are BroadCast itself and the icons LaserWriter, AppleShare, Disk, Phone and Bomb which are stolen from Apple files. You may change BroadCast to include more/other icons as well. The following defines the structure of the MenuRecord used by the icon menu defintion function, which may be translated to a equivalent resource definition easily: type IconMenuInfo = RECORD menuId: INTEGER; menuWidth: INTEGER; menuHeight: INTEGER; menuProc: Handle; enableFlags: LONGINT; filler : integer; {Jmakes ResEdit happy } height, width : integer; icon : array [0..99] of integer; { resource ids of icons } END; Warning: Don't open the MENU resource without holding down the option key. ResEdit doesn't know the structure given above. Instead it assumes a standard text menu definition. The filler is only good to stop ResEdit from displaying garbage. All icons should be numbered in the range -4096 through -4065. The icon with id -4096 is the default icon used by the receiver. Note that the icon is optional to a message. The CAP version of BroadCast does not support (at least at the time being) receiving of icons. Specification of BroadCast 0.5b3 ================================ The following notes describe the interface and some aspects of the implementation of BroadCast 0.5b3. Namebinding =========== Any node with Broadcast enabled registers itself as ChooserName:BroadCast:* - or whatever typestring is defined in STR -4096. If disabled, the type string of STR -4096 will be prefixed by the string Prefix (declaration.i) which consists of a -, thus the name will not be visible to the lookup of BroadCast (I tested differentiating through use of uppercase/lowercase characters, but NBP lookup turned out not to be casesensitive). Any program (e.g. mailserver) may choose to send broadcasts to both enabled and disabled BroadCast clients, depending upon its needs. The disabling feature just stops other BroadCast clients from sending. (BroadCast verifies that STR -4096 does not start with the Prefix character, thus the simplest approach to send messages to disabled clients is impossible) Sending Messages ================ After looking up an entity by name, an ATPSendRequest is used to send the actual message. The message that is sent by the ATPSendRequest must contain the following data - userData set to zero. other values might indicate future expansions. - requestPtr pointing to the following record record messagetext : str255; { required } messageicon : Icon; { optionally } end; - The name of the sender (choosername) is delimited by Delimiter (option-dash, ascii 0xD1) The receiver searches for the last occurence of this character in the message text. - The string may be transmitted either by declared size (256 bytes) or by actual size (length + 1 bytes). The message may be : 256 - if just the message text is transmitted using the declared size length + 1 - if the message text is transmitted using the actual size 384 - if message + icon are transmitted using declared sizes length + 129 - if message text and icon are transmitted packed. Message Response ================ The receiver will return the message by an ATPResponse. The response message is the time (local to the receiver) the message was received on. Userbytes are returned zeroed. There is no user feedback upon success/fail of a message sent. This might be changed in a future version. BroadCast does sort of 'best effort delivery'. The message will be saved until a new one arrives, no queuing is done. Action ====== The action depends upon the message received. If the actual length of the message text is zero AND shutdown is enabled, the Macintosh will be shutdown upon completion of Repsonse, otherwise messages of length zero are ignored. This feature is used in our Macintosh lab to shutdown all macintoshs at end of opening time. If the message is not empty, a dialog will be put up at one of the next calls to SystemTask. The delay between two calls of the driver control routine by SystemTask has been set to 30 ticks (half a second) to minimize overhead. Note that if more than one message arrives within a short peroid of time, only the last one will be saved. Interface Declaration ===================== { Copyright 1988 Joachim Lindenberg, University of Karlsruhe, Federal Republic of Germany. All rights reserved. } { Interface declarations for the Macintosh version. March 27th, 1988} { Declaration of the globals used by driver/chooser device. The device control entry in the unittable contains in the storage field a handle to the NetRecs record. The master pointer is actually located in the driver code segment because it must be accessed at interrupt time. Note that you might use BroadCast as notification manager by storing a message in the record and setting the correct flags. Note however that any incoming message will superseede your message. Note also, that messages arrive at interrupt time. } const ResId = -4096; Release = '05b3'; { current release } Prefix = '-'; { standard - } Delimiter = 'Q'; { option - $D1 } type Icon = array [0..31] of longint; IconPtr = ^Icon; IconHandle = ^IconPtr; ByteArray = packed array [0..1] of Byte; BytePtr = ^ByteArray; CharArray = packed array [0..1] of Char; CharPtr = ^CharArray; ByteHandle = ^BytePtr; CharHandle = ^CharPtr; IntPtr = ^Integer; IntHandle = ^IntPtr; MessageRec = record mText : str255; mIcon : Icon; end; NetRecs = record version : OSType; { used to check version of chooser against the version of the driver. this is inited to release during initialization. } messageenabled, { messages turned on, see note below } shutdownenabled, { does an empty message cause shutdown ? } domessage, { a message has arrived } includesicon : boolean; { did it include an icon ? } nbpType : str32; { NBP type, 'BroadCast', prefixed by Prefix if disabled. NOTE: you must change both messageenabled and nbpType during enable/ disable operations. } { all of the following fields are used by the driver only } nbpNTE : NamesTableEntry; request, response : ATPParamBlock; bds : BdsElement; Time : longint; Socket : integer; message : MessageRec; { the last message received } { note : the following handles are obtained from resources on startup. all of them are detached because the resource file is closed after that } broadcastdlog : Handle; { the dialog definition ... } broadcastditl : Handle; { ... and its item list } broadcasticon : Handle; { the default icon } end; NetPtr = ^NetRecs; NetHandle = ^NetPtr; { end of Declaration }