home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13g.zip / MULTSEND.DOC < prev    next >
Text File  |  1999-03-16  |  9KB  |  186 lines
  1. 16 February 1999
  2.  
  3.    The SREF_MULTI_SEND macrospace procedure of the SRE-http Web Server
  4.  
  5. SREF_MULTI_SEND is used to create multi-part document. It can also
  6. be used to "send pieces" of a document as it becomes available.
  7.  
  8.   * Multi-part documents are used for "server push" delivery of several files
  9.     sequentially. The basic presumption of a multi-part document is that
  10.     each part stand's on it's own. Typically, a browser will replace an earlier 
  11.     part as soon as the next part becomes available. For example, 
  12.     server push can be used as a form of animation, with each part being
  13.     a "frame" of a movie.
  14.  
  15.     For example, the GIF_TEXT addon uses multi-part document to build
  16.     complicated images, with simpler images displayed first, which 
  17.     are then replaced by more elaborate versions.
  18.  
  19.          Multi-part documents require browsers that are able to maintain
  20.          connections, and that understand the multipart/x-mixed-replace mimetype.
  21.          Older browsers, such as Web Explorer, can not do this.
  22.  
  23.     
  24.   * Sending pieces is used to send earlier portions of a document as 
  25.     they become available. This gives the client something to read when
  26.     long documents are being built on-the-fly. For example, the BBS
  27.     addon uses "sending in pieces" to display long listings, that
  28.     might "time out" the server (or the client's attention span)
  29.     if nothing is sent before the entire listing is created.
  30.         
  31.        Send-in-pieces documents can be handled by all browsers.
  32.  
  33.  
  34. By using SREF_MULTI_SEND, it's easy to create "multi-part" 
  35. or "send as pieces" documents. All you need to do is specify a list of 
  36. files (or strings), and let SREF_MULTI_SEND take care of the grubby details.
  37.  
  38.  
  39. I. Using SREF_MULTI_SEND 
  40.  
  41. The basic syntax of SREF_MULTI_SEND is:
  42.   rcode=sref_multi_send(message,mime_type,howsend,file_flag,verbose)
  43.  
  44. where:
  45.  
  46.    message:  either contains the "message" to be sent (either a text string or
  47.              binary value); OR  a fully qualified file name.
  48.    mime_type : A mime type; such as text/html or image/gif
  49.                You can also use mime_type to send additional response headers
  50.                (see the notes below).
  51.    howsend : A flag that tells SRE-http "where in the multi-send process
  52.              we are".  There are basically four values (with 
  53.              possible modifiers):
  54.               '1' == Single part document to "send in pieces" (requires
  55.                      a modifier)
  56.               'S' == Start the multipart send (i.e.; the first image)
  57.               'M' == A middle piece -- more will follow
  58.               'E' == End piece -- send this "message" and close the connection.
  59.                
  60.              In addition, you can "build" a long message, and display 
  61.              each portion as soon as they are added.  To do this, use the
  62.              following HowSend codes:
  63.                 '1S' and '1E' -- Start and end a "sent in pieces" single part
  64.                                  document
  65.                 'SS' and 'SE' -- Start and end the first "part"
  66.                 'MS' and 'ME' -- Start and end the middle "part(s)"
  67.                 'ES' and 'EE' -- Start and end the final "part"
  68.                 'A'  and '1A' -- Add stuff (between 1S-1E; SS-SE ; MS-ME; or ES-EE)
  69.   fileflag: If equal to 1, then "message" is to be treated as a
  70.             fully-qualified file name (Optional)
  71.    verbose : If > 2, some status info will be displayed (optional)
  72.    name    : Name to use when writing to GoServe audit file (for future 
  73.              implementation)
  74.  
  75. Notes:
  76.   * The return code (rcode) is the RC from the 'SEND' command: you can
  77.     check for negative values which  indicate a broken connection.
  78.   * x and xS are the same (where x=1,S,M, or E.
  79.     In particular: 1S=1, SS=S, MS=M, and ES=E.
  80.   * name is ONLY used on "first calls".
  81.     In particular, when howsend=1, 1S, S, or SS.
  82.   * mime_type is only used on "first calls of a part".
  83.     In particular, when howsend=1, 1S, S, SS, M, MS, E, or ES.
  84.   * If howsend='A', the name and mime_type arguments are ignored.
  85.   * If mime_type is not specified, text/html is assumed.
  86.   * If howsend is not specified, A is assumed.
  87.   * In most cases, the mime_type argument should contain a mime-type,
  88.     such as image/gif, text/html, etc.  However, you can also use
  89.     the mime_type argument to  add additional response headers for a "part".
  90.     To do this, append (after the mime-type) a '0d0a'x (a CRLF), followed
  91.     by a list (CRLF delimited) of response headers.
  92.     Examples:
  93.         mime_type='image/gif'||'0d0a'x||'Content-Disposition: attachment; filename=MySTUFF.GIF'
  94.         mime_type='text/plain'||'0d0a'x||'X-my_header: Hello1'||'0d0a'x||'X-his-header: goodbye'
  95.     Note that: 
  96.         i) the mime-type (for example, the 'image/gif') MUST be first, 
  97.        ii) the mime-type must be immediately followed by a '0d0a'x.
  98.       iii) you should NOT end the string with a '0d0a'x.     
  99.  
  100. Examples:
  101. A 3 picture animation:
  102.         foo=sref_multi_send('d:\i1.gif','image/gif','S',1)
  103.         foo=sref_multi_send('d:\i2.gif','image/gif','M',1)
  104.         foo=sref_multi_send('d:\i3.gif','image/gif','E',1)
  105.  
  106. A 3 screen status report, with the middle portion a "running tally"
  107.         foo=sref_multi_send('Welcome','text/plain','S')
  108.         foo=sref_multi_send('Part 1 is done','text/plain','MS')
  109.         foo=sref_multi_send('Part 2 is done','text/plain','A')
  110.         foo=sref_multi_send('Part 3 is done','text/plain','ME')
  111.         foo=sref_multi_send('good bye','text/plain','E')
  112.  
  113. A 5 piece single part document:
  114.         foo=sref_multi_send(' This is the first line,'text/plain','1S')
  115.         foo=sref_multi_send(' This is line 2 ','text/plain','1A')
  116.         foo=sref_multi_send(' This is line 3 ','text/plain','1A')
  117.         foo=sref_multi_send(' This is line 4 ','text/plain','1A')
  118.         foo=sref_multi_send(' This is the last line  ','text/plain','1E')
  119.  
  120. Simple usage:
  121.         foo=sref_multi_send('<h2>Technical Notes</h2>')
  122.            is the same as
  123.         foo=sref_multi_send('<h2>Technical Notes</h2>',,'A')
  124.         (note that the second argument is ignored when howsend='A')
  125.  
  126. For a longer example, see http://www.srehttp.org/addons/multsend?
  127.  
  128.  
  129. II. Technical Notes 
  130.  
  131.  
  132. Multi-Part Documents:
  133.   When ever you issue a S (or SS), M (or MS), or E (or ES) command,
  134.   SRE will assume that you are "starting a part" .  
  135.   Specifically, xS (x=S,M, or E) will start a new part of a  
  136.   "multi part document".  On the other hand, xE will close this part.
  137.  
  138.   Upon recieving a "new part", multipart aware browsers (such as 
  139.   netscape 2.0 and  above) will "remove old stuff". This might mean
  140.   clearing the screen (or frame); or clearing the box within
  141.   which an in-line image is drawn.
  142.  
  143.   In contrast, "A" means "add new content" -- it never generates a new
  144.   document.  "A" can be used with any browser, since it does
  145.   not require multi-part awareness. Note that using A with non-text 
  146.   information should work (i.e.; streaming audio), but has not 
  147.   been tested.
  148.  
  149.   Therefore, "animated" documents (or images) should be generated by
  150.   using:
  151.   1) "S" -- which sends the appropriate "this is a multi-part document" 
  152.             headers to the browser, as well as the file/string you specify, 
  153.   2) one one more "M"  --which sends a seperator line and the 
  154.                          file/string), and
  155.   3) "E" -- which sends the file/string, and closes the multi-part document.
  156.  
  157. If one of these (S, M, or E) will be sent in pieces (with each piece
  158. appended to previously sent portions of the "part"), then you should use 
  159. a series of xS, A ... A,xE (where x is S,M or E) calls.
  160.  
  161. Single Part Document Sent In Pieces:
  162.    Single part documents are more generally understood (by older
  163.    browsers). The calling sequence should be 1S, 1A,..,1A,1E.
  164.    Notes:
  165.      *    You can use a sequence of SS, A, SE to send-in-pieces
  166.           a single part document, but it's not recommended (GoServe
  167.           may not close the document properly)
  168.      *    As with multi-part documents, you can use as many "1A" calls 
  169.           as needed.
  170.      *    A '1' and a '1S' have the same effect (starting a "send in          
  171.           pieces" document).
  172.      *    You can NOT intermix "1x"  with "SX", "Mx", or "Ex".
  173.      *    You should always end a "send in pieces" document with
  174.           a '1E'.
  175.           
  176.    
  177.    
  178. Expiration note:
  179.  
  180.    As of ver 1.3a, the FIX_EXPIRE "correction" is automatically handled
  181.    when SREF_MULTI_SEND is first invoked (with a '1S', 'S', or 'SS').
  182.  
  183.  
  184.         
  185.  
  186.