chickadee » http-client » call-with-input-request

This procedure is a convenience wrapper around call-with-response.

It is much less strict - uri-or-request can be an intarweb request object, but also an uri-common object or even a string with the URI in it, in which case a request object will be automatically constructed around the URI, using the GET method when writer is #f or the POST method when writer is not #f.

writer can be either #f (in which case nothing is written and the GET method chosen), a string containing the raw data to send, an alist, or a procedure that accepts a port and writes the response data to it. If you supply a procedure, do not forget to set the content-length header! In the other cases, whenever possible, the length is calculated and the header automatically set for you.

If you supplied an alist, the content-type header is automatically set to application/x-www-form-urlencoded unless there's an alist entry whose value is a list starting with the keyword file: or data:, in which case multipart/form-data is used. See the examples for with-input-from-request below. If the data cannot be form-encoded, a condition of type (exn http formdata-error) is raised.

reader is either #f or a procedure which accepts a port and reads out the data. If there is data left in the port when the reader returns (or #f was supplied), this will be automatically discarded to avoid problems.

Returns three values: The result of the call to reader (or #f if there is no message body in the response), the request-uri of the last request and the response object. If the response code is not in the 200 class, it will raise a condition of type (exn http client-error), (exn http server-error) or (exn http unexpected-server-response), depending on the response code. This includes 404 not found (which is a client-error).

If there is no response body to read (as determined by intarweb's response-has-message-body-for-request?), the reader procedure is not invoked at all.

When posting multipart form data, the value of a file entry is a list of keyword-value pairs. The following keywords are recognised:

One of the following two must be specified:

file:

This indicates a file to read from. Can be either a string (filename to read from) or any type of input port (see below).

data:

This indicates a string to send. This can be used to force multipart even if only sending static string data.

These are optional:

filename:

This indicates the filename to pass on to the server. If not specified or #f, the file:'s string (or port-name in case of a port) will be used.

headers:

Additional headers to send for this entry (an intarweb headers-object).

If the URI argument is not a valid URI, a condition of type (exn http bad-uri) will be raised.

If the writer is a list it is taken to be form-data, but if the encoding fails, a condition of type (exn http form-data-error) will be raised.

NOTE: If file: is used, retrying the request is not supported. The port will have been consumed after the first request. That means that max-redirect-depth, max-retry-attempts and retry-request? are effectively useless. When a request would be retried and a port is found to be already consumed, a condition of type (exn http port-already-consumed) will be raised.