Sends an HTTP
request to a web server and returns its reply.
uri is where the request is sent to,
and it is either a string denoting a uniform resource
identifier or a PURI:URI object. The scheme
of uri must be `http' or `https'.
The function returns SEVEN values - the body of the
reply0 (but see below), the status
code1 as an integer, an alist of the
headers2 sent by the server where for each
element the car (the name of the header) is a keyword and
the cdr (the value of the header) is a string, the
uri3 the reply comes from (which might be
different from the uri the request
was sent to in case of redirects), the stream4
the reply was read from, a generalized boolean5
which denotes whether the stream should be closed (and
which you can usually ignore), and finally the reason
phrase6 from the status line as a string.
protocol is the HTTP protocol version
which is going to be used in the request line. It must be
one of the keywords :HTTP/1.0 or
:HTTP/1.1.
method is the method used in the
request line, a keyword (like :GET or
:HEAD) denoting a valid HTTP/1.1 or WebDAV
request method, or :REPORT, as described in
the Versioning Extensions to WebDAV. Additionally, you
can also use the pseudo method :OPTIONS*
which is like :OPTIONS but means that an
"OPTIONS *" request line will be sent, i.e. the
uri's path and query parts will be
ignored.
If force-ssl is true, SSL will be
attached to the socket stream which connects Drakma with
the web server. Usually, you don't have to provide this
argument, as SSL will be attached anyway if the scheme of
uri is `https'.
certificate is the file name of the PEM
encoded client certificate to present to the server when
making a SSL connection. key specifies
the file name of the PEM encoded private key matching the
certificate. certificate-password
specifies the pass phrase to use to decrypt the private key.
verify can be specified to force
verification of the certificate that is presented by the
server in an SSL connection. It can be specified either
as NIL if no check should be performed,
:OPTIONAL to verify the server's certificate
if it presented one or :REQUIRED to verify
the server's certificate and fail if an invalid or no
certificate was presented.
max-depth can be specified to change
the maximum allowed certificate signing depth that is
accepted. The default is 10.
ca-file and
ca-directory can be specified to set
the certificate authority bundle file or directory to use
for certificate validation.
The certificate,
key,
certificate-password,
verify,
max-depth,
ca-file and
ca-directory parameters are ignored
for non-SSL requests. They are also ignored on LispWorks.
parameters is an alist of name/value
pairs (the car and the cdr each being a string) which
denotes the parameters which are added to the query part
of the URL or (in the case of a POST request) comprise the
body of the request. (But see
content below.) The values can also
be NIL in which case only the name (without
an equal sign) is used in the query string. The
name/value pairs are URL-encoded using the FLEXI-STREAMS
external format external-format-out
before they are sent to the server unless
form-data is true in which case the
POST request body is sent as `multipart/form-data' using
external-format-out. The values of
the parameters alist can also be
pathnames, open binary input streams, unary functions, or
lists where the first element is of one of the former
types. These values denote files which should be sent as
part of the request body. If files are present in
parameters, the content type of the
request is always `multipart/form-data'. If the value is
a list, the part of the list behind the first element is
treated as a plist which can be used to specify a content
type and/or a filename for the file, i.e. such a value
could look like, e.g., (#p"/tmp/my_file.doc"
:content-type "application/msword" :filename
"upload.doc").
url-encoder specifies a custom URL
encoder function which will be used by drakma to
URL-encode parameter names and values. It needs to be a
function of two arguments. The arguments are the string
to encode and the external format to use (as accepted by
FLEXI-STREAMS:STRING-TO-OCTETS). The return value must be
the URL-encoded string. This can be used if specific
encoding rules are required.
content, if not NIL, is
used as the request body - parameters
is ignored in this case. content can
be a string, a sequence of octets, a pathname, an open
binary input stream, or a function designator. If
content is a sequence, it will be
directly sent to the server (using
external-format-out in the case of
strings). If content is a pathname,
the binary contents of the corresponding file will be sent
to the server. If content is a
stream, everything that can be read from the stream until
EOF will be sent to the server. If
content is a function designator, the
corresponding function will be called with one argument,
the stream to the server, to which it should send data.
Finally, content can also be the
keyword :CONTINUATION in which case
HTTP-REQUEST returns only one value -
a `continuation' function. This function has one required
argument and one optional argument. The first argument
will be interpreted like content
above (but it cannot be a keyword), i.e. it will be sent
to the server according to its type. If the second
argument is true, the continuation function can be called
again to send more content, if it is NIL the
continuation function returns what
HTTP-REQUEST would have returned.
If content is a sequence, Drakma will
use LENGTH to determine its length and will use the result
for the `Content-Length' header sent to the server. You
can overwrite this with the
content-length parameter (a
non-negative integer) which you can also use for the cases
where Drakma can't or won't determine the content length
itself. You can also explicitly provide a
content-length argument of
NIL which will imply that no `Content-Length'
header will be sent in any case. If no `Content-Length'
header is sent, Drakma will use chunked encoding to send
the content body. Note that this will not work with older
web servers.
Providing a true content-length
argument which is not a non-negative integer means that
Drakma /must/ build the request body in RAM and compute
the content length even if it would have otherwise used
chunked encoding, for example in the case of file uploads.
content-type is the corresponding
`Content-Type' header to be sent and will be ignored
unless content is provided as well.
Note that a query already contained in
uri will always be sent with the
request line anyway in addition to other parameters sent
by Drakma.
cookie-jar is a cookie jar containing
cookies which will potentially be sent to the server (if
the domain matches, if they haven't expired, etc.) - this
cookie jar will be modified according to the `Set-Cookie'
header(s) sent back by the server.
basic-authorization, if not
NIL, should be a list of two strings
(username and password) which will be sent to the server
for basic authorization.
user-agent, if not NIL,
denotes which `User-Agent' header will be sent with the
request. It can be one of the keywords
:DRAKMA, :FIREFOX,
:EXPLORER, :OPERA, or
:SAFARI which denote the current version of
Drakma or, in the latter four cases, a fixed string
corresponding to a more or less recent (as of August 2006)
version of the corresponding browser. Or it can be a
string which is used directly.
accept, if not NIL,
specifies the contents of the `Accept' header sent.
range optionally specifies a subrange
of the resource to be requested. It must be specified as
a list of two integers which indicate the start and
(inclusive) end offset of the requested range, in bytes
(i.e. octets).
If proxy is not NIL, it
should be a string denoting a proxy server through which
the request should be sent. Or it can be a list of two
values - a string denoting the proxy server and an integer
denoting the port to use (which will default to 80
otherwise). Defaults to
*default-http-proxy*.
proxy-basic-authorization is used
like basic-authorization, but for the
proxy, and only if proxy is true. If
the host portion of the uri is present in the
*NO-PROXY-DOMAINS* or the
NO-PROXY-DOMAINS list then the proxy
setting will be ignored for this request.
If NO-PROXY-DOMAINS is set then it
will supersede the *NO-PROXY-DOMAINS*
variable. Inserting domains into this list will allow them
to ignore the proxy setting.
If real-host is not NIL,
request is sent to the denoted host instead of the
uri host. When specified,
real-host supersedes
proxy.
additional-headers is a name/value
alist of additional HTTP headers which should be sent with
the request. Unlike in parameters,
the cdrs can not only be strings but also designators for
unary functions (which should in turn return a string) in
which case the function is called each time the header is
written.
If redirect is not NIL,
it must be a non-negative integer or T. If
redirect is true, Drakma will follow
redirects (return codes 301, 302, 303, or 307) unless
redirect is 0. If
redirect is an integer, it will be
decreased by 1 with each redirect. Furthermore, if
auto-referer is true when following
redirects, Drakma will populate the `Referer' header with
the uri that triggered the
redirection, overwriting an existing `Referer' header (in
additional-headers) if necessary.
If keep-alive is T, the server will
be asked to keep the connection alive, i.e. not to close
it after the reply has been sent. (Note that this not
necessary if both the client and the server use HTTP 1.1.)
If close is T, the server is
explicitly asked to close the connection after the reply
has been sent. keep-alive and
close are obviously mutually
exclusive.
If the message body sent by the server has a text content
type, Drakma will try to return it as a Lisp string.
It'll first check if the `Content-Type' header denotes an
encoding to be used, or otherwise it will use the
external-format-in argument. The
body is decoded using FLEXI-STREAMS. If FLEXI-STREAMS
doesn't know the external format, the body is returned as
an array of octets. If the body is empty, Drakma will
return NIL.
If the message body doesn't have a text content type or if
force-binary is true, the body is
always returned as an array of octets.
If want-stream is true, the message
body is NOT read and instead the (open) socket stream is
returned as the first return value. If the sixth value of
HTTP-REQUEST is true, the stream
should be closed (and not be re-used) after the body has
been read. The stream returned is a flexi-stream
with a chunked stream as its underlying stream.
If you want to read binary data from this stream, read
from the underlying stream which you can get with
FLEXI-STREAM-STREAM.
Drakma will usually create a new socket connection for
each HTTP request. However, you can use the
stream argument to provide an open
socket stream which should be re-used.
stream MUST be a stream returned by a
previous invocation of HTTP-REQUEST
where the sixth return value wasn't true. Obviously, it
must also be connected to the correct server and at the
right position (i.e. the message body, if any, must have
been read). Drakma will NEVER attach SSL to a stream
provided as the stream argument.
connection-timeout is the time (in
seconds) Drakma will wait until it considers an attempt to
connect to a server as a failure. It is supported only on
some platforms (currently abcl, clisp, LispWorks, mcl,
openmcl and sbcl). READ-TIMEOUT and WRITE-TIMEOUT are the
read and write timeouts (in seconds) for the socket stream
to the server. All three timeout arguments can also be
NIL (meaning no timeout), and they don't
apply if an existing stream is re-used. READ-TIMEOUT
argument is only available for LispWorks, WRITE-TIMEOUT is
only available for LispWorks 5.0 or higher.
deadline, a time in the future,
specifies the time until which the request should be
finished. The deadline is specified in internal time
units. If the server fails to respond until that time, a
COMMUNICATION-DEADLINE-EXPIRED condition is signalled.
deadline is only available on CCL 1.2
and later.
If preserve-uri is not
NIL, the given uri will
not be processed. This means that the
uri will be sent as-is to the remote
server and it is the responsibility of the client to make
sure that all parameters are encoded properly. Note that
if this parameter is given, and the request is not a POST
with a content-type of `multipart/form-data',
parameters will not be used.
If decode-content is not
NIL, then the content will automatically be
decoded according to any encodings specified in the
Content-Encoding header. The actual decoding is done by
the decode-stream generic function,
and you can implement new methods to support additional
encodings. Any encodings in Transfer-Encoding, such as
chunking, are always performed.