System Class Method Reference

The sections below describe the methods available under the system class.

---

Sanity Check

Tests communication with Centova Cast.

Arguments

None.

Return Value

A result of type CSuccess is returned if the request was received successfully, otherwise CError is returned. No data is returned by this method.

---

Image Daemon Interface

Manipulates an image via Centova Cast's Image Daemon.

Arguments

The following arguments are accepted:

• in (string)
  The full pathname for the input file to read.

• out (string)
  The full pathname for the output file to create.

• action (string)
  The action to perform. Currently only resize is supported by the API.

• width (int)
  The width to which the image should be resized

• height (int)
  The height to which the image should be resized

Return Value

A result of type CSuccess is returned if the operation was successful, otherwise CError is returned. No data is returned by this method.

---

Rename Account

Changes the username of an existing account. Note that this feature makes extensive changes to an account and cannot be used while the stream is online.

Arguments

The following arguments are accepted:

• newusername (string)
  the new username for the account

Return Value

A result of type CSuccess is returned if the operation was successful, otherwise CError is returned. No data is returned by this method.

---

Silently Update Media Library

Requests that the web control panel update the media library for the specified account(s). This request may be made anonymously (no authentication required) and to preserve privacy returns no information about the account or the tracks processed.

Arguments

The following arguments are accepted:

• accounts (string)
  A comma-separated list of usernames specifying the accounts to be reindexed.

  Example:

  bob
bob,john,harry

Return Value

A result of type CSuccess is returned if the media library was updated successfully, otherwise CError is returned. No data is returned by this method.

---

Version and Host Information

Obtains Centova Cast version information and general information about the host server.

Arguments

None.

Return Value

A result of type CSuccess is returned if the request was received successfully, otherwise CError is returned.

An array of data is returned with the following structure:

• web (array)
  an array of details for the web interface node, with the following structure:

  • version (string)
    the Centova Cast version number

  • loadavg1 (float)
    the server's 1-minute load average

  • loadavg5 (float)
    the server's 5-minute load average

  • loadavg15 (float)
    the server's 15-minute load average

  • uptime (int)
    the server's uptime in seconds

  • os (string)
    the server's OS name

  • osversion (string)
    the server's OS version, if available

  • accounts (int)
    the total number of Centova Cast accounts

  • activeaccounts (int)
    the total number of active (non-suspended/disabled) Centova Cast accounts

  • osrelease (string)
    the OS release identifier (kernel version on Linux)

  • osmachine (string)
    the OS machine identifier (kernel architecture on Linux)

  • totalram (int)
    the total amount of RAM on the server, in KB

  • freeram (int)
    the amount of free RAM on the server, in KB

  • sharedram (int)
    the amount of shared RAM on the server, in KB

  • bufferram (int)
    the amount of RAM allocated to buffers on the server, in KB

  • totalswap (int)
    the total amount of swap space on the server, in KB

  • freeswap (int)
    the amount of free swap space on the server, in KB

  • procs (in)
    the number of processes currently running on the server

---

Provision Account

Provisions a new client streaming server account in Centova Cast. Note that as of Centova Cast v2.2, account templates can and should be used for detailed configuration of new accounts. While the use of account templates is technically optional for user accounts, account templates must be used if a reseller account is being created as no other mechanism is provided to distinguish the account type.

Arguments

The following arguments are accepted:

---

When creating client accounts ...

• hostname (string)
  Specifies the hostname for the stream. This hostname should resolve to the IP address specified by the ipaddress argument.

  Example:

  radio.example.com

• ipaddress (string)
  Specifies the IP address on which the streaming server should listen. This IP address must of course be configured on the server on which Centova Cast will be running.

  Example:

  10.42.128.3

• port (int)
  Specifies the port number on which the streaming server should listen. This port must not already be in use by other Centova Cast streaming servers or other applications running on the server. Use auto to have Centova Cast select the next available port automatically.

  Example:

  8000

• rpchostid (int)
  Specifies the ID number of the hosting server on which this account should be created.

