home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / top2src.zip / MESSAGES.TXT < prev    next >
Text File  |  1999-02-07  |  57KB  |  1,264 lines
  1. TOP v3.00wb1 Message Specifications - Revision B000
  2. ---------------------------------------------------
  3.  
  4.     This file describes how TOP sends messages between nodes.  This messaging
  5. system is probably the most important element of TOP.  It is not overly
  6. complex, but a thorough understanding of how it works is needed by anybody
  7. making modifications to TOP, writing add-ons like TOPLink, or writing external
  8. command programs (ECPs).
  9.  
  10.     The first part of this file gives a brief introduction to sending messages
  11. in TOP.  Anybody working with TOP should know how this is done.  The second
  12. part describes each message, including what it is used for, what data it
  13. requires, and how it is to be responded to.  It is intended as a reference
  14. guide.    The third and last part of this file describes the inner workings of
  15. the messaging system, from a technical standpoint.    You only need to
  16. familiarize yourself with this part if you are planning to change TOP's
  17. messaging system, develop third-party add-ons like TOPLink, or if you are
  18. simply curious.
  19.  
  20.     NOTE:  This file refers to a couple of other files which are not
  21. distributed as part of the TOP specifications in the ECPDK.  As a result, only
  22. those who have obtained the TOP source code will have these files.  Please
  23. contact me if you need information regarding any of the features described.
  24.  
  25.                         ================================
  26.                         1. Introduction to TOP Messaging
  27.                         ================================
  28.  
  29.     Messages are sent from one node to another using files.  In TOP, this is
  30. done via the dispatch_message() function.  This function fills the msg_typ
  31. structure that will be written to the message file (see section 3).  It also
  32. determines which nodes receive the message.
  33.  
  34.     The dispatch_message() Function
  35.     -------------------------------
  36.  
  37.     The dispatch_message() function takes five parameters.    The prototype for
  38. the dispatch_message() function is reproduced below:
  39.  
  40. void dispatch_message(XINT type, unsigned char *string, XINT tonode,
  41.                       XINT priv, XINT echo);
  42.  
  43.     The first three parameters correspond directly to fields in the msg_typ
  44. structure (type, string, and doneto respectively).    As such, they will not be
  45. discussed right now.  Instead, refer to the discussion of the msg_typ structure
  46. below.
  47.  
  48.     The last two parameters determine which node or nodes receive the message.
  49. They are both boolean flags that can be either TRUE or FALSE.  The priv
  50. parameter controls whether the message should be sent privately.  If it is
  51. TRUE, dispatch_message() will only send the message to the node specified in
  52. the tonode parameter.  Otherwise, TOP will send the message to all nodes
  53. currently using TOP.  The echo parameters simply controls whether or not the
  54. node sending the message should receive a copy of it.  Setting it to TRUE sends
  55. a copy of the message to the sending node.    Otherwise, TOP will skip the
  56. sending node when dispatching the message.
  57.  
  58.     In addition, a few global variables also correspond to fields in the
  59. msg_typ structure.    Global variables were used when data was added in later
  60. versions of TOP, because I did not wish to change a hundred-some odd calls to
  61. dispatch_message().  The global variables msgextradata, msgminsec, and
  62. msgmaxsec correspond to the data1, minsec, and maxsec fields of the msg_typ
  63. structure, respectively.  The msgsendglobal global variable is a flag affects
  64. the channel field of the msg_typ structure.  If the flag is TRUE, the message
  65. will be sent on channel 0 (globally).  Otherwise, the message will be sent on
  66. the user's current channel.
  67.  
  68.     For ECP programmers, the parameters of the SendType and SendGlobal keywords
  69. correspond to the parameters of the dispatch_message() function.  The global
  70. variables are not available, except for msgsendglobal which is turned on by
  71. using SendGlobal.
  72.  
  73.     The msg_typ Structure
  74.     ---------------------
  75.  
  76.     The msg_typ structure contains all of the data needed for one node of TOP
  77. to communicate with another.  Most of the data in the structure depends on
  78. relatively constant information such as the user's handle and the current
  79. channel the user is on.  Only a few fields change with each message, and as
  80. noted above the parameters to dispatch_message() and the msg... global
  81. variables are used to change these fields.
  82.  
  83.     For ECP programmers, these fields are filled either with data from the
  84. parameters of the Send... keywords, or by TOP itself for fixed fields like the
  85. from node number.
  86.  
  87.     Each field of the msg_typ structure is discussed in detail below.
  88.  
  89. unsigned XINT    structlength    This field simply contains the length of the
  90.                                 msg_typ structure (i.e. sizeof(msg_typ)) for
  91.                                 the version of TOP in use.    It is intended for
  92.                                 future compatibility and linking.  A version of
  93.                                 TOP can look at this field and see how long the
  94.                                 msg_typ structure is.  If it is different than
  95.                                 the known size, compensations could be made.
  96.                                 This field is filled in by dispatch_message()
  97.                                 but is not currently used anywhere in TOP.
  98.  
  99. XINT            type            The type of message being sent.  This should be
  100.                                 one of the MSG_ constants defined in TOPSTR.H
  101.                                 and described below.  It is set by the type
  102.                                 parameter of the dispatch_message() function.
  103.  
  104. XINT            from            The node that is sending the message.  Filled
  105.                                 in by dispatch_message().
  106.  
  107. XINT            doneto            The node the message is being "done to".  This
  108.                                 is essentially the receiving node for the
  109.                                 message.  However, it does not mean that this
  110.                                 is the only node that will receive the message.
  111.                                 The receiving nodes are controlled by the priv
  112.                                 and echo parameters of dispatch_message() and
  113.                                 are described above.  Many messages used by TOP
  114.                                 can be "done to" one node but still seen by all
  115.                                 nodes.    The effect of this field depends on the
  116.                                 message type.  Regardless of the message type,
  117.                                 this field is always set to the tonode
  118.                                 parameter of dispatch_message().  If the
  119.                                 message is not being "done to" any specific
  120.                                 node, this should be set to -1.
  121.  
  122. XINT            gender            The gender of the node sending the message.  It
  123.                                 is set to user.gender by dispatch_message().
  124.                                 TOP uses 0 for male and 1 for female in this
  125.                                 field.
  126.  
  127. unsigned char*    handle            The handle of the user on the node that is
  128.                                 sending the message.  It is set to user.handle
  129.                                 by dispatch_message().
  130.  
  131. unsigned char*    string            The main text data of the message.    The actual
  132.                                 content of this field varies wildly with each
  133.                                 message type.  It is usually the actual text to
  134.                                 be displayed on screen, or specific data being
  135.                                 changed (eg. a user's new handle).  It is set
  136.                                 by the string parameter of the
  137.                                 dispatch_message() function.
  138.  
  139. unsigned long    channel         The user's current channel.  It is set to the
  140.                                 curchannel global variable by
  141.                                 dispatch_message(), unless the global variable
  142.                                 msgsendglobal is TRUE, in which case it will be
  143.                                 set to 0 (the global channel).    See
  144.                                 CHANNELS.TXT for a description of the internal
  145.                                 channel numbers used by TOP.
  146.  
  147. unsigned XINT    minsec            The minimum security that can receive this
  148.                                 message.  This field is set by the msgminsec
  149.                                 global variable.  It is neither supported nor
  150.                                 used by TOP at this time, so if you wish to use
  151.                                 this field you will need to add code to
  152.                                 process_messages() to check this parameter.
  153.  
  154. unsigned XINT    maxsec            The maximum security that can receive this
  155.                                 message.  This field is set by the minmaxsec
  156.                                 global variable.  Again, it is not currently
  157.                                 supported by TOP.
  158.  
  159. long            data1            Type-specific numeric data.  The contents
  160.                                 depend entirely on the message type, and most
  161.                                 message types don't use extra data.  It is set
  162.                                 by the msgextradata global variable.
  163.  
  164.                               ====================
  165.                               2. TOP Message Types
  166.                               ====================
  167.  
  168.     This section lists each TOP message type and the data that is required in
  169. certain fields.  It should be used as a reference when adding or changing
  170. features.  This section is also particularly important to those wishing to
  171. develop ECPs.
  172.  
  173.     Each entry in the list shows the MSG_ constant, its numeric equivalent, and
  174. a brief description on the top line.  After this, there are short (one line)
  175. descriptions of what data belongs in the doneto, string, and data1 fields.  A
  176. detailed usage description follows.  Concluding the entry is a list of related
  177. or similar message types.
  178.  
  179.     Some message types are not used in TOP and are marked as "Reserved" in
  180. TOPSTR.H.  These message types _are_ documented below, as there is an expected
  181. behaviour that is associated with each of these message types.    Unused message
  182. types have a * beside their number in the listings below.  If you wish to use
  183. one of these message types, you must remember to implement processing code in
  184. the process_message() function, or the message will not work.  ECP programmers
  185. should ignore these message types unless they are programming for a newer or
  186. customized version of TOP that is known to use them.
  187.  
  188.     I realize some of the message types are redundant and could be combined
  189. using the data1 field as a distinguisher, but I have left them the way they
  190. are.  Many of the message types were created before the data1 field was
  191. implemented, and since the type field can handle 65536 types, there is no
  192. danger of a shortage.  Also, the use of very specific types keeps the already
  193. cluttered process_message() function a little more organized.
  194.  
  195.     User Defined Types
  196.     ------------------
  197.  
  198.     If you wish to add your own message types, please assign them negative
  199. numbers.  This will prevent them from conflicting with any future versions of
  200. TOP or external utilities.    Negative message numbers ranging from -32768 to -1
  201. are available, so there is no danger of running out.
  202.  
  203.     TOP itself will simply ignore all message types that it does not recognize.
  204.  
  205.     Message Type List
  206.     -----------------
  207.  
  208.     In the list below, the term "formatting" refers to the adding of prefix and
  209. suffix text and colour codes to the actual text to make the text suit the
  210. command.  For example, the whisper command shows the text using a prefix of
  211. "From BlindSpot (whispered): ".  Formatting is done by the node receiving the
  212. message, unless otherwise noted in the list below.
  213.  
  214.     The term "raw text" means that text should be passed on as entered by the
  215. user, without formatting and without filtering PubColour(TM) codes.  (However,
  216. the censor and trimming routines should be used before sending if their effects
  217. are desired.)
  218.  
  219.     Where a "null string" or "empty string" is referred to it means that the
  220. string should contain a single \0 (ASCII 0) character in the first byte,
  221. effectively meaning the string is empty of displayable text.  NEVER PASS THE
  222. VALUE NULL AS THE string PARAMETER WHEN CALLING dispatch_message()!
  223.  
  224.     NOTE:  There are some cases where parameters are not used by TOP when
  225. processing messages, even though the parameters are listed below as requiring
  226. data.  To prevent confusion I will not list any specific cases.  For safety,
  227. you should always pass the data listed below, even if you have discovered that
  228. TOP does not use it.  Remember that there may be external utilities (like
  229. TOPLink) that may expect the data to be there.
  230.  
  231. -------------------------------------------------------------------------------
  232. MSG_NULL            #0        Null or deleted message.
  233.  
  234. doneto    -    Unused.
  235. string    -    Unused.
  236. data1    -    Unused.
  237.  
  238.     This is a null (or "deleted") message that TOP will ignore completely.  It
  239. is not sent by TOP itself.    The intent of this message is to provide a means
  240. for external utilities to delete messages quickly and easily.  The technique
  241. for accomplishing this is beyond the scope of this list, however.  Please note
  242. that TOP does NOT delete messages by simply setting them to this type.    A
  243. discussion of how TOP deletes messages follows this list.
  244.  
  245. See Also:  None
  246. ------------------------------------------------------------------------------
  247. MSG_TEXT            #1        Regular chat text.
  248.  
  249. doneto    -    Unused.
  250. string    -    The raw text that will be displayed.
  251. data1    -    Unused.
  252.  
  253.     This message type is used for normal chat text.  Any text that is typed by
  254. the user that does not trigger a valid command and is not blocked by the censor
  255. will be sent using this message type.
  256.  
  257. See Also:  MSG_GENERIC (#35)
  258. -------------------------------------------------------------------------------
  259. MSG_ENTRY            #2        A user has entered TOP.
  260.  
  261. doneto    -    Unused.
  262. string    -    Raw text of user's custom entry message, or null to use default.
  263. data1    -    Unused.
  264.  
  265.     This message type is sent when a user enters TOP.  In addition to
  266. displaying the user's entry message, this message tells all receiving nodes
  267. to mark the sending node as "active" so that it can see the user immediately.
  268.  
  269.     Generally, you can just pass user.emessage as the string parameter.  If the
  270. user has a custom entry message it is stored there, otherwise user.emessage
  271. will be an empty string.  The receiving node will show the default entry
  272. message if an empty string is detected.
  273.  
  274. See Also:  MSG_EXIT (#3)
  275. -------------------------------------------------------------------------------
  276. MSG_EXIT            #3        A user has exited TOP via the QUIT command.
  277.  
  278. doneto    -    Unused.
  279. string    -    Raw text of user's custom exit message, or null to use default.
  280. data1    -    Unused.
  281.  
  282.     This message type is sent when a user leaves TOP using the QUIT command. In
  283. addition to displaying the user's exit message, this message tells all
  284. receiving nodes to mark the sending node as "inactive" so that it can no longer
  285. see the user.
  286.  
  287.     Generally, you can just pass user.xmessage as the string parameter.  If the
  288. user has a custom exit message it is stored there, otherwise user.xmessage will
  289. be an empty string.  The receiving node will show the default exit message if
  290. an empty string is detected.
  291.  
  292.     Please note that there are three other message types used to exit TOP under
  293. different circumstances:  MSG_TOSSOUT, MSG_TOSSED, and MSG_ZAPPED.    MSG_UNLINK
  294. is also used to exit TOP for linked systems.
  295.  
  296. See Also:  MSG_ENTRY (#2), MSG_TOSSOUT (#19), MSG_UNLINK (#24),
  297.            MSG_TOSSED (#26), MSG_ZAPPED (#27)
  298. -------------------------------------------------------------------------------
  299. MSG_INEDITOR        #4        A user has entered the Profile Editor.
  300.  
  301. doneto    -    Unused.
  302. string    -    Handle of the user entering the Profile Editor.
  303. data1    -    Unused.
  304.  
  305.     This message is sent to inform other users that a user has entered the
  306. Profile Editor.  It is sent mainly to inform other users, although TOP will
  307. cancel any private chat requests involving the sending node (both to and from)
  308. upon reception of this message.
  309.  
  310. See Also:  MSG_OUTEDITOR (#5)
  311. -------------------------------------------------------------------------------
  312. MSG_OUTEDITOR        #5        A user has returned from the Profile Editor.
  313.  
  314. doneto    -    Unused.
  315. string    -    Handle of the user leaving the Profile Editor.
  316. data1    -    Unused.
  317.  
  318.     This message is sent to inform other users that a user has returned the
  319. Profile Editor.  It is sent purely to inform other users.
  320.  
  321. See Also:  MSG_INEDITOR (#4)
  322. -------------------------------------------------------------------------------
  323. MSG_WHISPER         #6        Private message from one user to another.
  324.  
  325. doneto    -    Node that is to receive the whisper.
  326. string    -    Raw text containing the private message.
  327. data1    -    Unused.
  328.  
  329.     A whisper is a private message sent from one node to another.  As such,
  330. this message should always be sent to just one node (priv parameter = TRUE).
  331.  
  332. See Also:  MSG_TEXT (#1), MSG_DIRECTED (#39)
  333. -------------------------------------------------------------------------------
  334. MSG_GA                #7        Regular general action.
  335.  
  336. doneto    -    Unused.
  337. string    -    Raw general action text.
  338. data1    -    Unused.
  339.  
  340.     This message type sends a general action to other nodes.  The string
  341. parameter should only contain the actual text that makes up the general action.
  342. It should not contain the user's handle or any formatting; that is added by the
  343. receiving node.
  344.  
  345. See Also:  MSG_GA2 (#8)
  346. -------------------------------------------------------------------------------
  347. MSG_GA2             #8        Possessive general action.
  348.  
  349. doneto    -    Unused.
  350. string    -    Raw general action text.
  351. data1    -    Unused.
  352.  
  353.     This message type sends a possessive general action to other nodes.  A
  354. possessive general action is the same as a regular one, except it uses
  355. different language items to show a possessive case.  The string parameter
  356. should only contain the actual text that makes up the general action.  It
  357. should not contain the user's handle or any formatting; that is added by the
  358. receiving node.
  359.  
  360. See Also:  MSG_GA (#7)
  361. -------------------------------------------------------------------------------
  362. MSG_ACTIONSIN        #9        Singular action of type Normal.
  363.  
  364. doneto    -    Unused.
  365. string    -    Formatted action text including colour codes and names.
  366. data1    -    Unused.
  367.  
  368.     This message type is sent when the user types a Normal action verb without
  369. specifying a user name.  The string parameter should contain the completely
  370. formatted action text, except for % tokens which are processed by the
  371. receiving node.
  372.  
  373. See Also:  MSG_ACTIONPLU (#10), MSG_TLKTYPSIN (#11), MSG_TLKTYPPLU (#12),
  374.            MSG_ACTPLUSEC (#13)
  375. -------------------------------------------------------------------------------
  376. MSG_ACTIONPLU        #10     Plural action of type Normal.
  377.  
  378. doneto    -    Node which the action is being done to.
  379. string    -    Formatted action text including colour codes and names.
  380. data1    -    Unused.
  381.  
  382.     This message type is sent when the user types a Normal action verb with a
  383. user name.    All nodes on channel should receive this message, i.e. it is not
  384. private.  Use MSG_ACTPLUSEC for private (secret) actions.  The string parameter
  385. should contain the completely formatted action text, except for % tokens which
  386. are processed by the receiving node.
  387.  
  388. See Also:  MSG_ACTIONSIN (#9), MSG_TLKTYPSIN (#11), MSG_TLKTYPPLU (#12),
  389.            MSG_ACTPLUSEC (#13)
  390. -------------------------------------------------------------------------------
  391. MSG_TLKTYPSIN        #11     Singular action of type TalkType.
  392.  
  393. doneto    -    Unused.
  394. string    -    Formatted action text including colour codes and names.
  395. data1    -    Unused.
  396.  
  397.     This message type is sent when the user types a TalkType action verb
  398. without specifying additional text.  The string parameter should contain the
  399. completely formatted action text, except for % tokens which are processed by
  400. the receiving node.
  401.  
  402. See Also:  MSG_ACTIONSIN (#9), MSG_ACTIONPLU (#10), MSG_TLKTYPPLU (#12),
  403.            MSG_ACTPLUSEC (#13)
  404. -------------------------------------------------------------------------------
  405. MSG_TLKTYPPLU        #12     Plural action of type TalkType.
  406.  
  407. doneto    -    Unused.
  408. string    -    Formatted action text including colour codes and names.
  409. data1    -    Offset in string where user text begins.
  410.  
  411.     This message type is sent when the user types a TalkType action verb with
  412. additional text.  The string parameter should contain the completely formatted
  413. action text, except for % tokens which are processed by the receiving node.
  414. The data1 parameter is used to tell the receiving nodes when the action prefix
  415. ends and the text that the user typed begins, so TOP can stop processing %
  416. tokens at that point.  Processing % tokens in the user text can be dangerous to
  417. system integrity.
  418.  
  419. See Also:  MSG_ACTIONSIN (#9), MSG_ACTIONPLU (#10), MSG_TLKTYPSIN (#11),
  420.            MSG_ACTPLUSEC (#13)
  421. -------------------------------------------------------------------------------
  422. MSG_ACTPLUSEC        #13     Private plural action of type Normal.
  423.  
  424. doneto    -    Node which the action is being done to.
  425. string    -    Formatted action text including colour codes and names.
  426. data1    -    Unused.
  427.  
  428.     This message type is sent when the user types a Normal action verb with a
  429. user name and the /S (secret) suffix.  Only the node in the doneto field should
  430. receive this message.  Use MSG_ACTIONPLU for public actions.  The string
  431. parameter should contain the completely formatted action text, except for %
  432. tokens which are processed by the receiving node, and except for the
  433. "...secretly!" message which is added after processing.
  434.  
  435. See Also:  MSG_ACTIONSIN (#9), MSG_ACTIONPLU (#10), MSG_TLKTYPSIN (#11),
  436.            MSG_TLKTYPPLU (#12)
  437. -------------------------------------------------------------------------------
  438. MSG_HANDLECHG        #14     A user has changed his/her TOP handle.
  439.  
  440. doneto    -    Unused.
  441. string    -    The new handle for the user.
  442. data1    -    Unused.
  443.  
  444.     This message type is sent whenever a user changes their handle in TOP, by
  445. way of the profile editor or the CHANGE HANDLE command.  In addition to
  446. informing other users, this messages lets other nodes on the same channel
  447. update the online handles index immediately.
  448.  
  449. See Also:  MSG_BIOCHG (#15), MSG_SEXCHG (#16), MSG_ACTIONCHG (#17),
  450.            MSG_PERACTCHG (#18), MSG_EXMSGCHG (#25)
  451. -------------------------------------------------------------------------------
  452. MSG_BIOCHG            #15     A user has changed his/her biography.
  453.  
  454. doneto    -    Unused.
  455. string    -    Null string.
  456. data1    -    Unused.
  457.  
  458.     This message is sent whenever a user changes a biography response in the
  459. biography editor.  It is sent purely to inform other users.
  460.  
  461.     NOTE:  In versions of TOP prior to 2.00 (2.00g1 and all RAP versions), this
  462. message type was sent when a user changed their description.
  463.  
  464. See Also:  MSG_HANDLECHG (#14), MSG_SEXCHG (#16), MSG_ACTIONCHG (#17),
  465.            MSG_PERACTCHG (#18), MSG_EXMSGCHG (#25)
  466. -------------------------------------------------------------------------------
  467. MSG_SEXCHG            #16     A user has changed his/her gender.
  468.  
  469. doneto    -    Unused.
  470. string    -    Raw text of the new gender.
  471. data1    -    Unused.
  472.  
  473.     This message is sent when a user changes their gender in the profile editor
  474. or using the CHANGE SEX command.  It is sent solely to inform other users.
  475.  
  476. See Also:  MSG_HANDLECHG (#14), MSG_BIOCHG (#15), MSG_ACTIONCHG (#17),
  477.            MSG_PERACTCHG (#18), MSG_EXMSGCHG (#25)
  478. -------------------------------------------------------------------------------
  479. MSG_ACTIONCHG        #17*    A user has changed an action list.
  480.  
  481. doneto    -    Unused.
  482. string    -    Null string.
  483. data1    -    Unused.
  484.  
  485.     This message is intended for use with an online action editor.    When the
  486. editor is used, it would send this message globally to all nodes.  Upon
  487. reception, a node should free and then reload all actions (using loadactions()
  488. should work fine).    The user should also be told of the change.
  489.  
  490. See Also:  MSG_HANDLECHG (#14), MSG_BIOCHG (#15), MSG_SEXCHG (#16),
  491.            MSG_PERACTCHG (#18), MSG_EXMSGCHG (#25)
  492. -------------------------------------------------------------------------------
  493. MSG_PERACTCHG        #18     A user has changed a personal action.
  494.  
  495. doneto    -    Unused.
  496. string    -    Null string.
  497. data1    -    Unused.
  498.  
  499.     This message is sent whenever a user changes a personal action in the
  500. profile editor.  It is sent purely to inform other users.
  501.  
  502. See Also:  MSG_HANDLECHG (#14), MSG_BIOCHG (#15), MSG_SEXCHG (#16),
  503.            MSG_ACTIONCHG (#17), MSG_EXMSGCHG (#25)
  504. -------------------------------------------------------------------------------
  505. MSG_TOSSOUT         #19     A user has abruptly left the pub.
  506.  
  507. doneto    -    Unused.
  508. string    -    Null string.
  509. data1    -    Unused.
  510.  
  511.     This message is sent whenever a user abruptly leaves TOP.  There are
  512. various reasons that this can occur.  The most common reasons are those listed
  513. in TOP.DOC for errorlevels 1-10.  From a technical standpoint, this message is
  514. sent whenever the before_exit() procedure is called without the node first
  515. having been manually deregistered.    Thus, it could be sent when TOP is exited
  516. for any reason.  The intent of this message is to inform other users that the
  517. user is no longer on the system.
  518.  
  519. See Also:  MSG_EXIT (#3), MSG_TOSSED (#26), MSG_ZAPPED (#27),
  520.            MSG_DELETED (#28)
  521. -------------------------------------------------------------------------------
  522. MSG_FORGET            #20     Sent when one user forgets another.
  523.  
  524. doneto    -    Node that is being forgotten.
  525. string    -    Null string.
  526. data1    -    Unused.
  527.  
  528.     This message is sent whenever one user forgets another with the FORGET
  529. command.  It is simply a notification message; there is no text displayed by
  530. the remote end.  (Forgetting is done in secrecy to avoid provoking the user
  531. being forgotten.)  Upon reception, the node should set the FGT_HASFORGOTME flag
  532. in the forgetstatus for the sending node.  Similarly, the sender should set the
  533. FGT_FORGOTTEN flag for the target node.
  534.  
  535. NOTE:  This message MUST reach the target node!  Forgetting is tracked on both
  536. the node that does the forgetting and the node being forgotten, and if the
  537. records of who has forgotten who don't match, it will cause a lot of problems.
  538. To ensure this messages reaches the target, simply send it globally.
  539.  
  540. See Also:  MSG_REMEMBER (#21)
  541. -------------------------------------------------------------------------------
  542. MSG_REMEMBER        #21     Sent when one user remembers another.
  543.  
  544. doneto    -    Node that is being remembered.
  545. string    -    Null string.
  546. data1    -    Unused.
  547.  
  548.     This message is sent when a user remembers another user with the REMEMBER
  549. command.  It works exactly the same as MSG_FORGET, except that the involved
  550. nodes should clear the appropriate forgetstatus flags as mentioned above.
  551.  
  552. See Also:  MSG_FORGET (#20)
  553. -------------------------------------------------------------------------------
  554. MSG_LINKUP            #22     A link to another system has been activated.
  555.  
  556. doneto    -    Unused.
  557. string    -    Name of the linked site.
  558. data1    -    Unused.
  559.  
  560.     This message is sent whenever a node establishes a link with another
  561. system.  Upon reception, the sending node's handle should be changed into the
  562. contents of string.  The sole purpose for this message is to notify users of
  563. the link's activation.  Aside from the handle change, nothing internal is
  564. changed.
  565.  
  566.     MSG_LINKUP as well as MSG_LINKTEXT and MSG_UNLINK are never sent by TOP.
  567. They were included for possible future internal linking support.  However, they
  568. ARE used by the TOPLink add-on and as such should be supported!
  569.  
  570. See Also:  MSG_LINKTEXT (#23), MSG_UNLINK (#24)
  571. -------------------------------------------------------------------------------
  572. MSG_LINKTEXT        #23     Text from a linked system.
  573.  
  574. doneto    -    Unused.
  575. string    -    Unformatted text to be sent.
  576. data1    -    Unused.
  577.  
  578.     This message is sent whenever a link node transmits text from the linked
  579. system.  Linked text is displayed using a special language item, hence the need
  580. for this message type.    In every other sense, however, linked text is just like
  581. normal text.
  582.  
  583. See Also:  MSG_LINKUP (#22), MSG_UNLINK (#24)
  584. -------------------------------------------------------------------------------
  585. MSG_UNLINK            #24     A linked system has disconnected.
  586.  
  587. doneto    -    Unused.
  588. string    -    Null string.
  589. data1    -    Unused.
  590.  
  591.     This message is sent whenever a linked system is disconnected.    The
  592. receiving node should mark the sender as inactive as for any other exit-type
  593. message.  Other than that, this message is a link-specific user notification
  594. (like MSG_LINKUP) and has no other function.
  595.  
  596. See Also:  MSG_LINKUP (#22), MSG_LINKTEXT (#23)
  597. -------------------------------------------------------------------------------
  598. MSG_EXMSGCHG        #25     A user has changed his/her entry and/or exit msg.
  599.  
  600. doneto    -    Unused.
  601. string    -    Null string.
  602. data1    -    Unused.
  603.  
  604.     This message is sent when a user changes their entry and/or exit message in
  605. the profile editor or using the CHANGE EMESAGE or CHANGE XMESSAGE commands.  It
  606. is sent solely to inform other users.
  607.  
  608. See Also:  MSG_HANDLECHG (#14), MSG_BIOCHG (#15), MSG_SEXCHG (#16),
  609.            MSG_ACTIONCHG (#17), MSG_PERACTCHG (#18)
  610. -------------------------------------------------------------------------------
  611. MSG_TOSSED            #26     A sysop has tossed a user back to the BBS.
  612.  
  613. doneto    -    Node that is being tossed.
  614. string    -    Unformatted optional reason text, or null for none.
  615. data1    -    Unused.
  616.  
  617.     This message is sent when a sysop uses the SYSOP TOSS command to send a
  618. user back to the BBS.  If a reason exists it will be displayed to the user
  619. before the toss.  This message should only be sent to the node that is being
  620. tossed, which will respond by exiting and sending a MSG_TOSSOUT.  Do not
  621. confuse this with MSG_TOSSOUT!
  622.  
  623. See Also:  MSG_TOSSOUT (#19), MSG_ZAPPED (#27), MSG_DELETED (#28)
  624. -------------------------------------------------------------------------------
  625. MSG_ZAPPED            #27     A sysop has zapped a user off the system.
  626.  
  627. doneto    -    Node that is being zapped.
  628. string    -    Unformatted optional reason text, or null for none.
  629. data1    -    Unused.
  630.  
  631.     This message is sent when a sysop uses the SYSOP ZAP command to send a user
  632. back to the BBS.  If a reason exists it will be displayed to the user before
  633. the toss.  This message should only be sent to the node that is being tossed,
  634. which will respond by sending a MSG_TOSSOUT and then disconnecting the user.
  635.  
  636. See Also:  MSG_TOSSOUT (#19), MSG_TOSSED (#26), MSG_DELETED (#28)
  637. -------------------------------------------------------------------------------
  638. MSG_DELETED         #28*    A sysop deleted a user that is currently online.
  639.  
  640. doneto    -    Node that the deleted user is on.
  641. string    -    Unformatted optional reason text, or null for none.
  642. data1    -    Unused.
  643.  
  644.     This message is intended for use with an online user editor or a SYSOP
  645. DELETE command.  It should be sent to a user who is being deleted, if that user
  646. is currently online.  TOP should respond by sending a MSG_TOSSOUT, then zeroing
  647. the entire user record and saving it, followed by disconnecting the user.  This
  648. of course does not delete the user from the BBS but does delete their TOP
  649. information.
  650.  
  651. See Also:  MSG_TOSSOUT (#19), MSG_TOSSED (#26), MSG_ZAPPED (#27)
  652. -------------------------------------------------------------------------------
  653. MSG_CLEARNODE        #29     A sysop cleared a crashed node.
  654.  
  655. doneto    -    Unused.
  656. string  -   String representation of the node that is being cleared.
  657. data1    -    Unused.
  658.  
  659.     This message is sent to _all_ nodes when a sysop issued a SYSOP CLEAR
  660. command.  It is a signal to the other nodes to clear the offending node from
  661. memory, effectively rendering that node to an unused state.  Should the node in
  662. question be active and not crashed, the user will suddenly be "cut out of the
  663. loop", and will not receive any text (except pages) though they can still type.
  664. While this can be funny it is not recommended as it may cause TOP to exhibit
  665. odd behaviour and even crash.
  666.  
  667. See Also:  MSG_KILLCRASH (#38)
  668. -------------------------------------------------------------------------------
  669. MSG_SYSGIVECD        #30     A sysop gave a user some CyberCash.
  670.  
  671. doneto    -    Node to receive the CyberCash.
  672. string    -    String representation of the amount of CyberCash to give.
  673. data1    -    Unused.
  674.  
  675.     This message is sent to a node when a sysop uses the SYSOP_CDGIVE command.
  676. It will credit the user with the amount of CyberCash specified in string.
  677.  
  678. See Also:  MSG_SYSTAKECD (#31), MSG_SYSSETCD (#32)
  679. -------------------------------------------------------------------------------
  680. MSG_SYSTAKECD        #31     A sysop took some CyberCash away from a user.
  681.  
  682. doneto    -    Node to take the CyberCash from.
  683. string    -    String representation of the amount of CyberCash to take.
  684. data1    -    Unused.
  685.  
  686.     This message is sent to a node when a sysop uses the SYSOP_CDTAKE command.
  687. It will debit the user with the amount of CyberCash specified in string.
  688.  
  689. See Also:  MSG_SYSGIVECD (#30), MSG_SYSSETCD (#32)
  690. -------------------------------------------------------------------------------
  691. MSG_SYSSETCD        #32     A sysop set a user's CyberCash total.
  692.  
  693. doneto    -    Node to receive the CyberCash.
  694. string    -    String representation of the amount of cash the user should have.
  695. data1    -    Unused.
  696.  
  697.     This message is sent to a node when a sysop uses the SYSOP_CDSET command.
  698. It will set the user's CyberCash total to the value specified in string.
  699.  
  700. See Also:  MSG_SYSGIVECD (#30), MSG_SYSTAKECD (#31)
  701. -------------------------------------------------------------------------------
  702. MSG_TRANSCD         #33*    A user transfered CyberCash to another user.
  703.  
  704. doneto    -    Node to receive the CyberCash.
  705. string    -    String representation of the amount of cash the user is to get.
  706. data1    -    Unused.
  707.  
  708.     This message type is intended for user-to-user CyberCash transfers.  It
  709. should be self explanitory.
  710.  
  711. See Also:  MSG_SYSGIVECD (#30), MSG_SYSTAKECD (#31), MSG_SYSSETCD (#32)
  712. -------------------------------------------------------------------------------
  713. MSG_EXTCOMMAND      #34     Triggers an external command on another node.
  714.  
  715. doneto    -    Node that is to run the command.
  716. string    -    Full command text, as if the user typed it into TOP.
  717. data1    -    Unused.
  718.  
  719.     This message type allows an external command program run on one node to
  720. trigger an external command program on another node.  The text in string should
  721. appear just as if the user on the other node typed it.  For example, "DICE
  722. 6d6".  The receiving node will then interpret this text as if it were typed by
  723. the user, searching through SPAWN.CFG records to find the program and command
  724. line to use.
  725.  
  726.     IMPORTANT:  TOP executes the command in the middle of message processing.
  727. As a result, the ECP being triggered MUST run quickly or it will interefere
  728. with the message processing and the overall operation of TOP!
  729.  
  730. See Also:  None
  731. -------------------------------------------------------------------------------
  732. MSG_GENERIC         #35     Sends unformatted, unedited text.
  733.  
  734. doneto    -    Unused.
  735. string    -    Full text to be shown, as it should appear to other users.
  736. data1    -    Unused.
  737.  
  738.     This is the most basic message for text displaying.  TOP will simply show
  739. whatever is in string, translating any codes but not adding any prefix or
  740. suffix text.
  741.  
  742. See Also:  MSG_TEXT (#1)
  743. -------------------------------------------------------------------------------
  744. MSG_INCHANNEL        #36     A user has entered a channel.
  745.  
  746. doneto    -    Unused.
  747. string    -    Null string.
  748. data1    -    Unused.
  749.  
  750.     This message is sent whenever a user joins a new channel.  The channel
  751. being joined is contained in the channel field of the message data.  This
  752. message is purely for user notification.
  753.  
  754. See Also:  MSG_OUTCHANNEL (#37)
  755. -------------------------------------------------------------------------------
  756. MSG_OUTCHANNEL        #37     A used has left a channel.
  757.  
  758. doneto    -    Unused.
  759. string    -    Null string.
  760. data1    -    Unused.
  761.  
  762.     This message is sent whenever a user leaves a channel.    The channel being
  763. left is contained in the channel field of the message data.  This message is
  764. purely for user notification.
  765.  
  766. See Also:  MSG_INCHANNEL (#36)
  767. -------------------------------------------------------------------------------
  768. MSG_KILLCRASH        #38     Instruction to clear a crashed node.
  769.  
  770. doneto    -    Unused.
  771. string    -    String represenation of the node being cleared.
  772. data1    -    Unused.
  773.  
  774.     This message is sent whenever TOP's crash protection detects that a node
  775. has crashed.  When this occurs, this message type will be sent globally to all
  776. nodes.    Upon receiving this message, TOP will clear the node in question from
  777. memory.  This message essentially functions like MSG_CLEARNODE except the
  778. language item that is displayed is different.
  779.  
  780. See Also:  MSG_CLEARNODE (#29)
  781. -------------------------------------------------------------------------------
  782. MSG_DIRECTED        #39     Directed message from one user to another.
  783.  
  784. doneto    -    Node that the message is directed to.
  785. string    -    Raw text containing the directed message.
  786. data1    -    Unused.
  787.  
  788.     A directed message is a public message that is directed towards a specific
  789. user.  As such it is always sent publically (priv = 0) with doneto being set to
  790. a specific node.
  791.  
  792. See Also:  MSG_WHISPER (#6)
  793. -------------------------------------------------------------------------------
  794. MSG_SYSINEDITOR     #40*    A sysop has entered a system editor.
  795.  
  796. doneto    -    Unused.
  797. string    -    Null string.
  798. data1    -    Unused.
  799.  
  800.     This message type is intended for use with online system editors, such as a
  801. user, configuration, or language file editor.  It is simply a notification to
  802. other users that a sysop has entered such an editor.
  803.  
  804. See Also:  MSG_SYSOUTEDITOR (#41), MSG_SYSUSEREDITED (#42),
  805.            MSG_SYSCFGEDITED (#43), MSG_SYSLANGEDITED (#44)
  806. -------------------------------------------------------------------------------
  807. MSG_SYSOUTEDITOR    #41*    A sysop has returned from a system editor.
  808.  
  809. doneto    -    Unused.
  810. string    -    Null string.
  811. data1    -    Unused.
  812.  
  813.     This message type is intended for use with online system editors, such as a
  814. user, configuration, or language file editor.  It is simply a notification to
  815. other users that a sysop has returned from such an editor.
  816.  
  817. See Also:  MSG_SYSINEDITOR (#40), MSG_SYSUSEREDITED (#42),
  818.            MSG_SYSCFGEDITED (#43), MSG_SYSLANGEDITED (#44)
  819. -------------------------------------------------------------------------------
  820. MSG_SYSUSEREDITED    #42*    A sysop has edited a user's data.
  821.  
  822. doneto    -    Node containing the user who's data was edited.
  823. string    -    Null string.
  824. data1    -    Unused.
  825.  
  826.     This message type is intended for use with an online user editor.  When a
  827. sysop using this editor edits a user that is currently in TOP, this message
  828. should be sent privately to that user.    Upon reception, a node should reload
  829. the user's data from USERS.TOP.
  830.  
  831. See Also:  MSG_SYSINEDITOR (#40), MSG_SYSOUTEDITOR (#41),
  832.            MSG_SYSCFGEDITED (#43), MSG_SYSLANGEDITED (#44)
  833. -------------------------------------------------------------------------------
  834. MSG_SYSCFGEDITED    #43*    A sysop has edited the system configuration.
  835.  
  836. doneto    -    Unused.
  837. string    -    Null string.
  838. data1    -    Unused.
  839.  
  840.     This message type is intended for use with an online configuration editor.
  841. When a sysop has finished editing the configuration, this message should be
  842. sent globally to all nodes.  Upon reception, a node should reload the entire
  843. system configuration (*.CFG).
  844.  
  845. See Also:  MSG_SYSINEDITOR (#40), MSG_SYSOUTEDITOR (#41),
  846.            MSG_SYSUSEREDITED (#42), MSG_SYSLANGEDITED (#44)
  847. -------------------------------------------------------------------------------
  848. MSG_SYSLANGEDITED    #44*    A sysop has edited the language file.
  849.  
  850. doneto    -    Unused.
  851. string    -    Base name of the language file that was edited (no path/extension).
  852. data1    -    Unused.
  853.  
  854.     This message type is intended for use with an online language editor.  When
  855. a sysop has finished editing the language file, this message should be sent
  856. globally to all nodes.  Upon reception, a node should check to see if the file
  857. name in string matches the language file that node is using, and if it does the
  858. language file should be reloaded.  The language file name is included in string
  859. to support a future version of TOP that will allow each user to choose a
  860. different language file.
  861.  
  862. See Also:  MSG_SYSINEDITOR (#40), MSG_SYSOUTEDITOR (#41),
  863.            MSG_SYSUSEREDITED (#42), MSG_SYSCFGEDITED (#43)
  864. -------------------------------------------------------------------------------
  865. MSG_SYSSETSEC       #45     A sysop has changed a user's security level.
  866.  
  867. doneto  -   Node containing the user who's security is being changed.
  868. string  -   String representation of the new security level.
  869. data1   -   Unused.
  870.  
  871.     This message is sent when a sysop uses the SYSOP SETSEC command.  It is
  872. sent privately to the node affected, which then adjusts the user's security to
  873. the specified level.
  874.  
  875. See Also:  None
  876. -------------------------------------------------------------------------------
  877. MSG_INPRIVCHAT      #46     A user has entered private chat mode.
  878.  
  879. doneto  -   Unused.
  880. string  -   Handle of the user entering private chat.
  881. data1   -   Unused.
  882.  
  883.     This message is sent when a user enters private chat with another user.  It
  884. it intended solely for notifying other users.  The other user is not specified;
  885. instead one message will be sent from each of the nodes involved.
  886.  
  887. See Also:  MSG_OUTPRIVCHAT (#47), MSG_WANTSPRIVCHAT (#48),
  888.            MSG_DENYPRIVCHAT (#49)
  889. -------------------------------------------------------------------------------
  890. MSG_OUTPRIVCHAT     #47     A user has returned from private chat mode.
  891.  
  892. doneto  -   Unused.
  893. string  -   Handle of the user returning from private chat.
  894. data1   -   Unused.
  895.  
  896.     This message is sent when a user returns from a private chat with another
  897. user.  It it intended solely for notifying other users.  The other user is not
  898. specified; instead one message will be sent from each of the nodes involved.
  899.  
  900. See Also:  MSG_INPRIVCHAT (#46), MSG_WANTSPRIVCHAT (#48),
  901.            MSG_DENYPRIVCHAT (#49)
  902. -------------------------------------------------------------------------------
  903. MSG_WANTSPRIVCHAT   #48     Private chat requested or accepted.
  904.  
  905. doneto  -   Node containing the user who the request is aimed at.
  906. string  -   Handle of the user requesting the private chat.
  907. data1   -   Unused.
  908.  
  909.     This message is sent globally whenever a user uses the CHAT command.  It
  910. either initiates a request for chat, or accepts a user's standing request to
  911. chat. Each user may only have a standing request to chat from one user at a
  912. time.  Consult PRIVCHAT.TXT when using this message to be sure that you do not
  913. confuse TOP.
  914.  
  915. See Also:  MSG_INPRIVCHAT (#46), MSG_OUTPRIVCHAT (#47), MSG_DENYPRIVCHAT (#49)
  916. -------------------------------------------------------------------------------
  917. MSG_DENYPRIVCHAT    #49     Denies a user's request for a private chat.
  918.  
  919. doneto  -   Node containing the user who's request is being denied.
  920. string  -   Handle of the user denying the chat request.
  921. data1   -   Unused.
  922.  
  923.     This message is sent globally to deny a user's private chat request with
  924. the DENYCHAT command.  Consult PRIVCHAT.TXT for why this is needed.
  925.  
  926. See Also:  MSG_INPRIVCHAT (#46), MSG_OUTPRIVCHAR (#47), MSG_WANTSPRIVCHAT (#48)
  927. -------------------------------------------------------------------------------
  928. MSG_CHANTOPICCHG    #50     The topic for the current channel has changed.
  929.  
  930. doneto  -   Unused.
  931. string  -   The new topic.
  932. data1   -   Unused.
  933.  
  934.     This message is sent whenever a moderator uses the MODERATOR SETTOPIC
  935. command to change a channel's topic.  This message not only notifies the users
  936. of the topic change, but instructs each node to update its current CMI
  937. information.
  938.  
  939. See Also:  MSG_CHANMODCHG (#55)
  940. -------------------------------------------------------------------------------
  941. MSG_CHANBANNED      #51     Bans a user from a channel.
  942.  
  943. doneto  -   Node containing the user to be banned.
  944. string  -   Null string.
  945. data1   -   Channel number to ban the user from.
  946.  
  947.     This message is sent whenever a moderator uses the MODERATOR BAN command to
  948. ban a user from the channel that the moderator is currently in.  As the command
  949. can be used on a user anywhere in TOP, the channel number is stored in the
  950. data1 field.  This command can only be used in certain types of channels.  See
  951. CHANNELS.TXT for more information.
  952.  
  953. See Also:  MSG_CHANUNBANNED (#52), MSG_CHANINVITED (#53),
  954.            MSG_CHANUNINVITED (#54)
  955. -------------------------------------------------------------------------------
  956. MSG_CHANUNBANNED    #52     Removes the ban on a user from a channel.
  957.  
  958. doneto  -   Node containing the user to be unbanned.
  959. string  -   Null string.
  960. data1   -   Channel number to unban the user from.
  961.  
  962.     This message is sent whenever a moderator uses the MODERATOR UNBAN command
  963. to undo a user's ban from the channel that the moderator is currently in.  As
  964. the command can be used on a user anywhere in TOP, the channel number is stored
  965. in the data1 field.  This command can only be used in certain types of
  966. channels.  See CHANNELS.TXT for more information.
  967.  
  968. See Also:  MSG_CHANBANNED (#51), MSG_CHANINVITED (#53),
  969.            MSG_CHANUNINVITED (#54)
  970. -------------------------------------------------------------------------------
  971. MSG_CHANINVITED     #53     Invites a user to a channel.
  972.  
  973. doneto  -   Node containing the user to be invited.
  974. string  -   Null string.
  975. data1   -   Channel number to invite the user to.
  976.  
  977.     This message is sent whenever a moderator uses the MODERATOR INVITE command
  978. to invite a user to the channel that the moderator is currently in.  As the
  979. command can be used on a user anywhere in TOP, the channel number is stored in
  980. the data1 field.  This command can only be used in certain types of channels.
  981. See CHANNELS.TXT for more information.
  982.  
  983. See Also:  MSG_CHANBANNED (#51), MSG_CHANUNBANNED (#52),
  984.            MSG_CHANUNINVITED (#54)
  985. -------------------------------------------------------------------------------
  986. MSG_CHANUNINVITED   #54     Removes a user's invitation to a channel.
  987.  
  988. doneto  -   Node containing the user to be uninvited.
  989. string  -   Null string.
  990. data1   -   Channel number to uninvite the user from.
  991.  
  992.     This message is sent whenever a moderator uses the MODERATOR UNINVITE
  993. command to remove a user's invitation to the channel that the moderator is
  994. currently in.  As the command can be used on a user anywhere in TOP, the
  995. channel number is stored in the data1 field.  This command can only be used in
  996. certain types of channels.  See CHANNELS.TXT for more information.
  997.  
  998. See Also:  MSG_CHANBANNED (#51), MSG_CHANUNBANNED (#52),
  999.            MSG_CHANINVITED (#53)
  1000. -------------------------------------------------------------------------------
  1001. MSG_CHANMODCHG      #55     Changes or adds a moderator for this channel.
  1002.  
  1003. doneto  -   Node containing the new or additional moderator.
  1004. string  -   Null string.
  1005. data1   -   Unused.
  1006.  
  1007.     This message is sent whenever a moderator uses the MODERATOR SETMOD to
  1008. change or add a moderator from the current channel.  Whether the old moderator
  1009. retains moderator powers depends on factors that are not covered here, but the
  1010. message used in both cases is the same.  This message serves to both notify
  1011. users of the change and to update each node's internal CMI information with the
  1012. new moderator.
  1013.  
  1014. See Also:  MSG_CHANTOPICCHG (#50)
  1015. -------------------------------------------------------------------------------
  1016. MSG_FORCERESCAN     #56     Forces nodes to reload the two node indexes.
  1017.  
  1018. doneto  -   Unused.
  1019. string  -   Null string.
  1020. data1   -   Unused.
  1021.  
  1022.     This message is not sent by TOP itself, but is supported if it is needed.
  1023. It forces all nodes that receive it to reload information from NODEIDX.TCH and
  1024. NODEIDX2.TCH.  It was originally implemented as a temporary workaround for a
  1025. problem that was later properly corrected.  Any routine that properly accesses
  1026. the node indexes and sends the appropriate change messages should never need to
  1027. use this message type, but it is here if it is needed.
  1028.  
  1029. See Also:  None
  1030. -------------------------------------------------------------------------------
  1031. MSG_INBIOEDITOR     #57     A user has entered the biography editor.
  1032.  
  1033. doneto  -   Unused.
  1034. string  -   Handle of the user that entered the biography editor.
  1035. data1   -   Unused.
  1036.  
  1037.     This message is sent whenever a user uses the BIO command to enter the
  1038. biography editor.  It is sent solely to notify other users.
  1039.  
  1040. See Also:  MSG_OUTBIOEDITOR (#58)
  1041. -------------------------------------------------------------------------------
  1042. MSG_OUTBIOEDITOR    #58     A user has returned from the biography editor.
  1043.  
  1044. doneto  -   Unused.
  1045. string  -   Handle of the user that returned from the biography editor.
  1046. data1   -   Unused.
  1047.  
  1048.     This message is sent whenever a user returns from the biography editor.  It
  1049. is sent solely to notify other users.
  1050.  
  1051. See Also:  MSG_INBIOEDITOR (#57)
  1052. -------------------------------------------------------------------------------
  1053. MSG_AFKON           #59     A user has entered AFK mode.
  1054.  
  1055. doneto  -   Unused.
  1056. string  -   Optional reason text, or null string for none.
  1057. data1   -   Unused.
  1058.  
  1059.     This message is sent whenever a user enters the AFK command to indicate
  1060. they are away from the keyboard.  It is sent only to notify other users.  The
  1061. optional reason, if present, will be displayed with the notification.
  1062.  
  1063. See Also:  MSG_AFKOFF (#60)
  1064. -------------------------------------------------------------------------------
  1065. MSG_AFKOFF          #60     A user has returned from AFK mode.
  1066.  
  1067. doneto  -   Unused.
  1068. string  -   Null string.
  1069. data1   -   Unused.
  1070.  
  1071.     This message is sent whenever a user enters the AFK command a second time to indicate
  1072. they have returned to the keyboard.  It is sent only to notify other users.
  1073.  
  1074. See Also:  MSG_AFKON (#59)
  1075. -------------------------------------------------------------------------------
  1076. MSG_INSHELL         #61     A local sysop has engaged a DOS shell.
  1077.  
  1078. doneto  -   Unused.
  1079. string  -   Null string.
  1080. data1   -   Unused.
  1081.  
  1082.     This message is sent whenever a sysop at the BBS site uses Alt-J to engage
  1083. a DOS shell.  During this time, the user on the node where the shell was run
  1084. will be held in limbo, so to notify other users, this message is sent.  It has
  1085. no function other than notification.
  1086.  
  1087. See Also:  MSG_OUTSHELL (#62)
  1088. -------------------------------------------------------------------------------
  1089. MSG_OUTSHELL        #62     A local sysop has returned from a DOS shell.
  1090.  
  1091. doneto  -   Unused.
  1092. string  -   Null string.
  1093. data1   -   Unused.
  1094.  
  1095.     This message is sent whenever a local sysop returns from a DOS shell, thus
  1096. releasing the user on that node from their "paused" state.  It has no function
  1097. other than notification.
  1098.  
  1099. See Also:  MSG_INSHELL (#61)
  1100. -------------------------------------------------------------------------------
  1101. MSG_INSYSCHAT       #63     A local sysop has engaged a chat with a user.
  1102.  
  1103. doneto  -   Unused.
  1104. string  -   Null string.
  1105. data1   -   Unused.
  1106.  
  1107.     This message is sent whenever a sysop at the BBS site uses Alt-C to engage
  1108. a sysop-to-user chat with a user.  This message is sent so that other users
  1109. will know that the user involved cannot respond.  It has no function other than
  1110. notification.
  1111.  
  1112. See Also:  MSG_OUTSYSCHAT (#64)
  1113. -------------------------------------------------------------------------------
  1114. MSG_OUTSYSCHAT      #64     A local sysop has ended a chat with a user.
  1115.  
  1116. doneto  -   Unused.
  1117. string  -   Null string.
  1118. data1   -   Unused.
  1119.  
  1120.     This message is sent when a local sysop terminates a sysop-to-user chat,
  1121. allowing the user to communicate with other TOP users once again.  It has no
  1122. function other than notification.
  1123.  
  1124. See Also:  MSG_INSYSCHAT (#63)
  1125. -------------------------------------------------------------------------------
  1126.  
  1127.                               ===================
  1128.                               Technical Reference
  1129.                               ===================
  1130.  
  1131.     While TOP's messaging system is not technically complex, it is very touchy.
  1132. Proper procedures must be followed and precautions must be taken, or the system
  1133. will break down.  Because the messaging system is the only way TOP can
  1134. dynamically communicate information between nodes, a complete understanding of
  1135. it is needed for anybody making modiciations to it or developing add-on
  1136. programs.  ECP programmers need not worry about these details as TOP handles
  1137. all of the messy work associated with exchanging messages.
  1138.  
  1139.     File Descriptions
  1140.     -----------------
  1141.  
  1142.     The TOP messaging system is made up of three types of files, which are
  1143. described below.
  1144.  
  1145.     CHGIDX.TCH      The change index.  This is a simple file that contains one
  1146.                     byte per node.  This byte, when true, signifies that at
  1147.                     least one new message has been sent to the node.  Each
  1148.                     node's change byte is located at an offset equal to the
  1149.                     node number.
  1150.  
  1151.     MIXnnnnn.TCH    The message index.  Each node has its own.  The message
  1152.                     index is also a series of bytes.  Each byte represents one
  1153.                     record in the message data file (see below).  When a byte
  1154.                     is true, it means there is a message at the corresponding
  1155.                     record.  nnnnn represents the node number in decimal
  1156.                     notation, zero-padded to five digits.
  1157.  
  1158.     MSGnnnnn.TCH    The message data file.  Again, each node has its own.  This
  1159.                     file contains a series of records of type msg_typ (see
  1160.                     TOPSTR.H).  The first record corresponds to the first byte
  1161.                     in the message index, etc.  nnnnn represents the node
  1162.                     number in decimal notation, zero-padded to five digits.
  1163.  
  1164.     File Access Procedure
  1165.     ---------------------
  1166.  
  1167.     Each file should be opened in DenyNone sharing mode.  Record locking is
  1168. used to restrict access.  Both reading and writing must be done under locked
  1169. conditions to ensure data does not change while it is being accessed.
  1170.  
  1171.     Proper locking procedure is to lock _ALL_ data in a record.  In the change
  1172. index and message index, this simply one byte at a time.  For the message data
  1173. file, the entire record should be locked even if it is not all being used.
  1174.  
  1175.     For speed, the change index should always be left open.  Also, TOP leaves
  1176. the incoming message files, that is those with the same number as the node,
  1177. open at all times.  This is not necessary (especially when sending more than
  1178. receiving) but is recommended for speed if possible.  The outgoing message
  1179. files, that is those that belong to another node, are only opened as needed.
  1180.  
  1181.     Reading
  1182.     -------
  1183.  
  1184.     To read a message, the procedure below is followed.  Sorry, but unless you
  1185. have the TOP source you don't get any source code examples.
  1186.  
  1187.     1. Scan the node's byte in the change index.  If it is true, proceed to the
  1188. next step, otherwise repeat.
  1189.  
  1190.     2. Immediately clear the change index byte.  This has to be done to prevent
  1191. any messages getting lost while reading.  This could occur if, for example, we
  1192. are processing a message later in the file and another node writes a new
  1193. message to the now cleared first record.  If the change index byte was not
  1194. cleared immediately, TOP would never know this new message was there!
  1195.  
  1196.     3. Looping for the entire length of the message index file, check one byte
  1197. at a time (in sequential order).  If the byte is true, DO NOT UNLOCK IT, and
  1198. proceed.  Leaving the byte locked prevents other nodes from trying to use this
  1199. spot.
  1200.  
  1201.     4. Read in the message from corresponding record of the message data file
  1202. and process it.  All checks regarding the validity or usefulness of the message
  1203. are performed after reading.  Unlock the message index byte after both reading
  1204. and processing have been completed.
  1205.  
  1206.     5. When the loop is finished, DO NOTHING.  NEVER TRUNCATE ANY OF THE FILES!
  1207. Files must not be truncated for the reason described in step 2.  New messages
  1208. that were sent during the reading process will be read the next time around.
  1209.  
  1210.     The above steps are generally repeated at a regular interval.  During steps
  1211. that reading is not performed, messages will accumulate in the files,
  1212. increasing their size.  Because many sysops use a RAMDisk, it is important not
  1213. to go too long without scanning.
  1214.  
  1215.     Writing
  1216.     -------
  1217.  
  1218.     The procedure for writing a message is described below.
  1219.  
  1220.     1. Looping for the entire length of the message index file, read each byte.
  1221.  
  1222.     2. Proceed when a false byte is found, noting the byte's offset.  If none
  1223. can be found, create a new record by using an offset equal to the length of the
  1224. message index file.  LEAVE THE BYTE BEING USED LOCKED.
  1225.  
  1226.     3. Write true to the message index byte being used.  LEAVE IT LOCKED.
  1227.  
  1228.     4. Write the message to the corresponding record of the message data file.
  1229.  
  1230.     5. Unlock the message index byte.
  1231.  
  1232.     6. Write a true byte to the change index to tell the receiving node that
  1233. there is a new message.
  1234.  
  1235.     Determining Recipients
  1236.     ----------------------
  1237.  
  1238.     When determining where to send a message, use the same criteria (tonode,
  1239. priv, echo) that the dispatch_message() function uses.  This is easily done as
  1240. described below.
  1241.  
  1242.     1. Check if tonode is not set (i.e. if it is negative) and if priv is
  1243. false.  If either conditions is true, assume ALL nodes, otherwise assume only
  1244. the tonode.
  1245.  
  1246.     2. If echo is set and all nodes are being used, send the message to ourself
  1247. as well, otherwise skip us during the sending.  echo has no effect for private
  1248. messages.
  1249.  
  1250.     Note that the channel, message type, security, forget status, etc. all have
  1251. no effect whether or not a node gets the message.
  1252.  
  1253.                                    =========
  1254.                                    Afterword
  1255.                                    =========
  1256.  
  1257.     That is essentially all the information you need to know about the message
  1258. system.  If you have any questions, please do not hesitate to contact me by
  1259. Internet as follows:
  1260.  
  1261. Email   -   paulsid@home.com
  1262. WWW     -   http://members.home.net/paulsid/ismware/top/
  1263.  
  1264.