Document XMLRPC calls and added a .php class wrapper for them

2 files changed, 139 insertions, 0 deletions

diff --git a/docs/XMLRPC/XMLRPC b/docs/XMLRPC/XMLRPC
new file mode 100644
index 000000000..dad7641e3
--- /dev/null
+++ b/docs/XMLRPC/XMLRPC
@@ -0,0 +1,28 @@
+Starting with Anope 1.9.4 XMLRPC using PHP's xmlrpc_encode_request and xmlrpc_decode functions is supported.
+This allows external applications, such as websites, to execute remote procedure calls to Anope in real time.
+
+Currently there are 6 supported XMLRPC calls, provided by m_xmlrpc_main:
+
+login - Takes two parameters, the username and password. Useful only if there is a username and password setting in
+        the XMLRPC configuration block. If there is, clients wanting to execute RPC calls must login first using this.
+
+checkAuthetication - Takes two parameters, an account name and a password. Checks if the account name is valid and the password
+                     is correct for the account name, useful for making login pages on websites.
+
+command - Takes three parameters, a service name (BotServ, ChanServ, NickServ), a user name (whether online or not), and the command
+          to execute. This will execute a the given command to Anope using the given service name. If the user given is online, the
+	  command reply will go to them, if not it is returned by XMLRPC.
+
+stats - Takes no parameters, returns miscellaneous stats that can be found in the /operserv stats command.
+
+channel - Takes one parameter, a channel name, and returns real time information regarding that channel, such as users, modes
+          (ban lists and such), topic etc.
+
+user - Takes one parameter, a user name, and returns real time information regarding that user.
+
+XMLRPC was designed to be used with m_mysql and db_mysql, and will not return any information that can be pulled from the SQL
+database, such as accounts and registered channel information. For examples on how to use these calls in PHP, see xmlrpc.php in docs/XMLRPC for an example PHP class.
+          
+Also note that the parameter named "id" is reserved for query ID. If you pass a query to Anope containing a value for id. it will
+be stored by Anope and the same id will be passed back in the result.
+
diff --git a/docs/XMLRPC/xmlrpc.php b/docs/XMLRPC/xmlrpc.php
new file mode 100644
index 000000000..768fcd449
--- /dev/null
+++ b/docs/XMLRPC/xmlrpc.php
@@ -0,0 +1,111 @@
+<?php
+
+/* XMLRPC Functions
+ *
+ * (C) 2003-2010 Anope Team
+ * Contact us at team@anope.org
+ *
+ */
+
+class AnopeXMLRPC
+{
+	private $Host, $Bind, $Port, $Username, $Pass;
+
+	private $Socket;
+
+	function __construct($Host, $Port, $Bind = NULL, $Username = NULL, $Pass = NULL)
+	{
+		$this->Host = $Host;
+		$this->Port = $Port;
+		$this->Bind = $Bind;
+		$this->Username = $Username;
+		$this->Pass = $Pass;
+
+		$this->Socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
+		if ($Bind && socket_bind($this->Socket, $this->Bind) == false)
+			$his->Socket = false;
+		if (socket_connect($this->Socket, $this->Host, $this->Port) == false)
+			$this->Socket = false;
+
+		if ($Username && $Pass)
+		{
+			/* Login to XMLRPC, if required */
+			$query = array("login", array($Username, $Pass));
+			$xmlquery = xmlrpc_encode_request($query);
+			socket_write($this->Socket, $xmlquery);
+		}
+	}
+
+	function __destruct()
+	{
+		@socket_close($this->Socket);
+	}
+
+	/** Run an XMLRPC command. Name should be a query name and params an array of parameters, eg:
+	 * $this->RunXMLRPC("checkAuthentication", array("adam", "qwerty"));
+	 * If successful returns back an array of useful information.
+	 *
+	 * Note that $params["id"] is reserved for query ID, you may set it to something if you wish.
+	 * If you do, the same ID will be passed back with the reply from Anope.
+	 */
+	private function RunXMLRPC($name, $params)
+	{
+		$xmlquery = xmlrpc_encode_request($name, $params);
+		socket_write($this->Socket, $xmlquery);
+
+		$inbuf = socket_read($this->Socket, 4096);
+		$inxmlrpc = xmlrpc_decode($inbuf);
+
+		if (isset($inxmlrpc[0]))
+			return $inxmlrpc[0];
+		return NULL;
+	}
+
+	/** Do Command on Service as User, eg:
+	 * $anope->DoCommand("ChanServ", "Adam", "REGISTER #adam");
+	 * Returns an array of information regarding the command execution, if
+	 * If 'online' is set to yes, then the reply to the command was sent to the user on IRC.
+	 * If 'online' is set to no, then the reply to the command is in the array member 'return'
+	 */
+	function DoCommand($Service, $User, $Command)
+	{
+		return $this->RunXMLRPC("command", array($Service, $User, $Command));
+	}
+
+	/** Check an account/nick name and password to see if they are valid
+	 * Returns the account display name if valid
+	 */
+	function CheckAuthentication($Account, $Pass)
+	{
+		$ret = $this->RunXMLRPC("checkAuthentication", array($Account, $Pass));
+
+		if ($ret && $ret["result"] == "Success")
+			return $ret["account"];
+		return NULL;
+	}
+
+	/* Returns an array of misc stats regarding Anope
+	 */
+	function DoStats()
+	{
+		return $this->RunXMLRPC("stats", NULL);
+	}
+
+	/* Look up data for a channel
+	 * Returns an array containing channel information, or an array of size one
+	 * (just containing the name) if the channel does not exist
+	 */
+	function DoChannel($Channel)
+	{
+		return $this->RunXMLRPC("channel");
+	}
+
+	/* Like DoChannel(), but different.
+	 */
+	function DoUser($User)
+	{
+		return $this->RunXMLRPC("channel", array($User));
+	}
+}
+
+?>