Xmlrpc_pstream User Manual

xmlrpc_pstream makes a pseudo-XML-RPC remote procedure call (RPC) and displays the response. xmlrpc_pstream runs a pseudo-XML-RPC client.

The difference from true XML-RPC is that xmlrpc_pstream uses XML-RPC For C/C++'s "pstream" transport mechanism instead of HTTP. The pstream transport uses a simple TCP connection.

## Examples

         $ socketexec -connect \
             -remote_host=localhost -remote_port=8080 --filedes=3 -- \
             xmlrpc_pstream --serverfd=3

         >sample.add i/3 i/5

           Result:
             Integer: 8

         $ socketexec -connect \
             -remote_host=localhost -remote_port=8080 --filedes=3 -- \
             xmlrpc_pstream sample.add i/3 i/5

           Result:
             Integer: 8

See the manual for the program xmlrpc for more examples; you specify the RPC arguments the same way.

## Overview

xmlrpc_pstream [-serverfd=integer] [methodName [parameter ...]]

parameter:

i/integer | s/string | h/hexstring | b/{true|false|t|f} | d/realnum | n/ | string

Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value.

## Description

This program is mainly useful for debugging and learning about XML-RPC servers. XML-RPC is such that the RPCs normally need to be made by a program rather than a person to be of use.

You supply a TCP connection to the server as an open file descriptor. socketexec is a good way to create that socket and pass it to xmlrpc_pstream.

You run xmlrpc_pstream in one of two modes: interactive and single RPC.

In interactive mode, which you select by giving no arguments to the program, xmlrpc_pstream prompts you for RPCs using the Readline library. You type in an RPC description and xmlrpc_pstream executes it, then asks you for another. This continues until you close the readline session (usually by typing Control-D). Then, the program exits, which causes the server file descriptor to close, which causes the client-server TCP connection to close, which means the client-server XML-RPC connection terminates.

In single RPC mode, you give the RPC information as arguments to the program. xmlrpc_pstream executes one RPC, then exits. But note that when you invoke xmlrpc_pstream with socketexec in single RPC mode, you can't exploit one of the main purposes of a pstream transport: it lets you establish an RPC session with the server. With the single RPC socketexec method, socketexec establishes a session with the server (by creating the TCP connection), then xmlrpc_pstream performs one RPC in that session, then the OS closes the session as xmlrpc_pstream exits (by virtue of closing the TCP socket).

## Arguments

There are no arguments in interactive mode. The fact that there are no arguments is what tells xmlrpc_pstream you want interactive mode.

For single RPC mode, the arguments are as follows.

methodName
  The name of the XML-RPC method you want to invoke.
parameter ...
  The list of parameters for the RPC. xmlrpc_pstream turns each of these arguments into an XML-RPC parameter, in the order given. You may specify no parameters if you like.

  You specify the data type of the parameter with a prefix ending in a slash. Example: i/5. Here, the "i" signifies an integer data type. "5" is the value.

  xmlrpc_pstream is capable of only a subset of the possible XML-RPC types, as follows by prefix:

  i/
    integer (<i4>) (32 bit)
  s/
    string (<string>)
  h/
    byte string (<base64>). Specify the value in hexadecimal.
  b/
    boolean (<boolean>). Specify the value as "true" or "t" for true; "false" or "f" for false.
  d/
    double (<double>) (i.e. real number)
  n/
    nil (<nil>)
  I/
    64 bit integer (<i8>)

  As a shortcut, if you don't specify a prefix (i.e. your argument does not contain a slash), xmlrpc_pstream assumes string data type.

## Options

-serverfd=integer
  This identifies the client-server connection (and thus identifies the server). It is the file descriptor (an integer file handle) of the socket associated with an established TCP connection that you set up before invoking xmlrpc_pstream.

  In interactive mode, don't use 0 or 1, because those are Standard Input and Standard Output and are used to communicate with you. 2 is a bad choice any time, because that is Standard Error and xmlrpc_pstream uses that to communicate with you.

  socketexec is a good way to create the required socket. Use the socketexec's -filedes option to tell it what file descriptor to use for the socket, then use that same value on xmlrpc_pstream's -serverfd option.

  The default is 3.

## Interactive Commands

Example: `> sample_add i/5 i/7`

In interactive mode, xmlrpc_pstream prompts you for RPC calls with the prompt ">".

At the prompt, type a series of words, delimited by one or more blanks.

The first word is the XML-RPC method name.

The remaining words are the parameters of the XML-RPC method, in the same form as the xmlrpc_pstream arguments for single RPC mode.