Annotation of embedaddon/libpdel/http/servlet/http_servlet_xmlrpc.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_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