♣ Description

Poker Mavens Pro contains an interface for communicating with the live game server from external programs, including scripting systems like PHP and ASP.NET. Commands can also be tested by hand via any web browser but note that this system is different from the Remote Administration system, which is designed for human interaction with your server. The application interface described here is for computer to computer interaction and currently only supports a few commands. However, more can be added in the future as requests are made.

To use this system you must have "Allow remote administration" set to "Yes" in the server settings and your server must be started and online. It works by making an HTTP request to the file port of your server with /control appended to the end of the URL. Parameters can be passed via GET (embedded in the URL) or via POST (embedded in the HTTP header). There are two parameters that must be included with each request: Password and Command. Password must be set to your administration password and Command is set to one of the available commands as listed below. Other parameters may be required, depending on the particular command.

♣ Example

For example, if your IP is 12.34.56.789, your file port is 8077, your administration password is banana, and you want to get the current chip balance of a player named Aces123, then your program would make an HTTP request to:

http://12.34.56.789:8077/control

with parameters set via POST as:

Password=banana
Command=GetBalance
Player=Aces123

of via GET as:

http://12.34.56.789:8077/control?Password=banana&Command=GetBalance&Player=Aces123

The order and case of the parameters is not important but the first one must begin with a question mark and all remaining ones must be separated by an ampersand when using the GET method.

The server always responds with a block of text containing a "Result" parameter and possibly others depending on the particular command and if there were any errors. Result will either be set to Ok or Errror. If there was an error then an Error parameter will be included with a description of the error. When there are multiple parameters returned, they are separated by a carriage return/line feed pair (ASCII 13 and 10). Using the example above, a typical response will look something like this:

Result=Ok
Balance=5000

Or if there was an error:

Result=Error
Error=Unknown player

♣ Command List

The following commands are currently available:

DecBalance - used to decrement the account balance of a player. Use a Player parameter to specify the player's name and an Amount parameter to specify the number of chips to subtract from the account. Note that this command does not check to see if you have "Allow negative balance" turned on or not in the Account Settings.

GetBalance - used to retrieve the chip balance of a player. Use a Player parameter to specify the player's name. If successful, a return value named Balance will be set (e.g., Balance=5000). Note that if the specified player is currently seated at any tables, the return value does not include those chips in the report.

IncBalance - used to increment the account balance of a player. Use a Player parameter to specify the player's name and an Amount parameter to specify the number of chips to add to the account.

SetBalance - used to set the chip balance of a player. Use a Player parameter to specify the player's name and an Amount parameter to specify the number of chips to put in the account.

TourneyResults - used to retrieve a tournament results file. Use a Date parameter to specify the day the tournament finished in the form of YYYY-MM-DD. Use a Tournament parameter to specify the name of the tournament. If found, the entire contents of the results file (as saved in the TourneyResults folder) will be returned immediately after the "Result=Ok" line.

♣ URL Encoding

Certain characters like "?", "&", "=", "%", "#", and several others are treated as control characters in URL strings. Therefore you must encode those characters using the form %xx where xx is the ASCII code of the character in hexadecimal format. For example, if you wanted to retrieve the tournament results for a tournament called "Rough&Ready", using the raw parameter of:

Tournament=Rough&Ready

would fail because the "&" would indicate the beginning of a new parameter. The ASCII code for "&" is 38 decimal or 26 hexadecimal so the proper encoding would be:

Tournament=Rough%26Ready