• maxclients (int)
  Specifies the maximum number of listeners that may simultaneously tune in to this stream at any given time.

  Example:

  10

• adminpassword (string)
  Specifies the password for this stream. This will be used both to administer the streaming server itself, and to allow the client to login to Centova Cast.

  Example:

  secret

• sourcepassword (string)
  Specifies the source password for this stream. This will be used to allow streaming sources to connect to the streaming server and begin broadcasting.

  Example:

  secret

• maxbitrate (int)
  Specifies the maximum bit rate for this stream, in kilobits per second (kbps). Note that some streaming servers (notably IceCast) do not enforce this setting, but it must still be specified.

  Example:

  128

• transferlimit (int)
  Specifies the maximum monthly data transfer for this stream, in megabytes (MB). If you do not wish to impose a limit, specify unlimited.

  Example:

  1000

• diskquota (int)
  Specifies the maximum disk space for this stream, in megabytes (MB). If you do not wish to impose a limit, specify unlimited.

  Example:

  100

• title (string)
  Specifies the title for the stream. This will be displayed by listeners' media players when they tune into the stream.

  Example:

  XYZ Widgets Streaming Radio

• genre (string)
  Specifies the genre of the stream.

  Example:

  Rock

  v2.0.1+

• url (string)
  Specifies the URL to the web site associated with this stream (if any).

  Example:

  http://xyzwidgets.example.com

• introfile (string)
  Specifies the path and filename to the introduction audio file for this stream, relative to the streaming host's base directory. If an absolute filename is provided, the file is assumed to exist on the web interface server and will be copied into the account. This may be left blank to specify no introduction audio file.

  Example:

  var/spool/sounds/introduction.mp3

• fallbackfile (string)
  Specifies the path and filename to the fallback audio file for this stream, relative to the streaming host's base directory. If an absolute filename is provided, the file is assumed to exist on the web interface server and will be copied into the account. This may be left blank to specify no fallback audio file.

  Example:

  var/spool/sounds/fallback.mp3

• autorebuildlist (string)
  Specifies whether or not the playlist should be rebuilt from the stream's server-side media library every time the stream is started or restarted. This has no effect if the usesource argument is set to 0.

  Possible values include:

  • 0 - Do not automatically rebuild the playlist (unless no playlist exists)
  • 1 - Automatically rebuild the playlist

• autostart (int)
  Specifies whether or not the stream should automatically be started after provisioning. Note that this option will only be used if the usesource option is set to 0 or 2. (If autoDJ support is enabled, the stream cannot be started until the client has uploaded some media.)

  Possible values include:

  • 0 - Do not automatically start the stream after provisioning. This is the default.
  • 1 - Automatically start the stream after provisioning if usesource is set to 0 or 2.

  v2.0.1+

• charset (string)
  Specifies the character set for the account.

  Example:

  ISO-8859-1 - Use the Latin-1 character set

  v2.1.4+

• servertype (string)
  Specifies the streaming server type for the stream. The selected server type must be installed on the server and enabled in Centova Cast.

  Example:

  IceCast - Use IceCast
  ShoutCast2 - Use ShoutCast DNAS v2
  ShoutCast - Use ShoutCast DNAS v1

  v2.2.0+

• apptypes (string)
  Specifies the supporting application types for the stream, possibly including a streaming source application for autoDJ support. The selected applications must be installed on the server and enabled in Centova Cast.

  Example:

  icescc - Use the "ices-cc" application
  sctrans,foo - Use the "sc_trans" and "foo" applications

  v3.0.0+

• sourcetype (string)
  DEPRECATED - use apptypes instead. Specifies the streaming source type for the stream. The selected source type must be installed on the server and enabled in Centova Cast.

  Example:

  icescc - Use ices-cc
  sctrans - Use sc_trans

  v2.2.0+

• template (string)
  Specifies the name of the account template to use for this account. The account template must exist in Centova Cast.

  Example:

  mytemplate - (Use the template named "mytemplate".)

  v2.2.0+

When creating reseller accounts ...

