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

FreeBSD Manual Pages

  
 
  

home | help 
HTTP_CLIENT(3)		    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	corre-
       sponding	 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 en-
       abled 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.

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	ports 15.0		April 22, 2002			HTTP_CLIENT(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=http_client_get_response&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help