NiceVentriloStatus is a user friendly way to get information from a Ventrilo server and represent it in PHP. It contains functions that will make it easy for anyone to retrieve information about channels, users and the server itself.
You will need a web server, PHP and the ventrilo_status program. If you have none of these, and are running Windows XP, you should definately read this guide on how to install/setup. The guide might also be valuable to Linux users.
The ventrilo_status program should be bundled in the Ventrilo server package, if downloaded from ventrilo.com. If you're running Windows, it's called "ventrilo_status.exe", and if you're running Linux it should be an executable file named "ventrilo_status".
This program must be accessible by NiceVentriloStatus. Place it in the same directory if you wish, but I prefer to have it where it was installed ("C:\Program Files\VentSrv\ventrilo_status.exe").
To set up NiceVentriloStatus on your own computer, you will need a web server, typically Apache, and PHP. Note that you must set PHP safe_mode to off. Look for the php.ini (Windows: "C:\Windows\php.ini"; Linux: "/etc/php4/apache/php.ini"). Search for "safe_mode" and make sure that it says "safe_mode = Off". If safe mode is on, PHP is not allowed to run external programs, such as ventrilo_status, and it depends on doing that.
A good tip is to download WAMP: "Windows, Apache, MySQL, PHP". It installs a web server (Apache), PHP and a MySQL database in a bundle. Very convenient for less tech-savvy people. Just google for WAMP and you should find it.
If you're renting from a web hosting company, it is likely that their running PHP in safe_mode. If so, there's still a chance. Ask for a safe_mode_exec_dir. If there is one, place the ventrilo_status program there, and then you should be fine. If there isn't, you will not be able to run NiceVentriloStatus. Sorry.
Of course, you will need a Ventrilo server to connect to. It is not necessary to run the Ventrilo server on the same computer as NiceVentriloStatus.
Please, make sure that no firewall is blocking the Ventrilo server port on outgoing traffic (this is usually not a problem). "It must be the firewall. It's always the firewall." :-)
First, make sure you have met all the requirements mentioned above. You may also wish to read my guide: Install a webserver, PHP and NVS on Windows.
Okay, I assume that you know something about HTML, PHP and such. However, this should be easy to understand.
The first thing to do is to include the core that contains the class entire class. Let's say you put your index.php in the folder "MyVentriloTest" and also extracted NiceVentriloStatus to this folder. Then we initialize the class.
This following example sets the class up. What happens here is that the class tries to connect to the ventrilo server and gather all data. You might need to adjust the variables according to your setup.
./MyVentriloTest/index.php
<?php
include("NiceVentriloStatus/core.php");
$pathToVentStatus = "C:\\Program Files\\VentSrv\\ventrilo_status.exe";
$hostOrIP = "127.0.0.1";
$serverPort = 3784;
$NVS = new NiceVentriloStatus($pathToVentStatus, $hostOrIP, $serverPort);
?>
The parameters that are passed to the NiceVentriloStatus class is: path to the ventrilo_status program, the port on which the ventrilo server is running and last: the hostname, or IP address, of the ventrilo server. "127.0.0.1" refers to your own computer (ventrilo server is running on your computer). And now you should be good to go, actually. Continue to next section to see some handy functionality.
If things doesn't work, check out 5 Help and troubleshooting.
There are a few handy functions that you might want to know about.
<?php
include("NiceVentriloStatus/core.php");
$NVS = new NiceVentriloStatus( ... );
// Get a table with all the connected users.
echo $NVS->GetUserListTable();
?>
Figure 3.1: Generate a table of all connected users.
<?php
include("NiceVentriloStatus/core.php");
$NVS = new NiceVentriloStatus( ... );
// Get information about my ventrilo server
echo $NVS->GetServerInformationTable();
// Get all channels and their connected users. Even channels that are empty.
echo $NVS->GetUserListByChannelsTable(false);
?>
Figure 3.2: Get server information table, and all channel and users information.
<?php
include("NiceVentriloStatus/core.php");
$NVS = new NiceVentriloStatus( ... );
// Get all users
$users = $NVS->Users;
// Print all the user names
foreach($users as $user)
echo "<p>" . $user["Name"] . "</p>";
?>
Figure 3.3: More advanced. Get the user list, loop through and print names only.
All HTML that is generated from the functions listed in 3.1 Handy functions, is well marked up to make it easy to apply a CSS stylesheet to it. An example CSS file, default.css, should be bundled with the NiceVentriloStatus package.
The in-depth sections are probably useful only if you want to do something more advanced then the functionality that is described in 3.1 Handy functions.
Besides those functions, there are a few more functions that might be useful, and a couple of fields containing channels and users. For full specification, see section 4.4 Full class specification.
A channel is represented as an array:
Array
(
[Name] => The name of the channel
[ID] => The ID of the channel (0 if it's the lobby)
[ParentID] => The ID of this channels parent. If channel is lobby, ParentID is -1
[IsProtected] => A true/false value, indicating if channel is password protected
[Comment] => The channel's comment, if available
[Users] => Array
(
An array of users. See "User concept".
)
)
echo $NVS->FlatChannelList[0]["Name"];
Figure 4.1: Array representation of a Channel.
There are two different fields from which you can get channel arrays; FlatChannelList and Channels.
$NVS = new NiceVentriloStatus(...);
print_r( $NVS->FlatChannelList );
Output:
Array
(
[0] => Array
(
[Name] => Lobby
[ID] => 0
... see figure 4.1 for Channel description
[Users] => Array
(
)
)
[1] => Array
(
[Name] => Foo channel 1
[ID] => 1
... ...
[Users] => Array
(
[0] => Array
... see User Concept
[1] => Array
... see User Concept
)
)
[2] => Array
(
[Name] => Foo channel 2
[ID] => 2
... ...
)
)
print_r( $NVS->Channels );
Output:
Array
(
[Name] => Lobby
[ID] => 0
[ParentID] => -1
... ...
[Users] => Array
(
)
[SubChannels] => Array
(
[0] => Array
(
[Name] => Foo channel 1
[ID] => 7
[ParentID] => 0
[Users] => Array
(
[0] => Array
... see User Concept
[1] => Array
... see User Concept
)
[SubChannels] => Array
(
)
)
[1] => Array
(
[Name] => Foo channel 2
[ID] => 5
[ParentID] => 0
[Users] => Array
(
)
[SubChannels] => Array
(
[0] => Array
(
[Name] => Foobar channel
[ID] => 15
[ParentID] => 5
... ...
)
)
)
)
)
Figure 4.2: Example output from the printing of both Channel-fields.
These examples are just a glance of the output.
The first variant will give you a one dimensional array of channels. The second variant will give you a nested array of channels. The first, and only, element is the Lobby. This is similar to the $channel array described earlier, but it also has an array of $SubChannels, which is another array of $channel's. Those $channels does also have an array of $SubChannels, and so on ...
Users are represented through a one dimensional array. A user is an array that looks like this:
Array
(
[Name] => Username
[Uptime] => The time the user has been connected, in seconds.
[Ping] => Users ping
[Comment] => Any comment of the user, if avavilable
[UserID] => ID of the user, determined by Ventrilo server
[ChannelID] => ID of the channel the user is in
[IsAdmin] => True if admin, otherwise false.
[IsPhantom] => True if phantom (refer to Ventrilo help for description of phantoms.)
)
echo $NVS->Users[0]["Name"];
Figure 4.3: User represented as an array
The ServerInformation field contains all information related to the Ventrilo server itself.
Array
(
[Name] => Server name
[Host] => Host or IP address of the server (depending on constructor parameter)
[Port] => Server port
[Uptime] => Server uptime in seconds
[Version] => Ventrilo server version
[Comment] => Comment of the server, if available
[Platform] => Operative system (Windows, Linux ...)
[UserCount] => Number of users connected
[UserLimit] => Number of users allowed
[ChannelCount] => Number of channels
[ErrorMessage] => Any error message when connecting to server.
[Phonetic] => Server name phonetic
[VoiceCodec] => Refer to Ventrilo help
[VoiceFormat] => Refer to ventrilo help
[AuthModeCode] => A digit (1-3) representing auth mode.
[AuthMode] => Descriptive text of the auth mode.
)
echo $NVS->ServerInformation["Name"];
<?php class NiceVentriloStatus { var $Errors; // Array of errors. var $SilentMode // Bool indicating silent mode. var $DetailMode; // 1 or 2, indicating detail mode. var $ServerInformation; // Array of ServerInformation var $FlatChannelList; // Flat channel array var $RawChannels; // Raw parsed channels array var $Channels; // Recursive Channel array var $Users; // User array /** * The constructor. Connects to ventrilo server, gathers data and fills up the fields above. * ventrilo_status_path: The path to the ventrilo_status program. * server_host_or_ip: The host name or IP address that the Ventrilo server is running on. * server_port: The port that the Ventrilo server is running on. * detailMode: Level of detail. Level 1 gathers some of the ServerInformation only, 2 (default) gathers all info. * statusPassword: any password needed to gather information. */ function NiceVentriloStatus($ventrilo_status_path, $server_host_or_ip="127.0.0.1", $server_port=3784, $detail_mode=2, $silent_mode=false, $status_password="") /** * Returns a string that contains a well formatted HTML table with server information. */ function GetServerInformationTable() /** * Checks if it's legal to access users and channels (e.g. not when detailmode == 1). Returns true if * all is fine, otherwise false. An error will be added to $this->Errors if there is an attempt to access * when detail mode == 1. */ function TryAccess($type) /** * Returns an array of users that are connected to the channel with the specified channel ID. */ function GetUsersFromChannel($channelID) /** * Returns a string that contains a simple, well formatted HTML table with all connected users. */ function GetUserListTable() /** * Returns a string that contains all channels and the users connected to them. Spinning recursively through * $this->Channels, starting with the channel with ID == $rootChannelID. * onlyPopulated: If true (default), only channels that have users connected to them will be returned. * rootChannelID: The ID of the channel to start with. Default is 0 (Lobby). * subChannelSeparator: The string to separate a channel from a subchannel. Default is » (ยป). * preChannelNameText: The text to put before channel name. Default is "Channel: ". */ function GetUserListByChannelsTable($onlyPopulated=true, $rootChannelID=0, $subChannelSeparator=" » ", $preChannelNameText="Channel: ") /** * This function is utilized by GetUserListByChannelsTable. It loops through the $this->Channels array recursively, * starting with the specified channel. To start from the root, pass the $this->Channel array as the $channel-parameter. * Refer to GetUserListByChannelsTable for the rest of the parameter descriptions. */ function GetChannelTableRowsRecursive($channel, $onlyPopulated=true, $prepath="", $subChannelSeparator=" » ", $preChannelNameText="Channel: ") /** * Appends a string and a newline to the stringToAppendTo, indented with indentionCount spaces. * Solely used for producing well formatted HTML. */ function AddWellFormattedLine(&$stringToAppendTo, $indentionCount, $stringToAppend) /** * Converts seconds into days, hours and minutes. */ function GetFormattedUptime($seconds) /** * This function loops throught the $this->RawChannels array and fills up the $this->Channels * array and $this->FlatChannelsList array. */ function ResolveChannels($channelID=0) /** * Returns a Channel from the Channels field with the specified ID. The $channel parameter is used by the function when * it loops through the Channel field recursively, searching for the channel. */ function GetChannelByID($channelID, $channel=null) /** * This method will generate a detailed html list, containing all $this->Errors. Will only print if * NVS is not in silent mode, or the $force_print parameter is true. */ function PrintErrors($force_print=false) /** * This method opens a pipe to the shell, executes $commandLine, * and passes the output, line by line, to HandleOutputLine(). */ function QueryServer($commandLine) /** * Populates ServerInformation with contents of line, or passes the line on to ParseUser * or ParseChannel, depending on what $line contains. */ function HandleOutputLine($line) /** * Takes a line ($channelData) from HandleOutputLine that contains channel data, parses it * and adds a channel to $this->RawChannels. */ function ParseChannel($channelData) /** * Takes a line ($userData) from HandleOutputLine that contains user data, parses it * and adds a user to $this->Users. */ function ParseUser($userData) } ?>
The first thing you need to think of before contacting me for answers: is the problem related to NiceVentriloStatus?
For instance, if you can't get the Ventrilo server to start, you should search for help at ventrilo.com. If you can't get the web server to run, search in forums. If you can't get PHP to work, also search forums or Google it.
If nothing works, you could always send me a mail, and I'll try to help you out. My email adress below is written like that to avoid being caught by spambots.
c DOT skeppstedt AT gmail DOT com