Description || View SENDFILE.CNT

### Demo of the SendFile SREhttp/2 Utility

Enter one, two, or three selectors -- the files these selectors point to will be sequentially sent to your browser (with an optional pause between each file).

Selector to retrieve: | Wait 5 seconds after sending this file?
Selector to retrieve: | Wait 5 seconds after sending this file?
Selector to retrieve: | Wait 5 seconds after sending this file?

Options...

- Record request info to the SENDFILE log file.
- Send all files as `text/plain` mimetype?
  Send all files as `application/octet-stream` mimetype?
- Close connection as soon as last file is sent?
- Additional response headers:

### Description of SendFile

SendFile is an SREhttp/2 utility that can be used to send a file to a client, given that the file is associated with a URI. It's advantages over the use of standard URLS are several:

- You can use `SendFile` to push several files in a row.
- SendFile keeps an accurate count of successful file transfers in special SREhttp/2 counter file (SENDFILE.CNT). By accurate, we mean that unsuccessful transfer (say, due to a prematurely broken connection) will not be counted.
- You can easily specify a few options, such as an extra response header

Syntax:
SENDFILE is invoked with a request selector of the form:
`/SENDFILE?file=selector&force=1&header=response_header&pause=nsecs&nowait=j&log=1`

SENDFILE will ...

1. Check for the existence of a file corresponding to the `selector` (the file that the `selector` maps to is assumed to be relative to a possibly host-specific data directory or relative to a possibly host-specific virtual directory).
2. Send the file to the client
3. If the entire file was sent, the "count of requests" for this `selector` is augmented. That is, if the client killed the connection half way through, the count will not be augmented.
4. Optionally, SENDFILE can record the particulars of this transaction (such as the client address and the current time) to the SENDFILE log file.

#### Notes

- `HEADER`: The values of `HEADER=` options are used as additional response headers.
  Examples:
- `SENDFILE?file=foo.bar&HEADER=refresh:+2+;+url=/sample/thanku.htm`
  would cause a `Refresh: 2 ; url=/sample/thanku.htm`
  response header to be sent (2 seconds after SENDFILE transmits the file, the browser will then request /sample/thanku.htm )

- `&HEADER=content-disposition:+attachment;+filename="spiffy.2"&file=foo.bar`
  would cause a `Content-disposition: attachment; filename="spiffy.2"` to be sent (the "save file as" box will offer spiffy.2 as the default filename)
  Note that the value of a HEADER= option must be URL encoded (i.e.; + characters used for spaces).

- If more then one `FILE=selector` option appears, then SENDFILE will attempt to send each of the files (that the `selector`s map to) to the client without requiring further mouse clicks.

  This does require a browser that can handle multipart-mixed documents -- for example, Netscape 2.0 and above.

  > Example:`/SENDFILE?file=/dir1/hello.htm&file=/download/spiffy.zip&file=/dir1/thanks.htm`.

  > First, `/dir1/hello.htm` is sent to the client; which is immediately followed by `/download/spiffy.zip` (the client will almost certainly be asked to provide a name to save spiffy.zip as). After spiffy.zip has been transmitted, `/dir1/thanks.htm` will be sent.

- As a shortcut, you do not need to specify the `FILE=` -- an option with no = is assumed to be a FILE= option. For example, `SENDFILE?samples/intro.doc` is equivalent to `SENDFILE?file=samples/intro.doc`

- `NOWAIT=1` instructs the server to close the connection immediately after the final file is sent. For some older browsers, this removes the tedious wait time associated with maintaining an open connection.

- `LOG=1` instructs SENDFILE to record the particulars of this transaction to the SENDFILE log file. Specifically, the host-nickname, the selector, the requesting client's IP address, the current time, and the size of the file. If you do not include `LOG=1`, of if you use `LOG=0`, then the request will not be recorded in the SENDFILE log file.

  Note that a single log file is used, so information on all requests using SENDFILE will be commingled. That is, no attempt is made to keep information seperated on a selector (or file) specific basis.

- `PAUSE=jsec` will pause the server for jsec seconds. This is typically used between `FILE=` statments, so as to put a slight pause between the end of one file and when it is overwritten by the next file.
  Caution: the use of many, or long, jsec values may cause the total amount of time allocated to a request (as set by the LIMITTIMETOTAL parameter) to be exceeded -- in which case the connection will be terminated.

- If `FORCE=1`, (or `FORCE=TEXT`) SENDFILE will assume that all files are of mime-type `text/plain`. This can be a useful trick (it tricks the client into displaying everything as a text file), but if .GIF (or other non-text files) are chosen, garbage will be displayed ( use this option with discretion)!

- If `FORCE=2` (or `FORCE=BIN`), SENDFILE will assume that all files are of mime-type `application/octet-stream`. This can be used to induce a browser to save a file to disk (rather then display it).

- If the client breaks the connection before the a file is completely sent, the SENDFILE.CNT counter file will not be updated
- By default, this SENDFILE.CNT file is located in the SREHTTP2\WORKDATA directory (along with the HITS.CNT and REQUESTS.CNT files).

- If multiple files are sent, the counter for each one (in SENDFILE.CNT) is individually augmented.

- The selector(s) requested in the `FILE` options are all checked for access control restrictions -- selector specific access controls, and `HTACCESS` access controls, are checked. If any of the requested files require require privileges (or a username) the client does not have, none of the files will be sent.

- On multiple file sends, SREhttp2 will first check that the browser understands multipart-mixed documents (it looks for a connection: request header, or if the browser claims to be http/1.1 compliant). If the browser can not handle such documents, an error message is returned.

- SENDFILE makes extensive use of the SREH2_MULTI_SEND procedure.