Documentation | Internals | API Reference
The Centova Cast XML API provides a simple XML-over-HTTP interface to Centova Cast's automation API. API methods are called via a standard HTTP POST request to the api.php script in the Centova Cast web root, in which an XML request packet is provided as POST data. Centova Cast responds to API requests by returning an XML response packet as the payload of the HTTP response.
XML Request Packet Structure
An XML request packet always begins with a standard XML header, followed by a single
<centovacast> element, a single
<request> element identifies the packet as
a request packet. The
<request> element must include both a class attribute indicating the API
method class (described under the API Method Classes sections below), as well as a method attribute
indicating the API method to be called. All API methods available are described in detail under their
respective headings below under the Server Class Method Reference
and System Class Method Reference sections below.
<request> element, one or more additional elements may be provided as arguments to the
API method. The name of each argument element must correspond to the name of an argument accepted by
the requested API method, and the contents of each argument element must specify the value of each
A typical XML request packet might look something like the following:
<?xml version="1.0" encoding="UTF-8"?> <centovacast> <request class="system" method="info"> <password>secret</password> <username>jdoe</username> </request> </centovacast>
The packet above would indicate a request to the
info method of the
system class. Two arguments,
password, are provided with values
Note that while the character encoding is specified by convention in the XML preamble, Centova Cast always expects UTF-8 character encoding in request packets regardless of the encoding specified in the XML preamble.
XML Response Packet Structure
An XML response packet always begins with a standard XML header, followed by a single
element with a
version attribute indicating the Centova Cast version, and a
indicating the hostname of the Centova Cast web interface serving the request.
<centovacast> element, a single
<response> element identifies the packet as a response
<response> element always includes a
type attribute indicating the type of result:
success (corresponding to
CSuccess in the API method reference sections) if the request was
error (corresponding to
CError in the API method reference sections) if an error
<response> element, a single
<message> attribute always contains a textual description
of the result of the request.
The <response> element may also include a
<data> element containing result data generated by the
request. For information about the structure of the data within the
<data> element, consult the
Return Value section of the specific API method you wish to call.
A typical XML response packet might look something like the following:
<?xml version="1.0" encoding="UTF-8"?> <centovacast version="3.0.0" host="example.com:2199"> <response type="success"> <message>Check complete</message> <data> <row> <username>jdoe</username> <state>up</state> <expected>up</expected> <sourcestate>up</sourcestate> <sourceexpected>up</sourceexpected> </row> </data> </response> </centovacast>
The response packet above would indicate that a request was successfully processed by Centova Cast version 3.0.0. One result row was generated by the request, which contained fields entitled username, state, expected, sourcestate, and sourceexpected, whose values were jdoe, up, up, up, and up, respectively.
Had the response included additional result rows, these would have been represented by additional
<row> elements within the