NAME

SYNOPSIS

($status, $resp, $http, $hdr_last_modified, $hdr_etag) =
http_request($sockref, $req, $path, $host, $auth, $close, $lastmodified, $etag);

$status =
http_status($http);

$sockref =
sock_open($proto, $host, $port, $sockref);

sock_close($sockref);

DESCRIPTION

http_request() sends a request over the network to a remote HTTP server using either the HTTPS or the HTTP protocols. It reads the response, parses certain types of response into simpler ones and returns the end result. http_request() takes as arguments $sockref, a reference to an open socket obtained from sock_open(); $req a hashref containing the request to be sent (see below); $path, the URL to be requested; $host, the host's domain name; $auth, a hashref to the access authorization information (again, below); $close, a boolean flag which indicates whether or not to close the socket after use; and $lastmodified and $etag, any ‘Last-Modified’ and ‘Etag’ header strings received from an earlier request on this URL. All arguments must be provided, except $lastmodified and $etag which may be ‘undef’ if they are not available.

http_request() formats the HTTP request and sends it to the remote server. It then reads the server's response. Both simple as well as chunked HTTP responses are accepted; if the server is sending a chunked response, http_request() performs multiple reads to obtain all chunks and combine them to a single response. The server's HTTP header status line as well as its ‘Last-Modified’ and ‘Etag’ headers, if any, are noted and returned a separate values.

Without $auth, $lastmodified or $etag parameters, http_request() can be used as a general-purpose HTTP interface to any web server. When $auth is provided, it adds an ‘Authorization:’ header. When $lastmodified is provided, an ‘If-Modified-Since:’ header is added. And when $etag is provided, an ‘If-None-Match:’ header is added if the request is a ‘PUT’.

http_status() takes a HTTP header status line as returned from http_request() and parses it, returning the numeric HTTP status value.

The socket functions sock_open() and sock_close() provide a robust, persistent socket management layer.

sock_open() takes a $proto argument which must be either ‘https’ or ‘http’, $host and $port arguments which indicate the host and network port of the socket to open, and $sockref, a socket reference. The final $sockref argument will usually be ‘undef’ but it can be a socket reference returned from a previous call to sock_open() for this same host and URL. This is used internally to maintain the illusion of a persistent socket over multiple HTTP requests to the same server. sock_open() opens the network socket. The $proto and $host arguments must be provided. $port will default to port 443 or 80 as given by $proto. If opened in ‘https’ mode, peer verification is performed; it should be noted that this requires properly configured SSL certificates in the system SSL directory.

sock_close() closes a socket opened by sock_open().

The sockets layer provides the illusion of a persistent socket between this device and the remote server. The persistent socket can be used for a single request such as when downloading an iCalendar calendar, or for repeated HTTP requests to obtain calendar principal, home-set, calendars and the actual calendar data during a CalDAV dialog. The sockets layer takes care of sockets being closed by servers after one or some number of requests or after a timeout and re-opens the socket as needed. It also detects when this device moves between networks and the local network address changes (e.g., following a laptop suspend/move/resume sequence), again re-opening any sockets that were in use.

DATA TYPES

The $auth hashref contains the following fields:

RETURN VALUES

http_status() returns the numeric status code value from the server HTTP status line (the 200 in the example above).

sock_open() returns a reference to an open socket or ‘undef’ if the socket could not be opened.

sock_close() does not return a value.

SEE ALSO

STANDARDS

HISTORY