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