1. xmlrpcval
Prev | Chapter 7. Class documentation | Next

## 1. xmlrpcval

This is where a lot of the hard work gets done. This class enables the creation and encapsulation of values for XML-RPC.

Ensure you've read the XML-RPC spec at http://www.xmlrpc.com/stories/storyReader$7 before reading on as it will make things clearer.

The `xmlrpcval` class can store arbitrarily complicated values using the following types: `i4 int boolean string double dateTime.iso8601 base64 array struct`. You should refer to the spec for more information on what each of these types mean.

### 1.1. Notes on types

#### 1.1.1. int

The type `i4` is accepted as a synonym for `int` when creating xmlrpcval objects. The xml parsing code will always convert `i4` to `int`: `int` is regarded by this implementation as the canonical name for this type.

#### 1.1.2. base64

Base 64 encoding is performed transparently to the caller when using this type. Decoding is also transparent. Therefore you ought to consider it as a "binary" data type, for use when you want to pass data that is not 7-bit clean.

#### 1.1.3. boolean

The php values `true` and `1` map to `true`. All other values (including the empty string) are converted to `false`.

#### 1.1.4. string

Characters <, >, ', ", &, are encoded using their entity reference as &lt; &gt; &apos; &quot; and &amp; All other characters outside of the ASCII range are encoded using their character reference representation (e.g. &#200 for é). The XML-RPC spec recommends only encoding `< &` but this implementation goes further, for reasons explained by the XML 1.0 recommendation. In particular, using character reference representation has the advantage of producing XML that is valid independently of the charset encoding assumed.

### 1.2. Creation

The constructor is the normal way to create an `xmlrpcval`. The constructor can take these forms:

`$myVal = new xmlrpcval(` | `)`; |

`$myVal = new xmlrpcval(` | $stringVal`)`; |

`string` | `$stringVal;`

`$myVal = new xmlrpcval(` | $scalarVal, |
| $scalartyp`)`; |

`mixed` | `$scalarVal;`
`string` | `$scalartyp;`

`$myVal = new xmlrpcval(` | $arrayVal, |
| $arraytyp`)`; |

`array` | `$arrayVal;`
`string` | `$arraytyp;`

The first constructor creates an empty value, which must be altered using the methods `addScalar`, `addArray` or `addStruct` before it can be used.

The second constructor creates a simple string value.

The third constructor is used to create a scalar value. The second parameter must be a name of an XML-RPC type. Valid types are: "`int`", "`boolean`", "`string`", "`double`", "`dateTime.iso8601`", "`base64`".

Examples:

    $myInt = new xmlrpcvalue(1267, "int");
    $myString = new xmlrpcvalue("Hello, World!", "string");
    $myBool = new xmlrpcvalue(1, "boolean");
    $myString2 = new xmlrpcvalue(1.24, "string"); // note: this will serialize a php float value as xmlrpc string

The fourth constructor form can be used to compose complex XML-RPC values. The first argument is either a simple array in the case of an XML-RPC `array` or an associative array in the case of a `struct`. The elements of the array must be `xmlrpcval` objects themselves.

The second parameter must be either "`array`" or "`struct`".

Examples:

    $myArray = new xmlrpcval(
      array(
        new xmlrpcval("Tom"),
        new xmlrpcval("Dick"),
        new xmlrpcval("Harry")
      ),
      "array");

    // recursive struct
    $myStruct = new xmlrpcval(
      array(
        "name" => new xmlrpcval("Tom", "string"),
        "age" => new xmlrpcval(34, "int"),
        "address" => new xmlrpcval(
          array(
            "street" => new xmlrpcval("Fifht Ave", "string"),
            "city" => new xmlrpcval("NY", "string")
          ),
          "struct")
      ),
      "struct");

See the file `vardemo.php` in this distribution for more examples.

### 1.3. Methods

#### 1.3.1. addScalar

`$ok = $val->addScalar(` | $stringVal`)`; |

`string` | `$stringVal;`

`$ok = $val->addScalar(` | $scalarVal, |
| $scalartyp`)`; |

