Annotation of embedaddon/libpdel/http/http_client.3, revision 1.1
1.1 ! misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
! 2: .\" All rights reserved.
! 3: .\"
! 4: .\" Subject to the following obligations and disclaimer of warranty,
! 5: .\" use and redistribution of this software, in source or object code
! 6: .\" forms, with or without modifications are expressly permitted by
! 7: .\" Packet Design; provided, however, that:
! 8: .\"
! 9: .\" (i) Any and all reproductions of the source or object code
! 10: .\" must include the copyright notice above and the following
! 11: .\" disclaimer of warranties; and
! 12: .\" (ii) No rights are granted, in any manner or form, to use
! 13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
! 14: .\" on advertising, endorsements, or otherwise except as such
! 15: .\" appears in the above copyright notice or in the software.
! 16: .\"
! 17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
! 18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
! 19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
! 20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
! 21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
! 22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
! 23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
! 24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
! 25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
! 26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
! 27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
! 28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
! 29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
! 30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
! 31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
! 32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
! 33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
! 34: .\" THE POSSIBILITY OF SUCH DAMAGE.
! 35: .\"
! 36: .\" Author: Archie Cobbs <archie@freebsd.org>
! 37: .\"
! 38: .\" $Id: http_client.3,v 1.10 2004/06/02 17:24:36 archie Exp $
! 39: .\"
! 40: .Dd April 22, 2002
! 41: .Dt HTTP_CLIENT 3
! 42: .Os
! 43: .Sh NAME
! 44: .Nm http_client
! 45: .Nd threaded client for HTTP and HTTPS
! 46: .Sh LIBRARY
! 47: PDEL Library (libpdel, \-lpdel)
! 48: .Sh SYNOPSIS
! 49: .In sys/types.h
! 50: .In stdio.h
! 51: .In netinet/in.h
! 52: .In openssl/ssl.h
! 53: .In pdel/http/http_defs.h
! 54: .In pdel/http/http_server.h
! 55: .Ft "struct http_client *"
! 56: .Fn 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"
! 57: .Ft "int"
! 58: .Fn http_client_destroy "struct http_client **clientp"
! 59: .Ft "struct http_client_connection *"
! 60: .Fn http_client_connect "struct http_client *client" "struct in_addr ip" "u_int16_t port" "int https"
! 61: .Ft "struct in_addr"
! 62: .Fn http_client_get_local_ip "struct http_client_connection *cc"
! 63: .Ft u_int16_t
! 64: .Fn http_client_get_local_port "struct http_client_connection *cc"
! 65: .Ft "struct http_request *"
! 66: .Fn http_client_get_request "struct http_client_connection *client"
! 67: .Ft "struct http_response *"
! 68: .Fn http_client_get_response "struct http_client_connection *client"
! 69: .Ft "void"
! 70: .Fn http_client_close "struct http_client_connection **cconp"
! 71: .Ft "const char *"
! 72: .Fn http_client_get_reason "struct http_client_connection *ccon"
! 73: .Sh DESCRIPTION
! 74: These functions implement threaded HTTP clients, supporting SSL and
! 75: HTTP keep-alive.
! 76: .Pp
! 77: An HTTP client (represented by a
! 78: .Li "struct http_client")
! 79: can be used to make multiple simultaneous individual HTTP connections
! 80: (each corresponding to a single HTTP request/reply pair and represented by a
! 81: .Li "struct http_client_connection") .
! 82: To reduce overhead, a client will cache TCP connections to each remote
! 83: server and reuse TCP connections for subsequent requests, using the
! 84: HTTP keep-alive mechanism.
! 85: .Pp
! 86: .Fn http_client_create
! 87: creates a new HTTP client.
! 88: .Fa ctx
! 89: is a
! 90: .Xr pevent 3
! 91: event context.
! 92: The
! 93: .Fa user_agent
! 94: string is used for the "User-Agent:" HTTP header.
! 95: .Fa max_conn
! 96: limits the number of active connections that may exist simultaneously.
! 97: .Fa max_cache
! 98: is the maximum number of server TCP sessions that the client may cache
! 99: (or zero to disable caching), and
! 100: .Fa max_cache_idle
! 101: is the maximum idle time for cached TCP sessions, after which they are closed.
! 102: .Fa max_cache
! 103: must be strictly less than
! 104: .Fa max_conn .
! 105: The
! 106: .Fa logger ,
! 107: if not
! 108: .Dv NULL,
! 109: specifies a callback for logging:
! 110: .Pp
! 111: .Bd -literal -offset 3n
! 112: typedef void http_logger_t(int sev, const char *fmt, ...);
! 113: .Ed
! 114: .Pp
! 115: Here
! 116: .Fa sev
! 117: is a
! 118: .Xr syslog 3
! 119: severity level.
! 120: .Pp
! 121: .Fn http_client_destroy
! 122: attempts to destroy an HTTP client.
! 123: If there are still active connections (i.e., connections for which
! 124: .Fn http_client_close
! 125: has yet to be called), then
! 126: .Fn http_client_destroy
! 127: will fail and return -1 with
! 128: .Va errno
! 129: set to
! 130: .Er EBUSY.
! 131: Otherwise, upon return
! 132: .Fa "*clientp"
! 133: is set to
! 134: .Dv NULL.
! 135: If
! 136: .Fa "*clientp"
! 137: is already
! 138: .Dv NULL
! 139: when
! 140: .Fn http_client_destroy
! 141: is invoked, nothing happens.
! 142: .Pp
! 143: .Fn http_client_connect
! 144: creates a new HTTP connection associated with
! 145: .Fa client .
! 146: If there are already
! 147: .Fa max_conn
! 148: active connections, then
! 149: .Fn http_client_connect
! 150: will block until a connection becomes free.
! 151: The new connection is initiated to the HTTP (or HTTPS if
! 152: .Fa https
! 153: is non-zero) server at IP address
! 154: .Fa ip
! 155: and port
! 156: .Fa port .
! 157: .Pp
! 158: .Fn http_client_get_local_ip
! 159: and
! 160: .Fn http_client_get_local_port
! 161: return the local IP address and port used for the connection, respectively.
! 162: .Pp
! 163: .Fn http_client_get_request
! 164: and
! 165: .Fn http_client_get_response
! 166: return the HTTP request and response objects associated with the
! 167: connection (see
! 168: .Xr http_request 3
! 169: and
! 170: .Xr http_response 3) .
! 171: .Pp
! 172: .Fn http_client_close
! 173: closes and frees a connection.
! 174: If caching is enabled and the remote server supports keep-alive,
! 175: the connection will cached for up to
! 176: .Fa max_cache_idle
! 177: seconds.
! 178: Upon return,
! 179: .Fa "*cconp"
! 180: is set to
! 181: .Dv NULL.
! 182: If
! 183: .Fa "*cconp"
! 184: is already
! 185: .Dv NULL
! 186: when
! 187: .Fn http_client_close
! 188: is invoked, nothing happens.
! 189: .Pp
! 190: If
! 191: .Fn http_client_get_response
! 192: returns
! 193: .Dv NULL
! 194: (for example, the server sent back a malformed response), then
! 195: .Fn http_client_get_reason
! 196: may be used to retrieve an explanatory error string.
! 197: The string is only valid until
! 198: .Fn http_client_close
! 199: is invoked.
! 200: .Sh RETURN VALUES
! 201: Upon error,
! 202: .Fn http_client_create ,
! 203: .Fn http_client_connect ,
! 204: and
! 205: .Fn http_client_get_response
! 206: return
! 207: .Dv NULL
! 208: and set
! 209: .Va errno
! 210: to an appropriate value.
! 211: .Sh SEE ALSO
! 212: .Xr http_mime 3 ,
! 213: .Xr http_request 3 ,
! 214: .Xr http_response 3 ,
! 215: .Xr http_server 3 ,
! 216: .Xr http_xml 3 ,
! 217: .Xr libpdel 3 ,
! 218: .Xr pevent 3 ,
! 219: .Xr syslog 3
! 220: .Rs
! 221: .%A R. Fielding
! 222: .%A J. Gettys
! 223: .%A J. Mogul
! 224: .%A H. Frystyk
! 225: .%A L. Masinter
! 226: .%A P. Leach
! 227: .%A T. Berners-Lee
! 228: .%T "Hypertext Transfer Protocol -- HTTP/1.1"
! 229: .%O RFC 2616
! 230: .Re
! 231: .Sh HISTORY
! 232: The PDEL library was developed at Packet Design, LLC.
! 233: .Dv "http://www.packetdesign.com/"
! 234: .Sh AUTHORS
! 235: .An Archie Cobbs Aq archie@freebsd.org
! 236: .Sh BUGS
! 237: Support for validating a server's SSL certificates against a list of
! 238: known, trusted certificate authorities should be added.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_client.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / http