home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / top2src.zip / CHANNELS.TXT < prev    next >
Text File  |  2000-07-03  |  7KB  |  125 lines
  1. How TOP's Channels & CMI Work (v3.00b1)
  2. ---------------------------------------
  3.  
  4.     This file explains how TOP manages and uses different channels for
  5. conferencing from a programming point of view.  There is already a lengthy
  6. explanation from an outsider's point of view in TOP.DOC.  In particular, this
  7. file describes how TOP's Channel Management Interface (CMI) works, as this is
  8. the most important part of the system, and anybody changing TOP's core
  9. operations will need to at least be aware of how the CMI works so they can make
  10. the expected function calls when needed.
  11.  
  12.     The first part of this file is a description about how TOP uses channels.
  13. It begins with a condensed version of the information in TOP.DOC and covers
  14. TOP's internal numbering of channels.  Next, it moves on to describe how TOP
  15. determines which messages are on which channels.  Finally, it introduces the
  16. CMI and explains all of the concepts, such as joining, moderatorship, and
  17. ban/invite lists.  The second part is a reference guide for the CMI, and the
  18. third part describes how the CMI is actually used within TOP.
  19.  
  20.     This file assumes familiarity with TOP's messaging system and with
  21. MESSAGES.TXT.
  22.  
  23.  
  24.                               ====================
  25.                               1. How Channels Work
  26.                               ====================
  27.  
  28.     Channel Numbering
  29.     -----------------
  30.  
  31.    TOP supports a maximum of (2^32)-2 (4.2 billion) different chat channels.
  32. This is, of course, a theoretical maximum, because it is actually impossible to
  33. have more channels in use than nodes inside TOP, and is it not possible to have
  34. more than 32767 nodes period.  However, even if this were to actually happen,
  35. TOP's channel system would (theoretically) have no problem coping!
  36.  
  37.     This seemingly absurd maximum makes sense once you realize that all a
  38. channel is, from TOP's point of view, is a number.  Every time a message is
  39. sent, the "channel" field (see MESSAGES.TXT) is set to a certain number.  The
  40. receiving node simply only displays those messages that have a channel number
  41. matching the one its user is currently joined to.  This brings up an important
  42. concept that will be needed later:  EVERY NODE RECEIVES AND PROCESSES MESSAGES
  43. SENT TO IT REGARDLESS OF ITS CHANNEL.  Normally, however, each node of TOP just
  44. skips messages not received on its current channel.
  45.  
  46.     As you know, TOP has three different types of channels:  Normal,
  47. Conferences, and Personal Channels.  (If you didn't know this, read TOP.DOC and
  48. CHANNELS.CFG before proceeding.)  To accomplish this, TOP reserves blocks of
  49. numbers within the 4.2 billion for each type of channel.  TOP also reserves two
  50. numbers for "special" channels.  The channel blocks are assigned as follows:
  51.  
  52.     * B means "billion" (the North American definition of 1 000 000 000)
  53.     * M means "million".
  54.  
  55. 0                   Global channel.  This is a special channel.  Any message
  56.                     received on this channel will be treated as if it came from
  57.                     the same channel the user is currently joined to.  This
  58.                     is critical for messages such as MSG_FORGET, MSG_REMEMBER,
  59.                     MSG_INVITE, MSG_BAN, etc.  This channel cannot be joined
  60.                     except by Sysops, who can use it to make global
  61.                     announcements to all users.
  62.  
  63. 1 to 4B-1           Normal channels.  These are channels any user can join by
  64.                     simply typing JOIN x, where x is a number from 1 to
  65.                     3999999999 inclusive.  One of these channels will be
  66.                     designated the "default", as specified by the
  67.                     DefaultChannel setting in TOP.CFG.  They may also have
  68.                     alias names setup in CHANNELS.CFG.
  69.  
  70. 4B to 4B+1M-1       Personal Channels.  These are the channels that can be
  71.                     accessed by typing JOIN username, where username is the
  72.                     name of a user currently inside TOP.  Internally, the
  73.                     number given to each channel is 4B plus the node number
  74.                     which the user is on.  So, for example, if BlindSpot is on
  75.                     node 5, then his personal channel number is 4B+5, or
  76.                     4000000005.
  77.  
  78. 4B+1M to (2^32)-2   Conference Channels.  These are channels defined as
  79.                     Conferences in CHANNELS.CFG.  The numbering is simple:  The
  80.                     first conference definition in CHANNELS.CFG is 4B+1M
  81.                     (4001000000), the next is 4B+1M+1 (4001000001), then
  82.                     4B+1M+2 (4001000002), etc.
  83.  
  84. (2^32)-1            Busy channel.  This last channel (whose actual number is
  85.                     4294967295) is used by nodes who are "busy".  Busy nodes
  86.                     are those currently doing things that don't allow them to
  87.                     process messages.  This most commonly occurs in Private
  88.                     Chat or during execution of an ECP.  This channel is never
  89.                     joined by any node, so it never has any messages on it
  90.                     specifically.
  91.  
  92.  
  93.     Channels & Messages
  94.     -------------------
  95.  
  96.     As mentioned above, when a TOP node sends a message, it simply sets the
  97. channel field of the message to the number which corresponds to the channel its
  98. user is on, or to the global channel.  This is explained in MESSAGES.TXT so it
  99. won't be covered again here.
  100.  
  101.     The processing that actually makes the channels work occurs at the
  102. receiving end of a message.  When TOP receives a message, it checks to see what
  103. the channel field is.  If it's 0 or the user's current channel, it processes
  104. the message.  Otherwise, it is skipped outright.
  105.  
  106.     The skipping of the message is not essential, but it makes things easier
  107. and (more importantly) faster.  For example, not skipping messages would
  108. eliminate the need for a global channel, but then TOP wouldn't know to ignore
  109. the message until it had checked its type as well.  This doesn't seem like
  110. much, but since messages are processed while their data on disk is locked, it's
  111. important to keep the processing time as low as possible.  It would also
  112. require either a check in the processing of each message type, or a general
  113. check with a list of message types to process, so it's much simpler to simply
  114. skip all off-channel messages.
  115.  
  116.     Again, note that nodes are sent messages on every channel, but its up to the
  117. node which ones it wants to process.  This concept is important because it
  118. provides enormous flexibility.  There are many ways in which the channel system
  119. could be enhanced by taking advantage of this functionality.  It would be a
  120. simple matter to modify TOP to allow a user (ideally a sysop) to receive chat
  121. messages from any channel, regardless of their current channel inside TOP.
  122.  
  123.  
  124.  
  125.