This chapter describes the functions in the libxmlrpc function library, which is part of XML-RPC For C/C++ (Xmlrpc-c). Also see General Library Information - C.
libxmlrpc provides fundamental services that are useful in XML-RPC clients and servers. For example, it contains functions that manipulate the various data types defined by XML-RPC. You use these services with every other Xmlrpc-c library (except libxmlrpc_abyss), and those libraries also use libxmlrpc internally. Few Xmlrpc-c applications use only libxmlrpc.
You must know something about XML-RPC (the protocol) to understand this chapter. You don't have to know the details of the protocol, since Xmlrpc-c is meant to spare you from learning that, but you do have to know the kinds of things that make up an XML-RPC transaction.
Almost everything you need to know about XML-RPC is here. But you will find that the official specification of the protocol is riddled with ambiguity and other usability problems. This page adds to it and accurately describes most so-called "XML-RPC" clients and servers.
The <xmlrpc-c/xmlrpc.h> header file declares the interface to libxmlrpc and many other things described in this chapter.
You'll have to figure out where on your system this file lives and how to make your compiler look there for it. Or use xmlrpc-c-config.
The classic Unix name for the file containing the libxmlrpc library is libxmlrpc.a or libxmlrpc.so. The classic linker option to cause the library to be linked into your program is -l xmlrpc. These are hints; you'll have to modify this according to conventions of your particular platform. You'll also have to figure out where the library resides and how to make your linker look there for it. Or use xmlrpc-c-config.
The following libraries are prerequisites of libxmlrpc, so you'll need to link them in too:
Any program that uses libxmlrpc should invoke xmlrpc_init as it starts up and xmlrpc_term as it shuts down. It should call xmlrpc_init while the program is still one thread, before it has generated any additional ones, and should call xmlrpc_term when the program is once again one thread, having joined with any others. The call to xmlrpc_init must be before any other call to a libxmlrpc function or a function of any other Xmlrpc-c library that depends upon libxmlrpc, except that the program may (and must) call xmlrpc_env_init beforehand, since xmlrpc_init uses an error environment variable. Likewise, there must be no call to such a function after xmlrpc_term.
Examples:
xmlrpc_env env;
xmlrpc_env_init(&env);
xmlrpc_init(&env);
...
xmlrpc_term();
A program may call these more than once; the number of xmlrpc_term calls must match the number of xmlrpc_init calls and only the first xmlrpc_init call and the last xmlrpc_term call has effect. (The only reason you'd want to call them more than once is if you have a modular program. For example, if you have multiple libraries that each uses libxmlrpc, each library would initialize and terminate libxmlrpc).
While these calls are logically required, there's actually little practical reason for them. The functions did not exist before Xmlrpc-c 1.33 (December 2012), so most programs do not call them, and nothing has changed yet to make them more necessary. However, that could change in future releases.
Xmlrpc-c does not itself maintain any static state and probably never will, so the only reason for these functions is that libraries that Xmlrpc-c uses do, and it is through these functions that Xmlrpc-c initializes and terminates those libraries.
As of Xmlrpc-c 1.33, the only known effect of not doing xmlrpc_init and xmlrpc_term is that a program that uses a version of Xmlrpc-c that uses libxml2 for XML parsing will appear to leak memory if you don't initialize and terminate the library. A memory allocation analyzer such as Valgrind will show that as the program exits, it still has memory allocated. This doesn't matter, of course, but it does complicate your search for more significant memory leaks.
The C type xmlrpc_value is an XML-RPC value (i.e. what you could represent with a <value> XML element). But Xmlrpc-c uses this type for a few things besides values that will end up in an XML-RPC stream.
Examples of the kinds of value that an XML-RPC value could be are:
Do not confuse XML-RPC types with the various C types the Xmlrpc-c libraries define and use. For example, <xmlrpc-c/base.h> defines a typedef xmlrpc_bool to represent a boolean value, simply as an integer where 0 means false and 1 means true. This has nothing to do with the boolean XML-RPC type, which represents a boolean value in a much more complex way.
xmlrpc_value is designed for cheap copies by just copying a pointer. This has two major ramifications:
The read-only requirement says that after you've constructed an xmlrpc_value, you must not modify it. For the purposes of this read-only requirement, we define two phases of the life of an xmlrpc_value: construction and use. During construction, you can modify the object as much as you want, for example you could iteratively add elements to an array. But during this phase, you must not use the value for anything. During the use phase, you can use the value, but not modify it (except to change its reference count). An example of an illegal use of xmlrpc_value would be to create an array of 4 elements and use it as a parameter to an XML-RPC call, then add 2 more elements and use it as a parameter to a second XML-RPC call.
In the construction phase, xmlrpc_value is not thread-safe, so don't try to have multiple threads construct an xmlrpc_value without serializing their accesses to the object (it would be weird to want to, anyway).
The libraries do not enforce this read-only two-phase requirement, but if you fail to observe it, you may have unpredictable results.
The simultaneous thread access limitation for early Xmlrpc-c flows from the fact that the cheap copies mentioned above involve reference counts, which get modified even in the use phase. Before Xmlrpc-c 1.33, there is no serialization in the library for the reference counts, so to avoid undefined behavior, you can't ever manipulate the reference count of an xmlrpc_value from two threads at once. And because Xmlrpc-c libraries manipulate these reference counts all the time internally and you can't know when that is, the discipline you must observe is never to have two threads simultaneously working in the same universe of xmlrpc_values. For example, if thread X were to look up an element of Array A, while Thread Y looks up an element of Array B, that could cause a problem if there is any chance there is a value V that was added to both arrays, since both arrays probably contain a pointer to V. On the other hand, if Thread X built Array A out of xmlrpc_values it created itself that no other thread knows about, and Thread Y similarly built Array B out of private xmlrpc_values, then there is no chance of interference and the threads can proceed independently.
XML-RPC was designed to make remote procedure calls look a lot like traditional in-program procedure calls, so the value types are meant to be very similar to the types you find in common programming languages. The types fit fairly well with those commonly used in C programs.
An XML-RPC value has one of the following basic types. Type xmlrpc_type is the type of an XML-RPC value. These names are C macros for the corresponding value of a xmlrpc_type variable.
These types are largely self-explanatory, and we will not describe them all in detail, but some require more explanation.
A string is, roughly speaking, a string of text such as "hello world." But there are some complex details you may need to know to use them in some cases.
An XML-RPC string is a sequence of characters and line delimiters. The characters can be any XML character except linefeed (aka LF, aka newline). An XML character is any Unicode character except the control characters (those with code points 0 - 31), plus carriage return, line feed, and tab.
That's clear enough, but the situation is actually a lot less clear. If you read the XML-RPC spec, you don't find those words in it, and in fact you find words that seem to say something quite different: "Any characters are allowed in a string except < and &, which are encoded as < and &. A string can be used to encode binary data." I say the spec must be interpreted as if that whole sentence never happened. There is a much more important requirement elsewhere in the spec that an XML-RPC message be an XML document, and this sentence conflicts with that. The sentence is actually gibberish in XML terminology: The part about encoding binary data is OK, but it fails to specify a code in which to encode the binary data, and the one simple code that comes to mind is impossible in XML because of the fact there are some 8 bit numbers that are not legal XML characters. For example, there is no XML character with code point 0. Finally, it doesn't make any sense to have a string type that contains "binary data" because XML-RPC has another type just for that.
Consensus among people who have studied XML-RPC and XML is that the sentence quoted above should simply be read out of the XML-RPC spec.
The XML requirement, and common sense, then, lead you to the definition at the top of this section.
If you want to represent arbitrary 8 bit bytes, don't consider using an XML-RPC string for it. See Bits instead.
The definition speaks of a line delimiter. Do not attempt to interpret this as a character or sequence of characters. For the purposes of the definition, it is merely an abstract entity. Naturally, when we have to represent a line delimiter (for example, in the argument to a function that creates an xmlrpc_value object, or in an XML-RPC message) we will use characters to do so, but those characters are not the delimiter itself -- they are merely an encoding of it.
And now, I will modify the ideal definition above to get to the actual definition used in Xmlrpc-c. The modifications make it more universally usable, if less clean. The modification I make is to add to the set of possible characters all the missing control characters except line feed. The main reason this extension is necessary is because of all the people who interpreted the poorly drafted XML-RPC spec differently and expected strings to be useful for transmitting arbitrary bytes masquerading as a UTF-8 encoding of a string. Note that linefeed is still missing from the modified definition, but that is not a problem because the line delimiter can naturally take its place.
Beware: if you take advantage of this extension and send an XML-RPC message containing a string that contains, for example, a NUL (0x00) character, your XML-RPC message will not be a legal XML document and as a result, your XML-RPC partner may choke on it. If you have a choice, stick to the pure definition of string and just don't ever create a string with the extended characters in it. The xmlrpc_string_validate function can help with that.
Now that we've covered what type of information can be represented by an XML-RPC string (and therefore a string xmlrpc_value), the following sections look at how one communicates that information to and from Xmlrpc-c library routines.
The Xmlrpc-c functions that create a string xmlrpc_value take conventional C character arrays as the argument that describes the value of the string.
In these arrays, some functions recognize any of the three conventional ASCII line delimiters as line delimiters: CR, LF, and CRLF. Some functions recognize only LF, which makes CR available to represent a CR character.
In these arrays, some functions recognize a NUL character as an end of string delimiter, while others have an explicit length argument, which makes NUL available to represent a NUL character.
Some of the functions take UTF-8 character arrays, while some take wide character (wchar_t) UTF-16 arrays. See Character Encoding.
ASCII character arrays are a subset of UTF-8 character arrays, so if you don't want to learn what UTF-8 and UTF-16 are all about, just stick to ASCII. Note that all ASCII codes have zero for the high order bit of the byte, so if you're taking this easy route, make sure you never have a one in your high order bit.
To extract the value of a string xmlrpc_value for use in your program, there are functions that are pretty much the converse of the creator functions described above. The output is a character array in the same formats as the arguments to the creator functions.
For line delimiters, you can choose whether to get them as LF, CR, or CRLF. LF is generally your best choice.
Before Xmlrpc-c 1.11 (June 2007), if you created a string xmlrpc_value directly (as opposed to extracting it from an XML-RPC message), these functions returned as line delimiters whatever you used in the argument to the creator function.
When an Xmlrpc-c facility sends a string value in an XML-RPC message (or just encodes one for use in such a message), it represents the value as a sequence of XML characters which is the content of an XML string element, as specified by XML-RPC.
Xmlrpc-c represents each character of the XML-RPC string with the corresponding XML character (and if it's one of the extended characters, represents it "as if" it were a legal XML character). It represents a line delimiter as a linefeed XML character. As the contents of an XML element, the value cannot contain a '<' or '&' XML character, so instead Xmlrpc-c uses an XML entity reference (<, &) for those. Similarly, an XML CR character has special meaning as a line delimiter (or half of one), so Xmlrpc-c uses an XML character reference (&x0d;) for that. Xmlrpc-c also uses an entity reference for '>' (>), just for symmetry.
Remember that there is no such thing as a linefeed character in an XML-RPC string, so there is no question about how to represent that in an XML-RPC message.
To represent a line delimiter, Xmlrpc-c uses a linefeed XML character. XML allows all three kinds of line delimiters: CR, LF, and CRLF. You may think it would be a good idea to give the user control of which of these to use, especially since the xmlrpc_value creator functions recognize those same three delimiters. But it really wouldn't help; it would just confuse. That's because XML clearly specifies that all three are equivalent, and mandates that an XML processor always render a line delimiter to its client as an LF.
Because of some unfortunate bad draftsmanship in the XML spec, the use in this section of the term "XML character" might be confusing. In the XML spec, "character" is defined circularly, such that "<" encodes a less-than character, but the ampersand, ell, tee, and semicolon that compose the code are also called characters. But common sense should tell you what I mean.
Before Xmlrpc-c 1.11 (June 2007), Xmlrpc-c sends whatever line delimiter sequence you used in the argument to the function you used to create the xmlrpc_value.
When an Xmlrpc-c facility receives a string value in an XML-RPC message (or just decodes one from such a message), it interprets XML characters which are the content of an XML string element, as specified by XML-RPC.
Xmlrpc-c logically processes those characters as specified by XML (as an XML processor). In the resulting character stream, Xmlrpc-c recognizes LF as a line delimiter and everything else as the corresponding XML-RPC string character. In the case of an extended character (e.g. NUL), it recognizes the XML character it would be if it were a legal XML character.
N.B. Section 2.11 of the XML spec, which says the XML processor presents any of the three conventional line ending sequences (CR, LF, CRLF) in an XML document to its client as LF.
A byte string is an ordered sequence of bits, a multiple of 8 bits in length. XML-RPC gives no meaning whatsoever to the bits. An example of what this would be useful for is a GIF image.
The XML-RPC specification refers to this data type as "base64," unfortunately, and inconsistently, confusing a data type with an encoding of a data type.
The Xmlrpc-c functions that create a byte string xmlrpc_value take an array of unsigned characters and an unsigned integer for length as the arguments that describe the value of the byte string. (In fact, in general Xmlrpc-c considers a signed character to be a character of text (or sometimes a byte of a multibyte encoding of a character of text) and an unsigned character to be an arbitrary byte).
To extract the value of a byte string xmlrpc_value for use in your program, there are functions that are pretty much the converse of the creator functions described above. The output is an unsigned character array and unsigned integer length.
When an Xmlrpc-c facility sends a byte string value in an XML-RPC message (or just encodes one for use in such a message), it represents the value as a sequence of XML characters which is the content of an XML base64 element, as specified by XML-RPC.
As specified by XML-RPC, Xmlrpc-c encodes the byte string in base64 code. XML-RPC isn't any more specific about what that code is, but Xmlrpc-c uses the code described by RFC 4648, with an XML line delimiter after every 76 characters (of code).
When an Xmlrpc-c facility receives a byte string value in an XML-RPC message (or just decodes one from such a message), it interprets XML characters which are the content of an XML base64 element, as specified by XML-RPC.
As specified by XML-RPC, Xmlrpc-c decodes the byte string as base64. XML-RPC isn't any more specific about what that code is, but Xmlrpc-c uses the code described by RFC 4648, with an XML line delimiters anywhere within. The line delimiters have no effect on the value Xmlrpc-c interprets.
A datetime identifies an instant -- a point in time.
Note that this is not relative to some other time (such as the beginning of the day) and is not relative to a local (sun-based) time standard. It's a simple point in time.
XML-RPC provides for indicating a datetime to one second granularity; The precision is infinite, but you can identify only the instants between the one-second periods of the UTC time scale.
Xmlrpc-c implements an extension of the XML-RPC datetime type that has microsecond granularity.
The Xmlrpc-c functions that create a datetime xmlrpc_value take a variety of Unix standard datetime representations as arguments (e.g. time_t, struct timeval). Where the argument specifies a datetime that cannot be represented in true XML-RPC (i.e. one that identifies a non-whole-second instant), Xmlrpc-c uses its XML-RPC extension.
To extract the value of a datetime xmlrpc_value for use in your program, there are functions that are pretty much the converse of the creator functions described above. Where you don't provide for extraction of the full precision of the value (e.g. the value is 01:05:06.3 and you use a function that extracts with one second granularity), the functions round down.
When an Xmlrpc-c facility sends a datetime value in an XML-RPC message (or just encodes one for use in such a message), it represents the value as a dateTime.iso8601, as specified by XML-RPC.
Where that's not possible because the datetime is between whole seconds, Xmlrpc-c still uses dateTime.iso8601, but uses a natural extension of the XML-RPC format for its contents: the text representing the next earlier whole second datetime is followed by a decimal point and standard decimal fraction digits. For example, "20080628T18:48:05.123000 ". Xmlrpc-c always uses six digits after the decimal point, and rounds down if you specify a datetime that requires more than that. But Xmlrpc-c always uses true XML-RPC (no decimal point and fraction) when it can.
In formatting a dateTime.iso8601 element, Xmlrpc-c uses the timezone-unspecified local time format (i.e. no suffix like "Z" or "+07:00"). As explained below in the context of receiving, this is required by XML-RPC.
When an Xmlrpc-c facility receives a datetime value in an XML-RPC message (or just decodes one from such a message), it interprets XML characters which are the content of an XML dateTime.iso8601 element, as specified by XML-RPC.
Furthermore, Xmlrpc-c recognizes the subsecond extension described above. It understands any number of digits (except 0) after the decimal point, but functions that query the value round the value down to a microsecond.
The XML-RPC specification says, though vaguely, that the content of a dateTime.iso8601 element is not one of the variations that specifies a time zone (i.e. does not end in ";Z" or something like "+07:00". Apart from the specifications, this is the de facto standard because for at least 20 years, Xmlrpc-c would not recognize such variations and it was never reported as a problem. However, starting in Xmlrpc-c 1.60 (September 2022), Xmlrpc-c recognizes the UTC variation (i.e. with a "Z" suffix).
In any case, Xmlrpc-c XML-RPC interpretation facilities do not provide a means of specifying a timezone; they assume the datetime in a dateTime.iso8601 is UTC, so it is as if the Z is there even if it is not.
The XMLRPC_TYPE_NIL type is not a type you can represent in XML-RPC. But there is a common extension of XML-RPC that defines such a type (with the XML element type "nil"). This type was new in Xmlrpc-c 1.02 (April 2005).
The same is true for XMLRPC_TYPE_I8 This type was new in Xmlrpc-c 1.07 (October 2006). In versions of Xmlrpc-c new enough to have this type, the interface header file declares macro XMLRPC_HAVE_I8.
The XMLRPC_TYPE_C_PTR type is not a type you can represent in XML-RPC or any known extension of it. This type exists because you may find it convenient to use xmlrpc_value in your program for objects not directly related to your use of XML-RPC. (In fact, some people use it in a program that that doesn't involve XML-RPC at all).
XMLRPC_TYPE_CPTR represents a pointer to an arbitrary C variable, much like a C void *.
You can optionally supply a destructor function when you construct the xmlrpc_value. libxmlrpc calls that as it destroys the xmlrpc_value, so you can take advantage of xmlrpc_value reference counting to have self-destroying objects of any kind.
The destructor option was new in Xmlrpc-c 1.25 (December 2010).
xmlrpc_value_type() returns the type (type xmlrpc_type) of a specified XML-RPC value.
xmlrpc_type_name() gives a short textual name for a given
type, e.g. xmlrpc_type_name(XMLRPC_TYPE_INT) returns the
string "INT". This text is meant only to be displayed for
humans.
XMLRPC_TYPE_CHECK() throws an error if a given Xmlrpc-c value is not of a given type.
There is such a thing as an xmlrpc_value that is not valid. To assert that you (the coder) know that is not the case, you can use XMLRPC_ASSERT_VALUE_OK().
XMLRPC_ASSERT_ARRAY_OK() asserts that you (the coder) know that the indicated xmlrpc_value is valid and is an array.
An xmlrpc_value object has a reference count. The program is allowed to access the xmlrpc_value object only when its reference count is positive. An Xmlrpc-c library call that leaves the reference count of an xmlprc_value object zero also frees any resources (to wit, memory) that back the object.
Any Xmlrpc-c library function that returns a pointer to an xmlrpc_value object to you adds a reference to the object to cover your use of that pointer. You own that reference. You are responsible for releasing it eventually. This includes functions that create an xmlrpc_value object. A brand new object, returned to you, has a reference count of 1.
Note that when a function fails, it never returns any object to you.
Some older Xmlrpc-c library functions return pointers to xmlrpc_value objects without adding a reference. These are deprecated and have been replaced with proper reference counting alternatives. This manual clearly identifies such functions.
When you stop using a reference to an object, decrease its reference count with xmlrpc_DECREF().
When you create another reference to an object (e.g. by making a copy of its handle), you should increase the reference count with xmlrpc_INCREF().
Whenever you pass an xmlrpc_value object to an Xmlrpc-c library function, the function might cause some other object to refer to it, and consequently add a reference.
When you pass an xmlrpc_value object to an Xmlrpc-c function, just as when you do anything else with one, you must own a reference to it.
The following functions create a simple (i.e. not array or structure) xmlrpc_value.
The function of these should be obvious. Each creates a certain type of xmlrpc_value.
Each of these functions creates an xmlrpc_value with a reference count of one, to cover your reference to it. Be sure you decrement the reference count when you are done with it.
There are no functions to alter the value of an existing xmlrpc_value. Since the object is supposed to represent an actual value, as opposed to a place to store a value, setting one doesn't make sense. If you need to represent a different value from the one you have, you should destroy the old one and create a new one.
None of these "new" functions existed before Xmlrpc-c 1.02 (April 2005). In older versions, you use xmlrpc_build_value() instead.
xmlrpc_value *
xmlrpc_int_new(xmlrpc_env * const envP,
int const intValue);
xmlrpc_value *
xmlrpc_i8_new(xmlrpc_env * const envP,
long long const intValue);
xmlrpc_value *
xmlrpc_double_new(xmlrpc_env * const envP,
double const doubleValue);
xmlrpc_int_new() generates a value whose type is an integer of 32 bit precision (called <int> or <i4> in XML-RPC XML).
xmlrpc_double_new() generates a value whose type is a double precision floating point number type value (called <double> in XML-RPC XML, equivalent to type "double" in C).
xmlrpc_i8_new() generates a value whose type is an integer of 64 bit precision (called <double> in extended XML-RPC XML, equivalent to type "long long" in C). Note that there is no such type in XML-RPC, but there is in a common extension to XML-RPC.
xmlrpc_i8_new() was new in Xmlrpc-c 1.07 (October 2006). Before that, there was no defined way to represent 64 bit integers. In versions of Xmlrpc-c new enough to have this function, the macro XMLRPC_HAVE_I8 is defined in the interface header file.
xmlrpc_value *
xmlrpc_bool_new(xmlrpc_env * const envP,
xmlrpc_bool const boolValue);
Examples:
xmlrpc_value * myStringP;
myStringP = xmlrpc_string_new(&env, "hello world");
myStringP = xmlrpc_string_new_lp(&env, "hello\0world", 11);
myStringP = xmlrpc_string_new_f(&env, "The result is %d", 7);
va_list args;
va_start(args, format);
myStringP = xmlrpc_string_new_va(&env, "The result is %d", args)
va_end(args)
myStringP = xmlrpc_string_new_cr(&env, "hello world\r");
myStringP = xmlrpc_string_new_lp(&env, "\0\r\n", 3);
xmlrpc_string_validate(&env, myStringP);
Overview:
xmlrpc_value *
xmlrpc_string_new(xmlrpc_env * const envP,
const char * const stringValue);
xmlrpc_value *
xmlrpc_string_new_lp(xmlrpc_env * const envP,
size_t const length,
const char * const stringValue);
xmlrpc_value *
xmlrpc_string_new_f(xmlrpc_env * const envP,
const char * const format,
...);
xmlrpc_value *
xmlrpc_string_new_va(xmlrpc_env * const envP,
const char * const format,
va_list args);
xmlrpc_value *
xmlrpc_string_w_new(xmlrpc_env * const envP,
const wchar_t * const stringValue);
xmlrpc_value *
xmlrpc_string_w_new_lp(xmlrpc_env * const envP,
size_t const length,
const wchar_t * const stringValue);
xmlrpc_value *
xmlrpc_string_new_cr(xmlrpc_env * const envP,
const char * const stringValue);
xmlrpc_value *
xmlrpc_string_new_lp_cr(xmlrpc_env * const envP,
size_t const length,
const char * const stringValue);
xmlrpc_value *
xmlrpc_string_w_new_cr(xmlrpc_env * const envP,
const wchar_t * const stringValue);
xmlrpc_value *
xmlrpc_string_w_new_lp_cr(xmlrpc_env * const envP,
size_t const length,
const wchar_t * const stringValue);
void
xmlrpc_string_validate(xmlrpc_env * const envP,
xmlrpc_value * const valueP);
First, you should understand just what a string is, because it's not exactly the same a C string. See the mind-numbing explanation of the XML-RPC string fiasco in the String section. There is a safe harbor, though. You can ignore that section as long as you aren't interested in any string that is composed of multiple lines or contains ASCII control characters, including LF and CR. In that case, XML-RPC strings and Xmlrpc-c string xmlrpc_values are just what you would expect them to be.
xmlrpc_string_new() takes as an argument a null-terminated string of UTF-8-encoded text. (Note that an ASCII string is a UTF-8 string, so if you don't want to know what UTF-8 is, just supply ASCII). In that argument, any of the three common line delimiter sequences (LF (linefeed, newline), CR (carriage return), and CRLF) denotes a line delimiter (CRLF is always one line delimiter, never two). There is no way to specify a NUL, CR or LF character as part of the text.
xmlrpc_string_new_lp() is a little different in that it takes the string and its length as arguments and works with strings that contain NUL characters.
xmlrpc_string_new_cr() is the same as xmlrpc_string_new() except that only an LF (newline) character denotes a line delimiter. CR is just another character. This function was new in Xmlrpc-c 1.11 (June 2007).
Similarly, xmlrpc_string_new_lp_cr() is the same as xmlrpc_string_new_lp() except CR is a regular character. With this function, you can specify any UTF-8 character except LF. (But if you just consider a line delimiter to be LF, then you have the full set). This function was new in Xmlrpc-c 1.11 (June 2007).
xmlrpc_string_new_f() takes as arguments a a printf-style format string followed by printf-style substitution arguments, but otherwise is like xmlrpc_string_new().
xmlrpc_string_new_va() is the same as xmlrpc_string_new_f() except that it takes the substitution arguments as a varargs argument (like vsprintf()).
xmlrpc_string_new_f() and xmlrpc_string_new_va() were new in Xmlrpc-c 1.10 (March 2007).
xmlrpc_string_w_new() is like xmlrpc_string_new() except you specify the contents with UTF-16 characters instead of UTF-8.
xmlrpc_string_w_new_lp(), xmlrpc_string_w_new_cr(), and xmlrpc_string_w_new_lp_cr() are similarly related to their non-w counterparts.
Use xmlrpc_string_validate() to be sure the string value you created doesn't result in invalid XML when you use it in an XML-RPC call or response, as described in the String section. If the string is OK, it succeeds; otherwise, it fails. What makes a string fail this test is that you supplied non-XML characters when you constructed it. If you are sure you didn't supply any control characters other than newline, carriage return, and tab, you don't need xmlrpc_string_validate(). Also, if you know that whatever interprets the XML-RPC call or response you generate with this string value is OK with non-XML characters, you don't need it.
xmlrpc_string_validate() was new in Xmlrpc-c 1.42 (June 2015).
xmlrpc_value *
xmlrpc_datetime_new(xmlrpc_env * const envP,
xmlrpc_datetime const value);
xmlrpc_value *
xmlrpc_datetime_new_sec(xmlrpc_env * const envP,
time_t const value);
xmlrpc_value *
xmlrpc_datetime_new_timeval(xmlrpc_env * const envP,
struct timeval const value);
xmlrpc_value *
xmlrpc_datetime_new_timespec(xmlrpc_env * const envP,
struct timespec const value);
xmlrpc_value *
xmlrpc_datetime_new_usec(xmlrpc_env * const envP,
time_t const secs,
unsigned int const usecs);
xmlrpc_value *
xmlrpc_datetime_new_str(xmlrpc_env * const envP,
const char * const value);
Many of these functions are capable of generating datetimes with subsecond granularity, but XML-RPC is not capable of expressing datetimes to this granularity. That means if you specify a datetime which is not at a whole second boundary, any message you make from it will not be true XML-RPC. Rather, it will use a protocol invented for Xmlrpc-c. So any partner that uses Xmlrpc-c will understand it, but any other XML-RPC partner probably will not. To use standard XML-RPC, you can use all these functions, but you must make sure to specify a whole-second datetime (i.e. set the microsecond part to zero).
xmlrpc_datetime_new() takes as an argument an xmlrpc_datetime value, which represents a datetime as follows:
typedef struct {
unsigned int Y; /* 1- */
unsigned int M; /* 1-12 */
unsigned int D; /* 1-31 */
unsigned int h; /* 0-23 */
unsigned int m; /* 0-59 */
unsigned int s; /* 0-59 */
unsigned int u; /* 0-999999 */
} xmlrpc_datetime;
The integer values are year AD, month, day, hour, minute, second, and microseconds. Note that it cannot represent datetimes before AD 1. If the values of the members don't describe a valid date, e.g. they say 01:76 on February 30, the datetime value you construct represents an arbitrary datetime.
xmlrpc_datetime_new() was new in Xmlrpc-c 1.20 (September 2009).
xmlrpc_datetime_new_sec() takes as an argument a time_t value representing a datetime. time_t is a traditional Unix way of expressing a datetime with one second precision. It consists of the number of seconds since 1969 UTC, not counting leap seconds, as a 32 bit number. It cannot represent times before 1970 or after mid-2038. If you need to represent one of those times, use xmlrpc_datetime_new() instead.
xmlrpc_datetime_new_sec() was new with Xmlrpc-c 1.03 (June 2005).
xmlrpc_datetime_new_timeval() is the same thing, but its argument is the slightly less traditional struct timeval type, which is capable of expressing datetimes to microsecond granularity.
xmlrpc_datetime_new_timeval() was new with Xmlrpc-c 1.15 (June 2008).
xmlrpc_datetime_new_timeval() is the same thing, but its argument is the even slightly less traditional struct timespec type, which is capable of expressing datetimes to nanosecond granularity.
xmlrpc_datetime_new_timespec() was new with Xmlrpc-c 1.15 (June 2008).
xmlrpc_datetime_new_usec() lets you specify a datetime to microsecond granularity using two arguments: secs is the whole-second time in traditional Unix form; usecs is the number of microseconds past that. usecs must be less than one million.
xmlrpc_datetime_new_usec() was new with Xmlrpc-c 1.15 (June 2008).
xmlrpc_datetime_new_str() takes as an argument the datetime value as a string, in the same format as is used in the XML. For example, "19980717T14:08:55". You'll note that this isn't terribly useful or normal. It's this way because it was easy to implement. Use the other functions if you can.
You represent arbitrary bits with a byte string data type.
xmlrpc_value *
xmlrpc_base64_new(xmlrpc_env * const envP,
unsigned int const length,
const unsigned char * const bytestringValue);
If you're confused by the distinction between data type and XML encoding, then you might think that the argument here is a string of base64 code. It is not. It is an arbitrary byte string. Every 3 of these bytes corresponds to 4 base64 characters in the XML encoding. See the examples of xmlrpc_decompose_value() to understand.
Note that the name of the function is for backward compatibity with a historical mistake. xmlrpc_bytestring_new would be a more appropriate name.
xmlrpc_value *
xmlrpc_nil_new(xmlrpc_env * const envP);
This creates a nil value -- representing absence of a value.
Note that there is no such type in XML-RPC, but there is in a common extension to XML-RPC.
Examples:
struct color {
unsigned int red;
unsigned int green;
unsigned int blue;
};
struct color backgroundColor;
xmlrpc_value * valueP;
valueP = xmlrpc_cptr_new(&env, &backgroundColor);
struct color {
unsigned int red;
unsigned int green;
unsigned int blue;
};
struct color * backgroundColorP = malloc(sizeof(struct color));
xmlrpc_value * valueP;
static void
destroy(void * const context,
void * const objectP)
{
free(objectP)
}
valueP =
xmlrpc_cptr_new_dtor(&env, &backgroundColor, &destroy, NULL);
Prototype:
xmlrpc_value *
xmlrpc_cptr_new(xmlrpc_env * envP,
void * value);
xmlrpc_value *
xmlrpc_cptr_new_dtor(xmlrpc_env * envP,
void * objectP,
xmlrpc_cptr_dtor_fn dtor,
void * dtorContext);
This creates a pointer to an arbitrary C object.
The second form identifies a destructor. This destructor gets called as the xmlrpc_value gets destroyed (by the library call that reduces its reference count to zero). dtor points to a destructor function, with the followinng prototype:
void
myDestructor(void * context,
void * objectP);
If dtor is null, there is no destructor.
context is the value dtorContext you provided when you constructed the xmlrpc_value, meaningful only to you. It might be, for example, the handle of a memory pool to which the object's memory should be returned when destroyed.
objectP is the pointer to the C object (not a pointer to the xmlrpc_value).
dtorContext is meaningless when dtor is null.
xmlrpc_cptr_new_dtor was new in Xmlrpc-c 1.25 (December 2010).
Note that there is no such type in XML-RPC. This facility is not for use in XML-RPC communication.
xmlrpc_array_new() creates an empty array xmlrpc_value.
xmlrpc_array_append_item() adds an item to the end of an array.
xmlrpc_env env;
xmlrpc_value * myArrayP;
xmlrpc_env_init(&env);
myArrayP = xmlrpc_array_new(&env);
...
xmlrpc_DECREF(myArrayP);
xmlrpc_env_clean(&env);
Overview:
xmlrpc_value *
xmlrpc_array_new(xmlrpc_env * const envP);
This generates a new XML-RPC value object of type array, size 0 (no elements). You can use xmlrpc_array_append_item() to add items to it.
You have a reference to the new XML-RPC value; you must ultimately release that with xmlrpc_DECREF(). When there are no more references to the object, it ceases to exist.
xmlrpc_array_new() was new in Xmlrpc-c 1.02 (April 2005). Before that, use xmlrpc_build_value() to create an array.
xmlrpc_value * myArrayP;
xmlrpc_value * itemP;
myArrayP = xmlrpc_array_new(&env);
itemP = xmlrpc_string_new(&env, "This is array item 0");
xmlrpc_array_append_item(&env, myArrayP, itemP);
xmlrpc_DECREF(itemP);
Overview:
void
xmlrpc_array_append_item(xmlrpc_env * const envP,
xmlrpc_value * const arrayP,
xmlrpc_value * const valueP);
This adds an item to an XML-RPC value object of type array. The array size grows by one and the new item becomes the last item (the one with the highest index) in the array.
The array refers to your *valueP by reference, and adds to its reference count. That means if you modify *valueP, you modify the value of the array. And if you release all other references to *valueP, it continues to exist as long as the array does.
xmlrpc_struct_new() creates a structure xmlrpc_value that has no members.
xmlrpc_struct_set_value_v() sets the value of the named member of a structure. If a member by that name already exists, it changes the value. If a member by that name does not exist, it adds one.
With xmlrpc_struct_set_value_v(), you specify the member name with an xmlrpc_value object, which is the most natural thing to do. But it can be cumbersome in coding to build the xmlrpc_value for the name, when it's normally a string and you already have the string in a normal C data type. So as a shortcut, you can use xmlrpc_struct_set_value(), which takes a null-terminated UTF-8 string (conventional C string) for the member name.
These functions create references to the xmlrpc_value you supply (as opposed to copying their contents), but they add to the xmlrpc_value's reference count to account for it. I.e. they do not "borrow" your reference -- you may terminate your reference as soon as the function returns.
xmlrpc_env env;
xmlrpc_value * myStructP;
xmlrpc_env_init(&env);
myStructP = xmlrpc_struct_new(&env);
...
xmlrpc_DECREF(myStructP);
xmlrpc_env_clean(&env);
Overview:
xmlrpc_value *
xmlrpc_struct_new(xmlrpc_env * const envP);
This generates a new XML-RPC value object of type structure, with no members. You can use xmlrpc_struct_set_value() to add members to it.
You have a reference to the new XML-RPC value; you must ultimately release that with xmlrpc_DECREF(). When there are no more references to the object, it ceases to exist.
xmlrpc_struct_new() was new in Xmlrpc-c 1.02 (April 2005). Before that, use xmlrpc_build_value() to create a structure.
xmlrpc_value * myStructP;
xmlrpc_value * memberValueP;
myStructP = xmlrpc_struct_new(&env);
memberValueP = xmlrpc_double_new(&env, 19.2);
xmlrpc_struct_set_value(&env, myStructP,
"temperature", memberValueP);
xmlrpc_DECREF(memberValueP);
Overview:
void
xmlrpc_struct_set_value(xmlrpc_env * const envP,
xmlrpc_value * const structP,
const char * const key,
xmlrpc_value * const valueP);
This sets the value of a member in an XML-RPC value object of type structure, adding a member if one doesn't already exist with the specified key.
Note that structures have no order, so it does not matter in what order you add members to a structure.
The structure refers to your *valueP by reference, and adds to its reference count. That means if you modify *valueP, you modify the value of the structure. And if you release all other references to *valueP, it continues to exist as long as the structure does.
xmlrpc_build_value() is a higher level mechanism for creating an xmlrpc_value than the functions described above, which you can use to create a complex value (e.g. a structure of arrays of structures and strings) in one easy subroutine call.
You supply a variety of values as ordinary C expressions and a format string describing the structure of a (probably composite) xmlrpc_value and xmlrpc_build_value() creates the xmlrpc_value accordingly. It is analogous to standard Unix sprintf().
See Format Strings to understand how this function works.
Examples:
xmlrpc_value *sevenP, *piP, *temperaturesP;
sevenP = xmlrpc_build_value(&env, "i", 7);
piP = xmlrpc_build_value(&env, "d", 3.14159);
temperaturesP = xmlrpc_build_value(&env,
"({s:d,s:d}{s:d,s:d}{s:d,s:d})",
"min", 0.2,
"max", 20,
"min", 0.5,
"max", 31.9,
"min", 5.75,
"max", 35.9
);
-- Use the values --
xmlrpc_DECREF(sevenP);
xmlrpc_DECREF(piP);
xmlrpc_DECREF(temperaturesP);
Or, you can use xmlrpc_build_value_va(), which is the same thing except is uses a va_list argument in place of the variable number of arguments.
With some compilers, you need to cast the arguments after the format string with the type that the format string indicates (see format string specification) in order to avoid some varargs weirdness.
If you want to build an array and your program does not know until run time how many elements the array is to have, or what types of elements, you cannot build it using xmlrpc_build_value() because the number of function arguments has to be fixed at compile time (and the va_list variation doesn't help, because a legitimate va_list variable must be generated from a C function argument list, which is fixed at compile time). Instead, see Creating An Array and do it the long way.
The same consideration applies to a structure when your program doesn't know until run time how many and what type of members there are to be. See Creating A Structure.
Eric Kidd says this translation scheme between XML-RPC and C is borrowed from Python's external C API.
Examples:
xmlrpc_value * value1P;
xmlrpc_value * value2P;
value1P = xmlrpc_int_new(&env, 7);
value2P = xmlrpc_value_new(value1P);
xmlrpc_value * temperaturesP;
xmlrpc_value * temperatures2P;
xmlrpc_decompose_value(&env,
temperaturesP,
"({s:d,s:d,*}{s:d,s:d,*}{s:d,s:d,*})",
"min", &temp[0].min,
"max", &temp[0].max,
"min", &temp[1].min,
"max", &temp[1].max,
"min", &temp[2].min,
"max", &temp[2].max
);
temperatures2P = xmlrpc_value_new(&env, temperaturesP);
xmlrpc_value objects are normally passed around by reference rather than by copying (that's what xmlrpc_INCREF and xmlrpc_DECREF are for), but sometimes you need to make a complete copy, and that is what xmlrpc_value_new() is for. One reason to make a copy would be that you want to modify the two copies independently.
xmlrpc_value_new() creates an xmlrpc_value in all new memory - it does not refer to any pre-existing object. If the value is compound (an array or struct), xmlrpc_value_new() copies all the way down. e.g. for an array, xmlrpc_value_new makes a new xmlrpc_value for the struct, and new xmlrpc_values for each element of the array.
xmlrpc_value_new() was new in Xmlrpc-c 1.43 (September 2015). With older Xmlrpc-c, you can implement the same function yourself using other Xmlrpc-c library facilities if you need it.
Often, XML-RPC values just get passed around from one function to another opaquely and your code does not need to understand the value at all. But when you need to process the value, there are functions to translate an xmlrpc_value object into normal C data types. The best example of where you would do this is in code you write for an XML-RPC server to implement some XML-RPC method. Your code will receive the parameters of the XML-RPC call as xmlrpc_value objects and your code will need to do things with the values they represent.
The first step in interpreting a value is often determining what type is is, because you'll use different facilities to interpret a string than to interpret an array of integers. You can use xmlrpc_value_type() for that.
On the other hand, in many cases your code expects a string value and if it was passed anything else, it's just going to fail. In that case, there's no need for you to check the type; just treat it like a string and the Xmlrpc-c function you call to interpret it will fail with an error string indicating what is supposed to be a string isn't.
These are the basic functions for extracting the value of a simple (not array or structure) xmlrpc_value into an ordinary C data structure.
The functions of these are pretty obvious. Each function is for a particular xmlrpc_value type. If you call it on an xmlrpc_value of a different type, it fails with a fault code of XMLRPC_TYPE_ERROR
None of these "read" functions existed before Xmlrpc-c 1.02 (April 2005). In older versions, you use xmlrpc_parse_value() instead.
void
xmlrpc_read_int(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
int * const intValueP);
xmlrpc_read_i8(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
long long * const intValueP);
void
xmlrpc_read_double(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
xmlrpc_double * const doubleValueP);
xmlrpc_read_i8() was new in Xmlrpc-c 1.07 (October 2006). Before that, there was no defined way to represent 64 bit integers. In versions of Xmlrpc-c new enough to have this function, the macro XMLRPC_HAVE_I8 is defined in the interface header file.
void
xmlrpc_read_bool(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
xmlrpc_bool * const boolValueP);
void
xmlrpc_read_datetime(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
xmlrpc_datetime * const timeValueP);
void
xmlrpc_read_datetime_sec(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
time_t * const timeValueP);
void
xmlrpc_read_datetime_timeval(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
struct timeval * const timeValueP);
void
xmlrpc_read_datetime_timespec(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
struct timespec * const timeValueP);
void
xmlrpc_read_datetime_usec(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
time_t * const secsP,
unsigned int * const usecsP);
void
xmlrpc_read_datetime_8601(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
const char ** const iso8601ValueP);
void
xmlrpc_read_datetime_str(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
const char ** const stringValueP);
xmlrpc_read_datetime() gets you the datetime value as an xmlrpc_datetime value, which represents the datetime in UTC-like year, month, day, ..., seconds, microseconds format. For details, see xmlrpc_datetime_new().
xmlrpc_read_datetime() was new in Xmlrpc-1.20 (September 2009).
xmlrpc_read_datetime_sec() gets you the datetime value as a time_t value. time_t is a traditional Unix way of expressing a datetime with one second precision. It consists of the number of seconds since 1969 UTC, not counting leap seconds, as a 32 bit number. It cannot represent times before 1970 or after mid-2038. If you expect a datetime may be one of those times, use xmlrpc_read_datetime() instead. If the datetime is not a whole second boundary (which can be true only if the value came from a partner that implements an extension of XML-RPC, because XML-RPC provides only for whole-second datetimes), the time_t value you get is of the next earlier whole second datetime.
xmlrpc_read_datetime_sec() was new in Xmlrpc-1.03 (June 2005).
xmlrpc_read_datetime_sec() before Xmlrpc-1.10 (March 2007) is not thread-safe because it manipulates the TZ environment variable. So you cannot call it while another thread in your process might be using or modifying TZ -- for example, another thread that calls xmlrpc_read_datetime_sec(). You can work around this by using xmlrpc_read_datetime_str() and parsing the output yourself.
xmlrpc_read_datetime_timeval() is like xmlrpc_read_datetime_sec() except that it extracts the value as the slightly less traditional Unix type struct timeval, which is capable of expressing a datetime to microsecond granularity. Note that XML-RPC is not capable of representing a datetime to this granularity, so when you receive a datetime from a true XML-RPC partner, you will always see a whole second datetime. But if your partner is using Xmlrpc-c, it is using an extension of XML-RPC that is capable of sending finer granularity datetimes.
xmlrpc_read_datetime_timeval() was new with Xmlrpc-c 1.15 (June 2008).
xmlrpc_read_datetime_timespec() is like xmlrpc_read_datetime_timeval() except that it extracts the value as the even slightly less traditional Unix type struct timespec, which is capable of expressing a datetime to nanosecond granularity.
xmlrpc_read_datetime_timespec() was new with Xmlrpc-c 1.15 (June 2008).
xmlrpc_read_datetime_usec() reads a datetime as two values: *secsP is the next earlier whole second in time_t form and *usecsP is the number of microseconds past that. Note the discussion above about whether you're likely to see subsecond datetimes.
xmlrpc_read_datetime_usec() was new with Xmlrpc-c 1.15 (June 2008).
xmlrpc_read_datetime_8601 reads a datetime in ISO 8601 format, which
is a string. The ISO 8601 standard provides for many ways to represent a
particular datetime; the particular one this function returns is as in the
following example: 19930214T131030,250000Z (13:10:30.25 on
February 14, 1993). There are always 4 digits for the year. There are always
6 digits after the comma (microseconds). Midnight is hour 0, not 24.
xmlrpc_read_datetime_8601 was new in Xmlrpc-c 1.31 (June 2012).
A datetime xmlrpc_value, because of implementation laziness, is capable of being invalid -- it exists but does not indicate a datetime. This would happen if you create it with xmlrpc_datetime_new_str() and supply an argument that does not have the required format. In practice, you see this when using the Xmlrpc-c client facilities and a broken XML-RPC server. The broken server sends invalid XML-RPC in that a datetime value does not have the required format. The client facilities use it to create an invalid xmlrpc_value. When you have an invalid datetime xmlrpc_value, xmlrpc_read_datetime_sec() usually fails, but may read an arbitrary datetime. xmlrpc_read_datetime_str() simply returns whatever garbage string was used to create the xmlrpc_value.
xmlrpc_read_datetime_str() gets you the datetime value as a string, in the same format as is used in the XML. For example, "19980717T14:08:55". You'll note that this isn't terribly useful or normal. It's this way because it was easy to implement. Use xmlrpc_read_datetime_sec() if you can.
void
xmlrpc_read_string(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
const char ** const stringValueP);
void
xmlrpc_read_string_lp(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
size_t * const lengthP,
const char ** const stringValueP);
void
xmlrpc_read_string_crlf(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
const char ** const stringValueP);
void
xmlrpc_read_string_lp_crlf(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
size_t * const lengthP,
const char ** const stringValueP);
void
xmlrpc_read_string_w(xmlrpc_env * const envP,
xmlrpc_value * const valueP,
const wchar_t ** const stringValueP);
void
xmlrpc_read_string_w_lp(xmlrpc_env * const envP,
xmlrpc_value * const valueP,
size_t * const lengthP,
const wchar_t ** const stringValueP);
void
xmlrpc_read_string_w_crlf(xmlrpc_env * const envP,
xmlrpc_value * const valueP,
const wchar_t ** const stringValueP);
void
xmlrpc_read_string_w_lp_crlf(xmlrpc_env * const envP,
xmlrpc_value * const valueP,
size_t * const lengthP,
const wchar_t ** const stringValueP);
Example:
const char * cvalue;
xmlrpc_read_string(&env, &value, &cvalue);
...
free((void *)cvalue);
First, understand the meaning of the string data type,
xmlrpc_read_string() extracts a string value as a conventional C Unicode UTF-8 null-terminated string. If the value in question contains a NUL character, it cannot be represented as a null-terminated string, so xmlrpc_read_string() fails.
These subroutines return the string in newly malloc'ed memory, pointed to by *stringValueP, that you must eventually free. Sometimes, the OS function you use to free memory is declared to take a pointer to something non-constant as its argument, so because *stringValueP is a pointer to a constant, you might get a compiler warning about a type mismatch. To avoid that, you can use a cast as in the example above.
In a string value you examine with the functions in this section, you get an array of UTF-8 characters as output. In that array, lines are delimited by a Unix newline (ASCII Line Feed, aka LF) character. LF is not used any other way.
Before Xmlrpc-c 1.11 (June 2007), if you created a string xmlrpc_value directly (as opposed to extracting it from an XML-RPC message), this function returned as line delimiters whatever you used in the argument to the creator function.
xmlrpc_read_string_lp() is a little different in that it returns the string and its length and works with strings that contain NUL characters.
xmlrpc_read_string_crlf() is the same as xmlrpc_read_string() except that in the string it returns, a line delimiter is represented by the pair of character CR and LF (CRLF) instead of just LF. Though LF is still not used any other way in this string, CR may be present to represent a CR character as well as followed by LF to represent a line delimiter. This function was new in Xmlrpc-c 1.11 (June 2007).
Similarly, xmlrpc_read_string_lp_crlf() is the same as xmlrpc_read_string_lp() except line delimiters are CRLF.
xmlrpc_read_string_w, xmlrpc_read_string_w_lp(). xmlrpc_read_string_w_crlf(), and xmlrpc_read_string_w_lp_crlf()are like their xmlrpc_read_string counterparts except that they return wide characters (UTF-16) instead of UTF-8.
void
xmlrpc_read_base64(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
unsigned int * const lengthP,
const unsigned char ** const bytestringValueP);
void
xmlrpc_read_base64_size(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
size_t * const lengthP);
Example:
const unsigned char * cvalue;
unsigned int length;
xmlrpc_read_base64(&env, &value, &length, &cvalue);
...
free((void *)cvalue);
xmlrpc_read_base64_size(&env, &value, &length);
xmlrpc_read_base64() returns the value of a byte string xmlrpc_value as an array of plain bytes. The array is in malloc'ed storage, which you must eventually free.
Sometimes, the OS function you use to free memory is declared to take a pointer to something non-constant as its argument, so because *bytestringValueP is a pointer to a constant, you might get a compiler warning about a type mismatch. To avoid that, you can use a cast as in the example above.
xmlrpc_read_base64_size() was new in Xmlrpc-c 1.03 (June 2005).
void
xmlrpc_read_nil(xmlrpc_env * const envP,
xmlrpc_value * const valueP);
xmlrpc_read_nil() is a little silly, since a nil value has no value, but it's there for completeness and does at least serve to validate that the xmlrpc_value has nil type.
void
xmlrpc_read_cptr(xmlrpc_env * const envP,
const xmlrpc_value * const valueP,
void ** const ptrValueP);
You can access an element of an array by index with xmlrpc_array_read_item(). Use xmlrpc_array_size() to determine how many elements the array has.
Example:
xmlrpc_value * const myArrayP =
xmlrpc_build_value(envP, "(ii)", 5, 7);
xmlrpc_value * firstElementP;
xmlrpc_int firstInt;
printf("Array has %u elements\n", xmlrpc_array_size(envP, myArrayP));
/* prints "Array has 2 elements" */
xmlrpc_array_read_item(envP, myArrayP, 0, &firstElementP);
xmlrpc_read_int(envP, firstElementP, &firstInt);
printf("First element is %d\n", firstInt);
/* prints "First element is 5" */
xmlrpc_DECREF(firstElementP);
There is also xmlrpc_array_get_item(), but it deprecated. It was replaced by xmlrpc_array_read_item(). The main difference is that xmlrpc_array_get_item() does not acquire a reference to the value it returns.
This returns the number of elements in the array identified by arrayP.
Prototype:
int
xmlrpc_array_size(xmlrpc_env * const envP,
const xmlrpc_value * const arrayP);
The return value is of signed integer type for historical reasons; it cannot of course ever be negative.
The only way this can fail is if arrayP is not actually an array XML-RPC value. So it is usually not worth checking *envP.
This extracts the value of one element of an XML-RPC array, by index.
Prototype:
void
xmlrpc_array_read_item(xmlrpc_env * const envP,
const xmlrpc_value * const arrayP,
unsigned int const index,
xmlrpc_value ** const valuePP);
This returns as *valuePP the element with index index of the array arrayP (The first element in the array has index 0, the second has index 1, etc.).
xmlrpc_array_read_item() fails with a XMLRPC_INDEX_ERROR fault code if the array is too small to contain the specified element. You can check the size of the array with xmlrpc_array_size().
xmlrpc_array_read_item() fails if arrayP identifies something other than an array. You can check its type with xmlrpc_value_type().
xmlrpc_array_read_item() was new in Xmlrpc-c 1.01 (January 2005).
You can access a member of a structure by name. You can specify that name either as an xmlrpc_value or a simple null-terminated text string.
The xmlrpc_struct_find_value functions consider "not found" to be a normal result. If a member of the structure with the specified key exists, it returns it as a handle to an xmlrpc_value. If not, it returns NULL in place of that handle.
By contrast, the xmlpc_struct_read_value functions consider "not found" to be a failure (they return a failure indication with a XMLRPC_INDEX_ERROR fault code in the specified error environment variable).
When these functions return a value (as an xmlrpc_value), they increase the reference count to represent the caller's reference to it. The caller must eventually release that reference.
Example:
xmlrpc_value * const myStructP =
xmlrpc_build_value(envP, "{%s:%d}", "age", 32);
xmlrpc_value * ageP;
xmlrpc_struct_find_value(envP, myStructP, "age", &ageP);
if (ageP) {
xmlrpc_int age;
xmlrpc_read_int(envP, ageP, &age);
printf("age is %d\n", age);
xmlrpc_DECREF(ageP);
} else
printf("There is no member named 'age'");
xmlrpc_DECREF(myStructP);
xmlrpc_struct_find_value() takes a null-terminated text string as a key. You can't use it for a key that has NUL characters in it.
xmlrpc_struct_find_value_v() takes a xmlrpc_value as a key value. The value must be of string type, but in a future version, that restriction might be relaxed.
xmlrpc_struct_read_value() and xmlrpc_struct_read_value_v() are similar.
All of these functions fail with fault code XMLRPC_TYPE_ERROR if the argument that is supposed to be the structure is an xmlrpc_value of some type other than structure. But they assume it is a valid xmlrpc_value.
The xmlrpc_struct_get_value functions are deprecated. They used to be the only way to access a member of a structure. They are like xmlrpc_struct_read_value except that they don't acquire a reference to the returned value.
If you just want to know whether a member by a certain name exists (and avoid a failure when you try to get its value), use xmlrpc_struct_has_key_v() and its shortcut xmlrpc_struct_has_key().
You can read out the contents of a structure when you don't know the names of its members with xmlrpc_struct_read_member(). For the purposes of this function, the structure is organized like an array. Each member has an integer index, from a consecutive set starting at zero, and an argument to xmlrpc_struct_read_member() specifies that index. Use xmlrpc_struct_size(), described above, to determine how many members there are.
The mapping from index to member is not predictable, except that it is fixed as long as the structure does not change.
The xmlrpc_struct_get_key_and_value() is deprecated. It was replaced by xmlrpc_struct_read_member(). It is like xmlrpc_struct_read_member() except that it doesn't acquire a reference to the returned value.
To determine the size of a structure (number of members in it), use xmlrpc_struct_size().
xmlrpc_decompose_value() is a higher level mechanism for interpreting an xmlrpc_value than the functions described above.
It is the opposite of xmlrpc_build_value() -- you give it a (probably composite) xmlrpc_value and a format string that describes its structure and it decomposes the xmlrpc_value and extracts the various values in it into variables you provide. It is analogous to standard Unix sscanf().
See Format Strings to understand how this function works.
Here is an example, which uses the xmlrpc_value objects that were created in the above example of xmlrpc_build_value().
xmlrpc_int seven;
double pi;
const char * employeeName[3];
struct {double min;
double max;
} temp[3];
unsigned char * binaryBlob;
size_t binaryBlobSize;
xmlrpc_decompose_value(&env, sevenP, "i", &seven);
xmlrpc_decompose_value(&env, piP, "d", &pi);
xmlrpc_decompose_value(&env, employeeNameP, "(sss*)",
&employeeName[0],
&employeeName[1],
&employeeName[2]);
xmlrpc_decompose_value(&env,
temperaturesP,
"({s:d,s:d,*}{s:d,s:d,*}{s:d,s:d,*})",
"min", &temp[0].min,
"max", &temp[0].max,
"min", &temp[1].min,
"max", &temp[1].max,
"min", &temp[2].min,
"max", &temp[2].max
);
xmlrpc_decompose_value(&env, "6", &binaryBlob, &binaryBlobSize);
There is also the va_list version, xmlrpc_decompose_value_va().
The arguments after the format string are pointers to variables which xmlrpc_decompose_value() sets to describe the XML-RPC value. We call these pointed-to variables "extraction variables." The types of the extraction variables must be as specified in the format string specification.
The format specifier for the name of a structure member is an exception. The argument that corresponds to that is an input, not an output like everything else. The argument is a variable of the indicated type, not a pointer to such a variable. The format specifier here says to extract the value of a particular named member of the structure. The example above shows this.
The name of a structure member must be a string. If it is anything else, xmlrpc_decompose_value() fails.
You may specify * (asterisk) as the last element of an array. This stands for zero or more additional elements, and has no associated C data type. That means the format string validly matches the XML-RPC array value, but the interpretation function ignores its tail.
Similarly, you may specify * as the last member of a structure to cause xmlrpc_decompose_value() to ignore the members you don't name. Actually, in the present implementation, you must specify this asterisk. That's because xmlrpc_decompose_value() is not capable of determining whether your format string extracts all the members of a structure, which is what no asterisk would imply. Some day, this will get fixed.
When xmlrpc_decompose_value() returns an xmlrpc_value to you (for a format specifier of A, S, or V), it adds to the xmlrpc_value's reference count to cover your reference. Be sure to decrement the reference count when you are done referencing it.
For a format specifier that return strings and byte strings (8, s, w, and 6), xmlrpc_decompose_value() allocates new memory for you with malloc(). Be sure to free it when you are done with it.
When xmlrpc_decompose_value() fails, it does not return anything, and therefore does not increase any reference count or allocate any memory and the values of the extraction variables are undefined.
xmlrpc_decompose_value() did not exist before Xmlrpc-C 1.02 (April 2005). In older releases, you use xmlrpc_parse_value() instead.
This deprecated function is the predecessor to xmlrpc_decompose_value(). It's the same, but xmlrpc_parse_value() doesn't do proper memory management, as follows.
For a format specifier that return strings and byte strings (8, s, w, and 6), xmlrpc_parse_value() returns a pointer into the xmlrpc_value's internal representation. That means you must coordinate your access to the string with the setting of and existence of the xmlrpc_value. This isn't always easy. But as long as you hold a reference to the xmlrpc_value which you give to xmlrpc_parse_value() and don't modify it at all, you should be safe to access the string.
For the A, S, and V format specifiers, xmlrpc_parse_value() returns a pointer to an xmlrpc_value object without a reference to it. This means you're in the same boat with these format specifiers as described for strings above. You must make sure something else holds a reference to the object while you are using it. (or at least until you can acquire one of your own).
The easiest functions for building and interpreting xmlrpc_value objects, which represent XML-RPC values, use a format string to describe the type of the XML-RPC value. For example the format string might say that the XML-RPC value is an integer. Or it might say it is an array of 4 dates. This section explains how a format string describes the type of an XML-RPC value.
The format string also defines a translation between the XML-RPC value and a sequence of C-friendly data types that represent the same information. For example, it might say that a floating point number translates to or from a C 'double' value, or that an array of 4 dates translates to or from 4 C time_t values.
When you call a function that builds an xmlrpc_value, you must supply arguments of the type prescribed here. If you don't, the result is undefined. (The function might fail, or generate some arbitrary value or generate an invalid value or make the program crash -- the reason the build functions don't validate it for you and avoid some of the worst of these possibilities is that it would be expensive).
When you call a function that interprets an xmlrpc_value, you must supply arguments which are pointers to variables of the type prescribed here.
A format string works a lot like the format string in a printf() or scanf() function call.
Examples of format strings:
| format string | type of XML-RPC value |
|---|---|
| i | integer |
| s | string |
| (iii) | Array of 3 integers |
| {s:i,s:d} | Structure with two elements. The first has a string for a name (true of any XML-RPC structure) and an integer for a value. The second has a string for a name and a floating point number for a value. |
| {s:i,s:(ss{s:s,s:d})} | A structure whose first element has a string for a name and an integer for a value, and whose second element has a string for a name and an array for a value. That array's first two elements are strings. Its third element is a structure. That structure has two elements, both named by strings. The value of the first is a string; the value of the second is a floating point number. |
A format string describes the type of one XML-RPC value. But some types (array and structure) are compound types -- they are composed recursively of other XML-RPC values. So a single format string might involve multiple XML-RPC values.
But first, lets look at the simple (not compound) format types. These are easy. The format string consists of one of the strings in the table below. The string is called a format specifier, and in particular a simple format specifier. The table also tells what C type represents the value of that XML-RPC type when you use an Xmlrpc-c library routine to translate to or from ordinary C types.
The following table describes all of the simple format specifiers. A format string consists of either a single simple format specifier or a single compound format specifier. The next section covers compound format specifiers.
| specifier | XML-RPC type | C type |
|---|---|---|
| i | 32 bit integer (<int>) | xmlrpc_int |
| b | boolean (<boolean>) | xmlrpc_bool |
| d | double precision floating point number (<double>) | xmlrpc_double (double) |
| s | string (<string>) | const char * null-terminated UTF-8 string (doesn't work if string contains NUL). |
| s# | string (<string>) | const char * and size_t; UTF-8 pointer/length string. |
| w | string (<string>) | const wchar_t * |
| w# | string (<string>) | const wchar_t * and size_t; pointer/length string. |
| 6 | base64-encoded byte string (<base64>) | const unsigned char * and size_t; The latter is the size in bytes. |
| t | date/time (<dateTime.iso8601>) | time_t |
| 8 | date/time (<dateTime.iso8601>) | const char *; null-terminated UTF-8 string pseudo-ISO 8601 |
| p | none; an Xmlrpc-c extension for internal use. A C pointer. | void * |
| n | nil (<nil> or <ex:nil>) (not an XML-RPC type, but a common extension of XML-RPC) | none |
| I | 64 bit integer (<i8> or <ex:i8>) (not an XML-RPC type) | none |
| A | array (<array>) | xmlrpc_value * |
| S | structure (<struct>) | xmlrpc_value * |
| V | any simple or compound | xmlrpc_value * |
Note that any place you could use A or S, you could equivalently use V. The difference is that the former fail when the XML-RPC value isn't of the indicated type, which is convenient in many cases.
The details of the correspondence between the XML-RPC values and the C data structure values is the same as for the individual constructor and extractor functions such as xmlrpc_string_new() for strings or xmlrpc_read_int() for integers.
The "8" format specifier isn't really meant to be useful; you'll prefer "t". At one time, "8" was the only way to specify a datetime, and that was only because the implementers were lazy. (Note that the C representation and the XML-RPC representation are the same with this format specifier; that makes the code to implement it really easy).
With the s# and w# format specifiers, be careful to supply a size_t second argument. If you supply an integer instead (and if you code a literal such as "3", that's an integer), the compiler will won't complain, but it may generate the parameter list in the wrong format and you will get bizarre results at run time.
The "t" format specifier was new in Xmlrpc-c 1.12 (September 2007). Before that, you can use "8" instead.
The "I" format specifier was new in Xmlrpc-c 1.10 (March 2007). But as early as 1.07 (October 2006), you can use other functions to deal with 64 bit integer XML-RPC values.
The "n" format specifier and the nil type were new in Xmlrpc-c 1.02 (April 2005).
The simple format specifiers above are not sufficient to translate between an xmlrpc_value and ordinary C types. The A and S format specifiers don't help, because the "ordinary C type" for those is itself an xmlrpc_value! To build or interpret an XML-RPC array or structure, you need a compound format specifier.
A compound format specifier is a string that contains other format specifiers (either compound or simple).
Array: The compound format specifier for an array is the concatenation of specifiers for each of its elements, in index order, enclosed in "()" (i.e. parentheses). For example: (iii) (an array of 3 integers) or (i(d)) (an array with element 0 an integer, element 1 an array of one floating point number). () is an empty array.
Structure: To specify a structure, enclose a string for each member of the structure in "{}" (i.e. braces), separated by commas. The string for a member of a structure is a format specifier for the member name and a format specifier for the value, separated by a colon, e.g. s:i. An example of a complete format specifier for a structure is {s:i,s:i,s:d}. This specifies a structure with 3 members, each with a string for a name. Two of them have integer values; one has a floating point number value. Note that members of a structure do not have order. {} specifies a structure with no elements (not generally useful, but legal).
Note that there is no rule that the member name must be a string. It could be anything. But: in XML-RPC, the member name is a string, so if you build an exotic xmlrpc_value with a date as a member name and then try to use that xmlrpc_value as an RPC parameter (say, as an argument to xmlrpc_client_call(), you will fail. (In the example, xmlrpc_client_call() would fail, telling you that you haven't supplied a valid XML-RPC parameter).
What C types does a compound format specifier specify for when the XML-RPC array or structure gets translated? They are the set of C types that correspond to the constituent simple format specifiers. For example, the format string {s:s,s:(iii)}, specifies a single XML-RPC structure value that gets translated to or from six separate C types: 3 strings and 3 integers.
In case you're confused about the difference between "()" and "A", here it is: The format strings (iii) and A both specify an XML-RPC array. The former specifically specifies an array of 3 integers, while the latter could be any array at all. But the most important difference is that when you use the format string to build the XML-RPC array from ordinary C data structures, (iii) builds it from three xmlrpc_int (essentially, int) variables, while A would build the very same array from a single xmlprc_value object. This would be pretty useless all by itself, because the input and output are the same xmlrpc_value. But if you consider the format strings ((iii)(iii)(iii)) and (AAA), you can see the value.
The functions that use format strings to interpret an XML-RPC value define an extension to this format string format in which an asterisk ('*') means "ignore tail." See the descriptions of those functions for details.
These are functions for creating and interpreting XML streams that are part of an XML-RPC conversation. You don't need these functions if you use the high level client and server functions. Those take care of generating and interpreting XML without you ever seeing the XML.
These functions are for programs that control the conversation at a lower level or implement a variation on XML-RPC. For example, you might substitute some other method than HTTP to transmit the XML. (XML-RPC specifies HTTP).
An example of using these library routines to generate XML for an XML-RPC call is the program gen_sample_add_xml in the examples directory of the Xmlrpc-c source tree. It writes to Standard Output the XML for the call that the xmlrpc_sample_add_client example client makes. Here are the highlights:
params = xmlrpc_build_value(&env, "(ii)",
(xmlrpc_int32) 5, (xmlrpc_int32) 7);
xmlmemblockP = XMLRPC_MEMBLOCK_NEW(char, &env, 0);
xmlrpc_serialize_call(&env, xmlmemblockP, methodName, params);
fwrite(XMLRPC_MEMBLOCK_CONTENTS(char, xmlmemblockP),
sizeof(char),
XMLRPC_MEMBLOCK_SIZE(char, xmlmemblockP),
stdout);
XMLRPC_MEMBLOCK_FREE(char, xmlmemblockP);
/* Dispose of our parameter array. */
xmlrpc_DECREF(params);
In all the XML encoding functions, the XML comes back as a character array in the form of a memory block. You supply a memory block and the encoding function appends characters to it. For some strange reason, the XML decoding functions aren't symmetrical. They take the XML as a regular C character array and a length.
The decoding functions that return an xmlrpc_value object add a reference to the object to represent the caller's use of it (so the caller must eventually release it). The encoding functions copy instead of refer to input objects, so they never add references.
The XML that these functions generates always uses UTF-8 character encoding (as in "<?xml encoding="UTF-8"?>).
Strings in the Xmlrpc-c interface also are always encoded in UTF-8, so if you take some XML and convert it naively to a C string (i.e. use the same bytes and add a terminating NUL), that XML had better use UTF-8 character encoding.
All of these functions place a limit on the size and nesting level of XML they are willing to work with (encode or decode), intended to reduce the chance of overusing computer resources.
There is a generalized resource limits facility in libxmlrpc. It is designed to cover all aspects of the Xmlrpc-c libraries, but in the present implementation it affects only XML encoding and decoding.
Any function that you ask to encode or decode XML in excess of a limit fails.
The limits are process-global (i.e. stored as C static global variables).
Each limit has a name and an integer value. Here is a list of them; the name is also the name of a C macro that you can use in the library functions to refer to the limit.
The default is 64.
Note that this limit does not control the network layer; your system may still attempt to receive XML much larger than this. After it successfully receives it into a buffer, libxmlrpc will refuse to process it and discard it.
The default is 512K.
Example:
xmlrpc_limit_set(XMLRPC_XML_SIZE_LIMIT_ID, 5e6);
This function sets a limit.
Example:
printf("The nesting limit is %u",
xmlrpc_limit_get(XMLRPC_NESTING_LIMIT_ID);
This function queries a limit.
All of the XML encoding ("serializing") functions return results like this: The function takes a handle of a memory block as an argument, and returns the XML by appending it to the memory block. The value does not have a terminating NUL.
xmlrpc_serialize_call() creates the XML for an entire XML-RPC call. As an XML-RPC client, all you have to do to make a call is transmit this text string over an HTTP connection to an XML-RPC server (and then accept the forthcoming response).
To use the function, you supply a method name and the parameters and the function gives you XML. You supply the parameters as an xmlrpc_value array object, one array element per parameter.
The XML-RPC dialect this subroutine generates is i8.
This is the same as xmlrpc_serialize_call() except that it has an argument to specify the XML-RPC dialect for the generated XML.
This subroutine was new in Xmlrpc-c 1.11 (June 2007).
xmlrpc_serialize_response() creates the XML for an entire success response to an XML-RPC call. As an XML-RPC server, all you have to do to respond to (and thus complete) a call is transmit this text string over the HTTP connection on which you received the call. You supply the response value as an xmlrpc_value object and the function gives you XML.
The XML-RPC dialect this subroutine generates is i8.
This is the same as xmlrpc_serialize_response() except that it has an argument to specify the XML-RPC dialect for the generated XML.
This subroutine was new in Xmlrpc-c 1.11 (June 2007).
xmlrpc_serialize_fault() is similar to xmlrpc_serialize_response() except that it creates the XML for a fault response. You supply the fault information as a xmlrpc_env object.
There is no corresponding function to decode fault XML, as explained in XML Decoding.
xmlrpc_serialize_params() generates a <params> XML element. (a <params> element is part of an XML-RPC call). You give it an xmlrpc_value array object and it makes a parameter out of each element of the array.
The XML-RPC dialect this subroutine generates is i8.
There is no corresponding function to decode parameter XML, as explained in XML Decoding.
This is the same as xmlrpc_serialize_params() except that it has an argument to specify the XML-RPC dialect for the generated XML.
There is no corresponding function to decode parameter XML, as explained in XML Decoding.
This subroutine was new in Xmlrpc-c 1.11 (June 2007).
xmlrpc_serialize_value() generates a <value> XML element (<value> elements are found in XML-RPC calls and responses). You give it the value as an xmlrpc_value object.
The XML-RPC dialect this subroutine generates is i8.
You can decode value XML with xmlrpc_parse_value_xml()
This is the same as xmlrpc_serialize_value() except that it has an argument to specify the XML-RPC dialect for the generated XML.
There is no corresponding function to decode value XML, as explained in XML Decoding.
This subroutine was new in Xmlrpc-c 1.11 (June 2007).
These are functions you can use to decode the two kinds of XML documents that occur in XML-RPC: call and response.
You might expect the library to contain functions for decoding the individual XML-RPC entities such as parameter lists, since the library does include functions for going the other direction (e.g. xmlrpc_serialize_value2()). But it doesn't because of a basic asymmetry in the world of XML: It is much harder to parse XML than to construct it. Because of this, a program that has to parse XML-RPC normally uses a general purpose XML document parser (such as libxml2 or expat) to parse an entire call or response and never actually sees the XML for the individual XML-RPC entities. So a function to parse XML text for just an XML-RPC value would be waste of development effort.
xmlrpc_parse_value_xml() interprets the XML for an XML-RPC value -- a <value> element. You supply the XML and the function returns the value it represents as an xmlrpc_value object.
You probably won't find this useful, because in the course of processing XML-RPC, you rarely find a <value> element on its own, as explained at the top of XML Decoding.
xmlrpc_parse_call() interprets the XML for an entire XML-RPC call. You supply XML and the function returns the name of the method called and its parameters. The parameters come as an xmlrpc_value array object, with one element for each parameter.
xmlrpc_parse_response2() interprets the XML for an entire XML-RPC response. You supply XML and the function returns the response value or fault information, depending on whether it is a success or failure response. The response value comes back as an xmlrpc_value object. The fault information as an xmlrpc_env object.
xmlrpc_parse_response() is obsolete, superseded by xmlrpc_parse_response2(). The essential difference is that xmlrpc_parse_response() merges the concept of a response that indicates failure and the concept of a failure to decode the response (i.e. the envP and faultCodeP and faultStringP arguments of xmlrpc_parse_response2().
These facilities follow the Xmlrpc-c rules for character sets and encodings where you are encoding or decoding an entire XML-RPC message.
Facilities for encoding just a fragment of an XML-RPC message (in particular, an XML-RPC value, as a <value> element), do not include an XML Processing Instruction declaring the encoding. Likewise, facilities for decoding a fragment typically will not see an XML Processing Instruction and thus will work properly only if the fragment is encoded in UTF-8.
The JSON feature of XML-RPC For C/C++ is a bonus feature unrelated to XML-RPC. It lets you use Xmlrpc-c XML-RPC value processing facilities (i.e. the xmlrpc_value data type) with JSON, but does not provide any way for you use use JSON in any client/server communication (and if it did, that would not be XML-RPC).
The idea is that if you already know Xmlrpc-c and have code to deal with xmlrpc_value, or have a program that uses Xmlrpc-c for XML-RPC communication, it may be convenient to be able to use the same facilities to represent integers and arrays and such as JSON.
While you could instead use Xmlrpc-c facilities such as xmlrpc_serialize_value to represent integers and arrays and such in XML, JSON is usually more convenient. Indeed, if JSON had been around when XML-RPC was invented, XML-RPC might have been JSON-RPC instead. (In fact, there exists a protocol called JSON-RPC today, but it is fundamentally different from XML-RPC in that it is not an RPC protocol at all, but rather a general messaging protocol).
Here is an example of how you might use these JSON facilities in your XML-RPC server: Assume this server performs an RPC by reading information out of a file and sending it to a client. You could define that file to be in JSON format. So use json_parse_value() to read the information from the file as a xmlrpc_value. Now use that xmlrpc_value as the return value of your XML-RPC method function.
The JSON taxonomy of values is somewhat different from the XML-RPC taxonomy; Xmlrpc-c resolves that as follows:
There is a complete example of using the JSON encoding and decoding facilities in the examples directory of the Xmlrpc-c source tree as json.c.
Before Xmlrpc-c 1.25 (December 2010), JSON integers mapped to XML-RPC standard 32 bit integers. (We accepted this compatibility-breaking change because we believed there were virtually no users of this new facility at that time).
xmlrpc_serialize_json() generates a JSON representation of an XML-RPC value, which you supply as an xmlrpc_value object.
Example:
xmlrpc_mem_block * jsonP;
xmlrpc_value * valP;
jsonP = XMLRPC_MEMBLOCK_NEW(char, &env, 0);
xmlrpc_serialize_json(&env, valP, jsonP);
printf("JSON: %s\n", XMLRPC_MEMBLOCK_CONTENTS(char, jsonP));
Prototype:
void
xmlrpc_serialize_json(xmlrpc_env * const envP,
xmlrpc_value * const valP,
xmlrpc_mem_block * const jsonP);
valP points to the XML-RPC value object to be converted.
xmlrpc_serialize_json() appends the JSON representation of the XML-RPC value to the memory block pointed to by jsonP, and an ASCIIZ string.
envP points to the environment variable.
This subroutine was new in Xmlrpc-c 1.22 (March 2010).
xmlrpc_parse_json() generates an xmlrpc_value that represents the value that is represented by JSON text you supply.
Example:
const char * const json = "{"serial": 7}
xmlrpc_value * const valP = xmlrpc_parse_json(&env, json);
xmlrpc_value * serialP;
int serial;
xmlrpc_struct_find_value(&env, valP, "serial", &serialP);
xmlrpc_read_int(&env, serialP, &serial);
assert(serial == 7);
Prototype:
xmlrpc_value *
xmlrpc_parse_json(xmlrpc_env * const envP,
const char * const json);
json is the JSON representation of the value, as an ASCIIZ string.
The return value is a new XML-RPC value object that represents the value. The caller owns a reference to the value and must enventually release it.
envP points to the environment variable.
xmlrpc_parse_json recognizes and ignores comments in C++/Java/Javascript form (i.e. everything from "//" to the end of the line is a comment). This is an extension of JSON; standard JSON has no comments.
This subroutine was new in Xmlrpc-c 1.22 (March 2010).
xmlrpc_version() tells you what version (release, level) of libxmlrpc is linked to your program.
Example:
unsigned int major, minor, point;
xmlrpc_version(&major, &minor, &point);
printf("libxmlrpc version %u.%u.%u\n", major, minor, point);
Prototype:
void
xmlrpc_version(unsigned int * const majorP,
unsigned int * const minorP,
unsigned int * const pointP);
This is declared in <xmlrpc-c/base.h> as follows:
The numbers returned are those you see in regular text references to the version of XML-RPC For C/++ from which that libxmlrpc comes, E.g. "1.16.31."
This function was new in Xmlrpc-c 1.25 (December 2010). Before that, you can use the following external integer variables (Still available, but now deprecated, because it's not possible to export integer variables directly in a Windows DLL).
extern unsigned int const xmlrpc_version_major;
extern unsigned int const xmlrpc_version_minor;
extern unsigned int const xmlrpc_version_point;
These symbols were new in Xmlrpc-c 1.13 (December 2007).