• maxclients (int)
  Specifies the maximum total number of listener slots that the reseller can allocate. If you do not want to limit the listener slots, specify unlimited.

  Example:

  10 - specifies that the reseller can divide up 10 listener slots between his client accounts; i.e., two 5-listener client accounts, one 10-listener client account, etc.

• resellerusers (int)
  Specifies the maximum total number of client accounts that the reseller can create. If you do not want to limit the client accounts, specify unlimited.

• transferlimit (int)
  Specifies the maximum total monthly data transfer that the reseller can allocate, in megabytes (MB). If you do not wish to impose a limit, specify unlimited.

  Example:

  10000 - specifies that the reseller can divide up 10000MB of monthly data transfer between his client accounts; i.e., two 5000MB client accounts, four 2500MB accounts, etc.

• diskquota (int)
  Specifies the maximum disk space that the reseller can allocate, in megabytes (MB). If you do not wish to impose a limit, specify unlimited.

  Example:

  10000 - specifies that the reseller can divide up 10000MB of disk space between his client accounts; i.e., two 5000MB client accounts, four 2500MB accounts, etc.

• resellerbandwidth (int)
  Specifies the total amount of bandwidth that the reseller can allocate, in kilobits-per-second (kbps). If you do not want to limit the bandwidth, specify unlimited. If you do not understand the difference between bandwidth and data transfer, specify unlimited here and enter a value for transferlimit instead.

  Example:

  512 - specifies that the reseller can divide up 512kbps of bandwidth between his client accounts; i.e., two 256kbps client accounts, four 128kbps accounts, etc.

• maxbitrate (int)
  Specifies the maximum bit rate that a client can allocate to a SINGLE CLIENT ACCOUNT. Unlike the other limits this is a per-stream value, and is NOT divided up between the client's accounts.

  Example:

  128 - specifies that regardless of any other limits, the reseller can never create a stream with a bit rate limit higher than 128kbps (i.e., a 192kbps stream would be forbidden).

• adminpassword (string)
  Specifies the password for the reseller account.

  Example:

  secret

• resellersenderemail (string)
  Specifies an alternate E-mail address which will be used as the sender or From: address for any notification messages Centova Cast sends to the reseller's clients. If not specified, the address specified in the email field is used instead.

• resellerdefcharset (string)
  Specifies the default character set for new accounts created by the reseller.

  Example:

  ISO-8859-1 - Use the Latin-1 character set

  v2.1.4+

Common settings that can be provided for either client or reseller accounts ...

• username (string)
  Specifies the username for this account. This will be used to log in to Centova Cast.

  Example:

  jdoe

• organization (string)
  Specifies the company/organization to whom this account belongs.

  Example:

  XYZ Widgets Inc.

• email (string)
  Specifies the account's E-mail address. Centova Cast will automatically send notifications to this address when necessary.

  Example:

  xyzwidgets@example.com

• timezone (string)
  Specifies the local time zone for the account, in hours relative to UTC (GMT), used to ensure that the playlist scheduler uses times that make sense to the client. Leave blank or specify auto to use the server's time zone. For reseller accounts, this is the default time zone used for all of the reseller's clients.

  Example:

  -8 - UTC -08:00 - Vancouver
  0 - UTC - London
  3 - GMT +03:00 - Moscow

  v2.0.1+

• allowproxy (int)
  Specifies whether or not the stream account be permitted to use the port-80 web proxy. For reseller accounts, this indicates whether the client can create proxy-enabled client accounts.

  Possible values include:

  • 0 - Disallow access to the port-80 proxy.
  • 1 - Allow access to the port-80 proxy.

  v2.1.4+

• locale (string)
  Specifies the locale (language) for the account. For reseller accounts, this is the default language used for all of the reseller's clients.

  Example:

  en_US - Use the US English locale.
  de_DE - Use the German locale.

  v3.0.0+

