From ShockvoiceWiki

This document describes how to use the SOAP interface of Shockvoice to control it and do maintenance tasks

Contents 1 Configuring the interface 2 Testing the interface 3 List of interface functions 3.1 Server functions 3.2 User functions 3.3 Role(Group) functions 3.4 Plugin functions 3.5 Codec functions 3.5.1 List of all codecs 3.6 Upcoming functions in next SV version 4 Using PHP to access the interface

Configuring the interface

Before you can use the interface, you can specify a user and a password to gain access via SOAP to your server. The authentication is done via basic http authentication. This can be done by using the svsoap.exe that comes with the SOAP download package. Simply enter this on the commandline:

svsoap.exe <username> <password>

or if you are on mac or linux and you have a bundled server installation, use the following command

./svconsole --soappw <username> <password>

This will create a file soap_passwd.xml that contains your credentials. If you're running the bundled version of svserver and you have no separate mono installation on your machine, you can also create the xml file on any windows machine and copy the resulting file over. You can skip the step of creating a password file, but then your interface will be open to anyone. Alternatively (or additionally) you can configure the interface to listen only on localhost.

The next step is to configure the interface in the config.xml. Look for this part in the file:

<webserviceactive>false</webserviceactive>
<webserviceip>127.0.0.1</webserviceip>
<webserviceport>8080</webserviceport>

First of all change webserviceactive to true. In case you want to use a different port or want SOAP to run on a different interface than localhost edit webserviceip and/or webserviceport to fit to your needs. When you are done just restart the server.

Testing the interface

Start your server and you should be able to access http://localhost:8080 (or whatever you have configured) in your Webbrowser. It should ask you for your credentials and then respond with a lot of XML. (In case nothing happens please check the config.xml file for entry <webserviceactive>true</webserviceactive>). This is the WSDL description of the interface which you should save. Depending on which way you want to use the SOAP interface, you might need this XML as input.

List of interface functions

Next comes a list of all functions the SOAP interface currently supports. All functions return a boolean value indicating the success of the function. They also take two strings by reference in which they return information about what was done or what the error was if any.

Server functions

bool serverStart(int serverid, ref string message, ref string errors)

Starts a server and updates the activity status in the database

bool serverStop(int serverid, ref string message, ref string errors)

Stops a server and updates the activity status in the database

bool serverReload(int serverid, ref string message, ref string errors)

Reloads the server configuration. This will restart the instance.

bool serverCreate(string name, string description, string password, int max_users, int port, bool no_anonymous,
                  bool active, string homepage, bool register, bool list_on_svn, ref int serverid, 
                  ref string message, ref string errors)

Creates a new server.

bool serverCreateDefaultChannels(int server_id, ref string message, ref string errors)

Creates all default channels on a server. These can be configured in the servers config.xml

bool serverCreateDefaultRoles(int server_id, string roles, ref string message, ref string errors)

Creates all default roles on a server. These can be configured in the servers config.xml

bool serverModify(int serverid, string name, string description, int max_users, int port, bool no_anonymous,
                  bool active, string homepage, bool register, bool list_on_svn, ref string message, 
                  ref string errors)

Modifies an existing server

bool serverSetBanner(int serverid, bool active, string banner_url, string banner_link_url, 
                     ref string message, ref string errors)  

Resets the displayed banner in a server

bool serverClone(int serverid, string name, int port, ref int newserverid, ref string message, ref string errors)

Clones an existing server onto a new port with a new name.

bool serverDelete(int serverid, ref string message, ref string errors)

Deletes a server including all its information like users, channels, groups, etc.

bool serverList(ref string message, ref string errors)

Returns a list of all servers that currently exist

User functions

bool userCreate(string name, string password, bool isadmin, int serverid, ref int userid, 
                ref string message, ref string errors)

Creates a new user on a server instance. This user will have initially no permissions. If you specify the isAdmin flag, the user will have superadmin permissions on all servers. To get a better control over permissions, you will need to also create a role for the user and add the specific permissions that the user should have.

