home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / mac / misc / document / broadcas.txt < prev    next >
Text File  |  1992-11-05  |  8KB  |  212 lines
  1. BroadCast 0.5b3
  2. ===============
  3.  
  4. Copyright 1988 Joachim Lindenberg, University of Karlsruhe,
  5. Federal Republic of Germany. All rights reserved.
  6.  
  7. BroadCast is a copyrighted procuct. Permission is granted to
  8. everybody not envolved in military projects to use it freely
  9. at no charge, as long as it is not repackaged or sold.
  10.  
  11. BroadCast may not be used within other products without
  12. prior express permission in writing by University of Karlsruhe.
  13. Our licensing terms require you to grant a site license of your
  14. product at no charge to 
  15.  
  16.     University of Karlsruhe,
  17.     Joachim Lindenberg, Fakultaet fuer Informatik
  18.     Postfach 6980, 7500 Karlsruhe 1
  19.     Federal Republic of Germany
  20.  
  21. [ Include standard disclaimers - you know that it may habe bugs.
  22.   Mail bug reports and/or other stuff to joachim@ira.uka.de. ]
  23.  
  24.  
  25.  
  26.  
  27. MenuIcons
  28. =========
  29.  
  30. BroadCast supports sending/receiving of any icon. Note that the icon
  31. is actually transmitted via the network. There is no need for the
  32. receiver to know the icons in advance.
  33.  
  34. The 6 icons currently included are BroadCast itself and the icons  
  35. LaserWriter, AppleShare, Disk, Phone and Bomb which are stolen from
  36. Apple files.
  37.  
  38. You may change BroadCast to include more/other icons as well. The
  39. following defines the structure of the MenuRecord used by the
  40. icon menu defintion function, which may be translated to a equivalent
  41. resource definition easily:
  42.  
  43. type     IconMenuInfo = RECORD
  44.          menuId: INTEGER;
  45.          menuWidth: INTEGER;
  46.          menuHeight: INTEGER;
  47.          menuProc: Handle;
  48.          enableFlags: LONGINT;
  49.          filler : integer; {Jmakes ResEdit happy }
  50.          height, width : integer;
  51.          icon : array [0..99] of integer; { resource ids of icons } 
  52.     END;
  53.  
  54. Warning: Don't open the MENU resource without holding down the option
  55. key. ResEdit doesn't know the structure given above. Instead it assumes
  56. a standard text menu definition. The filler is only good to stop ResEdit
  57. from displaying garbage.
  58.  
  59. All icons should be numbered in the range -4096 through -4065. The icon
  60. with id -4096 is the default icon used by the receiver.
  61.  
  62. Note that the icon is optional to a message. The CAP version of BroadCast
  63. does not support (at least at the time being) receiving of icons.
  64.  
  65.  
  66.  
  67. Specification of BroadCast 0.5b3
  68. ================================
  69.  
  70. The following notes describe the interface and some aspects of the
  71. implementation of BroadCast 0.5b3.
  72.  
  73.  
  74. Namebinding
  75. ===========
  76.  
  77. Any node with Broadcast enabled registers itself as ChooserName:BroadCast:*
  78. - or whatever typestring is defined in STR -4096. If disabled, the type
  79. string of STR -4096 will be prefixed by the string Prefix (declaration.i)
  80. which consists of a -, thus the name will not be visible to the lookup of
  81. BroadCast (I tested differentiating through use of uppercase/lowercase
  82. characters, but NBP lookup turned out not to be casesensitive). Any program
  83. (e.g. mailserver) may choose to send broadcasts to both enabled and disabled
  84. BroadCast clients, depending upon its needs. The disabling feature just
  85. stops other BroadCast clients from sending. (BroadCast verifies that STR -4096
  86. does not start with the Prefix character, thus the simplest approach to
  87. send messages to disabled clients is impossible)
  88.  
  89.  
  90. Sending Messages
  91. ================
  92.  
  93. After looking up an entity by name, an ATPSendRequest is used to send the
  94. actual message. 
  95.  
  96. The message that is sent by the ATPSendRequest must contain the following data
  97. - userData set to zero. other values might indicate future expansions.
  98. - requestPtr pointing to the following record
  99.     record
  100.       messagetext : str255;  { required }
  101.       messageicon : Icon;    { optionally }
  102.     end;
  103.   - The name of the sender (choosername) is delimited by Delimiter 
  104.     (option-dash, ascii 0xD1) The receiver searches for the last occurence
  105.     of this character in the message text.
  106.   - The string may be transmitted either by declared size (256 bytes) or by
  107.     actual size (length + 1 bytes). The message may be :
  108.       256 - if just the message text is transmitted using the declared size
  109.       length + 1 - if the message text is transmitted using the actual size
  110.       384 - if message + icon are transmitted using declared sizes
  111.       length + 129 - if message text and icon are transmitted packed.
  112.       
  113.       
  114. Message Response
  115. ================
  116.  
  117. The receiver will return the message by an ATPResponse. The response message
  118. is the time (local to the receiver) the message was received on. Userbytes
  119. are returned zeroed.
  120.  
  121. There is no user feedback upon success/fail of a message sent. This might
  122. be changed in a future version. BroadCast does sort of 'best effort delivery'.
  123. The message will be saved until a new one arrives, no queuing is done.
  124.  
  125.  
  126. Action
  127. ======
  128.  
  129. The action depends upon the message received. If the actual length of the
  130. message text is zero AND shutdown is enabled, the Macintosh will be shutdown
  131. upon completion of Repsonse, otherwise messages of length zero are ignored.
  132. This feature is used in our Macintosh lab to shutdown all macintoshs at end
  133. of opening time.
  134.  
  135. If the message is not empty, a dialog will be put up at one of the next calls
  136. to SystemTask. The delay between two calls of the driver control routine by 
  137. SystemTask has been set to 30 ticks (half a second) to minimize overhead.
  138.  
  139. Note that if more than one message arrives within a short peroid of time, 
  140. only the last one will be saved.
  141.  
  142.  
  143. Interface Declaration
  144. =====================
  145.  
  146.  
  147. { Copyright 1988 Joachim Lindenberg, University of Karlsruhe, 
  148.                  Federal Republic of Germany. All rights reserved. }
  149.                  
  150. { Interface declarations for the Macintosh version. March 27th, 1988}
  151.  
  152. { Declaration of the globals used by driver/chooser device. The device control 
  153.   entry in the unittable contains in the storage field a handle to the NetRecs 
  154.   record. The  master pointer is actually located in the driver code segment 
  155.   because it must be accessed at interrupt time. Note that you might use 
  156.   BroadCast as notification manager by storing a message in the record and
  157.   setting the correct flags. Note however that any incoming message will
  158.   superseede your message. Note also, that messages arrive at interrupt time. }
  159.  
  160. const 
  161.  
  162.     ResId     = -4096;
  163.  
  164.     Release   = '05b3';    { current release }
  165.     Prefix    = '-';       { standard -      }
  166.     Delimiter = 'Q';       { option - $D1    }
  167.       
  168. type    
  169.  
  170.     Icon = array [0..31] of longint; IconPtr = ^Icon; IconHandle = ^IconPtr;
  171.  
  172.     ByteArray = packed array [0..1] of Byte; BytePtr = ^ByteArray; 
  173.     CharArray = packed array [0..1] of Char; CharPtr = ^CharArray;
  174.     ByteHandle = ^BytePtr; CharHandle = ^CharPtr;
  175.     IntPtr = ^Integer; IntHandle = ^IntPtr;
  176.  
  177.     MessageRec = record mText : str255; mIcon : Icon; end;
  178.     
  179.     NetRecs = record
  180.         version : OSType;          { used to check version of chooser against
  181.                                      the version of the driver. this is inited
  182.                                      to release during initialization. }
  183.         messageenabled,            { messages turned on, see note below }
  184.         shutdownenabled,           { does an empty message cause shutdown ? }
  185.         domessage,                 { a message has arrived }
  186.         includesicon : boolean;    { did it include an icon ? }
  187.         
  188.         nbpType : str32;           { NBP type, 'BroadCast', prefixed by Prefix
  189.                                      if disabled. NOTE: you must change both
  190.                                      messageenabled and nbpType during enable/
  191.                                      disable operations. }
  192.  
  193. { all of the following fields are used by the driver only }
  194.  
  195.         nbpNTE : NamesTableEntry;                            
  196.         request, response : ATPParamBlock; bds : BdsElement;
  197.         Time : longint; Socket : integer;
  198.         
  199.         message : MessageRec;      { the last message received }
  200.         
  201. { note : the following handles are obtained from resources on startup. all
  202.   of them are detached because the resource file is closed after that }
  203.    
  204.         broadcastdlog : Handle;    { the dialog definition ... }
  205.         broadcastditl : Handle;    { ... and its item list }
  206.         broadcasticon : Handle;    { the default icon }
  207.     end;
  208.  
  209.     NetPtr = ^NetRecs; NetHandle = ^NetPtr;
  210.  
  211. { end of Declaration }
  212.