• usesource (int)
  Specifies whether or not the stream uses autoDJ capabilities. For reseller accounts, this is the default setting used for all of the reseller's clients, and if set to 0 the reseller cannot create autoDJ-enabled accounts at all.

  Possible values include:

  • 0 - Use of autoDJ is permitted, but disabled by default
  • 1 - Use of autoDJ is permitted, and enabled by default
  • 2 - Use of autoDJ is prohibited (live source must be used)

Return Value

A result of type CSuccess is returned if the account was created successfully, otherwise CError is returned. Upon success an array of data is returned with the following structure:

• account (array)
  an array of details for the new account, with the following structure (and possibly including additional values)

  • username (string)
    the username for the new account

  • ipaddress (string)
    the IP address for the new account

  • port (int)
    the port number for the new account

  • servertype (string)
    the server type for this account

  • sourcetype (string)
    the source type for this account

Remove Account

Removes an existing client streaming server account from Centova Cast. The complete account (including all settings, logs, and any source media) will be permanently deleted.

Arguments

The following arguments are accepted:

• username (string)
  Specifies the username of the stream to remove.

  Example:

  jdoe

• clientaction (string)
  Specifies how to handle client accounts if removing a reseller account.

  Possible values include:

  • delete - Delete the reseller's client accounts.
  • reparent - Move the reseller's client accounts to another reseller account

• targetreseller (string|int)
  Specifies the username or account ID of the reseller account to receive the deleted reseller's client accounts, if clientaction=reparent.

Return Value

A result of type CSuccess is returned if the streaming server account was removed successfully, otherwise CError is returned. No data is returned by this method.

---

Reparent Account

Moves a client account from one reseller (or the admin account) to another reseller (or the admin account).

Arguments

The following arguments are accepted:

• username (string)
  Specifies the username of the stream to reparent.

  Example:

  jdoe

• newreseller (string)
  Specifies the username of the new reseller account to own the account, or admin to reparent to the admin account.

  Example:

  jsmith

Return Value

A result of type CSuccess is returned if the account was moved successfully, otherwise CError is returned. No data is returned by this method.

---

Set Account Status

Changes the status of an existing client account in Centova Cast.

Arguments

The following arguments are accepted:

• status (string)
  Specifies the new status for the account.

  Possible values include:

  • disabled - Disables the account. While disabled, the account will not be permitted to log in to Centova Cast, and if it is a client account, its streaming server be shut down (if necessary) and will remain offline until the account is re-enabled. If the account is a reseller account, all of the reseller's client accounts will also be disabled.
  • enabled - Enables the account. If the account is a client account, its streaming server will not be automatically be started even if it was up prior to being disabled. If the account is a reseller account, all of the reseller's client accounts will be restored to their original state prior to the reseller account being disabled.

Return Value

A result of type CSuccess is returned if the account was updated successfully, otherwise CError is returned. No data is returned by this method.

---

Check Stream Outages

Checks the specified account(s) for outages and restarts processes as necessary. Normally this is done automatically by the cron job, but this method allows processes to be checked on-demand as well.

Arguments

None.

Return Value

A result of type CSuccess is returned on success, otherwise CError is returned. No data is returned by this method.

---

Get Account State