bool userModify(int userid, string password, bool isadmin, int serverid, ref string message, ref string errors)

Modifies an existing user.

bool userDelete(int userid, ref string message, ref string errors)

Deletes a user including all his information

bool userClone(int userid, int serverid, string newname, string newpassword, ref int newuserid, 
               ref string message, ref string errors)

Clones a user including all his permission information onto a new server. You can use this to easily create new users from a template user account.

bool userList(int serverid, ref string message, ref string errors) 

Returns a list of all users for a server instance.

Role(Group) functions

bool roleFind(string name, int server_id, ref int role_id, ref string message, ref string errors)

Finds a role by its name on a server and returns its role ID.

bool roleCreate(string name, ref int role_id, ref string message, ref string errors) 

Creates a new role. After creating a role, you need to assign it specific permissions using the roleSetPermission command and then assign the role to a user using the roleAssign command.

bool roleModify(int role_id, string name, ref string message, ref string errors) 

Modifies an existing role.

bool roleDelete(int role_id, ref string message, ref string errors) 

Deletes an existing role.

bool roleAssign(int role_id, int user_id, ref string message, ref string errors) 

Assigns a role to a user.

bool roleRevoke(int role_id, int user_id, ref string message, ref string errors) 

Revokes a role from a user.

bool roleSetPermission(int role_id, string permission_id, int assign, int execute, 
                       ref string message, ref string errors) 

Sets a specific permission (for example SUM for user modification permission) for a role. To assign this permission, use a value of 1 for execute. If you also want this person to be able to give this permission to others, use a value of 1 for assign. For non-boolean permissions like quota, you can use values bigger than 1.

bool roleList(ref string message, ref string errors) 

Returns a list of all roles.

Plugin functions

bool pluginActivate(int serverid, string pluginid, ref string message, ref string errors)

Activates a plugin on a server.

bool pluginDeactivate(int serverid, string pluginid, ref string message, ref string errors)

Deactivates a plugin on a server.

bool pluginSetQuota(int serverid, string pluginid, int quota, ref string message, ref string errors) (*)

Sets a new quota value for a plugin on a server.

bool pluginList(int server_id, ref string message, ref string errors)

Returns a list of all plugins that are active on a server.

Codec functions

bool codecAdd(int server_id, string codecname, int quality, string qualityname, 
              ref string message, ref string errors)

This adds a new codec option to the server which users can then use. Codecname and Quality identify the codec option. Qualityname is a text string that describes the codec and that will be stored on the server and sent to the clients on connect to display in the codec select boxes. It can be anything and it is possible to use localized versions of these strings in your own language if you choose to do so.

bool codecRemove(int server_id, string codecname, int quality, ref string message, ref string errors)

Removes the codec option from the server. It may not be in use at the time or this function will return an error.

bool codecRemoveAllQualities(int server_id, string codecname, ref string message, ref string errors)

This function will remove all quality options of one codec type. None of the options may be currently in use.

bool codecReplace(int server_id, string oldcodecname, int oldquality, string newcodecname, int newquality, 
                         ref string message, ref string errors)

This function will replace one codec option with another one in case you want to delete a codec option that is in use.

bool codecList(int server_id, ref string message, ref string errors)

Lists all active codec options on the server.

List of all codecs

This is a list of all possible codecs, their names, quality and qualityname values for use with the codec functions above:

codecname, quality, qualityname
"CELT", 0, "CELT 32kbits/32khz"
"CELT", 1, "CELT 40kbits/32khz"
"CELT", 2, "CELT 48kbits/32khz"
"GSM6", 0, "GSM 52kbits/32khz"
"SPEX", 0, "Speex 8kbits/16khz"
"SPEX", 1, "Speex 12kbits/16khz"
"SPEX", 2, "Speex 16kbits/16khz"
"SPEX", 3, "Speex 24kbits/16khz"
"SPEX", 4, "Speex 32kbits/16khz"
"SPEX", 5, "Speex 16kbits/32khz"
"SPEX", 6, "Speex 24kbits/32khz"
"SPEX", 7, "Speex 32kbits/32khz"
"SPEX", 8, "Speex 38kbits/32khz"
"SPEX", 9, "Speex 44kbits/32khz"

