XMLRPC C API Reference
Complete C API Reference
Examples / Tutorial
XMLRPC Protocol Spec
RFC: Standard Fault Codes
xmlrpc mailing List
xmlrpc mailing List
new expat project
|To better illustrate how to use the library, there are some
hello_client and hello_server are minimalist. They are meant to be extremely simple examples of how to use the API.
Each of the rest of them takes "--help" as an argument to describe usage. Here are some things to try:
sampleimplements both client (request) and server (response) behavior. The options used tell it to print both request and response.
-outputNext we'll display both a request and a response. This is done by setting output to 'both'. Notice that we set verbosity to none, indicating that we favor compactness over prettiness.
-verbosityAdmittedly, that was ugly. Now we'll print just the request for a method called "method_TestArray". This example uses all of sample's available arguments. First output=request. This is self-explanatory. Second, method=method_TestArray. This is a method that is exported by the "server" in sample.c. Third, verbosity=pretty. Thus we can read the output nicely. Fourth, version=xmlrpc, so the output will be in the standard xmlrpc serialization. Fifth, escaping=cdata, so all string values will be in CDATA sections. Sixth, encoding=iso-8859-1, so the xml declaration tag will include iso-8859-1, and the client/server will convert the utf-8 encoded xml into iso-8859-1 before giving the data to the application.
-versionThat was much prettier, but still a bit verbose because each element takes up a whole line and there are several elements per value. For the rest of the examples, we will use a more compact serialization of the xml that we call "simplerpc". This is different from xmlrpc and will not work with other xmlrpc implementations. Here, we run the same command again, this time using simplerpc. See how much more readable it is? (note: although seemingly shorter due to fewer newlines, this vocab is typically a bit larger (in bytes) than xmlrpc, because of the redundant "type=" attributes.)
-escapingThere are basically two ways to escape xml. One way is CDATA, which attempts to preserve characters as is, but will still break a parser that is expecting another encoding type. Another is numeric entity escaping, eg: ¼ to send ¼ This way, the receiving parser will know to interpret the character as 188 in whichever character encoding it is using. Xmlrpc (and these example programs) support different ways of using these methods:
The client program has a hard-coded ¼ in its output. If the encoding is not specified and the character is unescaped, it will likely break the parser reading the xml. Here we use the "escaping non-ascii" flag. Note the ¼ in the output.
-encodingclient.c and server.c are present to show more clearly how easy it is to create just one side of the equation. In the following example, the results of the client are piped to stdin of the server, and only the server's response is printed. It is critical that the "-encoding" parameter be used, as the client embeds a character above ascii 127 in its output. If the encoding parameter were not there, the parser would assume utf-8 as the encoding, and would generate a parser error.
If you are completely confused about encodings now, don't worry about it too much. For most english applications, just stick with iso-8859-1. If you know enough to know you need something else, you probably understood all of the above anyway.