Returns the state (up or down) of one or more Centova Cast streaming server accounts. This can be used to monitor streams to see if any have crashed. (Note that Centova Cast's cron job automatically monitors and restarts crashed streaming servers as well.)

Arguments

None.

Return Value

A result of type CSuccess is returned if the account information could be retrieved successfully, otherwise CError is returned.

Zero or more rows of data are returned, each with the following structure:

• username (string)
  Indicates the username of the streaming server account that was tested.

• state (string)
  Indicates the actual state of the streaming server for the account.

  Possible values include:

  • up - The streaming server is online.
  • down - The streaming server is offline.

• expected (string)
  Indicates the expected state of the streaming server for the account.

  Possible values include:

  • up - The streaming server should be online.
  • down - The streaming server should be offline.

• sourcestate (string)
  Indicates the actual state of the autoDJ for the account.

  Possible values include:

  • up - The autoDJ is online.
  • down - The autoDJ is offline.

• sourceexpected (string)
  Indicates the expected state of the autoDJ for the account.

  Possible values include:

  • up - The autoDJ should be online.
  • down - The autoDJ should be offline.

---

Get Resource Utilization

Returns the resource utilization (data transfer, disk usage) of one or more Centova Cast streaming server accounts.

Arguments

None.

Return Value

A result of type CSuccess is returned if the account information could be retrieved successfully, otherwise CError is returned.

Zero or more rows of data are returned, each with the following structure:

• username (string)
  Indicates the username of the streaming server account.

• diskquota (int)
  Indicates the disk quota for the account, or -1 for unlimited.

• transferlimit (int)
  Indicates the data transfer limit for the account, or -1 for unlimited.

• diskusage (int)
  Indicates the current month's disk usage for the account.

• transferusage (int)
  Indicates the current month's data transfer usage for the account.

---

Perform Batch Operations

Runs a ServerControl method on one or more accounts.

Arguments

The following arguments are accepted:

• method (string)
  The ServerControl method to invoke for each account.

• username (string)
  A comma-separated list of usernames for which to execute the method, or all for all accounts.

Return Value

A result of type CSuccess is returned if all arguments are valid, otherwise CError is returned.

Zero or more rows of data are returned, each with the following structure:

• username (string)
  Indicates the username of the streaming server account.

• result (array)
  Indicates the result returned by the ServerControl method for this account

  • status (string)
    Indicates the status (success or error) returned by the method.

  • message (string)
    Indicates the result message returned by the method.

  • data (mixed)
    Provides the data returned by the method; data type will match the data returned by the method.

---

Account List

Returns a list of all accounts; if invoked by admin, all accounts (including resellers) are included, whereas if invoked by a reseller, only the reseller's accounts are included.

Arguments

The following arguments are accepted:

• start (int)
  the offset of the first account to retrieve

• limit (int)
  the maximum number of accounts to return

• filter (string)
  a keyword by which to filter the results

Return Value

A result of type CSuccess is returned if the account list could be loaded successfully, otherwise CError is returned.

Zero or more rows of data are returned, each representing an account. While the actual list of values returned for each account may vary from version to version, you can typically rely on the presence of the values passed to the provision API call, plus the additional elements listed below. Any other elements should be considered nonstandard, unsupported, and subject to change without notice.

• id (int)
  the internal ID number for the account

• username (string)
  the username for the account

• password (string)
  the password hash for the account (UNIX crypt() format)

---

Process Logs

Processes (and rotates, if required) the log files for all accounts. Normally this is done automatically by the cron job, but this method allows logs to be processed on-demand as well.

Arguments

None.

Return Value

A result of type CSuccess is returned on success, otherwise CError is returned. No data is returned by this method.

---

Database Import/Export

Imports or exports a database backup for an account. (Database only, no files.)

Arguments

The following arguments are accepted:

• action (string)
  The database action to perform; either import or export

  Example:

  import

• filename (string)
  The filename for the file to import from or export to.

  Example:

  /tmp/foo.ccsql

• dryrun (int)
  (action=import only.) 1 to perform a test run of the import without actually importing anything, 0 to actually import.

• nointegrity (int)
  (action=import only.) 1 to skip the integrity check, 0 to verify the integrity of the database dump.

• novalidate (int)
  (action=import only.) 0 to require a valid signature indicating that this database backup was generated by the same server it's being restored to, 1 to import backups generated on any server.

Return Value

A result of type CSuccess is returned if the import or export could be performed successfully, otherwise CError is returned. No data is returned by this method.

---

Account Backup

Creates a complete backup of an account.

Arguments

The following arguments are accepted:

• all (int)
1 to back up all accounts.

• users (int)
1 to back up all user accounts (skipping reseller accounts).

• resellers (int)
1 to back up all reseller accounts (skipping user accounts).

• username (string)
  The username of the account to back up. Ignored if all, users, or resellers is 1.

• nocontent (int)
1 to skip user content (media files, cover images, etc.), 0 to include user content.

• nologs (int)
1 to skip log files, 0 to include log files.

Return Value

A result of type CSuccess is returned if the backup could be created successfully, otherwise CError is returned.

If all, users, or resellers is 1, zero or more rows of data are returned, each with the following structure:

• username (string)
  Indicates the username of the account.

• filename (string)
  the complete pathname to the backup file that was created on the hosting server

• error (string)
  if included, indicates that this account could not be backed up, and provides a detailed error message

If username is specified, one result row is returned containing the following element(s): - filename (string)
the complete pathname to the backup file that was created on the hosting server

---

Account Restore

Restores a backup of an account.

Arguments

The following arguments are accepted:

• username (string)
  The new username to assign to the restored account.

• filename (string)
  The filename of the file containing the backup to import.

  Example:

  /tmp/foo_user_backup.zip

• rpchostid (int)
  Specifies the ID number of the hosting server onto which this account should be restored.

• reseller (string)
  Specifies the username of the reseller to whom the restored account should be assigned.

• dryrun (int)
1 to perform a test run of the import without actually importing anything, 0 to actually import.

• nointegrity (int)
1 to skip the integrity check, 0 to verify the integrity of the database dump.

• novalidate (int)
0 to require a valid signature indicating that this database backup was generated by the same server it's being restored to, 1 to import backups generated on any server.

• overwrite (int)
1 to overwrite an existing account with the same username if it exists, 0 to fail if the specified username already exists.

Return Value

A result of type CSuccess is returned if the backup could be restored successfully, otherwise CError is returned. No data is returned by this method.

---

Account Software Change

HIGHLY EXPERIMENTAL. Changes the software applications used by an account. Likely to be buggy. Will probably break your accounts. Don't even bother trying it unless you're a masochist daredevil with a penchant for wanton destruction of client account data.

Arguments

The following arguments are accepted:

• newapp (string)
  The identifier for the new application to replace the existing application of the same class. (eg: if newapp refers to a server application, the server will be changed; if newapp refers to an autoDJ application, the autoDJ will be changed.)

Return Value

A result of type CSuccess is returned if the account was updated successfully, otherwise CError is returned. No data is returned by this method. Note that while Centova Cast will apply as much of the configuration data as possible from the current application to the new application, the new application will still likely require some manual reconfiguration before it will behave as expected due to substantial differences in the options available for each application. Also note that when switching to a software application that requires additional ports, the entire account may need to be moved to a different port range.

---

Hosting Server List

Returns a list of all hosting servers managed by this web interface.

Arguments

None.

Return Value

A result of type CSuccess is returned if the host list could be loaded successfully, otherwise CError is returned.

Zero or more rows of data are returned, each representing a host.

• id (int)
  the internal ID number for the host

• parameters (array)
  the parameters for the host

  • ipaddress (string)
    the IP address for the host

  • port (int)
    the port for the host

  • title (string)
    the title for the host

  • defaultip (string)
    the default IP address for new accounts created on this host

  • hostname (string)
    the hostname used to address this host

  • proxyipaddress (string)
    the IP address for the port 80 proxy on this server

  • regionid (int)
    the ID number for the region to which this host is assigned

• status (array)
  information about the status of host

  • online (int)
    1 if the host is online, 0 if the host is offline

• accounts (array)
  information about the accounts hosted on this host

  • licensed (int)
    the number of accounts for which this server is licensed

  • active (int)
    the number of active accounts on this server

  • inactive (int)
    the number of inactive accounts on this server

---

Region List

Returns a list of all regions managed by this web interface.

Arguments

None.

Return Value

A result of type CSuccess is returned if the region list could be loaded successfully, otherwise CError is returned.

Zero or more rows of data are returned, each representing a region.

• id (int)
  the internal ID number for the region

• title (string)
  the title of the region

• name (string)
  the short name of the region

• target (string)
  an identifier indicating the selection method used to choose a host in this region when provisioning a new account

• targetid (int)
  the ID number of the target host if target is set to serverid

---