Annotation of embedaddon/libpdel/http/http_client.3, revision 1.1.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