1: <?php
  2: /**
  3:  * Mnemo external API interface.
  4:  *
  5:  * This file defines Mnemo's external API interface.  Other applications can
  6:  * interact with Mnemo through this API.
  7:  *
  8:  * Copyright 2001-2012 Horde LLC (http://www.horde.org/)
  9:  *
 10:  * See the enclosed file LICENSE for license information (ASL). If you
 11:  * did not receive this file, see http://www.horde.org/licenses/apache.
 12:  *
 13:  * @category Horde
 14:  * @package  Mnemo
 15:  */
 16: 
 17: class Mnemo_Api extends Horde_Registry_Api
 18: {
 19:     /**
 20:      * Removes user data.
 21:      *
 22:      * @deprecated  Use Horde's removeUserData API call instead.
 23:      *
 24:      * @param string $user  Name of user to remove data for.
 25:      *
 26:      * @throws Mnemo_Exception
 27:      */
 28:     public function removeUserData($user)
 29:     {
 30:         try {
 31:             $GLOBALS['registry']->removeUserData($user, 'mnemo');
 32:         } catch (Horde_Exception $e) {
 33:             throw new Mnemo_Exception($e);
 34:         }
 35:     }
 36: 
 37:     /**
 38:      * @param boolean $owneronly   Only return notepads that this user owns?
 39:      *                             Defaults to false.
 40:      * @param integer $permission  The permission to filter notepads by.
 41:      *
 42:      * @return array  The notepads.
 43:      */
 44:     public function listNotepads($owneronly, $permission)
 45:     {
 46:         return Mnemo::listNotepads($owneronly, $permission);
 47:     }
 48: 
 49:     /**
 50:      * Returns an array of UIDs for all notes that the current user is authorized
 51:      * to see.
 52:      *
 53:      * @param string $notepad  The notepad to list notes from.
 54:      *
 55:      * @return array  An array of UIDs for all notes the user can access.
 56:      * @throws Mnemo_Exception
 57:      * @throws Horde_Exception_PermissionDenied
 58:      */
 59:     public function listUids($notepad = null)
 60:     {
 61:         global $conf;
 62: 
 63:         if (!isset($conf['storage']['driver'])) {
 64:             throw new Mnemo_Exception('Not configured');
 65:         }
 66: 
 67:         // Make sure we have a valid notepad.
 68:         if (empty($notepad)) {
 69:             $notepad = Mnemo::getDefaultNotepad();
 70:         }
 71: 
 72:         if (!array_key_exists($notepad, Mnemo::listNotepads(false, Horde_Perms::READ))) {
 73:             throw new Horde_Exception_PermissionDenied(_("Permission Denied"));
 74:         }
 75: 
 76:         // Set notepad for listMemos.
 77:         $GLOBALS['display_notepads'] = array($notepad);
 78:         $memos = Mnemo::listMemos();
 79:         $uids = array();
 80:         foreach ($memos as $memo) {
 81:             $uids[] = $memo['uid'];
 82:         }
 83: 
 84:         return $uids;
 85:     }
 86: 
 87:     /**
 88:      * Method for obtaining all server changes between two timestamps. Basically
 89:      * a wrapper around listBy(), but returns an array containing all adds,
 90:      * edits and deletions.
 91:      *
 92:      * @param integer $start             The starting timestamp
 93:      * @param integer $end               The ending timestamp.
 94:      *
 95:      * @return array  An hash with 'add', 'modify' and 'delete' arrays.
 96:      * @since 3.0.5
 97:      */
 98:     public function getChanges($start, $end)
 99:     {
100:         return array('add' => $this->listBy('add', $start, null, $end),
101:                      'modify' => $this->listBy('modify', $start, null, $end),
102:                      'delete' => $this->listBy('delete', $start, null, $end));
103:     }
104: 
105:     /**
106:      * Returns an array of UIDs for notes that have had $action happen since
107:      * $timestamp.
108:      *
109:      * @param string  $action     The action to check for - add, modify, or delete.
110:      * @param integer $timestamp  The time to start the search.
111:      * @param string  $notepad    The notepad to search in.
112:      * @param integer $end        The optional ending timestamp.
113:      *
114:      * @return array  An array of UIDs matching the action and time criteria.
115:      */
116:     public function listBy($action, $timestamp, $notepad = null, $end = null)
117:     {
118:         /* Make sure we have a valid notepad. */
119:         if (empty($notepad)) {
120:             $notepad = Mnemo::getDefaultNotepad();
121:         }
122: 
123:         if (!array_key_exists($notepad, Mnemo::listNotepads(false, Horde_Perms::READ))) {
124:            throw new Horde_Exception_PermissionDenied(_("Permission Denied"));
125:         }
126: 
127:         $filter = array(array('op' => '=', 'field' => 'action', 'value' => $action));
128:         if (!empty($end)) {
129:             $filter[] = array('op' => '<', 'field' => 'ts', 'value' => $end);
130:         }
131:         $history = $GLOBALS['injector']->getInstance('Horde_History');
132:         $histories = $history->getByTimestamp('>', $timestamp, $filter, 'mnemo:' . $notepad);
133: 
134:         // Strip leading mnemo:username:.
135:         return preg_replace('/^([^:]*:){2}/', '', array_keys($histories));
136:     }
137: 
138:     /**
139:      * Returns the timestamp of an operation for a given uid an action.
140:      *
141:      * @param string $uid     The uid to look for.
142:      * @param string $action  The action to check for - add, modify, or delete.
143:      * @param string $notepad The notepad to search in.
144:      *
145:      * @return integer  The timestamp for this action.
146:      * @throws Horde_Exception_PermissionDenied
147:      */
148:     public function getActionTimestamp($uid, $action, $notepad = null)
149:     {
150:         /* Make sure we have a valid notepad. */
151:         if (empty($notepad)) {
152:             $notepad = Mnemo::getDefaultNotepad();
153:         }
154: 
155:         if (!array_key_exists($notepad, Mnemo::listNotepads(false, Horde_Perms::READ))) {
156:             throw new Horde_Exception_PermissionDenied(_("Permission Denied"));
157:         }
158: 
159:         $history = $GLOBALS['injector']->getInstance('Horde_History');
160:         return $history->getActionTimestamp('mnemo:' . $notepad . ':' . $uid, $action);
161:     }
162: 
163:     /**
164:      * Import a memo represented in the specified contentType.
165:      *
166:      * @param string $content      The content of the memo.
167:      * @param string $contentType  What format is the data in? Currently supports:
168:      *                             text/plain
169:      *                             text/x-vnote
170:      * @param string $notepad      (optional) The notepad to save the memo on.
171:      *
172:      * @return string  The new UID, or false on failure.
173:      * @throws Mnemo_Exception
174:      * @throws Horde_Exception_PermissionDenied
175:      */
176:     public function import($content, $contentType, $notepad = null)
177:     {
178:         global $prefs;
179: 
180:         /* Make sure we have a valid notepad and permissions to edit
181:          * it. */
182:         if (empty($notepad)) {
183:             $notepad = Mnemo::getDefaultNotepad(Horde_Perms::EDIT);
184:         }
185: 
186:         if (!array_key_exists($notepad, Mnemo::listNotepads(false, Horde_Perms::EDIT))) {
187:             throw new Horde_Exception_PermissionDenied(_("Permission Denied"));
188:         }
189: 
190:         /* Create a Mnemo_Driver instance. */
191:         $storage = $GLOBALS['injector']->getInstance('Mnemo_Factory_Driver')->create($notepad);
192: 
193:         switch ($contentType) {
194:         case 'text/plain':
195:             $noteId = $storage->add($storage->getMemoDescription($content), $content);
196:             break;
197: 
198:         case 'text/x-vnote':
199:             if (!($content instanceof Horde_Icalendar_Vnote)) {
200:                 $iCal = new Horde_Icalendar();
201:                 if (!$iCal->parsevCalendar($content)) {
202:                     throw new Mnemo_Exception(_("There was an error importing the iCalendar data."));
203:                 }
204: 
205:                 $components = $iCal->getComponents();
206:                 switch (count($components)) {
207:                 case 0:
208:                     throw new Mnemo_Exception(_("No iCalendar data was found."));
209: 
210:                 case 1:
211:                     $content = $components[0];
212:                     break;
213: 
214:                 default:
215:                     $ids = array();
216:                     foreach ($components as $content) {
217:                         if ($content instanceof Horde_Icalendar_Vnote) {
218:                             $note = $storage->fromiCalendar($content);
219:                             $noteId = $storage->add($note['desc'],
220:                                                     $note['body'],
221:                                                     !empty($note['category']) ? $note['category'] : '');
222:                             $ids[] = $noteId;
223:                         }
224:                     }
225:                     return $ids;
226:                 }
227:             }
228: 
229:             $note = $storage->fromiCalendar($content);
230:             $noteId = $storage->add($note['desc'],
231:                                     $note['body'], !empty($note['category']) ? $note['category'] : '');
232:             break;
233: 
234:         default:
235:             throw new Mnemo_Exception(sprintf(_("Unsupported Content-Type: %s"), $contentType));
236:         }
237:         $note = $storage->get($noteId);
238: 
239:         return $note['uid'];
240:     }
241: 
242:     /**
243:      * Export a memo, identified by UID, in the requested contentType.
244:      *
245:      * @param string $uid          Identify the memo to export.
246:      * @param string $contentType  What format should the data be in?
247:      *                             A string with one of:
248:      *                             <pre>
249:      *                               'text/plain'
250:      *                               'text/x-vnote'
251:      *                             </pre>
252:      *
253:      * @return string  The requested data
254:      * @throws Mnemo_Exception
255:      * @throws Horde_Exception_PermissionDenied
256:      */
257:     public function export($uid, $contentType)
258:     {
259:         $storage = $GLOBALS['injector']->getInstance('Mnemo_Factory_Driver')->create();
260:         try {
261:             $memo = $storage->getByUID($uid);
262:         } catch (Mnemo_Exception $e) {
263:             if ($e->getCode() == Mnemo::ERR_NO_PASSPHRASE ||
264:                 $e->getCode() == Mnemo::ERR_DECRYPT) {
265: 
266:                 $memo['body'] = _("This note has been encrypted.");
267:             } else {
268:                 throw $e;
269:             }
270:         }
271:         if (!array_key_exists($memo['memolist_id'], Mnemo::listNotepads(false, Horde_Perms::READ))) {
272:             throw new Horde_Exception_PermissionDenied(_("Permission Denied"));
273:         }
274: 
275:         switch ($contentType) {
276:         case 'text/plain':
277:             return $memo['body'];
278: 
279:         case 'text/x-vnote':
280:             // Create the new iCalendar container.
281:             $iCal = new Horde_Icalendar('1.1');
282:             $iCal->setAttribute('VERSION', '1.1');
283:             $iCal->setAttribute('PRODID', '-//The Horde Project//Mnemo ' . $registry->getVersion() . '//EN');
284:             $iCal->setAttribute('METHOD', 'PUBLISH');
285: 
286:             // Create a new vNote.
287:             $vNote = $storage->toiCalendar($memo, $iCal);
288:             return $vNote->exportvCalendar();
289:         }
290: 
291:         throw new Mnemo_Exception(sprintf(_("Unsupported Content-Type: %s"),$contentType));
292:     }
293: 
294:     /**
295:      * Delete a memo identified by UID.
296:      *
297:      * @param string | array $uid  Identify the note to delete, either a
298:      *                             single UID or an array.
299:      * @throws Horde_Exception_PermissionDenied
300:      */
301:     public function delete($uid)
302:     {
303:         // Handle an arrray of UIDs for convenience of deleting multiple
304:         // notes at once.
305:         if (is_array($uid)) {
306:             foreach ($uid as $u) {
307:                 $result = $this->delete($u);
308:             }
309:         }
310: 
311: 
312:         $storage = $GLOBALS['injector']->getInstance('Mnemo_Factory_Driver')->create();
313:         $memo = $storage->getByUID($uid);
314:         if (!$GLOBALS['registry']->isAdmin() &&
315:             !array_key_exists($memo['memolist_id'], Mnemo::listNotepads(false, Horde_Perms::DELETE))) {
316: 
317:             throw new Horde_Exception_PermissionDenied(_("Permission Denied"));
318:         }
319: 
320:         $storage->delete($memo['memo_id']);
321:     }
322: 
323:     /**
324:      * Replace the memo identified by UID with the content represented in
325:      * the specified contentType.
326:      *
327:      * @param string $uid         Idenfity the memo to replace.
328:      * @param string $content      The content of the memo.
329:      * @param string $contentType  What format is the data in? Currently supports:
330:      *                             text/plain
331:      *                             text/x-vnote
332:      * @throws Mnemo_Exception
333:      * @throws Horde_Exception_PermissionDenied
334:      */
335:     public function replace($uid, $content, $contentType)
336:     {
337:         $storage = $GLOBALS['injector']->getInstance('Mnemo_Factory_Driver')->create();
338:         $memo = $storage->getByUID($uid);
339:         if (!array_key_exists($memo['memolist_id'], Mnemo::listNotepads(false, Horde_Perms::EDIT))) {
340:             throw new Horde_Exception_PermissionDenied(_("Permission Denied"));
341:         }
342: 
343:         switch ($contentType) {
344:         case 'text/plain':
345:             $storage->modify($memo['memo_id'], $storage->getMemoDescription($content), $content, null);
346:             break;
347:         case 'text/x-vnote':
348:             if (!($content instanceof Horde_Icalendar_Vnote)) {
349:                 $iCal = new Horde_Icalendar();
350:                 if (!$iCal->parsevCalendar($content)) {
351:                     throw new Mnemo_Exception(_("There was an error importing the iCalendar data."));
352:                 }
353: 
354:                 $components = $iCal->getComponents();
355:                 switch (count($components)) {
356:                 case 0:
357:                     throw new Mnemo_Exception(_("No iCalendar data was found."));
358: 
359:                 case 1:
360:                     $content = $components[0];
361:                     break;
362: 
363:                 default:
364:                     throw new Mnemo_Exception(_("Multiple iCalendar components found; only one vNote is supported."));
365:                 }
366:             }
367:             $note = $storage->fromiCalendar($content);
368:             $storage->modify($memo['memo_id'],
369:                              $note['desc'],
370:                              $note['body'],
371:                              !empty($note['category']) ? $note['category'] : '');
372:             break;
373:         default:
374:             throw new Mnemo_Exception(sprintf(_("Unsupported Content-Type: %s"),$contentType));
375:         }
376:     }
377: 
378: }
379: