Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTTP_CLIENT(3)	       FreeBSD Library Functions Manual		HTTP_CLIENT(3)

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 subse-
     quent 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,	noth-
     ing 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 hap-
     pens.

     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.

SEE ALSO
     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.

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.

FreeBSD	13.0			April 22, 2002			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=http_client&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help