Developing Plugins
From ShockvoiceWiki
This document describes how to develop plugins for Shockvoice.
Contents |
Why develop plugins?
Developing plugins gives you the possibility to extend Shockvoice by your own functions. Shockvoice provides plugins with a list of methods to extend client and server. Among them are:
- Add new forms to the client.
- Add new functions to the main menu and context menus.
- Listen to communication between client & server
- Automate tasks
- Add a new subservice to the server
- Do maintenance tasks on the server
- much more...
What do I need?
To develop plugins for Shockvoice you will need Mono or the .NET Framework and ideally some kind of development environment. We recommend Visual C# Express, which can be obtained for free from Microsoft. On Linux, MonoDevelop is an alternative, however it does not provide tools for designing UI for plugins which uses Windows.Forms.
Libraries
This is a list of libraries that are used for development of plugins.
shockvoice_api.dll
The shockvoice API library contains all interface and class definitions you will need. A detailed description follows in the next chapters.
Plugin Interface
The plugin interface for Shockvoice consists of a series of interfaces which can be implemented depending on the kind of plugin you want to do.
- Base Plugin Interface - This is the plugin interface that all plugins have to implement.
- Client Plugin Interface - This interface has to be used for implementation of a plugin that runs in the client
- Server Plugin Interface - This interface has to be used for implementation of a plugin that runs in the server
- Authentication Plugin Interface - This interface is used to attach the server to a third party authentication system like a forum or clan website.
- Audio Plugin Interface - This interface is used to implement a new audio input/output plugin for the client.
This documentation covers client and server plugins only.
Base Plugin Interface
The base plugin interface is the one that all plugins have to be implemented. Since client and server plugin interfaces inherit from this interface, it is not necessary to implement it explicitly. The definition of the interface is as follows:
<source lang="csharp">
public interface Plugin
{
string getID();
string getName();
string getDescription();
int getVersionMajor();
int getVersionMinor();
Types.PluginType getPluginType();
}
</source>
string getID();
In this function you are expected to return a unique ID for your plugin. Try to keep it as short as possible since it is used for identifying network packages and the longer you choose it, the bigger the overhead of handling your plugin traffic if there is any. The current plugin IDs of the SV plugins are as follows:
- sv_chat
- sv_wboard
- sv_webbrowser
- sv_vmail
- sv_mediaplayer
- sv_g15
- sv_inpwin
- sv_dxaudio
- sv_alsaaudio
Choose the name wisely. It should be short but long enough so no conflicts are likely to occur. If 2 different plugins have the same ID, there will be communication problems. If your plugin has server and client parts, both have to have the same ID though in order for them to communicate together.
string getName();
This function will return a name of your plugin, preferrably in english language.
string getDescription();
This function will return a description of your plugin
int getVersionMajor();
This function will return a major version number of your plugin. If your plugin has the version 1.0 then this function will return 1.
int getVersionMinor();
This function will return a minor version number of your plugin. If your plugin has the version 1.0 then this function will return 0.
Types.PluginType getPluginType();
This function will return the type of your plugin. Valid values are:
- Types.PluginType.SERVERSIDE_PLUGIN
- Types.PluginType.CLIENTSIDE_PLUGIN
- Types.PluginType.AUTHENTICATION_PLUGIN
- Types.PluginType.AUDIO_PLUGIN
- Types.PluginType.INPUT_PLUGIN
Client Plugin Interface
The client plugin interface must be implemented by all client plugins. It inherits from the standard plugin interface and the messagelistener interface.
<source lang="csharp">
public interface ClientPlugin : Plugin, MessageListener
{
// -----------------------------------------
// Init functions
// -----------------------------------------
void init(ClientQuery cq);
void shutdown();
bool needsServerConnection();
bool needsServersidePlugin();
bool isAlwaysOpen();
List<MenuEntry> getMenuEntries();
// -----------------------------------------
// Frontend functions
// -----------------------------------------
Form getForm();
bool hasConfigWindow();
void openConfigWindow();
Image getButtonImage();
string getButtonDescription();
// -----------------------------------------
// Socket functions
// -----------------------------------------
void incomingData(string data);
}
</source>
Initialization
void init(ClientQuery cq);
This function is called by Shockvoice after the plugin is loaded and submits the ClientQuery interface. The client query interface can be used by the plugin whenever it wants Shockvoice to do some tasks.
void shutdown();
The shutdown method is called when the plugin is unloaded. Do any cleanup tasks here.
bool needsServerConnection();
This method has to return true, if it needs to do communication with the server as an important task and cannot function without.
bool needsServersidePlugin();
This method has to return true, if it has a server counterpart it needs to communicate with.
bool isAlwaysOpen();
This method returns true, if the plugin window will always be open and cannot be closed.
List<MenuEntry> getMenuEntries();
This method returns a list of MenuEntry objects. Menu entries are described in a separate chapter
Frontend functions
asdasf
Form getForm();
bool hasConfigWindow();
void openConfigWindow();
Image getButtonImage();
string getButtonDescription();
Socket functions
weroiuwer
void incomingData(string data);
Server Plugin Interface
This is an example text! asdföjahsdfkjahsdg asdögklj aöwkj awöuign wödvna wörguh akövjan ksdf asdg öjash öasjhg aöwogi aöraergkljasdgö asd ökjasgöl airgj aörjg oajg iojgrij aöeoj
<source lang="csharp">
public interface ServerPlugin : Plugin
{
// -----------------------------------------
// Init functions
// -----------------------------------------
ServerPlugin init(int server_id, ServerQuery cq, Dictionary<string, string> config);
void shutdown();
bool acceptsClients();
List<Types.Permission> getPermissionList();
List<Types.DbTable> getDatabaseTables();
string getSvNetworkInfo();
bool runsInPassiveMode();
// -----------------------------------------
// Notification functions
// -----------------------------------------
void serverDeleted(int server_id);
void userDeleted(int user_id);
void channelAdd(Channel c);
void channelRemove(Channel c);
void channelUpdate(Channel c);
void userAdd(Client c);
void userRemove(Client c);
void userUpdate(Client c);
// -----------------------------------------
// Socket functions
// -----------------------------------------
void incomingData(string data, Client c);
}
</source>
Initialization functions
qwetrqwer
ServerPlugin init(int server_id, ServerQuery cq, Dictionary<string, string> config);
void shutdown();
bool acceptsClients();
List<Types.Permission> getPermissionList();
List<Types.DbTable> getDatabaseTables();
string getSvNetworkInfo();
bool runsInPassiveMode();
Notification functions
ertzertz
void serverDeleted(int server_id);
void userDeleted(int user_id);
void channelAdd(Channel c);
void channelRemove(Channel c);
void channelUpdate(Channel c);
void userAdd(Client c);
void userRemove(Client c);
void userUpdate(Client c);
Socket functions
asdgadsg
void incomingData(string data, Client c);
Query Interface
This is an example text! asdföjahsdfkjahsdg asdögklj aöwkj awöuign wödvna wörguh akövjan ksdf asdg öjash öasjhg aöwogi aöraergkljasdgö asd ökjasgöl airgj aörjg oajg iojgrij aöeoj
Client Query Interface
This is an example text! asdföjahsdfkjahsdg asdögklj aöwkj awöuign wödvna wörguh akövjan ksdf asdg öjash öasjhg aöwogi aöraergkljasdgö asd ökjasgöl airgj aörjg oajg iojgrij aöeoj
<source lang="csharp">
public interface ClientQuery
{
// -----------------------------------------
// Version information functions
// -----------------------------------------
int queryVersionMajor();
int queryVersionMinor();
int queryVersionRevision();
// -----------------------------------------
// Socket functions
// -----------------------------------------
void sendData(string data);
// -----------------------------------------
// Channel/Client query functions
// -----------------------------------------
List<Channel> getChannelList();
Channel getCurrentChannel();
List<Client> getClientsInChannel();
List<Client> getClientList();
Client getMyClient();
Client getClient(int client_id);
// -----------------------------------------
// Sound functions
// -----------------------------------------
bool soundSetup(int channels, int bits, int frequency);
void soundOutputSample(byte[] data);
void soundOutputStream(byte[] data);
void soundGetCursors(out int readcursor, out int playcursor);
void soundStartStream(Types.SoundPlaybackDelegate scd);
void soundStopStream();
void soundStartCapture(Types.SoundCaptureDelegate scd);
void soundStopCapture();
float soundGetCapturePeak();
// -----------------------------------------
// Codec functions
// -----------------------------------------
byte[] codecAudioEncode(byte[] data, Types.CodecQuality quality);
byte[] codecAudioDecode(byte[] data);
// -----------------------------------------
// Message functions
// -----------------------------------------
void error(string msg);
void notice(string msg);
}
</source>
Version information functions
aweoiharg
int queryVersionMajor();
int queryVersionMinor();
int queryVersionRevision();
Socket functions
qwetoiuwet
void sendData(string data);
Channel/Client query functions
arweioqjert
List<Channel> getChannelList();
Channel getCurrentChannel();
List<Client> getClientsInChannel();
List<Client> getClientList();
Client getMyClient();
Client getClient(int client_id);
Sound functions
awetqwert
bool soundSetup(int channels, int bits, int frequency);
void soundOutputSample(byte[] data);
void soundOutputStream(byte[] data);
void soundGetCursors(out int readcursor, out int playcursor);
void soundStartStream(Types.SoundPlaybackDelegate scd);
void soundStopStream();
void soundStartCapture(Types.SoundCaptureDelegate scd);
void soundStopCapture();
float soundGetCapturePeak();
Codec functions
ertpzoitrz
byte[] codecAudioEncode(byte[] data, Types.CodecQuality quality);
byte[] codecAudioDecode(byte[] data);
Message functions
awepojaweo
void error(string msg);
void notice(string msg);
Server Query Interface
This is an example text! asdföjahsdfkjahsdg asdögklj aöwkj awöuign wödvna wörguh akövjan ksdf asdg öjash öasjhg aöwogi aöraergkljasdgö asd ökjasgöl airgj aörjg oajg iojgrij aöeoj
<source lang="csharp">
public interface ServerQuery
{
bool isPassiveQuery();
ServerInfo getServerInfo();
// -----------------------------------------
// Version information functions
// -----------------------------------------
int queryVersionMajor();
int queryVersionMinor();
int queryVersionRevision();
// -----------------------------------------
// Channel/Client query functions
// -----------------------------------------
List<Channel> getChannelList();
Channel getCurrentChannelForUser(int user_id);
List<VoiceGroup> getVoiceGroupList();
List<VoiceGroupUser> getVoiceGroupUserList();
List<Client> getClientsInChannel(int channel_id);
List<Client> getClientList();
List<Client> getUserList();
// -----------------------------------------
// Permission check functions
// -----------------------------------------
bool requireExecute(int client_id, string perm, int channel_id);
bool requireExecute(int client_id, string perm);
bool requireAssign(int client_id, string perm, int channel_id);
bool requireAssign(int client_id, string perm);
int getExecute(int client_id, string permlist, int channel_id);
int getAssign(int client_id, string permlist, int channel_id);
// -----------------------------------------
// File access functions
// -----------------------------------------
void fileCreate(string filename, byte[] data, int user_id);
void fileCreate(string filename, string data, int user_id);
void fileDelete(string filename);
byte[] fileLoad(string filename);
string fileLoadString(string filename);
int fileGetRemainingQuota();
// -----------------------------------------
// Database functions
// -----------------------------------------
bool databaseConnect();
void databaseDisconnect();
bool databaseExecute(string query);
DataTable databaseQuery(string query);
string databaseGetTablePrefix();
// -----------------------------------------
// Socket functions
// -----------------------------------------
void sendData(string data, int client_id);
void channelBroadcast(int channel_id, string data);
void channelBroadcast(int channel_id, string data, string permission);
void serverBroadcast(string data);
void serverBroadcast(string data, string permission);
// -----------------------------------------
// Statistics functions
// -----------------------------------------
string statsGetValue(String key);
void statsCommand(String command);
// -----------------------------------------
// Logging functions
// -----------------------------------------
void log(string text);
void log(int client_id, string text);
void logEx(string text);
void logEx(int client_id, string text);
void logDebug(string text);
void logDebug(int client_id, string text);
void logExDebug(string text);
void logExDebug(int client_id, string text);
}
</source>
Misc functions
bool isPassiveQuery();
ServerInfo getServerInfo();
Version information functions
wertiouwert
int queryVersionMajor();
int queryVersionMinor();
int queryVersionRevision();
Channel/Client query functions
qwetipue
List<Channel> getChannelList();
Channel getCurrentChannelForUser(int user_id);
List<VoiceGroup> getVoiceGroupList();
List<VoiceGroupUser> getVoiceGroupUserList();
List<Client> getClientsInChannel(int channel_id);
List<Client> getClientList();
List<Client> getUserList();
Permission check functions
awelkjsd
bool requireExecute(int client_id, string perm, int channel_id);
bool requireExecute(int client_id, string perm);
bool requireAssign(int client_id, string perm, int channel_id);
bool requireAssign(int client_id, string perm);
int getExecute(int client_id, string permlist, int channel_id);
int getAssign(int client_id, string permlist, int channel_id);
File access functions
sdfhlkjsfgd
void fileCreate(string filename, byte[] data, int user_id);
void fileCreate(string filename, string data, int user_id);
void fileDelete(string filename);
byte[] fileLoad(string filename);
string fileLoadString(string filename);
int fileGetRemainingQuota();
Database functions
sflkydcbg
bool databaseConnect();
void databaseDisconnect();
bool databaseExecute(string query);
DataTable databaseQuery(string query);
string databaseGetTablePrefix();
Socket functions
sefgjhdsfg
void sendData(string data, int client_id);
void channelBroadcast(int channel_id, string data);
void channelBroadcast(int channel_id, string data, string permission);
void serverBroadcast(string data);
void serverBroadcast(string data, string permission);
Statistics functions
sdfglkjafdg
string statsGetValue(String key);
void statsCommand(String command);
Logging functions
qwertpoqwet
void log(string text);
void log(int client_id, string text);
void logEx(string text);
void logEx(int client_id, string text);
void logDebug(string text);
void logDebug(int client_id, string text);
void logExDebug(string text);
void logExDebug(int client_id, string text);
Menu entries
awgpoiawgpoaweg
Type definitions
This is an example text! asdföjahsdfkjahsdg asdögklj aöwkj awöuign wödvna wörguh akövjan ksdf asdg öjash öasjhg aöwogi aöraergkljasdgö asd ökjasgöl airgj aörjg oajg iojgrij aöeoj
Code Examples
This is an example text! asdföjahsdfkjahsdg asdögklj aöwkj awöuign wödvna wörguh akövjan ksdf asdg öjash öasjhg aöwogi aöraergkljasdgö asd ökjasgöl airgj aörjg oajg iojgrij aöeoj
Developing a Client-Only Plugin
This is an example text! asdföjahsdfkjahsdg asdögklj aöwkj awöuign wödvna wörguh akövjan ksdf asdg öjash öasjhg aöwogi aöraergkljasdgö asd ökjasgöl airgj aörjg oajg iojgrij aöeoj
<source lang="csharp">
using System; using System.Collections; using System.Collections.Generic; using System.Text; using System.IO; using System.Resources; using System.Windows.Forms; using Shockvoice.API;
namespace Shockvoice.Plugin.MyPlugin {
public class MyPlugin : ClientPlugin
{
private const string PLUGIN_ID = "sv_myplugin";
private const string PLUGIN_NAME = "My Plugin";
private const string PLUGIN_DESC = "This plugin does nothing";
private const int VERSION_MAJ = 1;
private const int VERSION_MIN = 0;
private const bool NEEDS_CONNECTION = false;
private const bool NEEDS_SERVER = false;
private const bool HAS_CONFIG_FORM = false;
private const bool ALWAYS_OPEN = false;
private const string BUTTON_DESCRIPTION = "MyPlugin";
private ClientQuery m_ClientQuery;
public void init(ClientQuery cq)
{
m_ClientQuery = cq;
}
public List<MenuEntry> getMenuEntries()
{
return null;
}
public void shutdown()
{
}
public bool isAlwaysOpen()
{
return ALWAYS_OPEN;
}
public void message(GuiMessage msg)
{
}
public Types.PluginType getPluginType()
{
return Types.PluginType.CLIENTSIDE_PLUGIN;
}
public string getID()
{
return PLUGIN_ID;
}
public string getName()
{
return PLUGIN_NAME;
}
public string getDescription()
{
return PLUGIN_DESC;
}
public int getVersionMajor()
{
return VERSION_MAJ;
}
public int getVersionMinor()
{
return VERSION_MIN;
}
public bool needsServerConnection()
{
return NEEDS_CONNECTION;
}
public bool needsServersidePlugin()
{
return NEEDS_SERVER;
}
public System.Windows.Forms.Form getForm()
{
return null;
}
public void openConfigWindow()
{
}
public System.Drawing.Image getButtonImage()
{
return null;
}
public string getButtonDescription()
{
return BUTTON_DESCRIPTION;
}
public void incomingData(string data)
{
}
public bool hasConfigWindow()
{
return HAS_CONFIG_FORM;
}
}
}
</source>
Developing a Server-Only Plugin
This is an example text! asdföjahsdfkjahsdg asdögklj aöwkj awöuign wödvna wörguh akövjan ksdf asdg öjash öasjhg aöwogi aöraergkljasdgö asd ökjasgöl airgj aörjg oajg iojgrij aöeoj
<source lang="csharp">
using System; using System.Collections; using System.Collections.Generic; using System.Text; using System.IO; using System.Resources; using System.Threading; using Shockvoice.API;
namespace Shockvoice.ServerPlugin.MyPlugin {
public class MyPlugin : Shockvoice.API.ServerPlugin
{
private const string PLUGIN_ID = "sv_myplugin";
private const string PLUGIN_NAME = "My Plugin";
private const string PLUGIN_DESC = "This plugin does nothing";
private const int VERSION_MAJ = 1;
private const int VERSION_MIN = 0;
private const bool ACCEPTS_CLIENTS = false;
private const bool RUNS_IN_PASSIVE_MODE = false;
private Types.Permission[] m_Permissions = new Types.Permission[] {
new Types.Permission("MYPLUGIN", "User may use myplugin", Types.PermissionType.TYPE_SERVER, Types.PermissionDataType.DATATYPE_BOOL, 0, 1)
};
private ServerQuery m_ServerQuery;
public MyPlugin()
{
}
public MyPlugin(ServerQuery sq)
{
m_ServerQuery = sq;
}
public Shockvoice.API.ServerPlugin init(int server_id, ServerQuery sq, Dictionary<string, string> config)
{
return new MyPlugin(sq);
}
public void shutdown()
{
}
public bool acceptsClients()
{
return ACCEPTS_CLIENTS;
}
public bool runsInPassiveMode()
{
return RUNS_IN_PASSIVE_MODE;
}
public List<Types.Permission> getPermissionList()
{
return new List<Types.Permission>(m_Permissions);
}
public List<Types.DbTable> getDatabaseTables()
{
return null;
}
public string getSvNetworkInfo()
{
return "";
}
public void channelAdd(Channel c)
{
}
public void channelRemove(Channel c)
{
}
public void channelUpdate(Channel c)
{
}
public void userAdd(Client c)
{
}
public void userRemove(Client c)
{
}
public void userUpdate(Client c)
{
}
public void incomingData(string data, Client c)
{
}
public string getID()
{
return PLUGIN_ID;
}
public string getName()
{
return PLUGIN_NAME;
}
public string getDescription()
{
return PLUGIN_DESC;
}
public int getVersionMajor()
{
return VERSION_MAJ;
}
public int getVersionMinor()
{
return VERSION_MIN;
}
public Types.PluginType getPluginType()
{
return Types.PluginType.SERVERSIDE_PLUGIN;
}
}
}
</source>
Developing a Client-Server Plugin
This is an example text! asdföjahsdfkjahsdg asdögklj aöwkj awöuign wödvna wörguh akövjan ksdf asdg öjash öasjhg aöwogi aöraergkljasdgö asd ökjasgöl airgj aörjg oajg iojgrij aöeoj
