[API] TS3 PHP Framework

[Spiked]

$srv = TeamSpeak3::factory("serverquery://" . $cfg["user"] . ":" . $cfg["pass"] . "@" . $cfg["host"] . ":" . $cfg["query"] . "/?server_port=" . $cfg['voice'] . "&blocking=0");
$srv->notifyRegister("textserver"); // Register to receive ServerChat Messages
$srv->notifyRegister("textchannel"); // Receive Channelchat Messages of CURRENT CHANNEL

TeamSpeak3_Helper_Signal::getInstance()->subscribe("notifyTextmessage", "onTextMessage"); // Specify Callback Function to be called for each TextMessage in Server or current Channel. 

Can someone provide a detailed example of event callback usage?
I don't understand the usage since php is stateless.

Do they only work if the page is still processing?
Or does the plugin call a callback url which launches the same script so that it can be triggered? If so, how do you un-hook the event at that point?

Thanks in advance
- Spiked

[SilentStorm]

Hello ScP,

In "TeamSpeak3_Node_Abstract::getInfo => virtualserver_min_client_version" return Unix time, "TeamSpeak3_Helper_Convert\version()" not work in this.

And I think the correct format for DATE in this case: "TeamSpeak3_Helper_Convert\version()" would be:

293: public static function version($version, $format = "d/m/Y G:i:s")

...date would be expressed in the same format as the TeamSpeak client.

Thanks for your great work.

The format which the Client uses for displaying Dates and Times depends on your Locale Settings in your Operating System. For example European Clients will see the dates and Times as d.m.Y H:i:s
You can check for yourself by setting your Location in your Operating System to somewhere in Europe (with the possible exception of UK).

Can someone provide a detailed example of event callback usage?
I don't understand the usage since php is stateless.

Do they only work if the page is still processing?
Or does the plugin call a callback url which launches the same script so that it can be triggered? If so, how do you un-hook the event at that point?

Thanks in advance
- Spiked

PHP is NOT just used for Webpages! They can also be run on Commandline...

An example I did while playing around with it way back:

try
{
    $srv = TeamSpeak3::factory("serverquery://" . $cfg["user"] . ":" . $cfg["pass"] . "@" . $cfg["host"] . ":" . $cfg["query"] . "/?server_port=" . $cfg['voice'] . "&blocking=0");

    TeamSpeak3_Helper_Signal::getInstance()->subscribe("notifyTextmessage", "onTextMessage");

}
catch(Exception $e)
{
    trigger_error("TS3PHPFramework:: ERROR " . $e->getMessage(), E_USER_ERROR);
    die;
}

//
// Do not exit the Script
// 
while (true) {
    try {
        $srv->getAdapter()->wait();
    }
    catch (Exception $e) {
        trigger_error("ERROR " . $e->getCode() . ": " . $e->getMessage(), E_USER_ERROR);
    }
}


//
// The Callback Function called on each Message Event
//

function onTextMessage(TeamSpeak3_Adapter_ServerQuery_Event $e, TeamSpeak3_Node_Host $host) {
    $info = $e->getData();
    $srv = $host->serverGetSelected();
    switch ($info["targetmode"]) {
        case 1:
            echo "New Private Message from " . $info["invokername"]->toString() . ": " . $info["msg"] . "\n";
            break;
        case 2:
            echo "New Message from " . $info["invokername"]->toString() . " in Channel " . $srv->channelGetById($host->whoamiGet("client_channel_id"))->toString() . ": " . $info["msg"] . "\n";
            break;
        case 3:
            echo "New Server Message from " . $info["invokername"]->toString() . ": " . $info["msg"] . "\n";
            break;
    }
} 

This is old code I still had lying around... Did not test this with latest Server or latest Framework Version, so it might not be working anymore, or need some fixing.

[Spiked]

So realistically, the callbacks are only valid during the execution in which they are defined. I was hoping that the call back would register to the server and the event would call the original script each time, but that would require a way of unhooking the event.

I'm not fond of the idea of throwing php into a near infinite loop in order to catch chat events >.>

[SilentStorm]

The Script will need to stay connected to the Server to receive Events...
Also any Application basicly runs an infinite Loop until an error forces it to exit or the User tells it to exit...

[Spiked]

There's too much "magic" going on here. I've spent hours on this and pouring thru both ts3 and php framework docs has not yielded any list of acceptable strings for the first parameter here where "notifyTextmessage" is used.

TeamSpeak3_Helper_Signal::getInstance()->subscribe("notifyTextmessage", "onTextMessage");

It does indeed work, though to an extent. Perhaps I'm missing something. I understand calling notifyRegister($event) on the virtual server instance where $event is listed plainly on page 17:
http://media.teamspeak.com/ts3_liter...y%20Manual.pdf

and I understand the binding of the event callbacks to the server with the subscribe($signal, $callback) will call my callback function each time a previously registered event is fired.