`mixed` | `$scalarVal;`
`string` | `$scalartyp;`

If `$val` is an empty `xmlrpcval` this method makes it a scalar value, and sets that value.

If `$val` is already a scalar value, then no more scalars can be added and `0` is returned.

If `$val` is an xmlrpcval of type array, the php value `$scalarval` is added as its last element.

If all went OK, `1` is returned, otherwise `0`.

#### 1.3.2. addArray

`$ok = $val->addArray(` | $arrayVal`)`; |

`array` | `$arrayVal;`

The argument is a simple (numerically indexed) array. The elements of the array must be `xmlrpcval` objects themselves.

Turns an empty `xmlrpcval` into an `array` with contents as specified by `$arrayVal`.

If `$val` is an xmlrpcval of type array, the elements of `$arrayVal` are appended to the existing ones.

See the fourth constructor form for more information.

If all went OK, `1` is returned, otherwise `0`.

#### 1.3.3. addStruct

`$ok = $val->addStruct(` | $assocArrayVal`)`; |

`array` | `$assocArrayVal;`

The argument is an associative array. The elements of the array must be `xmlrpcval` objects themselves.

Turns an empty `xmlrpcval` into a `struct` with contents as specified by `$assocArrayVal`.

If `$val` is an xmlrpcval of type struct, the elements of `$arrayVal` are merged with the existing ones.

See the fourth constructor form for more information.

If all went OK, `1` is returned, otherwise `0`.

#### 1.3.4. kindOf

`$kind = $val->kindOf(` | `)`; |

Returns a string containing "struct", "array" or "scalar" describing the base type of the value. If it returns "undef" it means that the value hasn't been initialised.

#### 1.3.5. serialize

`$outString = $val->serialize(` | `)`; |

Returns a string containing the XML-RPC representation of this value.

#### 1.3.6. scalarVal

`$scalarVal = $val->scalarVal(` | `)`; |

If `$val->kindOf() == "scalar"`, this method returns the actual PHP-language value of the scalar (base 64 decoding is automatically handled here).

#### 1.3.7. scalarTyp

`$typeName = $val->scalarTyp(` | `)`; |

If `$val->kindOf() == "scalar"`, this method returns a string denoting the type of the scalar. As mentioned before, `i4` is always coerced to `int`.

#### 1.3.8. arrayMem

`$xmlrpcVal = $val->arrayMem(` | $n`)`; |

`int` | `$n;`

If `$val->kindOf() == "array"`, returns the `$n`th element in the array represented by the value `$val`. The value returned is an `xmlrpcval` object.

    // iterating over values of an array object
    for ($i = 0; $i < $val->arraySize(); $i++)
    {
      $v = $val->arrayMem($i);
      echo "Element $i of the array is of type ".$v->kindOf();
    }

#### 1.3.9. arraySize

`$len = $val->arraySize(` | `)`; |

If `$val` is an `array`, returns the number of elements in that array.

#### 1.3.10. structMem

`$xmlrpcVal = $val->structMem(` | $memberName`)`; |

`string` | `$memberName;`

If `$val->kindOf() == "struct"`, returns the element called `$memberName` from the struct represented by the value `$val`. The value returned is an `xmlrpcval` object.

#### 1.3.11. structEach

`list($key, $value) = $val->structEach(` | `)`; |

Returns the next (key, value) pair from the struct, when `$val` is a struct. `$value` is an xmlrpcval itself. See also structreset().

    // iterating over all values of a struct object
    $val->structreset();
    while (list($key, $v) = $val->structEach())
    {
      echo "Element $key of the struct is of type ".$v->kindOf();
    }

#### 1.3.12. structReset

`$val->structReset(` | `)`; |

Resets the internal pointer for `structEach()` to the beginning of the struct, where `$val` is a struct.

#### 1.3.13. structMemExists

`$exists = $val->structMemExsists(` | $memberName`)`; |

`string` | `$memberName;`

Returns `TRUE` or `FALSE` depending on whether a member of the given name exists in the struct.

Prev | Up | Next
Chapter 7. Class documentation | Home | 2. xmlrpcmsg