GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
HTTP_CLIENT(3) FreeBSD Library Functions Manual HTTP_CLIENT(3)

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.
April 22, 2002 FreeBSD 13.1-RELEASE

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.