Qore::Xml::XmlRpcClient Class Reference

The XmlRpcClient class provides easy access to XML-RPC web services. More...

## Public Member Functions

hash | call (string method,...)
| Calls a remote method taking all arguments after the method name for the method arguments and returns the response as qore data structure. More...
hash | callArgs (string method, any args)
| Calls a remote method using a single value after the method name for the method arguments and returns the response as a Qore data structure. More...
hash | callArgsWithInfo (reference info, string method, any args)
| Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure, accepts a reference to a hash as the first argument to give technical information about the call. More...
hash | callWithInfo (reference info, string method,...)
| Calls a remote method taking all arguments after the method name for the method arguments and returns the response as qore data structure, accepts a reference to a hash as the first argument to give technical information about the call. More...
| constructor ()
| Creates the XmlRpcClient object with no parameters. More...
| constructor (hash opts, softbool no_connect=False)
| Creates the XmlRpcClient object based on the parameters passed. More...
| copy ()
| Throws an exception; copying XmlRpcClient objects is currently not supported. More...
nothing | setEventQueue ()
| clears the event queue for the XmlRpcClient object More...
nothing | setEventQueue (Queue queue)
| sets the event queue for the XmlRpcClient object More...

## Detailed Description

The XmlRpcClient class provides easy access to XML-RPC web services.

This class inherits all public methods of the HTTPClient class. The inherited HTTPClient methods are not listed in this section, see the section on the HTTPClient class for more information on methods provided by the parent class. For a list of low-level XML-RPC functions, see XML-RPC.

The XmlRpcClient class understands the following protocols in addition to the protocols supported by the HTTPClient class:

XmlRpcClient Class Protocols

Protocol | Default Port | SSL? | Description
`xmlrpc` | `80` | No | Unencrypted XML-RPC protocol over HTTP
`xmlrpcs` | `443` | Yes | XML-RPC protocol over HTTP with SSL/TLS encryption

The XmlRpcClient supplies default values for HTTP headers as follows:

XmlRpcClient Default, but Overridable Headers

Header | Default Value
`Accept` | `text/xml`
`Content-Type` | `text/xml`
`User-Agent` | `Qore-XML-RPC-Client/1.1`
`Connection` | `Keep-Alive`

Note
  - if no `default_path` is given in the constructor(), then `"RPC2"` is used
  - This class is not available with the `PO_NO_NETWORK` parse option.

## Member Function Documentation

## call()

hash Qore::Xml::XmlRpcClient::call | ( | string | method,
|  |  | ...
| ) |  |

Calls a remote method taking all arguments after the method name for the method arguments and returns the response as qore data structure.

Parameters

  method | The XML-RPC method name to call
  ... | the arguments to the call

Returns
  a hash with one of the following keys:
  - `params:` will be present if the call completed normally
  - `fault:` will be present if the call is returning with error information; if this key is present then the value will be a hash with the following two keys:
    - `faultCode:` an integer fault code
    - `faultString:` a string error message

Exceptions

  XMLRPC-SERIALIZATION-ERROR | empty member name in hash or cannot serialize type to XML-RPC (ex: object)
  PARSE-XMLRPC-RESPONSE-ERROR | missing required element or other syntax error
  PARSE-XMLRPC-ERROR | syntax error parsing XML-RPC string
  HTTP-CLIENT-TIMEOUT | timeout on response from HTTP server
  HTTP-CLIENT-RECEIVE-ERROR | error communicating with HTTP server

Note
  other exceptions may be thrown related to communication errors (ex: SSL errors, etc)

Example:
  hash result = xrc.call("method.name", arg1, arg2);

## callArgs()

hash Qore::Xml::XmlRpcClient::callArgs | ( | string | method,
|  | any | args
| ) |  |

Calls a remote method using a single value after the method name for the method arguments and returns the response as a Qore data structure.

Parameters

  method | The XML-RPC method name to call
  args | An optional list of arguments (or single argument) for the method

Returns
  a hash with one of the following keys:
  - `params:` will be present if the call completed normally
  - `fault:` will be present if the call is returning with error information; if this key is present then the value will be a hash with the following two keys:
    - `faultCode:` an integer fault code
    - `faultString:` a string error message

Exceptions

  XMLRPC-SERIALIZATION-ERROR | empty member name in hash or cannot serialize type to XML-RPC (ex: object)
  PARSE-XMLRPC-RESPONSE-ERROR | missing required element or other syntax error
  PARSE-XMLRPC-ERROR | syntax error parsing XML-RPC string
  HTTP-CLIENT-TIMEOUT | timeout on response from HTTP server
  HTTP-CLIENT-RECEIVE-ERROR | error communicating with HTTP server

Note
  other exceptions may be thrown related to communication errors (ex: SSL errors, etc)

Example:
  hash result = xrc.callArgs("method.name", arg_list);

## callArgsWithInfo()

hash Qore::Xml::XmlRpcClient::callArgsWithInfo | ( | reference | info,
|  | string | method,
|  | any | args
| ) |  |

Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure, accepts a reference to a hash as the first argument to give technical information about the call.

Parameters

  info

  a reference to a hash that provides the following keys on output giving technical information about the HTTP call:
  - `request:` the literal outgoing request body sent
  - `request-uri`: the first line of the HTTP request
  - `headers:` a hash of HTTP headers in the outgoing request
  - `response-uri`: the first line of the HTTP response
  - `response:` the literal response body received from the server
  - `response_headers:` a hash of headers received in the response

  method | The XML-RPC method name to call
  args | An optional list of arguments (or single argument) for the method

