1: <?php
  2: /**
  3:  * Trean external API interface.
  4:  *
  5:  * This file defines Trean's external API interface. Other
  6:  * applications can interact with Trean through this API.
  7:  *
  8:  * $Horde: trean/lib/Api.php,v 1.2 2009-11-29 15:52:17 chuck Exp $
  9:  *
 10:  * Copyright 2002-2012 Horde LLC (http://www.horde.org/)
 11:  *
 12:  * See the enclosed file LICENSE for license information (BSD). If you
 13:  * did not receive this file, see http://www.horde.org/licenses/bsdl.php.
 14:  *
 15:  * @author Mike Cochrane <mike@graftonhall.co.nz>
 16:  */
 17: class Trean_Api extends Horde_Registry_Api
 18: {
 19:     /**
 20:      * Gets all of the folders that are a subfolder of the given folder
 21:      * (or the root.)
 22:      *
 23:      * @param integer $folderId     the ID of the folder, or -1 for the root
 24:      * @return array    Array of associative arrays (XMLRPC structs) with
 25:      *                  'id' as the folder's ID, and 'name' as its name.
 26:      */
 27:     public function getFolders($folderId)
 28:     {
 29:         if ($folderId == -1) {
 30:             $folder = null;
 31:         } else {
 32:             $folder = $GLOBALS['trean_shares']->getFolder($folderId);
 33:         }
 34:         if ($folder && is_a($folder, 'PEAR_Error')) {
 35:             return $folder;
 36:         }
 37:         $folderObs = Trean::listFolders(Horde_Perms::SHOW,
 38:                                         $folder ? $folder->getName() : null, false);
 39:         if (is_a($folderObs, 'PEAR_Error')) {
 40:             return $folderObs;
 41:         }
 42: 
 43:         $folders = array();
 44:         foreach ($folderObs as $folder) {
 45:             $folders[] = array('id' => $folder->getId(),
 46:                             'name' => $folder->get('name'));
 47:         }
 48:         return $folders;
 49:     }
 50: 
 51:     /**
 52:      * Adds a bookmark folder
 53:      *
 54:      * @param array $data   Object data
 55:      */
 56:     public function addObjects($data)
 57:     {
 58:         $return_map = array();
 59: 
 60:         foreach ($data as $props) {
 61:             $children = null;
 62: 
 63:             if (!isset($props['folder_id']) || !isset($props['return_key'])) {
 64:                 return new PEAR_Error('must specify folder_id and return_key properties');
 65:             }
 66: 
 67:             $return_key = $props['return_key'];
 68:             unset($props['return_key']);
 69: 
 70:             if (isset($props['name'])) {
 71:                 $parentFolder = $GLOBALS['trean_shares']->getFolder($props['folder_id']);
 72:                 unset($props['folder_id']);
 73:                 if (isset($props['child_objects'])) {
 74:                     $children = $props['child_objects'];
 75:                     unset($props['child_objects']);
 76:                 }
 77:                 $ret = $parentFolder->addFolder($props);
 78:             } else {
 79:                 if (!isset($props['bookmark_description'])) {
 80:                     $props['bookmark_description'] = '';
 81:                 }
 82:                 $bookmark = new Trean_Bookmark($props);
 83:                 $ret = $bookmark->save();
 84:             }
 85: 
 86:             if (is_a($ret, 'PEAR_Error')) {
 87:                 return $ret;
 88:             }
 89: 
 90:             $return_map[$return_key] = $ret;
 91: 
 92:             if ($children) {
 93:                 $id = $ret; // $ret = folder ID
 94:                 foreach ($children as $key => $child) {
 95:                     $children[$key]['folder_id'] = $id;
 96:                 }
 97:                 $ret = addObjects($children);
 98:                 if (is_a($ret, 'PEAR_Error')) {
 99:                     return $ret;
100:                 }
101:                 $return_map = array_merge($return_map, $ret);
102:             }
103:         }
104: 
105:         return $return_map;
106:     }
107: 
108:     /**
109:      * Updates a bookmark folder
110:      *
111:      * @param array $data   Object data
112:      */
113:     public function updateObjects($data)
114:     {
115:         foreach ($data as $props) {
116:             if (isset($props['bookmark_id'])) {
117:                 $obj = $GLOBALS['trean_shares']->getBookmark($props['bookmark_id']);
118:             } else if (isset($props['folder_id'])) {
119:                 $obj = $GLOBALS['trean_shares']->getFolder($props['folder_id']);
120:             } else {
121:                 $obj = new PEAR_Error("each inner associative array must have a (bookmark|folder)id key");
122:             }
123:             if (is_a($obj, 'PEAR_Error')) {
124:                 return $obj;
125:             }
126:             foreach ($props as $name => $value) {
127:                 if ($name == 'id') {
128:                     continue;
129:                 }
130:                 if (is_a($obj, 'Trean_Bookmark')) {
131:                     $obj->$name = $value;
132:                 } else {
133:                     if ($name == 'folder') {
134:                         $ret = $GLOBALS['trean_shares']->move($obj,
135:                         $GLOBALS['trean_shares']->getFolder($value));
136:                     } else {
137:                         $ret = $obj->set($name, $value);
138:                     }
139:                     if (is_a($ret, 'PEAR_Error')) {
140:                         return $ret;
141:                     }
142:                 }
143:             }
144:             $obj->save();
145:         }
146: 
147:         return true;
148:     }
149: 
150:     /**
151:      * Returns all the bookmarks in a given folder, sorted and "paginated."
152:      *
153:      * @param integer $folderId   the ID of a folder, or -1 for root
154:      * @param string  $sortby     field to sort by
155:      * @param integer $sortdir    direction to sort by (non-0 for descending)
156:      * @param integer $from       bookmark to start from
157:      * @param integer $count      how many bookmarks to return
158:      * @return array  An array of associative arrays (XMLRPC structs) representing
159:      * the bookmarks.
160:      * @see DataTreeObject_Folder->listBookmarks()
161:      */
162:     public function listBookmarks($folderId, $sortby = 'title', $sortdir = 0, $from = 0, $count = 0)
163:     {
164:         $folder = $GLOBALS['trean_shares']->getFolder($folderId);
165:         if (is_a($folder, 'PEAR_Error')) {
166:             return $folder;
167:         }
168:         return $folder->listBookmarks($sortby, $sortdir, $from, $count);
169:     }
170: 
171:     /**
172:      * Delete a given folder.
173:      *
174:      * @param integer $folderId   the ID of the folder
175:      * @param boolean $force      Force-remove child objects? (currently ignored)
176:      *
177:      * @return boolean  True for success.
178:      */
179:     public function deleteFolder($folderId, $force)
180:     {
181:         $folder = $GLOBALS['trean_shares']->getFolder($folderId);
182:         if (is_a($folder, 'PEAR_Error')) {
183:             return $folder;
184:         }
185:         $result = $folder->delete();
186:         if (is_a($result, 'PEAR_Error')) {
187:             return $result;
188:         }
189:         return true;
190:     }
191: 
192:     /**
193:      * Delete multiple folders.
194:      *
195:      * @param array $Ids   The IDs of the folders to delete
196:      *
197:      * @return boolean  True for success.
198:      */
199:     public function deleteFolders($Ids)
200:     {
201:         $Ids = array_reverse($Ids);
202:         foreach ($Ids as $Id) {
203:             $ret = deleteFolder($Id, true);
204:             if (is_a($ret, 'PEAR_Error')) {
205:                 return $ret;
206:             }
207:         }
208: 
209:         return true;
210:     }
211: 
212:     /**
213:      * Delete a given bookmark.
214:      *
215:      * @param integer   $bookmarkId the ID of the bookmark to delete
216:      *
217:      * @return boolean  True for success.
218:      */
219:     public function deleteBookmark($bookmarkId)
220:     {
221:         $result = $GLOBALS['trean_shares']->removeBookmark($bookmarkId);
222:         if (is_a($result, 'PEAR_Error')) {
223:             return $result;
224:         }
225:         return true;
226:     }
227: 
228:     /**
229:      * Delete multiple bookmarks.
230:      *
231:      * @param array $Ids   the IDs of the bookmarks to delete
232:      *
233:      * @return boolean  True for success.
234:      */
235:     public function deleteBookmarks($Ids)
236:     {
237:         foreach ($Ids as $Id) {
238:             $ret = deleteBookmark($Id);
239:             if (is_a($ret, 'PEAR_Error')) {
240:                 return $ret;
241:             }
242:         }
243: 
244:         return true;
245:     }
246: 
247:     /**
248:      * Synchronize bookmarks in a folder.  Send a list of IDs of bookmarks you
249:      * know about, get an array of new bookmarks and placeholders for bookmarks
250:      * you have that are now deleted.
251:      *
252:      * @param integer folderId     the ID of the folder, or -1 for root
253:      * @param array   bookmarkIds  integer array of the bookmark IDs to sync against
254:      * @return array  An array of associative arrays (XMLRPC structs) of all the
255:      * newly created bookmarks' data, or for deleted bookmarks, a placeholder with
256:      * 'id' as the ID of the bookmark and 'sync_deleted' as true.
257:      * @see listBookmarks()
258:      */
259:     public function syncBookmarks($folderId, $bookmarkIds)
260:     {
261:         $rawbookmarks = listBookmarks($folderId);
262:         if (is_a($rawbookmarks, 'PEAR_Error')) {
263:             return $rawbookmarks;
264:         }
265:         $bookmarks = array();
266:         foreach ($rawbookmarks as $bookmark) {
267:             $bookmarks[$bookmark->id] = $bookmark;
268:         }
269:         // We're authoritative, so we prune out any bookmarks the client
270:         // already knows about by ID, and let them know of the deletion of any we
271:         // don't know about
272:         foreach ($bookmarkIds as $id) {
273:             if (isset($bookmarks[$id])) {
274:                 unset($bookmarks[$id]);
275:             } else {
276:                 $bookmarks[$id] = array('id' => $id, 'sync_deleted' => true);
277:             }
278:         }
279: 
280:         // We should be left with a list of new bookmarks with their full details,
281:         // and deleted bookmarks with only an id and 'sync_deleted' boolean
282:         return array_values($bookmarks);
283:     }
284: 
285:     /**
286:      * Synchronize folders in a folder.  Send a list of IDs, get a list of new
287:      * folders and placeholders for deleted ones.  See syncBookmarks()
288:      * for more details.
289:      *
290:      * @param integer folderID   the ID of the folder, or -1 for root
291:      * @param array   folderIds  integer array of folder IDs to sync against
292:      * @return array  An array of associate arrays (XMLRPC structs) of all
293:      * the newly created folders' data, or placeholders for deleted folders.
294:      * @see getFolders()
295:      * @see syncBookmarks()
296:      */
297:     public function syncFolders($folderId, $folderIds)
298:     {
299:         $rawfolders = getFolders($folderId);
300:         if (is_a($rawfolders, 'PEAR_Error')) {
301:             return $rawfolders;
302:         }
303:         $folders = array();
304:         foreach ($rawfolders as $folder) {
305:             $folders[$folder['id']] = $folder;
306:         }
307: 
308:         // This works like the sync for bookmarks
309:         foreach ($folderIds as $id) {
310:             if (isset($folders[$id])) {
311:                 unset($folders[$id]);
312:             } else {
313:                 $folders[$id] = array('id' => $id, 'sync_deleted' => true);
314:             }
315:         }
316: 
317:         return array_values($folders);
318:     }
319: 
320:     /**
321:      * Returns a URL that can be used in other applications to add the currently
322:      * displayed page as a bookmark.  If javascript and DOM is available, an overlay
323:      * is used, if javascript and no DOM, then a pop-up is used and if no javascript
324:      * is available a URL to Trean's add.php page is returned.
325:      *
326:      * @param array $params  A hash of 'url' and 'title' properties of the requested
327:      *                       bookmark.
328:      * @return string  The URL suitable for use in a <a> tag.
329:      */
330:     public function getAddUrl($params = array())
331:     {
332:         $GLOBALS['no_compress'] = true;
333: 
334:         $browser = $GLOBALS['injector']->getInstance('Horde_Browser');
335:         if ($browser->hasFeature('javascript')) {
336:             if ($browser->hasFeature('dom')) {
337:                 $addurl = Horde_Util::addParameter(Horde::url('add.php', true, -1), 'iframe', 1);
338:                 $url = "javascript:(function(){o=document.createElement('div');o.id='overlay';o.style.background='#000';o.style.position='absolute';o.style.top=0;o.style.left=0;o.style.width='100%';o.style.height='100%';o.style.zIndex=5000;o.style.opacity=.8;document.body.appendChild(o);i=document.createElement('iframe');i.id='frame';i.style.zIndex=5001;i.style.border='thin solid #000';i.src='$addurl'+'&title=' + encodeURIComponent(document.title) + '&url=' + encodeURIComponent(location.href);i.style.position='absolute';i.style.width='350px';i.style.height='150px';i.style.left='100px';i.style.top='100px';document.body.appendChild(i);l=document.createElement('a');l.style.position='absolute';l.style.background='#ccc';l.style.color='#000';l.style.border='thin solid #000';l.style.display='block';l.style.top='250px';l.style.left='100px';l.style.zIndex=5001;l.style.padding='5px';l.appendChild(document.createTextNode('" . _("Close") . "'));l.onclick=function(){var o=document.getElementById('overlay');o.parentNode.removeChild(o);var i=document.getElementById('frame');i.parentNode.removeChild(i);this.parentNode.removeChild(this);};document.body.appendChild(l);})()";
339:             } else {
340:                 $addurl = Horde::url(Horde_Util::addParameter('add.php', 'popup', 1), true, -1);
341:                 $url = "javascript:d = new Date(); w = window.open('$addurl' + '&amp;title=' + encodeURIComponent(document.title) + '&amp;url=' + encodeURIComponent(location.href) + '&amp;d=' + d.getTime(), d.getTime(), 'height=200,width=400'); w.focus();";
342:             }
343:         } else {
344:             // Fallback to a regular URL
345:             $url = Horde::url(Horde_Util::addParameter('add.php', $params), true);
346:         }
347: 
348:         return $url;
349:     }
350: }
351: