home *** CD-ROM | disk | FTP | other *** search
/ Dream 42 / Amiga_Dream_42.iso / RiscPC / Internet / Connexion / SPak.spk / !NewsBase_docs_ClientNote < prev    next >
Encoding:
Text File  |  1994-11-09  |  3.8 KB  |  98 lines
  1. NewsBase clients
  2. ----------------
  3.  
  4. This file contains some notes about how a NewsBase client might interact
  5. with NewsBase.
  6.  
  7. Startup.
  8. --------
  9.  
  10. On startup, the client should broadcast NewsBase_Command 0 (Startup). If
  11. newsbase is running, it will reply with NewsBase_Reply 0, from which the
  12. client can obtain the newsbase task handle for future communication. If no
  13. reply is received, the client might want to either complain to the user, or
  14. attempt to start newsbase itself.
  15.  
  16. If newsbase terminates due to an error condition or user request, it
  17. broadcasts NewsBase_Reply 10 (shutdown), so that any clients can take
  18. appropriate action.
  19.  
  20. NewsBase also broadcasts NewsBase_Reply 0 (startup) when first started, so
  21. that already-running clients may be aware of this.
  22.  
  23. When a client has started, and established communication with NewsBase, it
  24. may wish to obtain site-specific data using NewsBase_Command 30. As a
  25. minimum, it should probably obtain the hostname. This data is optional, and
  26. provided to avoid the user to have to configure the same information in the
  27. client as well as other programs (NewsBase and the transport itself).
  28.  
  29. Groups
  30. ------
  31.  
  32. A list all of active groups may be obtained by sending NewsBase_Command 100
  33. (ListGroups). NewsBase responds with a stream of NewsBase_Reply 100
  34. messages, containing groupnames matching the given pattern ("*" to match
  35. all), one message per group. The list is terminated with a message
  36. containing a null groupname.
  37.  
  38. Each groupname message also contains the numbers of the lowest and highest
  39. article numbers in the group. This may be taken as guidance of how many
  40. articles are present, and whether there is unread news in the group for a
  41. user.
  42.  
  43. NewsBase reply messages differ from many wimp messages in that idle
  44. wimp_polls may occur between a command being sent and the reply being
  45. receieved; or during a stream of replies. the client thus has to make some
  46. effort to track the current command, and which command the replies apply to
  47. (though this should be simple, as commands are not allowed to "overlap").
  48.  
  49. Articles
  50. --------
  51.  
  52. A list of article data for agroup may be obtained using NewsBase_Command 200
  53. (ListArts). A sequence of Newsbase_Reply messages, containing article
  54. number, from and subject data, are returned, one per article.
  55.  
  56. An individual article may be retrieved using NewsBase_Command 220
  57. (GetArticle). A message NewsBase_Reply 220 is returned, containing the name
  58. of the file. If the file is not found or available, a NewsBase_Reply 221 is
  59. returned.
  60.  
  61. It should be noted that an article number may be returned by ListArts but
  62. not found by GetArticle... the ListArts data comes from the group index
  63. file, which does not guarantee availablilty of the actual file (though this
  64. should be rare, it could occur if an article is requested during an expiry
  65. operation).
  66.  
  67. Posting or Emailing.
  68.  
  69. A file containing a fully-formatted article or mail message, including
  70. RFC-compliant headers, should be generated. The filename should ten be
  71. passed in a NewsBase_Command 300 or 310 message. A newsBase_Reply 300 or 310
  72. message will be returned to indicate success, or 301/311 (including an error
  73. message) for failure.
  74.  
  75. NewsBase_Update messages
  76. ------------------------
  77.  
  78. These messages are broadcast during a debatch or expiry, to indicate that
  79. new articles or groups have been created or deleted. A client may either
  80. want to use these messages explicitly to update article lists and displays
  81. in realtime (Readnews-style), or may simply wish to note that a group has
  82. changed, and perform a rescan (ListGroups or ListArts) later.
  83.  
  84. In other words, the client can treat this message as it wishes, or even
  85. ignore it.
  86.  
  87. Default Client
  88. --------------
  89.  
  90. Client programs may define a variable as follows in their !Boot file:
  91.  
  92. set NewsBase$ClientXXXX <Obey$Dir>
  93.  
  94. (for example, NewsBase$ClientTTFN)
  95.  
  96. Newsbase uses these variables to present clients to the user in the Newsbase
  97. General Setup "Default Client" menu.
  98.