home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / internet / www / ArcWEB / !ArcWeb / Protocol < prev    next >
Text File  |  1995-06-28  |  33KB  |  708 lines
  1. /*
  2.  * ArcWeb
  3.  *
  4.  * Copyright (C) Stewart Brodie, 1994, 1995
  5.  *
  6.  * This product is supplied under the terms laid down in the `Terms' file.
  7.  *
  8.  * This file: Protocol
  9.  *
  10.  *   For ArcWeb versions 0.28 and later (until superceded)
  11.  *
  12.  *   Changes from protocol in version 0.26
  13.  *      'reload' and 'fast images' bits have been switched
  14.  *      the ExternalLaunch can accept non-extended URLs, although such use is
  15.  *      depracated.
  16.  *
  17.  *   Changes from protocol in version 0.25
  18.  *      Message_ArcwebExternalLaunch added
  19.  *      Message_ArcwebConfigure added
  20.  *      Notes on both of the above added.
  21.  *
  22.  *   Changes from protocol in version 0.20
  23.  *      More flags added to FetchRequest & PostRequest messages.  These are
  24.  *      for the information of the fetcher only and do not need to be preserved
  25. ***     From version 0.25, the use on non-extended URLs is depracated
  26.  *
  27.  *   Changes from protocol in version 0.19
  28.  *      Comments about bit 27 handling (arcweb_FLAGS_url_changed) changed
  29.  *      Comments in several other sections changed
  30.  *      Whole document should be reread by those implementing any part of
  31.  *      any of the ArcWeb protocols
  32.  *
  33.  *   Changes from protocol in version 0.12
  34.  *      Extensions to the Message_ArcwebRenderDone buffer.  The image renderer
  35.  *      must insert the X and Y pixel size of a graphical image (to enable
  36.  *      ArcWeb to calculate URLs for imagemaps unless the information is not
  37.  *      available or not applicable (eg. for sound)
  38.  *
  39.  *
  40.  *   Changes from protocol in version 0.11
  41.  *      Extended URL protocol defined
  42.  *      - in *Request message blocks
  43.  *      - notes about ownership of file handles
  44.  *      - in comments about the Flags word
  45.  *      - comments about how to handle Location: header from HTTP servers
  46.  *      Message_ArcwebEMailRequest/Done added
  47.  *      Handling of bit 27 in non-extended URL messages
  48.  *      In Other Notes: comment about expiry dates updated
  49.  *      Warning about setting type bits in Done messages
  50.  *      Renderer protocol warnings added
  51.  *      Sender protocol renamed to Poster protocol
  52.  *      EMail protocol added (uses a new bit in flags)
  53.  *      Suggestion about intelligent HTTP fetchers prefetching images
  54.  *      Message_ArcwebAbortRequest added   + description
  55.  *      Message_ArcwebTransferStatus added + description
  56.  *
  57.  */
  58.  
  59. This file describes the protocols used by ArcWeb.  There are nine protocols
  60. planned, although only the first eight are fully implemented so far.
  61.  
  62.  
  63.   * Fetcher Protocol
  64.   * Renderer Protocol
  65.   * Quit Protocol
  66.   * Extended URL Protocol
  67.   * Poster Protocol
  68.   * Email Protocol
  69.   * External Launch Protocol
  70.   * Configuration Protocol
  71.   * Expire Protocol
  72.  
  73.  
  74. Programmers supporting these protocols must be extremely careful with their
  75. memory, message and protocol management.  The protocols are allowed to be
  76. concurrent and nested.
  77.  
  78. The obvious example is that a renderer may find an inline image in a
  79. document, and will hence want to issue a request to fetch it.  A not so
  80. obvious example is an intelligent HTTP fetcher which tries to intelligently
  81. scan the returned document (if it was HTML) to pick out <img> tags and kick
  82. off requests for these in-lined images so that when ArcWeb comes to ask for
  83. them, a swifter reply can be made.  The impact of such a system would be
  84. more noticable, the more images there are inlined in a document.
  85.  
  86.  
  87. General
  88. =======
  89.  
  90.   Each protocol consists of 2 messages, a "Request" and a "Done". The
  91. Request is sent with event code 18 to force an acknowledgement.  The
  92. fetcher/renderer should acknowledge with the Done message to prevent the
  93. Wimp returning the message to the originator.  Should the fetcher/renderer
  94. wish to call Wimp_Poll before it is ready to send the Done reply, it MUST ack
  95. the message (ie. fill in the ref fields and reply with event type 19 to
  96. prevent the Wimp returning it to the originator), and then send the Done
  97. message when it is ready (having remembered to fill in the your_ref field
  98. from the my_ref of the original Request).
  99.  
  100.   Instead of sending a Wimp acknowledgement with event type 19 to prevent
  101. delivery failure, as mentioned above, it would be much better to actually
  102. reply with a Message_ArcwebTransferStatus, which doubles both as the ack and
  103. as a useful message.  Further Message_ArcwebTransferStatus messages can be
  104. sent periodically (use event type 17 and zero the ref field for these)
  105.  
  106.   C programmers will want to use requester.h to define the structures used. 
  107. The types have been divorced from any Wimp library, only char, void and int
  108. types have been used.
  109.  
  110. For an example of a Fetcher, see !ArcwebLcl application supplied.  For an
  111. example of a Renderer, see !ArcWebImg application supplied.  ArcWeb
  112. broadcasts a RenderRequest even for HTML and plain text files, as it listens
  113. for RenderRequest messages itself (and this allows it to be overridden).
  114.  
  115.  
  116. Messages
  117. ========
  118.  
  119. buf is the buffer returned from Wimp_Poll (&e->data in Risc_OSlib).  The
  120. obvious fields have been omitted (ie. buf+0 to buf+12).
  121. The 'Private ArcWeb handle' must always be preserved, as this is the only
  122. way ArcWeb can deliver replies to the request originator.
  123.  
  124. The types of each entry are given:  str0 = zero terminated string.  strN = 
  125. string whose length is defined elsewhere.  str0/N = string zero terminated
  126. unless it is maximum length (defined elsewhere) in which case the terminator
  127. is missing; date5 = 5 byte date string (in UTC) as returned by OS_Word 14,3
  128.  
  129. The buffers are all defined together and then explained below.  requester.h
  130. contains C structures for these messages.
  131.  
  132.  
  133.  
  134.  
  135. Message_ArcwebFetchRequest      (msg_Arcweb__base +  0)
  136.  
  137.         buf+16  int     Message_ArcwebFetchRequest      (0x4A240)
  138.         buf+20  void*   Private ArcWeb handle
  139.         buf+24  int     Flags
  140.         buf+28  int     RISC OS file handle (source)
  141.  
  142. EITHER  buf+32  str0    Uniform Resource Locator (fully qualified)
  143.  
  144.     OR  buf+32  int     RISC OS file handle (URL) (if flags bit 22 set)
  145.  
  146.  
  147. Message_ArcwebFetchDone         (msg_Arcweb__base +  1)
  148.  
  149.         buf+12  int     my_ref from Message_ArcwebFetchRequest
  150.         buf+16  int     Message_ArcwebFetchDone         (0x4A241)
  151.         buf+20  void*   Private ArcWeb handle
  152.         buf+24  int     Flags
  153.  
  154.  EITHER buf+28  str0    Error message
  155.  
  156.      OR buf+28  int     Zero=this item has an expiry date
  157.         buf+32  int     Non-zero=use default expiry delay
  158.         buf+36  date5   Expiry date in UTC (if buf+32 zero, and buf+28 zero)
  159.  
  160.  
  161. Message_ArcwebRenderRequest     (msg_Arcweb__base +  2)
  162.  
  163.         buf+16  int     Message_ArcwebRenderRequest     (0x4A242)
  164.         buf+20  void*   Private ArcWeb handle
  165.         buf+24  int     flags
  166.         buf+28  int     RISC OS file handle (source)
  167.         buf+32  int     RISC OS file handle (temporary)
  168.         buf+36  int     RISC OS file handle (diagram)
  169.         buf+40  int     RISC OS file handle (link)
  170.         buf+44  int     size of data following
  171.         buf+48  ---     (contents of buf+44) bytes of source file
  172.  
  173. Message_ArcwebRenderDone        (msg_Arcweb__base +  3)
  174.  
  175.         buf+16  int     Message_ArcwebRenderDone        (0x4A243)
  176.         buf+20  void*   Private ArcWeb handle
  177.         buf+24  int     flags
  178.  
  179. EITHER  buf+28  int     size of image in x pixels (0 if N/A)
  180.         buf+32  int     size of image in y pixesl (0 if N/A)
  181.  
  182. OR      buf+28  str0    error message
  183.  
  184.  
  185. Message_ArcwebPostRequest       (msg_Arcweb__base +  4)
  186.  
  187.         buf+16  int     Message_ArcwebPostRequest       (0x4A244)
  188.         buf+20  void*   Private ArcWeb handle
  189.         buf+24  int     flags
  190.         buf+28  int     RISC OS file handle (source)
  191.         buf+32  int     RISC OS file handle (form)
  192.  
  193. EITHER  buf+36  str0    Uniform Resource Locator (if flags bit 22 clear)
  194.  
  195.     OR  buf+36  int     RISC OS file handle (URL) (if flags bit 22 set)
  196.  
  197. Message_ArcwebPostDone          (msg_Arcweb__base +  5)
  198.  
  199.         buf+12  int     my_ref from Message_ArcwebPostRequest
  200.         buf+16  int     Message_ArcwebPostDone          (0x4A245)
  201.         buf+20  void*   Private ArcWeb handle
  202.         buf+24  int     flags
  203.  
  204.  EITHER buf+28  str0    Error message
  205.  
  206.      OR buf+28  int     Zero=this item has an expiry date
  207.         buf+32  int     Non-zero=use default e