1: <?php
2: /**
3: * Shout_Driver:: defines an API for implementing storage backends for Shout.
4: *
5: * Copyright 2005-2010 Alkaloid Networks LLC (http://projects.alkaloid.net)
6: *
7: * See the enclosed file COPYING for license information (BSD). If you
8: * did not receive this file, see
9: * http://www.opensource.org/licenses/bsd-license.php.
10: *
11: * @author Ben Klang <ben@alkaloid.net>
12: * @package Shout
13: */
14: class Shout_Driver {
15:
16: /**
17: * Hash containing connection parameters.
18: *
19: * @var array $_params
20: */
21: var $_params = array();
22:
23: function __construct($params = array())
24: {
25: $this->_params = $params;
26: }
27:
28: /**
29: * Get a list of accounts from the instantiated driver and filter
30: * the returned accounts for those which the current user can see/edit
31: *
32: * @param optional string $filter Filter for types of accounts to return.
33: * One of "system" "customer" or "all"
34: *
35: * @param optional string $filterperms Filter accounts for given permissions
36: *
37: * @return array Accounts valid for this user
38: *
39: * @access public
40: */
41: function getAccounts($filters = "all", $filterperms = null)
42: {
43: throw new Shout_Exception("This function is not implemented.");
44: }
45:
46: /**
47: * For the given account and type, make sure the account has the
48: * appropriate properties, that it is effectively of that "type"
49: *
50: * @param string $account the account to check type for
51: *
52: * @param string $type the type to verify the account is of
53: *
54: * @return boolean true of the account is of type, false if not
55: *
56: * @access public
57: */
58: function checkAccountType($account, $type)
59: {
60: throw new Shout_Exception("This function is not implemented.");
61: }
62:
63: /**
64: * Get a list of users valid for the current account. Return an array
65: * indexed by the extension.
66: *
67: * @param string $account Account for which users should be returned
68: *
69: * @return array User information indexed by voice mailbox number
70: */
71: function getUsers($account)
72: {
73: throw new Shout_Exception("This function is not implemented.");
74: }
75:
76: /**
77: * Returns the name of the user's default account
78: *
79: * @return string User's default account
80: */
81: function getHomeAccount()
82: {
83: throw new Shout_Exception("This function is not implemented.");
84: }
85:
86: /**
87: * Get a account's properties
88: *
89: * @param string $account Account for which to get properties
90: *
91: * @return integer Bitfield of properties valid for this account
92: */
93: function getAccountProperties($account)
94: {
95: throw new Shout_Exception("This function is not implemented.");
96: }
97:
98: /**
99: * Get a account's extensions and return as a multi-dimensional associative
100: * array
101: *
102: * @param string $account account to return extensions for
103: *
104: * @return array Multi-dimensional associative array of extensions data
105: *
106: */
107: function getDialplan($account)
108: {
109: throw new Shout_Exception("This function is not implemented.");
110: }
111:
112: /**
113: * Save an extension to the backend.
114: *
115: * This method is intended to be overridden by a child class. However it
116: * also implements some basic checks, so a typical backend will still
117: * call this method via parent::
118: *
119: * @param string $account Account to which the user should be added
120: *
121: * @param string $extension Extension to be saved
122: *
123: * @param array $details Phone numbers, PIN, options, etc to be saved
124: *
125: * @return TRUE on success, PEAR::Error object on error
126: * @throws Shout_Exception
127: */
128: public function saveExtension($account, $extension, $details)
129: {
130: if (empty($account) || empty($extension)) {
131: throw new Shout_Exception(_("Invalid extension."));
132: }
133:
134: if (!Shout::checkRights("shout:accounts:$account:extensions", PERMS_EDIT, 1)) {
135: throw new Shout_Exception(_("Permission denied to save extensions in this account."));
136: }
137: }
138:
139: public function deleteExtension($account, $extension)
140: {
141: if (empty($account) || empty($extension)) {
142: throw new Shout_Exception(_("Invalid extension."));
143: }
144:
145: if (!Shout::checkRights("shout:accounts:$account:extensions",
146: PERMS_DELETE, 1)) {
147: throw new Shout_Exception(_("Permission denied to delete extensions in this account."));
148: }
149: }
150:
151: /**
152: * Save a device to the backend.
153: *
154: * This method is intended to be overridden by a child class. However it
155: * also implements some basic checks, so a typical backend will still
156: * call this method via parent::
157: *
158: * @param string $account Account to which the user should be added
159: *
160: * @param string $extension Extension to be saved
161: *
162: * @param array $details Phone numbers, PIN, options, etc to be saved
163: *
164: * @return TRUE on success, PEAR::Error object on error
165: * @throws Shout_Exception
166: */
167: public function saveDevice($account, $devid, &$details)
168: {
169: if (empty($account)) {
170: throw new Shout_Exception(_("Invalid device information."));
171: }
172:
173: if (!Shout::checkRights("shout:accounts:$account:devices", PERMS_EDIT, 1)) {
174: throw new Shout_Exception(_("Permission denied to save devices in this account."));
175: }
176:
177: if (empty($devid) || !empty($details['genauthtok'])) {
178: list($devid, $password) = Shout::genDeviceAuth($account);
179: $details['devid'] = $devid;
180: $details['password'] = $password;
181: }
182:
183:
184: }
185:
186: /**
187: * Delete a device from the backend.
188: *
189: * This method is intended to be overridden by a child class. However it
190: * also implements some basic checks, so a typical backend will still
191: * call this method via parent::
192: *
193: * @param <type> $account
194: * @param <type> $devid
195: */
196: public function deleteDevice($account, $devid)
197: {
198: if (empty($account) || empty($devid)) {
199: throw new Shout_Exception(_("Invalid device."));
200: }
201:
202: if (!Shout::checkRights("shout:accounts:$account:devices",
203: PERMS_DELETE, 1)) {
204: throw new Shout_Exception(_("Permission denied to delete devices in this account."));
205: }
206: }
207:
208: /**
209: * Attempts to return a concrete Shout_Driver instance based on
210: * $driver.
211: *
212: * @param string $driver The type of the concrete Shout_Driver subclass
213: * to return. The class name is based on the storage
214: * driver ($driver). The code is dynamically
215: * included.
216: *
217: * @param array $params (optional) A hash containing any additional
218: * configuration or connection parameters a
219: * subclass might need.
220: *
221: * @return mixed The newly created concrete Shout_Driver instance, or
222: * false on an error.
223: */
224: function &factory($class, $driver = null, $params = null)
225: {
226: if (is_null($driver)) {
227: $driver = $GLOBALS['conf'][$class]['driver'];
228: }
229:
230: $driver = basename($driver);
231:
232: if (is_null($params)) {
233: if ($GLOBALS['conf'][$class]['params']['driverconfig'] == 'horde') {
234: $params = array_merge(Horde::getDriverConfig('storage', $driver),
235: $GLOBALS['conf'][$class]['params']);
236: } else {
237: $params = $GLOBALS['conf'][$class]['params'];
238: }
239: }
240:
241: $params['class'] = $class;
242:
243: require_once dirname(__FILE__) . '/Driver/' . $driver . '.php';
244: $class = 'Shout_Driver_' . $driver;
245: if (class_exists($class)) {
246: return new $class($params);
247: } else {
248: return false;
249: }
250: }
251:
252: }
253: