1: <?php
2: /**
3: * The Horde_Imsp_Client base class.
4: *
5: * Copyright 2003-2012 Horde LLC (http://www.horde.org/)
6: *
7: * See the enclosed file COPYING for license information (LGPL). If you
8: * did not receive this file, see http://www.horde.org/licenses/lgpl21.
9: *
10: * @author Michael Rubinsky <mrubinsk@horde.org>
11: * @package Horde_Imsp
12: */
13: abstract class Horde_Imsp_Client_Base
14: {
15:
16: const OCTET_COUNT = '/({)([0-9]{1,})(\}$)/';
17: const MUST_USE_LITERAL = '/[\x80-\xFF\\r\\n\"\\\\]/';
18: const MUST_QUOTE = '/[\W]/i';
19:
20: /**
21: * String containing name/IP address of IMSP host.
22: *
23: * @var string
24: */
25: public $host = 'localhost';
26:
27: /**
28: * String containing port for IMSP server.
29: *
30: * @var string
31: */
32: public $port = '406';
33:
34: /**
35: * String buffer containing the last raw NO or BAD response from the
36: * server.
37: *
38: * @var string
39: */
40: public $lastRawError;
41:
42: /**
43: * Current command prefix
44: *
45: * @var string
46: */
47: protected $_commandPrefix = 'A';
48:
49: /**
50: * Current command count
51: *
52: * @var integer
53: */
54: protected $_commandCount = 1;
55:
56: /**
57: * Currently in-use command tag
58: *
59: * @var string
60: */
61: protected $_tag;
62:
63: /**
64: * Command tag last used.
65: *
66: * @var string
67: */
68: protected $_lastCommandTag = 'undefined';
69:
70: /**
71: * Logger
72: *
73: * @var Horde_Log_Logger
74: */
75: public $_logger;
76:
77: /**
78: * The auth object
79: *
80: * @var Horde_Imsp_Auth
81: */
82: protected $_authObj;
83:
84: /**
85: * Constructor function.
86: * Required parameters:
87: *<pre>
88: * authObj <Horde_Imsp_Auth> The object to handle the authentication
89: *</pre>
90: *
91: * Optional parameters:
92: *<pre>
93: * server <string> The IMSP host
94: * port <string> The port the IMSP server listens on
95: * logger <Horde_Log_Logger> The logger.
96: *</pre>
97: * @param array $params Hash containing server parameters.
98: */
99: public function __construct(array $params)
100: {
101: if (empty($params['authObj'])) {
102: throw new InvalidArgumentException('Missing required AuthObj');
103: }
104: $this->_authObj = $params['authObj'];
105: if (!empty($params['server'])) {
106: $this->host = $params['server'];
107: }
108: if (!empty($params['port'])) {
109: $this->port = $params['port'];
110: }
111: if (!empty($params['logger'])) {
112: $this->_logger = $params['logger'];
113: } else {
114: $this->_logger = new Horde_Support_Stub();
115: }
116: }
117:
118: /**
119: * Determines if a string needs to be quoted before sending to the server.
120: *
121: * @param string $string String to be tested.
122: *
123: * @return string Original string, quoted if needed.
124: */
125: static public function quoteSpacedString($string)
126: {
127: if (strpos($string, ' ') !== false ||
128: preg_match(Horde_Imsp::MUST_QUOTE, $string)) {
129: return '"' . $string . '"';
130: } else {
131: return $string;
132: }
133: }
134:
135: /**
136: * Increments the IMSP command tag token.
137: *
138: * @return string Next command tag.
139: */
140: protected function _getNextCommandTag()
141: {
142: $this->_lastCommandTag = $this->_tag ? $this->_tag : 'undefined';
143: return $this->_commandPrefix . sprintf('%04d', $this->_commandCount++);
144: }
145:
146: /**
147: * Close connection and logout from IMSP server.
148: */
149: abstract public function logout();
150:
151: /**
152: * Returns the raw capability response from the server.
153: *
154: * @return string The raw capability response.
155: * @throws Horde_Imsp_Exception
156: */
157: abstract public function capability();
158:
159:
160: /**
161: * Attempts to send a command to the server.
162: *
163: * @param string $commandText Text to send to the server.
164: * @param boolean $includeTag Determines if command tag is prepended.
165: * @param boolean $sendCRLF Determines if CRLF is appended.
166: * @param boolean $continuation Expect a command continuation response.
167: *
168: * @throws Horde_Imsp_Exception
169: */
170: abstract public function send($commandText, $includeTag = true, $sendCRLF = true, $continuation = false);
171:
172: /**
173: * Receives a single CRLF terminated server response string
174: *
175: * @return mixed 'NO', 'BAD', 'OK', raw response.
176: * @throws Horde_Imsp_Exception
177: */
178: abstract public function receive();
179:
180: /**
181: * Retrieves CRLF terminated response from server and splits it into
182: * an array delimited by a <space>.
183: *
184: * @return array The exploded string
185: */
186: abstract public function getServerResponseChunks();
187:
188: /**
189: * Receives fixed number of bytes from IMSP socket. Used when server returns
190: * a string literal.
191: *
192: * @param integer $length Number of bytes to read from socket.
193: *
194: * @return string Text of string literal.
195: */
196: abstract public function receiveStringLiteral($length);
197:
198: /**
199: * Attempts to login to IMSP server.
200: *
201: * @param boolean $login Should we remain logged in after auth?
202: *
203: * @return boolean
204: */
205: abstract public function authenticate($login = true);
206:
207: }