NAME

http_client — threaded client for HTTP and HTTPS

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS

#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);

DESCRIPTION

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.

RETURN VALUES

Upon error, http_client_create(), http_client_connect(), and http_client_get_response() return NULL and set errno to an appropriate value.

HISTORY

The PDEL library was developed at Packet Design, LLC. http://www.packetdesign.com/

AUTHORS

Archie Cobbs ⟨archie@freebsd.org⟩

BUGS

Support for validating a server's SSL certificates against a list of known, trusted certificate authorities should be added.