Annotation of embedaddon/libpdel/http/servlet/http_servlet_xmlrpc.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_servlet_xmlrpc.3,v 1.17 2004/06/02 17:24:37 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt HTTP_SERVLET_XMLRPC 3
42: .Os
43: .Sh NAME
44: .Nm http_servlet_xmlrpc
45: .Nd HTTP servlet for XML-RPC requests
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: .In pdel/http/servlet/xmlrpc.h
56: .Ft "struct http_servlet *"
57: .Fn http_servlet_xmlrpc_create "const struct http_servlet_xmlrpc_info *info" "void *arg" "void (*destroy)(void *)"
58: .Sh DESCRIPTION
59: .Fn http_servlet_xmlrpc_create
60: creates a new servlet that handles XML-RPC HTTP requests.
61: The request and response data are automatically converted to and
62: from native binary format using the
63: .Xr structs 3
64: library.
65: .Pp
66: The
67: .Fa arg
68: is an opaque user cookie.
69: When the servlet is destroyed, if
70: .Fa destroy
71: is not
72: .Dv NULL ,
73: it will be invoked with
74: .Fa arg
75: as its parameter.
76: .Fa info
77: is a pointer to a
78: .Li "struct http_servlet_xmlrpc_info" ,
79: which contains a pointer to an array of
80: .Li "http_servlet_xmlrpc_method"
81: structures:
82: .Pp
83: .Bd -literal -compact -offset 3n
84: struct http_servlet_xmlrpc_method {
85: const char *name; /* method name */
86: http_servlet_xmlrpc_handler_t *handler; /* method handler */
87: const struct structs_type **ptypes; /* parameter types */
88: u_int min_params; /* min # params */
89: u_int max_params; /* max # params */
90: };
91:
92: struct http_servlet_xmlrpc_info {
93: const struct http_servlet_xmlrpc_method
94: *methods; /* methods */
95: http_logger_t *logger; /* loggging function */
96: };
97: .Ed
98: .Pp
99: The
100: .Fa methods
101: field points to the method descriptor array, which is terminated
102: with an entry having a
103: .Dv NULL
104: .Fa name .
105: .Pp
106: The
107: .Fa logger
108: is a logging function whose type is defined in
109: .Xr http_server 3 .
110: .Pp
111: Each element in the
112: .Fa methods
113: array describes one supported XML-RPC method:
114: .Fa name
115: is the method name;
116: .Fa min_params
117: and
118: .Fa max_params
119: specify the minimum and maximum number of parameters allowed for the method
120: (the servlet itself enforces these limits); and
121: .Fa ptypes
122: points to an array of
123: .Xr structs 3
124: types that has length
125: .Fa max_params ,
126: one for each possible parameter.
127: .Pp
128: The
129: .Fa handler
130: is a pointer to the user function that implements the XML-RPC method.
131: The function must be of this type:
132: .Pp
133: .Bd -literal -compact -offset 3n
134: typedef void *http_servlet_xmlrpc_handler_t(void *arg,
135: const char *method, struct http_request *req,
136: u_int nparams, const void **params, const char *mtype,
137: const struct structs_type **rtypep, int *faulted)
138: .Ed
139: .Pp
140: The
141: .Fa arg
142: is the opqaue cookie supplied to
143: .Fn http_servlet_xmlrpc_create ;
144: .Fa method
145: is the XML-RPC method name;
146: .Fa req
147: is the HTTP request object; and
148: .Fa params
149: points to an array of
150: .Fa nparams
151: pointers to the XML-RPC request parameters in native binary format.
152: .Fn handler
153: should not free the parameters.
154: .Pp
155: If successful,
156: .Fn handler
157: should allocate a region of memory with
158: .Xr typed_mem 3
159: type
160: .Fa mtype ,
161: initialize it with the response value in native binary format, and
162: return a pointer to it.
163: The
164: .Xr structs 3
165: type of the returned memory region must be stored in
166: .Fa "*rtypep".
167: .Pp
168: Since it's running as a servlet, the thread executing
169: .Fn handler
170: may be canceled at any cancellation point.
171: .Fn handler
172: should be written so as to not leak resources if this happens.
173: .\"
174: .Ss Returning Faults
175: .\"
176: If
177: .Fn handler
178: wishes to return an XML-RPC fault, it should set
179: .Fa "*faulted"
180: to one, return a pointer to a
181: .Li "struct structs_xmlrpc_fault"
182: structure, and set
183: .Fa "*rtypep"
184: to
185: .Va "&structs_type_xmlrpc_fault" .
186: .Pp
187: .Fn handler
188: may also return
189: .Dv NULL
190: and set
191: .Va errno ,
192: in which case an XML-RPC fault will be created using
193: .Va errno
194: as the fault code and
195: .Fn strerror errno
196: as the fault string.
197: .\"
198: .Ss Working With Raw XML-RPC
199: .\"
200: In some cases, the types of the XML-RPC parameters are not known
201: ahead of time, or it may be inconvenient to have to provide a
202: .Xr structs 3
203: type for the returned value.
204: In these situations,
205: .Fn handler
206: can operate with the XML-RPC parameters and/or response values in their raw,
207: .Dq exploded
208: forms.
209: .Pp
210: If
211: .Fa ptypes
212: is
213: .Dv NULL ,
214: then all of the parameters passed to
215: .Fn handler
216: via
217: .Fa params
218: are instances of the
219: .Xr structs 3
220: type
221: .Va structs_type_xmlrpc_value ,
222: i.e., every parameter is a
223: .Li "struct xmlrpc_value_union" ,
224: defined in
225: .Pa "<pdel/structs/xmlrpc.h>" .
226: .Pp
227: If
228: .Fn handler
229: returns a non-NULL result but sets
230: .Fa "*rtypep"
231: to
232: .Dv NULL ,
233: then the returned result is assumed to be an instance of the
234: .Xr structs 3
235: type
236: .Va structs_type_xmlrpc_value ,
237: i.e., a
238: .Li "struct xmlrpc_value_union" .
239: .Pp
240: Finally, if the method names themselves are not known ahead of time, a
241: .Fa name
242: equal to the empty string will match all method names.
243: Such an entry acts as a
244: .Dq "catch all"
245: and must be last in the
246: .Fa methods
247: list.
248: .Sh RETURN VALUES
249: On failure,
250: .Fn http_servlet_xmlrpc_create
251: returns
252: .Dv NULL
253: and sets
254: .Va errno
255: to an appropriate value.
256: .Sh SEE ALSO
257: .Xr http_request 3 ,
258: .Xr http_response 3 ,
259: .Xr http_server 3 ,
260: .Xr http_servlet 3 ,
261: .Xr http_servlet_xml 3 ,
262: .Xr http_xml 3 ,
263: .Xr libpdel 3 ,
264: .Xr structs 3 ,
265: .Xr structs_xmlrpc 3 ,
266: .Xr typed_mem 3
267: .Rs
268: .%T "XML-RPC Home Page"
269: .%O "http://www.xmlrpc.org/"
270: .Re
271: .Sh HISTORY
272: The PDEL library was developed at Packet Design, LLC.
273: .Dv "http://www.packetdesign.com/"
274: .Sh AUTHORS
275: .An Archie Cobbs Aq archie@freebsd.org
276: .Sh BUGS
277: .Fn http_servlet_xmlrpc_create
278: copies all information in
279: .Fa info
280: except each method's parameter
281: .Xr structs 3
282: types (pointed to by the elements of the
283: .Fa ptypes
284: array), so these must remain valid for the lifetime of the servlet.
285: Typically
286: .Xr structs 3
287: types are stored in static variables, so this is not usually a problem.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_servlet_xmlrpc.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 / servlet