Annotation of embedaddon/libpdel/http/http_xml.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_xml.3,v 1.7 2004/06/02 17:24:37 archie Exp $
! 39: .\"
! 40: .Dd April 22, 2002
! 41: .Dt HTTP_XML 3
! 42: .Os
! 43: .Sh NAME
! 44: .Nm http_xml_send ,
! 45: .Nm http_xml_send_xmlrpc ,
! 46: .Nd XML and XML-RPC requests over HTTP
! 47: .Sh LIBRARY
! 48: PDEL Library (libpdel, \-lpdel)
! 49: .Sh SYNOPSIS
! 50: .In sys/types.h
! 51: .In netinet/in.h
! 52: .In pdel/http/xml.h
! 53: .Ft int
! 54: .Fn http_xml_send "struct http_client *client" "struct in_addr ip" "u_int16_t port" "int https" "const char *urlpath" "const char *username" "const char *password" "const char *ptag" "const char *pattrs" "const struct structs_type *ptype" "const void *payload" "int pflags" "const char *rtag" "char **rattrsp" "const char *rattrs_mtype" "const struct structs_type *rtype" "void *reply" "int rflags" "structs_xmllog_t *rlogger"
! 55: .Ft int
! 56: .Fn http_xml_send_xmlrpc "struct http_client *client" "struct in_addr ip" "u_int16_t port" "int https" "const char *username" "const char *password" "const char *methodName" "u_int nparams" "const struct structs_type **ptypes" "const void **pdatas" "const struct structs_type *rtype" "void *reply" "struct xmlrpc_compact_fault *fault" "structs_xmllog_t *rlogger"
! 57: .Sh DESCRIPTION
! 58: These functions send and receive XML and XML-RPC over HTTP and HTTPS.
! 59: They are convenience wrappers around the
! 60: .Xr http_request 3 ,
! 61: .Xr http_response 3 ,
! 62: .Xr structx_xml_input 3 ,
! 63: .Xr structs_xml_output 3 ,
! 64: and
! 65: .Xr structs_xmlrpc 3
! 66: routines.
! 67: .Pp
! 68: .Fn http_xml_send
! 69: uses
! 70: .Fa client
! 71: to send an HTTP request for the URL path
! 72: .Fa urlpath
! 73: (which must being with a '/') to IP address
! 74: .Fa ip
! 75: and port
! 76: .Fa port .
! 77: If
! 78: .Fa https
! 79: is non-zero, an SSL (HTTPS) request is made.
! 80: The
! 81: .Fa username
! 82: and
! 83: .Fa password
! 84: may be non-
! 85: .Dv NULL
! 86: for "Basic" HTTP authentication.
! 87: .Pp
! 88: The remaining arguments to
! 89: .Fn http_xml_send
! 90: describe the optional XML request payload and the expected XML reply payload.
! 91: .Pp
! 92: To include a payload in the request,
! 93: .Fa payload
! 94: should be non-
! 95: .Dv NULL .
! 96: If so,
! 97: .Fa ptag ,
! 98: .Fa pattrs ,
! 99: .Fa ptype ,
! 100: .Fa payload ,
! 101: and
! 102: .Fa pflags
! 103: are handled exactly like the
! 104: .Fa elem_tag ,
! 105: .Fa attrs ,
! 106: .Fa type ,
! 107: .Fa data ,
! 108: and
! 109: .Fa flags
! 110: parameters (respectively) to the function
! 111: .Xr structs_xml_output 3 .
! 112: The request payload will be sent using an HTTP POST with MIME type "text/xml".
! 113: If
! 114: .Fa payload
! 115: is
! 116: .Dv NULL ,
! 117: an HTTP GET request is sent instead.
! 118: .Pp
! 119: The HTTP response must contain an XML document, which is parsed and
! 120: converted into native binary format.
! 121: The
! 122: .Fa rtag ,
! 123: .Fa rattrsp ,
! 124: .Fa rattrs_mtype ,
! 125: .Fa rtype ,
! 126: .Fa reply ,
! 127: .Fa rflags ,
! 128: and
! 129: .Fa rlogger
! 130: are handled exactly like the
! 131: .Fa elem_tag ,
! 132: .Fa attrp ,
! 133: .Fa attr_type ,
! 134: .Fa type ,
! 135: .Fa data ,
! 136: .Fa flags ,
! 137: and
! 138: .Fa logger
! 139: parameters (respectively) to the function
! 140: .Xr structs_xml_input 3 .
! 141: .Pp
! 142: .Fn http_xml_send_xmlrpc
! 143: sends an XML-RPC request.
! 144: The
! 145: .Fa client ,
! 146: .Fa ip ,
! 147: .Fa port ,
! 148: .Fa https ,
! 149: .Fa username ,
! 150: .Fa password ,
! 151: and
! 152: .Fa rlogger
! 153: parameters are as with
! 154: .Fn http_xml_send .
! 155: The XML-RPC method name is pointed to by
! 156: .Fa methodName .
! 157: .Fa nparams
! 158: XML-RPC request parameters are sent;
! 159: .Fa ptypes
! 160: must point to an array of
! 161: .Fa nparams
! 162: parameter types and
! 163: .Fa pdatas
! 164: to an array of
! 165: .Fa nparams
! 166: parameter values having the corresponding types.
! 167: These are
! 168: .Dq compact
! 169: .Xr structs 3
! 170: types that will be automatically expanded into
! 171: .Dq exploded
! 172: XML-RPC types when the actual request is sent (see
! 173: .Xr structs_xmlrpc 3) .
! 174: .Pp
! 175: To send exploded XML-RPC values directly, set
! 176: .Fa ptypes
! 177: to
! 178: .Dv NULL .
! 179: Then it will be assumed that each element in the
! 180: .Fa pdatas
! 181: array is an instance of
! 182: .Xr structs_type_xmlrpc_value 3 ,
! 183: i.e., a
! 184: .Li "struct xmlrpc_value_union" .
! 185: .Pp
! 186: If
! 187: .Fa reply
! 188: is
! 189: .Dv NULL ,
! 190: the reply is ignored.
! 191: Otherwise, the XML-RPC return value must have
! 192: .Dq compact
! 193: type matching
! 194: .Fa rtype
! 195: and
! 196: .Fa reply
! 197: must point to an uninitialized region of memory large enough
! 198: to hold an instance of
! 199: .Fa rtype .
! 200: If the request is successful and no fault is returned,
! 201: .Fn http_send_xmlrpc
! 202: returns zero and
! 203: .Fa reply
! 204: will be initialized with the
! 205: .Dq compacted
! 206: XML-RPC return value.
! 207: If the returned value does not match
! 208: .Fa rtype ,
! 209: then -1 is returned with
! 210: .Va errno
! 211: set appropriately.
! 212: .Pp
! 213: To have the exploded XML-RPC value returned directly, set
! 214: .Fa rtype
! 215: to
! 216: .Dv NULL .
! 217: Then it will be assumed that
! 218: .Fa reply
! 219: points to an uninitialized instance of
! 220: .Xr structs_type_xmlrpc_value 3 ,
! 221: i.e., a
! 222: .Li "struct xmlrpc_value_union" ,
! 223: and the reply will be returned unmodified.
! 224: .Pp
! 225: If an XML-RPC fault is returned, then
! 226: .Fa "*reply"
! 227: remains unmodified and
! 228: .Fn http_xml_send_xmlrpc
! 229: returns -2.
! 230: In addition, if
! 231: .Fa "fault"
! 232: is not
! 233: .Dv NULL ,
! 234: then it is assumed to point to an uninitialized instance of
! 235: .Fa structs_type_xmlrpc_compact_fault ,
! 236: i.e., a
! 237: .Li "struct xmlrpc_compact_fault" .
! 238: The instance will be initialized with the received XML-RPC fault.
! 239: The calling function is responsible for eventually uninitializing it.
! 240: .Sh RETURN VALUES
! 241: Upon error,
! 242: .Fn http_xml_send
! 243: and
! 244: .Fn http_xml_send_xmlrpc
! 245: return -1 and set
! 246: .Va errno
! 247: to an appropriate value.
! 248: .Pp
! 249: If
! 250: .Fn http_xml_send_xmlrpc
! 251: receives an XML-RPC fault from the server,
! 252: -2 is returned.
! 253: .Sh SEE ALSO
! 254: .Xr http_client 3 ,
! 255: .Xr http_request 3 ,
! 256: .Xr http_response 3 ,
! 257: .Xr http_servlet_xml 3 ,
! 258: .Xr http_servlet_xmlrpc 3 ,
! 259: .Xr libpdel 3 ,
! 260: .Xr structs_xml_input 3 ,
! 261: .Xr structs_xmlrpc 3
! 262: .Rs
! 263: .%T "XML-RPC Home Page"
! 264: .%O "http://www.xmlrpc.org/"
! 265: .Re
! 266: .Sh HISTORY
! 267: The PDEL library was developed at Packet Design, LLC.
! 268: .Dv "http://www.packetdesign.com/"
! 269: .Sh AUTHORS
! 270: .An Archie Cobbs Aq archie@freebsd.org
! 271: .Sh BUGS
! 272: HTTP redirects are not followed; instead they generate an error.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_xml.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