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.
$ 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.
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.
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).
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.
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 is capable of only a subset of the possible XML-RPC types, as follows by prefix:
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.
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.
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.