.\" Copyright (c) 2001-2002 Packet Design, LLC. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, .\" use and redistribution of this software, in source or object code .\" forms, with or without modifications are expressly permitted by .\" Packet Design; provided, however, that: .\" .\" (i) Any and all reproductions of the source or object code .\" must include the copyright notice above and the following .\" disclaimer of warranties; and .\" (ii) No rights are granted, in any manner or form, to use .\" Packet Design trademarks, including the mark "PACKET DESIGN" .\" on advertising, endorsements, or otherwise except as such .\" appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $Id: http_xml.3,v 1.1.1.1 2012/02/21 23:25:53 misho Exp $ .\" .Dd April 22, 2002 .Dt HTTP_XML 3 .Os .Sh NAME .Nm http_xml_send , .Nm http_xml_send_xmlrpc , .Nd XML and XML-RPC requests over HTTP .Sh LIBRARY PDEL Library (libpdel, \-lpdel) .Sh SYNOPSIS .In sys/types.h .In netinet/in.h .In pdel/http/xml.h .Ft int .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" .Ft int .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" .Sh DESCRIPTION These functions send and receive XML and XML-RPC over HTTP and HTTPS. They are convenience wrappers around the .Xr http_request 3 , .Xr http_response 3 , .Xr structx_xml_input 3 , .Xr structs_xml_output 3 , and .Xr structs_xmlrpc 3 routines. .Pp .Fn http_xml_send uses .Fa client to send an HTTP request for the URL path .Fa urlpath (which must being with a '/') to IP address .Fa ip and port .Fa port . If .Fa https is non-zero, an SSL (HTTPS) request is made. The .Fa username and .Fa password may be non- .Dv NULL for "Basic" HTTP authentication. .Pp The remaining arguments to .Fn http_xml_send describe the optional XML request payload and the expected XML reply payload. .Pp To include a payload in the request, .Fa payload should be non- .Dv NULL . If so, .Fa ptag , .Fa pattrs , .Fa ptype , .Fa payload , and .Fa pflags are handled exactly like the .Fa elem_tag , .Fa attrs , .Fa type , .Fa data , and .Fa flags parameters (respectively) to the function .Xr structs_xml_output 3 . The request payload will be sent using an HTTP POST with MIME type "text/xml". If .Fa payload is .Dv NULL , an HTTP GET request is sent instead. .Pp The HTTP response must contain an XML document, which is parsed and converted into native binary format. The .Fa rtag , .Fa rattrsp , .Fa rattrs_mtype , .Fa rtype , .Fa reply , .Fa rflags , and .Fa rlogger are handled exactly like the .Fa elem_tag , .Fa attrp , .Fa attr_type , .Fa type , .Fa data , .Fa flags , and .Fa logger parameters (respectively) to the function .Xr structs_xml_input 3 . .Pp .Fn http_xml_send_xmlrpc sends an XML-RPC request. The .Fa client , .Fa ip , .Fa port , .Fa https , .Fa username , .Fa password , and .Fa rlogger parameters are as with .Fn http_xml_send . The XML-RPC method name is pointed to by .Fa methodName . .Fa nparams XML-RPC request parameters are sent; .Fa ptypes must point to an array of .Fa nparams parameter types and .Fa pdatas to an array of .Fa nparams parameter values having the corresponding types. These are .Dq compact .Xr structs 3 types that will be automatically expanded into .Dq exploded XML-RPC types when the actual request is sent (see .Xr structs_xmlrpc 3) . .Pp To send exploded XML-RPC values directly, set .Fa ptypes to .Dv NULL . Then it will be assumed that each element in the .Fa pdatas array is an instance of .Xr structs_type_xmlrpc_value 3 , i.e., a .Li "struct xmlrpc_value_union" . .Pp If .Fa reply is .Dv NULL , the reply is ignored. Otherwise, the XML-RPC return value must have .Dq compact type matching .Fa rtype and .Fa reply must point to an uninitialized region of memory large enough to hold an instance of .Fa rtype . If the request is successful and no fault is returned, .Fn http_send_xmlrpc returns zero and .Fa reply will be initialized with the .Dq compacted XML-RPC return value. If the returned value does not match .Fa rtype , then -1 is returned with .Va errno set appropriately. .Pp To have the exploded XML-RPC value returned directly, set .Fa rtype to .Dv NULL . Then it will be assumed that .Fa reply points to an uninitialized instance of .Xr structs_type_xmlrpc_value 3 , i.e., a .Li "struct xmlrpc_value_union" , and the reply will be returned unmodified. .Pp If an XML-RPC fault is returned, then .Fa "*reply" remains unmodified and .Fn http_xml_send_xmlrpc returns -2. In addition, if .Fa "fault" is not .Dv NULL , then it is assumed to point to an uninitialized instance of .Fa structs_type_xmlrpc_compact_fault , i.e., a .Li "struct xmlrpc_compact_fault" . The instance will be initialized with the received XML-RPC fault. The calling function is responsible for eventually uninitializing it. .Sh RETURN VALUES Upon error, .Fn http_xml_send and .Fn http_xml_send_xmlrpc return -1 and set .Va errno to an appropriate value. .Pp If .Fn http_xml_send_xmlrpc receives an XML-RPC fault from the server, -2 is returned. .Sh SEE ALSO .Xr http_client 3 , .Xr http_request 3 , .Xr http_response 3 , .Xr http_servlet_xml 3 , .Xr http_servlet_xmlrpc 3 , .Xr libpdel 3 , .Xr structs_xml_input 3 , .Xr structs_xmlrpc 3 .Rs .%T "XML-RPC Home Page" .%O "http://www.xmlrpc.org/" .Re .Sh HISTORY The PDEL library was developed at Packet Design, LLC. .Dv "http://www.packetdesign.com/" .Sh AUTHORS .An Archie Cobbs Aq archie@freebsd.org .Sh BUGS HTTP redirects are not followed; instead they generate an error.