http_client
—
threaded client for HTTP and HTTPS
PDEL Library (libpdel, -lpdel)
#include
<sys/types.h>
#include
<stdio.h>
#include
<netinet/in.h>
#include
<openssl/ssl.h>
#include
<pdel/http/http_defs.h>
#include
<pdel/http/http_server.h>
struct http_client *
http_client_create
(
struct
pevent_ctx *ctx,
const char
*user_agent,
u_int max_conn,
u_int max_cache,
u_int
max_cache_idle,
http_logger_t
*logger);
int
http_client_destroy
(
struct
http_client **clientp);
struct http_client_connection *
http_client_connect
(
struct
http_client *client,
struct in_addr
ip,
u_int16_t
port,
int
https);
struct in_addr
http_client_get_local_ip
(
struct
http_client_connection *cc);
u_int16_t
http_client_get_local_port
(
struct
http_client_connection *cc);
struct http_request *
http_client_get_request
(
struct
http_client_connection *client);
struct http_response *
http_client_get_response
(
struct
http_client_connection *client);
void
http_client_close
(
struct
http_client_connection **cconp);
const char *
http_client_get_reason
(
struct
http_client_connection *ccon);
These functions implement threaded HTTP clients, supporting SSL and HTTP
keep-alive.
An HTTP client (represented by a
struct http_client
) can
be used to make multiple simultaneous individual HTTP connections (each
corresponding to a single HTTP request/reply pair and represented by a
struct http_client_connection
). To reduce overhead, a
client will cache TCP connections to each remote server and reuse TCP
connections for subsequent requests, using the HTTP keep-alive mechanism.
http_client_create
() creates a new HTTP
client.
ctx is a
pevent(3)
event context. The
user_agent string is used
for the "User-Agent:" HTTP header.
max_conn limits the number of active
connections that may exist simultaneously.
max_cache is the maximum number of server TCP
sessions that the client may cache (or zero to disable caching), and
max_cache_idle is the maximum idle time for
cached TCP sessions, after which they are closed.
max_cache must be strictly less than
max_conn. The
logger, if not
NULL,
specifies a callback for logging:
typedef void http_logger_t(int sev, const char *fmt, ...);
Here
sev is a
syslog(3)
severity level.
http_client_destroy
() attempts to destroy an
HTTP client. If there are still active connections (i.e., connections for
which
http_client_close
() has yet to be
called), then
http_client_destroy
() will
fail and return -1 with
errno set to
EBUSY.
Otherwise, upon return
*clientp is set to
NULL.
If
*clientp is already
NULL
when
http_client_destroy
() is invoked, nothing
happens.
http_client_connect
() creates a new HTTP
connection associated with
client. If there
are already
max_conn active connections, then
http_client_connect
() will block until a
connection becomes free. The new connection is initiated to the HTTP (or HTTPS
if
https is non-zero) server at IP address
ip and port
port.
http_client_get_local_ip
() and
http_client_get_local_port
() return the
local IP address and port used for the connection, respectively.
http_client_get_request
() and
http_client_get_response
() return the HTTP
request and response objects associated with the connection (see
http_request(3)
and
http_response(3)).
http_client_close
() closes and frees a
connection. If caching is enabled and the remote server supports keep-alive,
the connection will cached for up to
max_cache_idle seconds. Upon return,
*cconp is set to
NULL.
If
*cconp is already
NULL
when
http_client_close
() is invoked, nothing
happens.
If
http_client_get_response
() returns
NULL
(for example, the server sent back a
malformed response), then
http_client_get_reason
() may be used to
retrieve an explanatory error string. The string is only valid until
http_client_close
() is invoked.
Upon error,
http_client_create
(),
http_client_connect
(), and
http_client_get_response
() return
NULL
and set
errno to an appropriate value.
http_mime(3),
http_request(3),
http_response(3),
http_server(3),
http_xml(3),
libpdel(3),
pevent(3),
syslog(3)
R. Fielding,
J. Gettys, J. Mogul,
H. Frystyk, L. Masinter,
P. Leach, and T.
Berners-Lee, Hypertext Transfer Protocol --
HTTP/1.1, RFC 2616.
The PDEL library was developed at Packet Design, LLC.
http://www.packetdesign.com/
Archie Cobbs
⟨archie@freebsd.org⟩
Support for validating a server's SSL certificates against a list of known,
trusted certificate authorities should be added.