However, as far as I can tell, notifyRegister() takes an additional optional channel argument. Even if I leave this blank, I seem to only receive events triggered in the default server channel.

Perhaps I'm just missing something plainly obvious somewhere, but I remain confused on 2 things:
- list of $signals for subscribe()
- what did i miss to get events triggered in all channels, not just lobby?

Thanks >.>
- Spiked


So I ended up finding some some-what helpful info inside of /examples/apps/console/console.php...
it gives at least a brief listing of the signals, however it's not extremely helpful and appears slightly out-dated.

All examples of event binding I've seen so far do so on the node_abstract returned by the factory, but notifyRegister() is on the node_server. Though this is minor, and easily debugged, I'm throwing it out there since I'm still at a loss despite my efforts to get this working.

[SilentStorm]

You can only receive Channel Text Messages for the channel you are in (You in this case being the Query Connection from the PHP Script).

[Spiked]

Thanks for your help SilentStorm,

I don't see a command in either api to move channels. Also, it seems like it would be possible to subscribe to multiple channels since the notifyRegister takes an optional argument of a channel # (which to my testing has zero affect)

Although, at the very least it's looking like I need to take this to a different thread since what appeared to be my lack of understanding of the php framework is more like confusion over the ts3 api ^^

Thanks again for the assistance!

[SilentStorm]

It does likely have an effect for other Events not text Messages though...

As for moving there is moveClient which will switch you into the specified channel if you specify your own client id.

[ScP]

So I ended up finding some some-what helpful info inside of /examples/apps/console/console.php...
it gives at least a brief listing of the signals, however it's not extremely helpful and appears slightly out-dated.

For a list of static events, please check the TeamSpeak3_Helper_Signal_Interface. It contains possible callbacks for all of the signals that are emitted somewhere in the code and can be implemented in your own class with callback methods. Other event names are dynamically created. For example, when the server spits out a notifycliententerview notification, a signal called notifyCliententerview will be emited. If there's a notifychannelcreated, the signal will be notifyChannelcreated. This means you can create individual methods for each notification the server might give you. In addition, the notifyEvent signal is emitted on any notification so implementing a callback for it (like I did in the console example) means you'll never miss anything.

Also, it seems like it would be possible to subscribe to multiple channels since the notifyRegister takes an optional argument of a channel # (which to my testing has zero affect)

A ServerQuery client will automatically subscribe to all channels it's allowed to which means that you'll be able to receive notifications (notifycliententerview, notifyclientleftview, etc) on events for any client that you're able to see with the permissions you have. The optional id parameter will only work for events of type channel and is intended to watch over one or more specific channels. id=0 will watch over all channels and is the default setting in my code.

SilentStorm is right tho. As a ServerQuery client acts just like a regular client, you can only see text messages sent to the server or the channel you're currently in... and private messages of course.

I don't see a command in either api to move channels.

