SOAP Interface
From ShockvoiceWiki
This document describes how to use the SOAP interface of Shockvoice to control it and do maintenance tasks
Contents |
Configuring the interface
Before you can use the interface, you need to specify a user and a password to gain access via SOAP to your server. This can be done by using the svsoap.exe (windows) oder the bash script svsoap (linux) that comes with the server files. Simply enter this on the commandline:
Windows:
svsoap.exe <username> <password>
Linux:
./svsoap <username> <password>
This will create a file soap_passwd.xml that contains your credentials. 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.
ATTENTION: Not all functions are currently implemented. Functions which are marked with (*) will be implemented until the final 0.9.4 version. The rest are available in the beta.
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 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 serverStats(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 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.
Using PHP to access the interface
This is a small example PHP script that calls the serverStats() function and prints its result. It uses the nusoap library for PHP.
<?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('serverStats', array('parameters' => $param), , , false, true);
if ($client->fault)
{
print_r($result);
}
else
{
$err = $client->getError();
if ($err)
{
echo $err;
}
else
{
print_r($result);
}
}
?>
