plugins/Irc/extlib/phergie/Phergie/Driver/Abstract.php

   1 <?php
   2 /**
   3  * Phergie
   4  *
   5  * PHP version 5
   6  *
   7  * LICENSE
   8  *
   9  * This source file is subject to the new BSD license that is bundled
  10  * with this package in the file LICENSE.
  11  * It is also available through the world-wide-web at this URL:
  12  * http://phergie.org/license
  13  *
  14  * @category  Phergie
  15  * @package   Phergie
  16  * @author    Phergie Development Team <team@phergie.org>
  17  * @copyright 2008-2010 Phergie Development Team (http://phergie.org)
  18  * @license   http://phergie.org/license New BSD License
  19  * @link      http://pear.phergie.org/package/Phergie
  20  */
  21
  22 /**
  23  * Base class for drivers which handle issuing client commands to the IRC
  24  * server and converting responses into usable data objects.
  25  *
  26  * @category Phergie
  27  * @package  Phergie
  28  * @author   Phergie Development Team <team@phergie.org>
  29  * @license  http://phergie.org/license New BSD License
  30  * @link     http://pear.phergie.org/package/Phergie
  31  */
  32 abstract class Phergie_Driver_Abstract
  33 {
  34     /**
  35      * Currently active connection
  36      *
  37      * @var Phergie_Connection
  38      */
  39     protected $connection;
  40
  41     /**
  42      * Sets the currently active connection.
  43      *
  44      * @param Phergie_Connection $connection Active connection
  45      *
  46      * @return Phergie_Driver_Abstract Provides a fluent interface
  47      */
  48     public function setConnection(Phergie_Connection $connection)
  49     {
  50         $this->connection = $connection;
  51
  52         return $this;
  53     }
  54
  55     /**
  56      * Returns the currently active connection.
  57      *
  58      * @return Phergie_Connection
  59      * @throws Phergie_Driver_Exception
  60      */
  61     public function getConnection()
  62     {
  63         if (empty($this->connection)) {
  64             throw new Phergie_Driver_Exception(
  65                 'Operation requires an active connection, but none is set',
  66                 Phergie_Driver_Exception::ERR_NO_ACTIVE_CONNECTION
  67             );
  68         }
  69
  70         return $this->connection;
  71     }
  72
  73     /**
  74      * Returns an event if one has been received from the server.
  75      *
  76      * @return Phergie_Event_Interface|null Event instance if an event has
  77      *         been received, NULL otherwise
  78      */
  79     public abstract function getEvent();
  80
  81     /**
  82      * Initiates a connection with the server.
  83      *
  84      * @return void
  85      */
  86     public abstract function doConnect();
  87
  88     /**
  89      * Terminates the connection with the server.
  90      *
  91      * @param string $reason Reason for connection termination (optional)
  92      *
  93      * @return void
  94      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_1_6
  95      */
  96     public abstract function doQuit($reason = null);
  97
  98     /**
  99      * Joins a channel.
 100      *
 101      * @param string $channels Comma-delimited list of channels to join
 102      * @param string $keys     Optional comma-delimited list of channel keys
 103      *
 104      * @return void
 105      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_2_1
 106      */
 107     public abstract function doJoin($channels, $keys = null);
 108
 109     /**
 110      * Leaves a channel.
 111      *
 112      * @param string $channels Comma-delimited list of channels to leave
 113      *
 114      * @return void
 115      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_2_2
 116      */
 117     public abstract function doPart($channels);
 118
 119     /**
 120      * Invites a user to an invite-only channel.
 121      *
 122      * @param string $nick    Nick of the user to invite
 123      * @param string $channel Name of the channel
 124      *
 125      * @return void
 126      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_2_7
 127      */
 128     public abstract function doInvite($nick, $channel);
 129
 130     /**
 131      * Obtains a list of nicks of users in specified channels.
 132      *
 133      * @param string $channels Comma-delimited list of one or more channels
 134      *
 135      * @return void
 136      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_2_5
 137      */
 138     public abstract function doNames($channels);
 139
 140     /**
 141      * Obtains a list of channel names and topics.
 142      *
 143      * @param string $channels Comma-delimited list of one or more channels
 144      *                         to which the response should be restricted
 145      *                         (optional)
 146      *
 147      * @return void
 148      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_2_6
 149      */
 150     public abstract function doList($channels = null);
 151
 152     /**
 153      * Retrieves or changes a channel topic.
 154      *
 155      * @param string $channel Name of the channel
 156      * @param string $topic   New topic to assign (optional)
 157      *
 158      * @return void
 159      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_2_4
 160      */
 161     public abstract function doTopic($channel, $topic = null);
 162
 163     /**
 164      * Retrieves or changes a channel or user mode.
 165      *
 166      * @param string $target Channel name or user nick
 167      * @param string $mode   New mode to assign (optional)
 168      *
 169      * @return void
 170      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_2_3
 171      */
 172     public abstract function doMode($target, $mode = null);
 173
 174     /**
 175      * Changes the client nick.
 176      *
 177      * @param string $nick New nick to assign
 178      *
 179      * @return void
 180      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_1_2
 181      */
 182     public abstract function doNick($nick);
 183
 184     /**
 185      * Retrieves information about a nick.
 186      *
 187      * @param string $nick Nick
 188      *
 189      * @return void
 190      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_5_2
 191      */
 192     public abstract function doWhois($nick);
 193
 194     /**
 195      * Sends a message to a nick or channel.
 196      *
 197      * @param string $target Channel name or user nick
 198      * @param string $text   Text of the message to send
 199      *
 200      * @return void
 201      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_4_1
 202      */
 203     public abstract function doPrivmsg($target, $text);
 204
 205     /**
 206      * Sends a notice to a nick or channel.
 207      *
 208      * @param string $target Channel name or user nick
 209      * @param string $text   Text of the notice to send
 210      *
 211      * @return void
 212      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_4_2
 213      */
 214     public abstract function doNotice($target, $text);
 215
 216     /**
 217      * Kicks a user from a channel.
 218      *
 219      * @param string $nick    Nick of the user
 220      * @param string $channel Channel name
 221      * @param string $reason  Reason for the kick (optional)
 222      *
 223      * @return void
 224      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_2_8
 225      */
 226     public abstract function doKick($nick, $channel, $reason = null);
 227
 228     /**
 229      * Responds to a server test of client responsiveness.
 230      *
 231      * @param string $daemon Daemon from which the original request originates
 232      *
 233      * @return void
 234      * @link http://www.irchelp.org/irchelp/rfc/chapter4.html#c4_6_3
 235      */
 236     public abstract function doPong($daemon);
 237
 238     /**
 239      * Sends a CTCP ACTION (/me) command to a nick or channel.
 240      *
 241      * @param string $target Channel name or user nick
 242      * @param string $text   Text of the action to perform
 243      *
 244      * @return void
 245      * @link http://www.invlogic.com/irc/ctcp.html#4.4
 246      */
 247     public abstract function doAction($target, $text);
 248
 249     /**
 250      * Sends a CTCP PING request to a user.
 251      *
 252      * @param string $nick User nick
 253      * @param string $hash Hash to use in the handshake
 254      *
 255      * @return void
 256      * @link http://www.invlogic.com/irc/ctcp.html#4.2
 257      */
 258     public abstract function doPing($nick, $hash);
 259
 260     /**
 261      * Sends a CTCP VERSION request or response to a user.
 262      *
 263      * @param string $nick    User nick
 264      * @param string $version Version string to send for a response
 265      *
 266      * @return void
 267      * @link http://www.invlogic.com/irc/ctcp.html#4.1
 268      */
 269     public abstract function doVersion($nick, $version = null);
 270
 271     /**
 272      * Sends a CTCP TIME request to a user.
 273      *
 274      * @param string $nick User nick
 275      * @param string $time Time string to send for a response
 276      *
 277      * @return void
 278      * @link http://www.invlogic.com/irc/ctcp.html#4.6
 279      */
 280     public abstract function doTime($nick, $time = null);
 281
 282     /**
 283      * Sends a CTCP FINGER request to a user.
 284      *
 285      * @param string $nick   User nick
 286      * @param string $finger Finger string to send for a response
 287      *
 288      * @return void
 289      * @link http://www.irchelp.org/irchelp/rfc/ctcpspec.html
 290      */
 291     public abstract function doFinger($nick, $finger = null);
 292
 293     /**
 294      * Sends a raw command to the server.
 295      *
 296      * @param string $command Command string to send
 297      *
 298      * @return void
 299      */
 300     public abstract function doRaw($command);
 301 }