If you want to move a channel (change it's parent), there's the channelMove() method, but I think you're talking about moving your own client to another channel.

To switch a to another channel, you'll need to use the clientMove() method. Here's an example using the channel name (if you don't want to fiddle around with channel IDs):

$your_own_client_id = $server->whoamiGet("client_id");
$target_channel_obj = $server->channelGetByName("Some Channel Name");
$target_channel_pwd = "optional channel password";

$server->clientMove($own_client_id, $target_channel_obj, $target_channel_pwd); 

If you pass an object to any method where an ID is needed, my weird code will do some magic and grab the ID of the client, channel or server to generate the command.

[Spiked]

Thanks for the detailed answers ScP,

I was going about it a little wonky. I wasn't thinking of serverquery as a regular client and I was testing with serveradmin account, which ISN'T a regular client in the first place. Just making it harder on myself.

For others:
declare a nickname in your factory options. big help when acting on yourself like moving channels

[Dream]

I will refresh my problem. Please help me in resolving.

Framework version: newest

Problem: "Server is not running" - with attr. /?use_offline_as_virtual=1 or "Server got an invalid status for this operation" without this attr during using function Delete()

Class teamspeak

...
public function CheckVirtualServer($attr = '', $remove = FALSE)
{		
	try
	{
		if($remove)
		{
			$ts3_VirtualServer = TeamSpeak3::factory("serverquery://".self::QUERY_USERNAME.":".self::QUERY_PASSWORD."@".$this -> machine['machine_ip'].":".$this -> query_port."/?server_id=".$this -> data['server_vserver_id'].$attr);
		}
		else
		{
			$addid = rand(1024, 262144);
			$ts3_VirtualServer = TeamSpeak3::factory("serverquery://".self::QUERY_USERNAME.":".self::QUERY_PASSWORD."@".$this -> machine['machine_ip'].":".$this -> query_port."/?use_offline_as_virtual=1&server_id=".$this -> data['server_vserver_id']."&nickname=ServerAdmin:{$addid}".$attr);
		}
	}
	catch(Exception $e)
	{
		if($e->getMessage() == 'Connection refused')
		{
			$this -> error = "Połączenie zostało odrzucone.";;
			$this -> StartInstance();
		}
		else $this -> error = "Wystąpił nieoczekiwany błąd (".$e->getMessage().")";
		return false;	
	}
		
		return $ts3_VirtualServer;
	}

public function RemoveServer()
{
	global $cms; 
			
	if($this -> data['server_vserver_id'] < 1)
	{
		$this -> error = "Ten serwer nie jest zainstalowany.";
		return false;	
	}
		
	if(!($ts3_VirtualServer = $this -> CheckVirtualServer())) return false;
		
	if($ts3_VirtualServer -> isOnline()) $ts3_VirtualServer -> Stop();

	$ts3_VirtualServer ->  Delete();
	
	$cms -> db -> delete('server_backups', 'sb_server_id', $this -> id);
	$cms -> db -> delete('banners', 'banner_server_id', $this -> id);
		
	$cms -> db -> update('servers', array('server_vserver_id' => 0), 'server_id', $this -> id);
	$this -> data['server_vserver_id'] = 0;
	return true;	
}
...

exec. file

...
$srv = new teamspeak($server);	
			
try
{
	if($srv -> RemoveServer()) 
	{
		echo "DONE!";
	} else echo "[ERROR] {$server['server_id']}(VID: {$server['server_vserver_id']}): {$srv -> error}";
} 
catch (Exception $e)
{
	echo "[ERR] {$server['server_port']}: Serwer {$server['server_type']} ID: #{$server['server_id']}: {$e->getMessage()} || {$srv -> error}";
}
...

One person had the same problem http://forum.teamspeak.com/showthrea...462#post247462

[ScP]

I will refresh my problem. Please help me in resolving.

Framework version: newest

Problem: "Server is not running" - with attr. /?use_offline_as_virtual=1 or "Server got an invalid status for this operation" without this attr during using function Delete()

I'll try to explain what's happening... With your code, the framework will connect to the ServerQuery interface, authenticate *AND* select/use the virtual server you requested.

This is what causes your problem. Without use_offline_as_virtual, your code will do this when the server is already stopped:

login {username} {password}
use sid={server_id}

Since the -virtual parameter is missing, TS3 will not allow you to select/use the virtual server and instead spit out the "server is not running" message.

With your code and use_offline_as_virtual enabled, the framework will execute the follwing commands when the server is still running:

login {username} {password}
use sid={server_id} -virtual
clientupdate client_nickname={client_nickname}
serverstop sid={server_id}
serverdelete sid={server_id}

When these commands are executed by a script, the serverdelete command will probably fail because the virtual server is still in the process of shutting down. That's why you get the "server got an invalid status for this operation" error. Stopping a virtual server while it's selected/used is an asynchronous action (server returns "ok" and continues to shutdown in the background) as it will wait for the last user to be disconnected... which in this case is your ServerQuery client. So basically, this is a simple timing problem which might be fixed when you add a 2-3 second sleep() after stopping the server.

[Dream]

When these commands are executed by a script, the serverdelete command will probably fail because the virtual server is still in the process of shutting down. That's why you get the "server got an invalid status for this operation" error. Stopping a virtual server while it's selected/used is an asynchronous action (server returns "ok" and continues to shutdown in the background) as it will wait for the last user to be disconnected... which in this case is your ServerQuery client. So basically, this is a simple timing problem which might be fixed when you add a 2-3 second sleep() after stopping the server.

Could you tell me the best way to delete server with your API?

[maxi1990]

Replace

	if($ts3_VirtualServer -> isOnline()) $ts3_VirtualServer -> Stop();

	$ts3_VirtualServer ->  Delete();

with

	if($ts3_VirtualServer -> isOnline()) {
                $ts3_VirtualServer -> Stop();
                sleep(3);
        }
	$ts3_VirtualServer ->  Delete();

[Dream]

Replace

	if($ts3_VirtualServer -> isOnline()) $ts3_VirtualServer -> Stop();

	$ts3_VirtualServer ->  Delete();

with

	if($ts3_VirtualServer -> isOnline()) {
                $ts3_VirtualServer -> Stop();
                sleep(3);
        }
	$ts3_VirtualServer ->  Delete();

Sure. I tried that and it does not work (I used with /?use_offline_as_virtual=1). The problem occurs when server is offline. When server is online I can delete the server.


---

I try remove an offline server:

$ts3_VirtualServer = TeamSpeak3::factory("serverquery://".self::QUERY_USERNAME.":".self::QUERY_PASSWORD."@".self::getMachine('machine_ip').":".self::getQuery_port()."/?use_offline_as_virtual=1&server_id=".self::getData('server_vserver_id'));
$ts3_VirtualServer ->  Delete();

Result:

server got an invalid status for this operation