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

call-with-input-request uri-or-request writer readerprocedure

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:, 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:

This indicates the file to read from. Can be either a string or a port. This must be specified, everything else is optional.
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.
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 client-error 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 client-error form-data-error) will be raised.