Returns
  a hash with one of the following keys:
  - `params:` will be present if the call completed normally
  - `fault:` will be present if the call is returning with error information; if this key is present then the value will be a hash with the following two keys:
    - `faultCode:` an integer fault code
    - `faultString:` a string error message

Exceptions

  XMLRPC-SERIALIZATION-ERROR | empty member name in hash or cannot serialize type to XML-RPC (ex: object)
  PARSE-XMLRPC-RESPONSE-ERROR | missing required element or other syntax error
  PARSE-XMLRPC-ERROR | syntax error parsing XML-RPC string
  HTTP-CLIENT-TIMEOUT | timeout on response from HTTP server
  HTTP-CLIENT-RECEIVE-ERROR | error communicating with HTTP server

Note
  other exceptions may be thrown related to communication errors (ex: SSL errors, etc)

Example:
  hash info;
  hash result = xrc.callArgsWithInfo(\info, "method.name", arg_list);

## callWithInfo()

hash Qore::Xml::XmlRpcClient::callWithInfo | ( | reference | info,
|  | string | method,
|  |  | ...
| ) |  |

Calls a remote method taking all arguments after the method name for the method arguments and returns the response as qore data structure, accepts a reference to a hash as the first argument to give technical information about the call.

Parameters

  info

  a reference to a hash that provides the following keys on output giving technical information about the HTTP call:
  - `request:` the literal outgoing request body sent
  - `request-uri`: the first line of the HTTP request
  - `headers:` a hash of HTTP headers in the outgoing request
  - `response-uri`: the first line of the HTTP response
  - `response:` the literal response body received from the server
  - `response_headers:` a hash of headers received in the response

  method | The XML-RPC method name to call
  ... | the arguments to the call

Returns
  a hash with one of the following keys:
  - `params:` will be present if the call completed normally
  - `fault:` will be present if the call is returning with error information; if this key is present then the value will be a hash with the following two keys:
    - `faultCode:` an integer fault code
    - `faultString:` a string error message

Exceptions

  XMLRPC-SERIALIZATION-ERROR | empty member name in hash or cannot serialize type to XML-RPC (ex: object)
  PARSE-XMLRPC-RESPONSE-ERROR | missing required element or other syntax error
  PARSE-XMLRPC-ERROR | syntax error parsing XML-RPC string
  HTTP-CLIENT-TIMEOUT | timeout on response from HTTP server
  HTTP-CLIENT-RECEIVE-ERROR | error communicating with HTTP server

Note
  other exceptions may be thrown related to communication errors (ex: SSL errors, etc)

Example:
  hash info;
  hash result = xrc.callWithInfo(\info, "method.name", arg1, arg2);

## constructor() [1/2]

Qore::Xml::XmlRpcClient::constructor | ( |  | ) |

Creates the XmlRpcClient object with no parameters.

No connection is made because no connection parameters are set with this call; connection parameters must be set afterwards using the appropriate HTTPClient methods.

Example:
  XmlRpcClient xrc();
  xrc.setURL("http://localhost:8080");

## constructor() [2/2]

Qore::Xml::XmlRpcClient::constructor | ( | hash | opts,
|  | softbool | no_connect = `False`
| ) |  |

Creates the XmlRpcClient object based on the parameters passed.

By default the object will immediately attempt to establish a connection to the server

Parameters

  opts

  HTTPClient constructor options:
  - `url:` A string giving the URL to connect to; if no default path is given here or in the `default_path` option, then `"RPC2"` is used
  - `default_port:` The default port number to connect to if none is given in the URL.
  - `protocols:` A hash describing new protocols, the key is the protocol name and the value is either an integer giving the default port number or a hash with `'port'` and `'ssl'` keys giving the default port number and a boolean value to indicate that an SSL connection should be established.
  - `http_version:` Either `'1.0'` or `'1.1'` for the claimed HTTP protocol version compliancy in outgoing message headers.
  - `default_path:` The default path to use for new connections if a path is not otherwise specified in the connection URL; if this option is not given and no path appears in the URL, then `"RPC2"` is used instead
  - `max_redirects:` The maximum number of redirects before throwing an exception (the default is 5).
  - `proxy:` The proxy URL for connecting through a proxy.
  - `timeout:` The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: `5m`)
  - `connect_timeout:` The timeout value in milliseconds for establishing a new socket connection (also can be a relative date-time value for clarity, ex: `30s`)

  no_connect | pass a boolean True value argument to suppress the automatic connection and establish a connection on demand with the first request

See also
  HTTPClient::constructor() and HTTPClient::connect() for information on possible exceptions

Example:
  XmlRpcClient xrc(("url": "http://authuser:authpass@otherhost:8080/XMLRPC"));

## copy()

Qore::Xml::XmlRpcClient::copy | ( |  | ) |

Throws an exception; copying XmlRpcClient objects is currently not supported.

Exceptions

  XMLRPCCLIENT-COPY-ERROR | copying XmlRpcClient objects is currently not supported

## setEventQueue() [1/2]

nothing Qore::Xml::XmlRpcClient::setEventQueue | ( |  | ) |

clears the event queue for the XmlRpcClient object

Example:
  xrc.setEventQueue();

## setEventQueue() [2/2]

nothing Qore::Xml::XmlRpcClient::setEventQueue | ( | Queue | queue | ) |

sets the event queue for the XmlRpcClient object

Parameters

  queue | the Queue object to receive network events from the XmlRpcClient object

Example:
  Queue queue();
  xrc.setEventQueue(queue);

The documentation for this class was generated from the following file:

- /Users/david/src/qore/git/module-xml/src/QC_XmlRpcClient.dox.h