XML API

  1. API Reference
    1. API Types
    2. Class Types
    3. JSON API
    4. XML API
    5. Session API
    6. JSON and XML APIs - Asynchronous API Responses
    7. Server Class Method Reference {#apiserverclass}
    8. System Class Method Reference {#apisystemclass}
  2. System Accounts
  3. Advanced Configurations
    1. Dual v3/v2 Deployment
    2. Using centovacast.conf
  4. Command-line Tools
    1. Controlling Centova Cast
    2. Diagnostic Report Generator
    3. Fixing Problems
    4. Centova Cast Management Utility
      1. Management Utility Invocation
      2. Output Formats
    5. Reinstalling Centova Cast
    6. Uninstalling Centova Cast
    7. Update Utility
  5. Customizations
    1. Init Script
    2. Menu Customizations
    3. Wrapping Server Applications
  6. Event Scripts
    1. Event Script Reference
    2. Event Notification Scripts
    3. Event Script Structure
  7. Files and Paths
    1. Account Files and Paths
    2. Core Files and Paths
    3. Formats
      1. nextsong.log File Format
  8. Plugins
    1. Event Script Reference
    2. Example Plugin
    3. Plugins API
    4. Plugin Structure

XML API

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.

Request Stanza

Inside the <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.

Parameters

Within the <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 argument.

Example

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, username and password, are provided with values jdoe and secret, respectively.

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 <centovacast> element with a version attribute indicating the Centova Cast version, and a host attribute indicating the hostname of the Centova Cast web interface serving the request.

Response Type

Inside the <centovacast> element, a single <response> element identifies the packet as a response packet. The <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 successful, or error (corresponding to CError in the API method reference sections) if an error occurred.

Response Content

Within the <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.

Example

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 <data> elements.

Previous: JSON API
Section: API Reference
Next: Session API