Upcoming functions in next SV version

• serverSetDefaultRoles (int server_id, int anon_role, int reg_role, ref string message, ref string errors)
• serverSetDefaultCodec (int server_id, int defaultquality, string defaultcodec, ref string message, ref string errors)
• serverSetRedirect (int server_id, bool redirect_active, string redirect_url, ref string message, ref string errors)
• serverSetMaintenanceMode (int server_id, bool maintenance_mode_active, string maintenance_mode_message, string maintenance_mode_altserver, ref string message, ref string errors)
• serverSendMessage (int server_id, string text, ref string message, ref string errors)
• serverKickUser (int server_id, int user_id, ref string message, ref string errors)
• banAddUserID (int server_id, int user_id, string endtime, string reason, ref string message, ref string errors)
• banAddAddress (int server_id, string address, string endtime, string reason, ref string message, ref string errors)
• banRemoveAddress (int server_id, string address, ref string message, ref string errors)
• banList (int server_id, ref string message, ref string errors)
• channelCreate (int server_id, int parent_id, string name, string password, int max_users, string codec, int quality, int type, int ttl, string topic, string description, bool adminOnly, bool noAnonymous, bool noTempSubchannels, bool noRegSubchannels, bool noAdminSubchannels, bool moderated, bool hidden, int role_id, ref string message, ref string errors)
• channelModify (int channel_id, int parent_id, string name, int max_users, string codec, int quality, int type, int ttl, string topic, string description, bool adminOnly, bool noAnonymous, bool noTempSubchannels, bool noRegSubchannels, bool noAdminSubchannels, bool moderated, bool hidden, int role_id, ref string message, ref string errors)
• channelSetPassword (int channel_id, string password, ref string message, ref string errors)
• channelDelete (int channel_id, ref string message, ref string errors)
• channelList (int server_id, ref string message, ref string errors)
• channelBanAdd (int channel_id, int user_id, string endtime, string reason, ref string message, ref string errors)
• channelBanRemove (int channel_id, int user_id, ref string message, ref string errors)
• channelBanList (int server_id, ref string message, ref string errors)
• voicegroupCreate (int server_id, int channel_id, string name, string password, int role_id, bool moderated, bool hidden, bool no_anonymous, bool admin_only, ref string message, ref string errors)
• voicegroupModify (int voicegroup_id, int channel_id, string name, int role_id, bool moderated, bool hidden, bool no_anonymous, bool admin_only, ref string message, ref string errors)
• voicegroupSetPassword (int voicegroup_id, string password, ref string message, ref string errors)
• voicegroupDelete (int voicegroup_id, ref string message, ref string errors)
• voicegroupList (int server_id, ref string message, ref string errors)
• userSetExpiration (int user_id, bool expires, string expiredate, ref string message, ref string errors)
• userGetRoles (int user_id, int server_id, ref string message, ref string errors)

Using PHP to access the interface

This is a small example PHP script that calls the serverList() function and prints its result. It uses the nusoap library for PHP. For a complete implementation of all SOAP functions in PHP, check out our SOAP package we have for download. It contains all that is needed.

<?php

require_once('lib/nusoap.php');

$client = new nusoap_client('svsoap.xml', 'wsdl');
$client->setCredentials('user', 'password');
$client->setEndpoint("http://localhost:8080/");

$param = array('message' => , 'errors' => );
$result = $client->call('serverList', array('parameters' => $param), , , false, true);

if ($client->fault) 
{
	print_r($result);
} 
else 
{
	$err = $client->getError();
	if ($err) 
	{
		echo $err;
	} 
	else 
	{
		print_r($result);
	}
}

?>