source: trunk/www.guidonia.net/wp/wp-content/plugins/wordbook/facebook-platform/php/facebookapi_php5_restlib.php@ 44

Last change on this file since 44 was 44, checked in by luciano, 14 years ago
File size: 74.7 KB
Line 
1<?php
2//
3// +---------------------------------------------------------------------------+
4// | Facebook Platform PHP5 client |
5// +---------------------------------------------------------------------------+
6// | Copyright (c) 2007-2008 Facebook, Inc. |
7// | All rights reserved. |
8// | |
9// | Redistribution and use in source and binary forms, with or without |
10// | modification, are permitted provided that the following conditions |
11// | are met: |
12// | |
13// | 1. Redistributions of source code must retain the above copyright |
14// | notice, this list of conditions and the following disclaimer. |
15// | 2. Redistributions in binary form must reproduce the above copyright |
16// | notice, this list of conditions and the following disclaimer in the |
17// | documentation and/or other materials provided with the distribution. |
18// | |
19// | THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
20// | IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
21// | OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
22// | IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
23// | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
24// | NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
25// | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
26// | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
27// | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
28// | THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
29// +---------------------------------------------------------------------------+
30// | For help with this library, contact developers-help@facebook.com |
31// +---------------------------------------------------------------------------+
32//
33
34include_once 'jsonwrapper/jsonwrapper.php';
35class FacebookRestClient {
36 public $secret;
37 public $session_key;
38 public $api_key;
39 public $friends_list; // to save making the friends.get api call, this will get prepopulated on canvas pages
40 public $added; // to save making the users.isAppAdded api call, this will get prepopulated on canvas pages
41 public $is_user;
42 // we don't pass friends list to iframes, but we want to make
43 // friends_get really simple in the canvas_user (non-logged in) case.
44 // So we use the canvas_user as default arg to friends_get
45 public $canvas_user;
46 public $batch_mode;
47 private $batch_queue;
48 private $call_as_apikey;
49
50 const BATCH_MODE_DEFAULT = 0;
51 const BATCH_MODE_SERVER_PARALLEL = 0;
52 const BATCH_MODE_SERIAL_ONLY = 2;
53
54 /**
55 * Create the client.
56 * @param string $session_key if you haven't gotten a session key yet, leave
57 * this as null and then set it later by just
58 * directly accessing the $session_key member
59 * variable.
60 */
61 public function __construct($api_key, $secret, $session_key=null) {
62 $this->secret = $secret;
63 $this->session_key = $session_key;
64 $this->api_key = $api_key;
65 $this->batch_mode = FacebookRestClient::BATCH_MODE_DEFAULT;
66 $this->last_call_id = 0;
67 $this->call_as_apikey = '';
68 $this->server_addr = Facebook::get_facebook_url('api') . '/restserver.php';
69 if (!empty($GLOBALS['facebook_config']['debug'])) {
70 $this->cur_id = 0;
71 ?>
72<script type="text/javascript">
73var types = ['params', 'xml', 'php', 'sxml'];
74function getStyle(elem, style) {
75 if (elem.getStyle) {
76 return elem.getStyle(style);
77 } else {
78 return elem.style[style];
79 }
80}
81function setStyle(elem, style, value) {
82 if (elem.setStyle) {
83 elem.setStyle(style, value);
84 } else {
85 elem.style[style] = value;
86 }
87}
88function toggleDisplay(id, type) {
89 for (var i = 0; i < types.length; i++) {
90 var t = types[i];
91 var pre = document.getElementById(t + id);
92 if (pre) {
93 if (t != type || getStyle(pre, 'display') == 'block') {
94 setStyle(pre, 'display', 'none');
95 } else {
96 setStyle(pre, 'display', 'block');
97 }
98 }
99 }
100 return false;
101}
102</script>
103<?php
104 }
105 }
106
107
108 /**
109 * Start a batch operation.
110 */
111 public function begin_batch() {
112 if($this->batch_queue !== null)
113 {
114 throw new FacebookRestClientException(FacebookAPIErrorCodes::API_EC_BATCH_ALREADY_STARTED,
115 FacebookAPIErrorCodes::$api_error_descriptions[FacebookAPIErrorCodes::API_EC_BATCH_ALREADY_STARTED]);
116 }
117
118 $this->batch_queue = array();
119 }
120
121 /*
122 * End current batch operation
123 */
124 public function end_batch() {
125 if($this->batch_queue === null) {
126 throw new FacebookRestClientException(FacebookAPIErrorCodes::API_EC_BATCH_NOT_STARTED,
127 FacebookAPIErrorCodes::$api_error_descriptions[FacebookAPIErrorCodes::API_EC_BATCH_NOT_STARTED]);
128 }
129
130 $this->execute_server_side_batch();
131
132 $this->batch_queue = null;
133 }
134
135
136 private function execute_server_side_batch() {
137
138
139 $item_count = count($this->batch_queue);
140 $method_feed = array();
141 foreach($this->batch_queue as $batch_item) {
142 $method_feed[] = $this->create_post_string($batch_item['m'], $batch_item['p']);
143 }
144
145 $method_feed_json = json_encode($method_feed);
146
147 $serial_only = $this->batch_mode == FacebookRestClient::BATCH_MODE_SERIAL_ONLY ;
148 $params = array('method_feed' => $method_feed_json, 'serial_only' => $serial_only);
149 if ($this->call_as_apikey) {
150 $params['call_as_apikey'] = $this->call_as_apikey;
151 }
152
153 $xml = $this->post_request('batch.run', $params);
154
155 $result = $this->convert_xml_to_result($xml, 'batch.run', $params);
156
157
158 if (is_array($result) && isset($result['error_code'])) {
159 throw new FacebookRestClientException($result['error_msg'], $result['error_code']);
160 }
161
162 for($i = 0; $i < $item_count; $i++) {
163 $batch_item = $this->batch_queue[$i];
164 $batch_item_result_xml = $result[$i];
165 $batch_item_result = $this->convert_xml_to_result($batch_item_result_xml, $batch_item['m'], $batch_item['p']);
166
167 if (is_array($batch_item_result) && isset($batch_item_result['error_code'])) {
168 throw new FacebookRestClientException($batch_item_result['error_msg'], $batch_item_result['error_code']);
169 }
170 $batch_item['r'] = $batch_item_result;
171 }
172 }
173
174 public function begin_permissions_mode($permissions_apikey) {
175 $this->call_as_apikey = $permissions_apikey;
176 }
177
178 public function end_permissions_mode() {
179 $this->call_as_apikey = '';
180 }
181
182 /**
183 * Returns the session information available after current user logs in.
184 * @param string $auth_token the token returned by auth_createToken or
185 * passed back to your callback_url.
186 * @param bool $generate_session_secret whether the session returned should include a session secret
187 *
188 * @return assoc array containing session_key, uid
189 */
190 public function auth_getSession($auth_token, $generate_session_secret=false) {
191 //Check if we are in batch mode
192 if($this->batch_queue === null) {
193 $result = $this->call_method('facebook.auth.getSession',
194 array('auth_token' => $auth_token, 'generate_session_secret' => $generate_session_secret));
195 $this->session_key = $result['session_key'];
196
197 if (!empty($result['secret']) && !$generate_session_secret) {
198 // desktop apps have a special secret
199 $this->secret = $result['secret'];
200 }
201 return $result;
202 }
203 }
204
205 /**
206 * Generates a session specific secret. This is for integration with client-side API calls, such as the
207 * JS library.
208 * @error API_EC_PARAM_SESSION_KEY
209 * API_EC_PARAM_UNKNOWN
210 * @return session secret for the current promoted session
211 */
212 public function auth_promoteSession() {
213 return $this->call_method('facebook.auth.promoteSession', array());
214 }
215
216 /**
217 * Expires the session that is currently being used. If this call is successful, no further calls to the
218 * API (which require a session) can be made until a valid session is created.
219 *
220 * @return bool true if session expiration was successful, false otherwise
221 */
222 public function auth_expireSession() {
223 return $this->call_method('facebook.auth.expireSession', array());
224 }
225
226 /**
227 * Revokes the user's agreement to the Facebook Terms of Service for your application. If you call this
228 * method for one of your users, you will no longer be able to make API requests on their behalf until
229 * they again authorize your application. Use with care.
230 *
231 * @return bool true if revocation succeeds, false otherwise
232 */
233 public function auth_revokeAuthorization() {
234 return $this->call_method('facebook.auth.revokeAuthorization', array());
235 }
236
237 /**
238 * This method is used to create an association between an external user
239 * account and a Facebook user account, as per Facebook Connect.
240 *
241 * This method takes an array of account data, including a required email_hash and
242 * optional account data. For each connected account, if the user exists,
243 * the information is added to the set of the user's connected accounts.
244 * If the user has already authorized the site, the connected account is added
245 * in the confirmed state. If the user has not yet authorized the site, the
246 * connected account is added in the pending state.
247 *
248 * This is designed to help Facebook Connect
249 * recognize when two Facebook friends are both members of
250 * a external site, but perhaps are not aware of it. The Connect dialog(see
251 * fb:connect-form) is used when friends can be identified through these email
252 * hashes. See http://wiki.developers.facebook.com/index.php/Connect.registerUsers
253 * for further details.
254 *
255 * @param mixed $accounts A (JSON-encoded) array of arrays, where each array
256 * has three properties:
257 * 'email_hash' (req) - public email hash of account
258 * 'account_id' (opt) - remote account id;
259 * 'account_url' (opt) - url to remote account;
260 *
261 * @return array The list of email hashes for the successfully registered
262 * accounts.
263 *
264 */
265 public function connect_registerUsers($accounts) {
266 return $this->call_method('facebook.connect.registerUsers',
267 array('accounts' => $accounts));
268 }
269
270 /**
271 * Unregisters a set of accounts registered using connect.registerUsers.
272 *
273 * @param array $email_hashes The (JSON-encoded) list of email hashes to be
274 * unregistered.
275 * @return array The list of email hashes which have been successfully
276 * unregistered.
277 */
278 public function connect_unregisterUsers($email_hashes) {
279 return $this->call_method('facebook.connect.unregisterUsers',
280 array('email_hashes' => $email_hashes));
281 }
282
283 /**
284 * Returns events according to the filters specified.
285 * @param int $uid Optional: User associated with events.
286 * A null parameter will default to the session user.
287 * @param array $eids Optional: Filter by these event ids.
288 * A null parameter will get all events for the user.
289 * @param int $start_time Optional: Filter with this unix time as lower bound.
290 * A null or zero parameter indicates no lower bound.
291 * @param int $end_time Optional: Filter with this UTC as upper bound.
292 * A null or zero parameter indicates no upper bound.
293 * @param string $rsvp_status Optional: Only show events where the given uid
294 * has this rsvp status. This only works if you have specified a value for
295 * $uid. Values are as in events.getMembers. Null indicates to ignore
296 * rsvp status when filtering.
297 * @return array of events
298 */
299 public function &events_get($uid=null, $eids=null, $start_time=null, $end_time=null, $rsvp_status=null) {
300 return $this->call_method('facebook.events.get',
301 array(
302 'uid' => $uid,
303 'eids' => $eids,
304 'start_time' => $start_time,
305 'end_time' => $end_time,
306 'rsvp_status' => $rsvp_status));
307 }
308
309 /**
310 * Returns membership list data associated with an event
311 * @param int $eid : event id
312 * @return assoc array of four membership lists, with keys 'attending',
313 * 'unsure', 'declined', and 'not_replied'
314 */
315 public function &events_getMembers($eid) {
316 return $this->call_method('facebook.events.getMembers',
317 array('eid' => $eid));
318 }
319
320 /**
321 * RSVPs the current user
322 * @param int $eid : event id
323 * @param string $rsvp_status : 'attending', 'unsure', or 'declined'
324 * @return bool true if successful
325 */
326 public function &events_rsvp($eid, $rsvp_status) {
327 return $this->call_method('facebook.events.rsvp',
328 array(
329 'eid' => $eid,
330 'rsvp_status' => $rsvp_status));
331 }
332
333 /**
334 * Cancels an event. Only works for events application is admin of.
335 * @param int $eid : event id
336 * @param string $cancel_message : (optional) message to send to members of the event about why it is cancelled
337 * @return bool true if successful
338 */
339 public function &events_cancel($eid, $cancel_message) {
340 return $this->call_method('facebook.events.cancel',
341 array(
342 'eid' => $eid,
343 'cancel_message' => $cancel_message));
344 }
345
346 /**
347 * Creates an event on behalf of the user is there is a session, otherwise on behalf of app.
348 * Successful creation guarantees app will be admin.
349 * @param assoc array $event_info : json encoded event information
350 * @return int event id
351 */
352 public function &events_create($event_info) {
353 return $this->call_method('facebook.events.create',
354 array('event_info' => $event_info));
355 }
356
357 /**
358 * Edits an existing event. Only works for events application is admin of.
359 * @param int $eid : event id
360 * @param assoc array $event_info : json encoded event information
361 * @return bool true if successful
362 */
363 public function &events_edit($eid, $event_info) {
364 return $this->call_method('facebook.events.edit',
365 array(
366 'eid' => $eid,
367 'event_info' => $event_info));
368 }
369
370 /**
371 * Makes an FQL query. This is a generalized way of accessing all the data
372 * in the API, as an alternative to most of the other method calls. More
373 * info at http://developers.facebook.com/documentation.php?v=1.0&doc=fql
374 * @param string $query the query to evaluate
375 * @return generalized array representing the results
376 */
377 public function &fql_query($query) {
378 return $this->call_method('facebook.fql.query',
379 array('query' => $query));
380 }
381
382 public function &feed_publishStoryToUser($title, $body,
383 $image_1=null, $image_1_link=null,
384 $image_2=null, $image_2_link=null,
385 $image_3=null, $image_3_link=null,
386 $image_4=null, $image_4_link=null) {
387 return $this->call_method('facebook.feed.publishStoryToUser',
388 array('title' => $title,
389 'body' => $body,
390 'image_1' => $image_1,
391 'image_1_link' => $image_1_link,
392 'image_2' => $image_2,
393 'image_2_link' => $image_2_link,
394 'image_3' => $image_3,
395 'image_3_link' => $image_3_link,
396 'image_4' => $image_4,
397 'image_4_link' => $image_4_link));
398 }
399
400 public function &feed_publishActionOfUser($title, $body,
401 $image_1=null, $image_1_link=null,
402 $image_2=null, $image_2_link=null,
403 $image_3=null, $image_3_link=null,
404 $image_4=null, $image_4_link=null) {
405 return $this->call_method('facebook.feed.publishActionOfUser',
406 array('title' => $title,
407 'body' => $body,
408 'image_1' => $image_1,
409 'image_1_link' => $image_1_link,
410 'image_2' => $image_2,
411 'image_2_link' => $image_2_link,
412 'image_3' => $image_3,
413 'image_3_link' => $image_3_link,
414 'image_4' => $image_4,
415 'image_4_link' => $image_4_link));
416 }
417
418 public function &feed_publishTemplatizedAction($title_template, $title_data,
419 $body_template, $body_data, $body_general,
420 $image_1=null, $image_1_link=null,
421 $image_2=null, $image_2_link=null,
422 $image_3=null, $image_3_link=null,
423 $image_4=null, $image_4_link=null,
424 $target_ids='', $page_actor_id=null) {
425 return $this->call_method('facebook.feed.publishTemplatizedAction',
426 array('title_template' => $title_template,
427 'title_data' => $title_data,
428 'body_template' => $body_template,
429 'body_data' => $body_data,
430 'body_general' => $body_general,
431 'image_1' => $image_1,
432 'image_1_link' => $image_1_link,
433 'image_2' => $image_2,
434 'image_2_link' => $image_2_link,
435 'image_3' => $image_3,
436 'image_3_link' => $image_3_link,
437 'image_4' => $image_4,
438 'image_4_link' => $image_4_link,
439 'target_ids' => $target_ids,
440 'page_actor_id' => $page_actor_id));
441 }
442
443 public function &feed_registerTemplateBundle($one_line_story_templates,
444 $short_story_templates = array(),
445 $full_story_template = null,
446 $action_links = array()) {
447
448 $one_line_story_templates = json_encode($one_line_story_templates);
449
450 if (!empty($short_story_templates)) {
451 $short_story_templates = json_encode($short_story_templates);
452 }
453
454 if (isset($full_story_template)) {
455 $full_story_template = json_encode($full_story_template);
456 }
457
458 if (isset($action_links)) {
459 $action_links = json_encode($action_links);
460 }
461
462 return $this->call_method('facebook.feed.registerTemplateBundle',
463 array('one_line_story_templates' => $one_line_story_templates,
464 'short_story_templates' => $short_story_templates,
465 'full_story_template' => $full_story_template,
466 'action_links' => $action_links));
467 }
468
469 public function &feed_getRegisteredTemplateBundles() {
470 return $this->call_method('facebook.feed.getRegisteredTemplateBundles', array());
471 }
472
473 public function &feed_getRegisteredTemplateBundleByID($template_bundle_id) {
474 return $this->call_method('facebook.feed.getRegisteredTemplateBundleByID',
475 array('template_bundle_id' => $template_bundle_id));
476 }
477
478 public function &feed_deactivateTemplateBundleByID($template_bundle_id) {
479 return $this->call_method('facebook.feed.deactivateTemplateBundleByID',
480 array('template_bundle_id' => $template_bundle_id));
481 }
482
483 const STORY_SIZE_ONE_LINE = 1;
484 const STORY_SIZE_SHORT = 2;
485 const STORY_SIZE_FULL = 4;
486 public function &feed_publishUserAction($template_bundle_id, $template_data,
487 $target_ids='', $body_general='',
488 $story_size = FacebookRestClient::STORY_SIZE_ONE_LINE) {
489 if (is_array($template_data)) {
490 $template_data = json_encode($template_data);
491 } // allow client to either pass in JSON or an assoc that we JSON for them
492
493 if (is_array($target_ids)) {
494 $target_ids = json_encode($target_ids);
495 $target_ids = trim($target_ids, "[]"); // we don't want the square bracket delims
496 }
497
498 return $this->call_method('facebook.feed.publishUserAction',
499 array('template_bundle_id' => $template_bundle_id,
500 'template_data' => $template_data,
501 'target_ids' => $target_ids,
502 'body_general' => $body_general,
503 'story_size' => $story_size));
504 }
505
506 /**
507 * Returns whether or not pairs of users are friends.
508 * Note that the Facebook friend relationship is symmetric.
509 * @param array $uids1: array of ids (id_1, id_2,...) of some length X
510 * @param array $uids2: array of ids (id_A, id_B,...) of SAME length X
511 * @return array of uid pairs with bool, true if pair are friends, e.g.
512 * array( 0 => array('uid1' => id_1, 'uid2' => id_A, 'are_friends' => 1),
513 * 1 => array('uid1' => id_2, 'uid2' => id_B, 'are_friends' => 0)
514 * ...)
515 */
516 public function &friends_areFriends($uids1, $uids2) {
517 return $this->call_method('facebook.friends.areFriends',
518 array('uids1'=>$uids1, 'uids2'=>$uids2));
519 }
520
521 /**
522 * Returns the friends of the current session user.
523 * @return array of friends
524 */
525 public function &friends_get() {
526 if (isset($this->friends_list)) {
527 return $this->friends_list;
528 }
529 $params = array();
530 if (isset($this->canvas_user)) {
531 $params['uid'] = $this->canvas_user;
532 }
533 return $this->call_method('facebook.friends.get', $params);
534
535 }
536
537 /**
538 * Returns the friends of the session user, who are also users
539 * of the calling application.
540 * @return array of friends
541 */
542 public function &friends_getAppUsers() {
543 return $this->call_method('facebook.friends.getAppUsers', array());
544 }
545
546 /**
547 * Returns groups according to the filters specified.
548 * @param int $uid Optional: User associated with groups.
549 * A null parameter will default to the session user.
550 * @param array $gids Optional: group ids to query.
551 * A null parameter will get all groups for the user.
552 * @return array of groups
553 */
554 public function &groups_get($uid, $gids) {
555 return $this->call_method('facebook.groups.get',
556 array(
557 'uid' => $uid,
558 'gids' => $gids));
559 }
560
561 /**
562 * Returns the membership list of a group
563 * @param int $gid : Group id
564 * @return assoc array of four membership lists, with keys
565 * 'members', 'admins', 'officers', and 'not_replied'
566 */
567 public function &groups_getMembers($gid) {
568 return $this->call_method('facebook.groups.getMembers',
569 array('gid' => $gid));
570 }
571
572 /**
573 * Returns cookies according to the filters specified.
574 * @param int $uid Required: User for which the cookies are needed.
575 * @param string $name Optional:
576 * A null parameter will get all cookies for the user.
577 * @return array of cookies
578 */
579 public function data_getCookies($uid, $name) {
580 return $this->call_method('facebook.data.getCookies',
581 array(
582 'uid' => $uid,
583 'name' => $name));
584 }
585
586 /**
587 * Sets cookies according to the params specified.
588 * @param int $uid Required: User for which the cookies are needed.
589 * @param string $name Required: name of the cookie
590 * @param string $value Optional if expires specified and is in the past
591 * @param int$expires Optional
592 * @param string $path Optional
593 *
594 * @return bool
595 */
596 public function data_setCookie($uid, $name, $value, $expires, $path) {
597 return $this->call_method('facebook.data.setCookie',
598 array(
599 'uid' => $uid,
600 'name' => $name,
601 'value' => $value,
602 'expires' => $expires,
603 'path' => $path));
604 }
605
606 /**
607 * Permissions API
608 */
609
610 /**
611 * Checks API-access granted by self to the specified application
612 * @param string $permissions_apikey: Required
613 *
614 * @return array: API methods/namespaces which are allowed access
615 */
616 public function permissions_checkGrantedApiAccess($permissions_apikey) {
617 return $this->call_method('facebook.permissions.checkGrantedApiAccess',
618 array(
619 'permissions_apikey' => $permissions_apikey));
620 }
621
622 /**
623 * Checks API-access granted to self by the specified application
624 * @param string $permissions_apikey: Required
625 *
626 * @return array: API methods/namespaces which are allowed access
627 */
628 public function permissions_checkAvailableApiAccess($permissions_apikey) {
629 return $this->call_method('facebook.permissions.checkAvailableApiAccess',
630 array(
631 'permissions_apikey' => $permissions_apikey));
632 }
633
634 /**
635 * Grant API-access to the specified methods/namespaces to the specified application
636 * @param string $permissions_apikey: Required
637 * @param array(string) : Optional: API methods/namespaces to be allowed
638 *
639 * @return array: API methods/namespaces which are allowed access
640 */
641 public function permissions_grantApiAccess($permissions_apikey, $method_arr) {
642 return $this->call_method('facebook.permissions.grantApiAccess',
643 array(
644 'permissions_apikey' => $permissions_apikey,
645 'method_arr' => $method_arr));
646 }
647
648 /**
649 * Revoke API-access granted to the specified application
650 * @param string $permissions_apikey: Required
651 *
652 * @return bool
653 */
654 public function permissions_revokeApiAccess($permissions_apikey) {
655 return $this->call_method('facebook.permissions.revokeApiAccess',
656 array(
657 'permissions_apikey' => $permissions_apikey));
658 }
659
660 /**
661 * Returns the outstanding notifications for the session user.
662 * @return assoc array of
663 * notification count objects for 'messages', 'pokes' and 'shares',
664 * a uid list of 'friend_requests', a gid list of 'group_invites',
665 * and an eid list of 'event_invites'
666 */
667 public function &notifications_get() {
668 return $this->call_method('facebook.notifications.get', array());
669 }
670
671 /**
672 * Sends a notification to the specified users.
673 * @return (nothing)
674 */
675 public function &notifications_send($to_ids, $notification, $type) {
676 return $this->call_method('facebook.notifications.send',
677 array('to_ids' => $to_ids, 'notification' => $notification, 'type' => $type));
678 }
679
680 /**
681 * Sends an email to the specified user of the application.
682 * @param array $recipients : id of the recipients
683 * @param string $subject : subject of the email
684 * @param string $text : (plain text) body of the email
685 * @param string $fbml : fbml markup if you want an html version of the email
686 * @return comma separated list of successful recipients
687 */
688 public function &notifications_sendEmail($recipients, $subject, $text, $fbml) {
689 return $this->call_method('facebook.notifications.sendEmail',
690 array('recipients' => $recipients,
691 'subject' => $subject,
692 'text' => $text,
693 'fbml' => $fbml));
694 }
695
696 /**
697 * Returns the requested info fields for the requested set of pages
698 * @param array $page_ids an array of page ids
699 * @param array $fields an array of strings describing the info fields desired
700 * @param int $uid Optionally, limit results to pages of which this user is a fan.
701 * @param string type limits results to a particular type of page.
702 * @return array of pages
703 */
704 public function &pages_getInfo($page_ids, $fields, $uid, $type) {
705 return $this->call_method('facebook.pages.getInfo', array('page_ids' => $page_ids, 'fields' => $fields, 'uid' => $uid, 'type' => $type));
706 }
707
708 /**
709 * Returns true if logged in user is an admin for the passed page
710 * @param int $page_id target page id
711 * @return boolean
712 */
713 public function &pages_isAdmin($page_id) {
714 return $this->call_method('facebook.pages.isAdmin', array('page_id' => $page_id));
715 }
716
717 /**
718 * Returns whether or not the page corresponding to the current session object has the app installed
719 * @return boolean
720 */
721 public function &pages_isAppAdded() {
722 if (isset($this->added)) {
723 return $this->added;
724 }
725 return $this->call_method('facebook.pages.isAppAdded', array());
726 }
727
728 /**
729 * Returns true if logged in user is a fan for the passed page
730 * @param int $page_id target page id
731 * @param int $uid user to compare. If empty, the logged in user.
732 * @return bool
733 */
734 public function &pages_isFan($page_id, $uid) {
735 return $this->call_method('facebook.pages.isFan', array('page_id' => $page_id, 'uid' => $uid));
736 }
737
738 /**
739 * Returns photos according to the filters specified.
740 * @param int $subj_id Optional: Filter by uid of user tagged in the photos.
741 * @param int $aid Optional: Filter by an album, as returned by
742 * photos_getAlbums.
743 * @param array $pids Optional: Restrict to a list of pids
744 * Note that at least one of these parameters needs to be specified, or an
745 * error is returned.
746 * @return array of photo objects.
747 */
748 public function &photos_get($subj_id, $aid, $pids) {
749 return $this->call_method('facebook.photos.get',
750 array('subj_id' => $subj_id, 'aid' => $aid, 'pids' => $pids));
751 }
752
753 /**
754 * Returns the albums created by the given user.
755 * @param int $uid Optional: the uid of the user whose albums you want.
756 * A null value will return the albums of the session user.
757 * @param array $aids Optional: a list of aids to restrict the query.
758 * Note that at least one of the (uid, aids) parameters must be specified.
759 * @returns an array of album objects.
760 */
761 public function &photos_getAlbums($uid, $aids) {
762 return $this->call_method('facebook.photos.getAlbums',
763 array('uid' => $uid,
764 'aids' => $aids));
765 }
766
767 /**
768 * Returns the tags on all photos specified.
769 * @param string $pids : a list of pids to query
770 * @return array of photo tag objects, with include pid, subject uid,
771 * and two floating-point numbers (xcoord, ycoord) for tag pixel location
772 */
773 public function &photos_getTags($pids) {
774 return $this->call_method('facebook.photos.getTags',
775 array('pids' => $pids));
776 }
777
778
779 /**
780 * Returns the requested info fields for the requested set of users
781 * @param array $uids an array of user ids
782 * @param array $fields an array of strings describing the info fields desired
783 * @return array of users
784 */
785 public function &users_getInfo($uids, $fields) {
786 return $this->call_method('facebook.users.getInfo', array('uids' => $uids, 'fields' => $fields));
787 }
788
789 /**
790 * Returns the requested info fields for the requested set of users. No
791 * session key is required. Only data about users that have authorized
792 * your application will be returned.
793 *
794 * Check the wiki for fields that can be queried through this API call.
795 * Data returned from here should not be used for rendering to application
796 * users, use users.getInfo instead, so that proper privacy rules will be
797 * applied.
798 * @param array $uids an array of user ids
799 * @param array $fields an array of strings describing the info fields desired
800 * @return array of users
801 */
802 public function &users_getStandardInfo($uids, $fields) {
803 return $this->call_method('facebook.users.getStandardInfo', array('uids' => $uids, 'fields' => $fields));
804 }
805
806 /**
807 * Returns the user corresponding to the current session object.
808 * @return integer uid
809 */
810 public function &users_getLoggedInUser() {
811 return $this->call_method('facebook.users.getLoggedInUser', array());
812 }
813
814 /**
815 * Returns whether or not the user corresponding to the current session object has the give the app basic
816 * authorization.
817 * @return boolean
818 */
819 public function &users_isAppUser($uid=null) {
820 if (isset($this->is_user)) {
821 return $this->is_user;
822 }
823
824 return $this->call_method('facebook.users.isAppUser', array('uid' => $uid));
825 }
826
827 /**
828 * Returns whether or not the user corresponding to the current session object has the app installed
829 * @return boolean
830 */
831 public function &users_isAppAdded($uid=null) {
832 if (isset($this->added)) {
833 return $this->added;
834 }
835 return $this->call_method('facebook.users.isAppAdded', array('uid' => $uid));
836 }
837
838 /**
839 * Sets the FBML for the profile of the user attached to this session
840 * @param string $markup The FBML that describes the profile presence of this app for the user
841 * @param int $uid The user
842 * @param string $profile Profile FBML
843 * @param string $profile_action Profile action FBML (deprecated)
844 * @param string $mobile_profile Mobile profile FBML
845 * @param string $profile_main Main Tab profile FBML
846 * @return array A list of strings describing any compile errors for the submitted FBML
847 */
848 function profile_setFBML($markup, $uid = null, $profile='', $profile_action='', $mobile_profile='', $profile_main='') {
849 return $this->call_method('facebook.profile.setFBML', array('markup' => $markup,
850 'uid' => $uid,
851 'profile' => $profile,
852 'profile_action' => $profile_action,
853 'mobile_profile' => $mobile_profile,
854 'profile_main' => $profile_main));
855 }
856
857 public function &profile_getFBML($uid, $type=null) {
858 return $this->call_method('facebook.profile.getFBML', array('uid' => $uid,
859 'type' => $type));
860 }
861
862 public function &profile_getInfo($uid=null) {
863 return $this->call_method('facebook.profile.getInfo', array('uid' => $uid));
864 }
865
866 public function &profile_getInfoOptions($field) {
867 return $this->call_method('facebook.profile.getInfoOptions',
868 array('field' => $field));
869 }
870
871 public function profile_setInfoOptions($options, $field) {
872 return $this->call_method('facebook.profile.setInfoOptions',
873 array('options' => json_encode($options),
874 'field' => $field));
875 }
876
877 public function &profile_setInfo($title, $type, $info_fields, $uid=null) {
878 return $this->call_method('facebook.profile.setInfo',
879 array('uid' => $uid,
880 'type' => $type,
881 'title' => $title,
882 'info_fields' => json_encode($info_fields)));
883 }
884
885 public function &profile_addInfoItems($info_items, $uid=null) {
886 return $this->call_method('facebook.profile.addInfoItems',
887 array('uid' => $uid,
888 'info_items' => json_encode($info_items)));
889 }
890
891 public function &profile_removeInfoItems($info_labels, $uid=null) {
892 return $this->call_method('facebook.profile.removeInfoItems',
893 array('uid' => $uid,
894 'info_labels' => json_encode($info_labels)));
895 }
896
897
898 public function &fbml_refreshImgSrc($url) {
899 return $this->call_method('facebook.fbml.refreshImgSrc', array('url' => $url));
900 }
901
902 public function &fbml_refreshRefUrl($url) {
903 return $this->call_method('facebook.fbml.refreshRefUrl', array('url' => $url));
904 }
905
906 public function &fbml_setRefHandle($handle, $fbml) {
907 return $this->call_method('facebook.fbml.setRefHandle', array('handle' => $handle, 'fbml' => $fbml));
908 }
909
910 /**
911 * Get all the marketplace categories
912 *
913 * @return array A list of category names
914 */
915 function marketplace_getCategories() {
916 return $this->call_method('facebook.marketplace.getCategories', array());
917 }
918
919 /**
920 * Get all the marketplace subcategories for a particular category
921 *
922 * @param category The category for which we are pulling subcategories
923 * @return array A list of subcategory names
924 */
925 function marketplace_getSubCategories($category) {
926 return $this->call_method('facebook.marketplace.getSubCategories', array('category' => $category));
927 }
928
929 /**
930 * Get listings by either listing_id or user
931 *
932 * @param listing_ids An array of listing_ids (optional)
933 * @param uids An array of user ids (optional)
934 * @return array The data for matched listings
935 */
936 function marketplace_getListings($listing_ids, $uids) {
937 return $this->call_method('facebook.marketplace.getListings', array('listing_ids' => $listing_ids, 'uids' => $uids));
938 }
939
940 /**
941 * Search for Marketplace listings. All arguments are optional, though at least
942 * one must be filled out to retrieve results.
943 *
944 * @param category The category in which to search (optional)
945 * @param subcategory The subcategory in which to search (optional)
946 * @param query A query string (optional)
947 * @return array The data for matched listings
948 */
949 function marketplace_search($category, $subcategory, $query) {
950 return $this->call_method('facebook.marketplace.search', array('category' => $category, 'subcategory' => $subcategory, 'query' => $query));
951 }
952
953 /**
954 * Remove a listing from Marketplace
955 *
956 * @param listing_id The id of the listing to be removed
957 * @param status 'SUCCESS', 'NOT_SUCCESS', or 'DEFAULT'
958 * @return bool True on success
959 */
960 function marketplace_removeListing($listing_id, $status='DEFAULT', $uid=null) {
961 return $this->call_method('facebook.marketplace.removeListing',
962 array('listing_id'=>$listing_id,
963 'status'=>$status,
964 'uid' => $uid));
965 }
966
967 /**
968 * Create/modify a Marketplace listing for the loggedinuser
969 *
970 * @param int listing_id The id of a listing to be modified, 0 for a new listing.
971 * @param show_on_profile bool Should we show this listing on the user's profile
972 * @param listing_attrs array An array of the listing data
973 * @return int The listing_id (unchanged if modifying an existing listing)
974 */
975 function marketplace_createListing($listing_id, $show_on_profile, $attrs, $uid=null) {
976 return $this->call_method('facebook.marketplace.createListing',
977 array('listing_id'=>$listing_id,
978 'show_on_profile'=>$show_on_profile,
979 'listing_attrs'=>json_encode($attrs),
980 'uid' => $uid));
981 }
982
983
984 /////////////////////////////////////////////////////////////////////////////
985 // Data Store API
986
987 /**
988 * Set a user preference.
989 *
990 * @param pref_id preference identifier (0-200)
991 * @param value preferece's value
992 * @error
993 * API_EC_DATA_DATABASE_ERROR
994 * API_EC_PARAM
995 * API_EC_DATA_QUOTA_EXCEEDED
996 * API_EC_DATA_UNKNOWN_ERROR
997 */
998 public function &data_setUserPreference($pref_id, $value) {
999 return $this->call_method
1000 ('facebook.data.setUserPreference',
1001 array('pref_id' => $pref_id,
1002 'value' => $value));
1003 }
1004
1005 /**
1006 * Set a user's all preferences for this application.
1007 *
1008 * @param values preferece values in an associative arrays
1009 * @param replace whether to replace all existing preferences or
1010 * merge into them.
1011 * @error
1012 * API_EC_DATA_DATABASE_ERROR
1013 * API_EC_PARAM
1014 * API_EC_DATA_QUOTA_EXCEEDED
1015 * API_EC_DATA_UNKNOWN_ERROR
1016 */
1017 public function &data_setUserPreferences($values, $replace = false) {
1018 return $this->call_method
1019 ('facebook.data.setUserPreferences',
1020 array('values' => json_encode($values),
1021 'replace' => $replace));
1022 }
1023
1024 /**
1025 * Get a user preference.
1026 *
1027 * @param pref_id preference identifier (0-200)
1028 * @return preference's value
1029 * @error
1030 * API_EC_DATA_DATABASE_ERROR
1031 * API_EC_PARAM
1032 * API_EC_DATA_QUOTA_EXCEEDED
1033 * API_EC_DATA_UNKNOWN_ERROR
1034 */
1035 public function &data_getUserPreference($pref_id) {
1036 return $this->call_method
1037 ('facebook.data.getUserPreference',
1038 array('pref_id' => $pref_id));
1039 }
1040
1041 /**
1042 * Get a user preference.
1043 *
1044 * @return preference values
1045 * @error
1046 * API_EC_DATA_DATABASE_ERROR
1047 * API_EC_DATA_QUOTA_EXCEEDED
1048 * API_EC_DATA_UNKNOWN_ERROR
1049 */
1050 public function &data_getUserPreferences() {
1051 return $this->call_method
1052 ('facebook.data.getUserPreferences',
1053 array());
1054 }
1055
1056 /**
1057 * Create a new object type.
1058 *
1059 * @param name object type's name
1060 * @error
1061 * API_EC_DATA_DATABASE_ERROR
1062 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1063 * API_EC_PARAM
1064 * API_EC_PERMISSION
1065 * API_EC_DATA_INVALID_OPERATION
1066 * API_EC_DATA_QUOTA_EXCEEDED
1067 * API_EC_DATA_UNKNOWN_ERROR
1068 */
1069 public function &data_createObjectType($name) {
1070 return $this->call_method
1071 ('facebook.data.createObjectType',
1072 array('name' => $name));
1073 }
1074
1075 /**
1076 * Delete an object type.
1077 *
1078 * @param obj_type object type's name
1079 * @error
1080 * API_EC_DATA_DATABASE_ERROR
1081 * API_EC_DATA_OBJECT_NOT_FOUND
1082 * API_EC_PARAM
1083 * API_EC_PERMISSION
1084 * API_EC_DATA_INVALID_OPERATION
1085 * API_EC_DATA_QUOTA_EXCEEDED
1086 * API_EC_DATA_UNKNOWN_ERROR
1087 */
1088 public function &data_dropObjectType($obj_type) {
1089 return $this->call_method
1090 ('facebook.data.dropObjectType',
1091 array('obj_type' => $obj_type));
1092 }
1093
1094 /**
1095 * Rename an object type.
1096 *
1097 * @param obj_type object type's name
1098 * @param new_name new object type's name
1099 * @error
1100 * API_EC_DATA_DATABASE_ERROR
1101 * API_EC_DATA_OBJECT_NOT_FOUND
1102 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1103 * API_EC_PARAM
1104 * API_EC_PERMISSION
1105 * API_EC_DATA_INVALID_OPERATION
1106 * API_EC_DATA_QUOTA_EXCEEDED
1107 * API_EC_DATA_UNKNOWN_ERROR
1108 */
1109 public function &data_renameObjectType($obj_type, $new_name) {
1110 return $this->call_method
1111 ('facebook.data.renameObjectType',
1112 array('obj_type' => $obj_type,
1113 'new_name' => $new_name));
1114 }
1115
1116 /**
1117 * Add a new property to an object type.
1118 *
1119 * @param obj_type object type's name
1120 * @param prop_name name of the property to add
1121 * @param prop_type 1: integer; 2: string; 3: text blob
1122 * @error
1123 * API_EC_DATA_DATABASE_ERROR
1124 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1125 * API_EC_PARAM
1126 * API_EC_PERMISSION
1127 * API_EC_DATA_INVALID_OPERATION
1128 * API_EC_DATA_QUOTA_EXCEEDED
1129 * API_EC_DATA_UNKNOWN_ERROR
1130 */
1131 public function &data_defineObjectProperty($obj_type, $prop_name, $prop_type) {
1132 return $this->call_method
1133 ('facebook.data.defineObjectProperty',
1134 array('obj_type' => $obj_type,
1135 'prop_name' => $prop_name,
1136 'prop_type' => $prop_type));
1137 }
1138
1139 /**
1140 * Remove a previously defined property from an object type.
1141 *
1142 * @param obj_type object type's name
1143 * @param prop_name name of the property to remove
1144 * @error
1145 * API_EC_DATA_DATABASE_ERROR
1146 * API_EC_DATA_OBJECT_NOT_FOUND
1147 * API_EC_PARAM
1148 * API_EC_PERMISSION
1149 * API_EC_DATA_INVALID_OPERATION
1150 * API_EC_DATA_QUOTA_EXCEEDED
1151 * API_EC_DATA_UNKNOWN_ERROR
1152 */
1153 public function &data_undefineObjectProperty($obj_type, $prop_name) {
1154 return $this->call_method
1155 ('facebook.data.undefineObjectProperty',
1156 array('obj_type' => $obj_type,
1157 'prop_name' => $prop_name));
1158 }
1159
1160 /**
1161 * Rename a previously defined property of an object type.
1162 *
1163 * @param obj_type object type's name
1164 * @param prop_name name of the property to rename
1165 * @param new_name new name to use
1166 * @error
1167 * API_EC_DATA_DATABASE_ERROR
1168 * API_EC_DATA_OBJECT_NOT_FOUND
1169 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1170 * API_EC_PARAM
1171 * API_EC_PERMISSION
1172 * API_EC_DATA_INVALID_OPERATION
1173 * API_EC_DATA_QUOTA_EXCEEDED
1174 * API_EC_DATA_UNKNOWN_ERROR
1175 */
1176 public function &data_renameObjectProperty($obj_type, $prop_name,
1177 $new_name) {
1178 return $this->call_method
1179 ('facebook.data.renameObjectProperty',
1180 array('obj_type' => $obj_type,
1181 'prop_name' => $prop_name,
1182 'new_name' => $new_name));
1183 }
1184
1185 /**
1186 * Retrieve a list of all object types that have defined for the application.
1187 *
1188 * @return a list of object type names
1189 * @error
1190 * API_EC_DATA_DATABASE_ERROR
1191 * API_EC_PERMISSION
1192 * API_EC_DATA_QUOTA_EXCEEDED
1193 * API_EC_DATA_UNKNOWN_ERROR
1194 */
1195 public function &data_getObjectTypes() {
1196 return $this->call_method
1197 ('facebook.data.getObjectTypes',
1198 array());
1199 }
1200
1201 /**
1202 * Get definitions of all properties of an object type.
1203 *
1204 * @param obj_type object type's name
1205 * @return pairs of property name and property types
1206 * @error
1207 * API_EC_DATA_DATABASE_ERROR
1208 * API_EC_PARAM
1209 * API_EC_PERMISSION
1210 * API_EC_DATA_OBJECT_NOT_FOUND
1211 * API_EC_DATA_QUOTA_EXCEEDED
1212 * API_EC_DATA_UNKNOWN_ERROR
1213 */
1214 public function &data_getObjectType($obj_type) {
1215 return $this->call_method
1216 ('facebook.data.getObjectType',
1217 array('obj_type' => $obj_type));
1218 }
1219
1220 /**
1221 * Create a new object.
1222 *
1223 * @param obj_type object type's name
1224 * @param properties (optional) properties to set initially
1225 * @return newly created object's id
1226 * @error
1227 * API_EC_DATA_DATABASE_ERROR
1228 * API_EC_PARAM
1229 * API_EC_PERMISSION
1230 * API_EC_DATA_INVALID_OPERATION
1231 * API_EC_DATA_QUOTA_EXCEEDED
1232 * API_EC_DATA_UNKNOWN_ERROR
1233 */
1234 public function &data_createObject($obj_type, $properties = null) {
1235 return $this->call_method
1236 ('facebook.data.createObject',
1237 array('obj_type' => $obj_type,
1238 'properties' => json_encode($properties)));
1239 }
1240
1241 /**
1242 * Update an existing object.
1243 *
1244 * @param obj_id object's id
1245 * @param properties new properties
1246 * @param replace true for replacing existing properties; false for merging
1247 * @error
1248 * API_EC_DATA_DATABASE_ERROR
1249 * API_EC_DATA_OBJECT_NOT_FOUND
1250 * API_EC_PARAM
1251 * API_EC_PERMISSION
1252 * API_EC_DATA_INVALID_OPERATION
1253 * API_EC_DATA_QUOTA_EXCEEDED
1254 * API_EC_DATA_UNKNOWN_ERROR
1255 */
1256 public function &data_updateObject($obj_id, $properties, $replace = false) {
1257 return $this->call_method
1258 ('facebook.data.updateObject',
1259 array('obj_id' => $obj_id,
1260 'properties' => json_encode($properties),
1261 'replace' => $replace));
1262 }
1263
1264 /**
1265 * Delete an existing object.
1266 *
1267 * @param obj_id object's id
1268 * @error
1269 * API_EC_DATA_DATABASE_ERROR
1270 * API_EC_DATA_OBJECT_NOT_FOUND
1271 * API_EC_PARAM
1272 * API_EC_PERMISSION
1273 * API_EC_DATA_INVALID_OPERATION
1274 * API_EC_DATA_QUOTA_EXCEEDED
1275 * API_EC_DATA_UNKNOWN_ERROR
1276 */
1277 public function &data_deleteObject($obj_id) {
1278 return $this->call_method
1279 ('facebook.data.deleteObject',
1280 array('obj_id' => $obj_id));
1281 }
1282
1283 /**
1284 * Delete a list of objects.
1285 *
1286 * @param obj_ids objects to delete
1287 * @error
1288 * API_EC_DATA_DATABASE_ERROR
1289 * API_EC_PARAM
1290 * API_EC_PERMISSION
1291 * API_EC_DATA_INVALID_OPERATION
1292 * API_EC_DATA_QUOTA_EXCEEDED
1293 * API_EC_DATA_UNKNOWN_ERROR
1294 */
1295 public function &data_deleteObjects($obj_ids) {
1296 return $this->call_method
1297 ('facebook.data.deleteObjects',
1298 array('obj_ids' => json_encode($obj_ids)));
1299 }
1300
1301 /**
1302 * Get a single property value of an object.
1303 *
1304 * @param obj_id object's id
1305 * @param prop_name individual property's name
1306 * @return individual property's value
1307 * @error
1308 * API_EC_DATA_DATABASE_ERROR
1309 * API_EC_DATA_OBJECT_NOT_FOUND
1310 * API_EC_PARAM
1311 * API_EC_PERMISSION
1312 * API_EC_DATA_INVALID_OPERATION
1313 * API_EC_DATA_QUOTA_EXCEEDED
1314 * API_EC_DATA_UNKNOWN_ERROR
1315 */
1316 public function &data_getObjectProperty($obj_id, $prop_name) {
1317 return $this->call_method
1318 ('facebook.data.getObjectProperty',
1319 array('obj_id' => $obj_id,
1320 'prop_name' => $prop_name));
1321 }
1322
1323 /**
1324 * Get properties of an object.
1325 *
1326 * @param obj_id object's id
1327 * @param prop_names (optional) properties to return; null for all.
1328 * @return specified properties of an object
1329 * @error
1330 * API_EC_DATA_DATABASE_ERROR
1331 * API_EC_DATA_OBJECT_NOT_FOUND
1332 * API_EC_PARAM
1333 * API_EC_PERMISSION
1334 * API_EC_DATA_INVALID_OPERATION
1335 * API_EC_DATA_QUOTA_EXCEEDED
1336 * API_EC_DATA_UNKNOWN_ERROR
1337 */
1338 public function &data_getObject($obj_id, $prop_names = null) {
1339 return $this->call_method
1340 ('facebook.data.getObject',
1341 array('obj_id' => $obj_id,
1342 'prop_names' => json_encode($prop_names)));
1343 }
1344
1345 /**
1346 * Get properties of a list of objects.
1347 *
1348 * @param obj_ids object ids
1349 * @param prop_names (optional) properties to return; null for all.
1350 * @return specified properties of an object
1351 * @error
1352 * API_EC_DATA_DATABASE_ERROR
1353 * API_EC_DATA_OBJECT_NOT_FOUND
1354 * API_EC_PARAM
1355 * API_EC_PERMISSION
1356 * API_EC_DATA_INVALID_OPERATION
1357 * API_EC_DATA_QUOTA_EXCEEDED
1358 * API_EC_DATA_UNKNOWN_ERROR
1359 */
1360 public function &data_getObjects($obj_ids, $prop_names = null) {
1361 return $this->call_method
1362 ('facebook.data.getObjects',
1363 array('obj_ids' => json_encode($obj_ids),
1364 'prop_names' => json_encode($prop_names)));
1365 }
1366
1367 /**
1368 * Set a single property value of an object.
1369 *
1370 * @param obj_id object's id
1371 * @param prop_name individual property's name
1372 * @param prop_value new value to set
1373 * @error
1374 * API_EC_DATA_DATABASE_ERROR
1375 * API_EC_DATA_OBJECT_NOT_FOUND
1376 * API_EC_PARAM
1377 * API_EC_PERMISSION
1378 * API_EC_DATA_INVALID_OPERATION
1379 * API_EC_DATA_QUOTA_EXCEEDED
1380 * API_EC_DATA_UNKNOWN_ERROR
1381 */
1382 public function &data_setObjectProperty($obj_id, $prop_name,
1383 $prop_value) {
1384 return $this->call_method
1385 ('facebook.data.setObjectProperty',
1386 array('obj_id' => $obj_id,
1387 'prop_name' => $prop_name,
1388 'prop_value' => $prop_value));
1389 }
1390
1391 /**
1392 * Read hash value by key.
1393 *
1394 * @param obj_type object type's name
1395 * @param key hash key
1396 * @param prop_name (optional) individual property's name
1397 * @return hash value
1398 * @error
1399 * API_EC_DATA_DATABASE_ERROR
1400 * API_EC_PARAM
1401 * API_EC_PERMISSION
1402 * API_EC_DATA_INVALID_OPERATION
1403 * API_EC_DATA_QUOTA_EXCEEDED
1404 * API_EC_DATA_UNKNOWN_ERROR
1405 */
1406 public function &data_getHashValue($obj_type, $key, $prop_name = null) {
1407 return $this->call_method
1408 ('facebook.data.getHashValue',
1409 array('obj_type' => $obj_type,
1410 'key' => $key,
1411 'prop_name' => $prop_name));
1412 }
1413
1414 /**
1415 * Write hash value by key.
1416 *
1417 * @param obj_type object type's name
1418 * @param key hash key
1419 * @param value hash value
1420 * @param prop_name (optional) individual property's name
1421 * @error
1422 * API_EC_DATA_DATABASE_ERROR
1423 * API_EC_PARAM
1424 * API_EC_PERMISSION
1425 * API_EC_DATA_INVALID_OPERATION
1426 * API_EC_DATA_QUOTA_EXCEEDED
1427 * API_EC_DATA_UNKNOWN_ERROR
1428 */
1429 public function &data_setHashValue($obj_type, $key, $value, $prop_name = null) {
1430 return $this->call_method
1431 ('facebook.data.setHashValue',
1432 array('obj_type' => $obj_type,
1433 'key' => $key,
1434 'value' => $value,
1435 'prop_name' => $prop_name));
1436 }
1437
1438 /**
1439 * Increase a hash value by specified increment atomically.
1440 *
1441 * @param obj_type object type's name
1442 * @param key hash key
1443 * @param prop_name individual property's name
1444 * @param increment (optional) default is 1
1445 * @return incremented hash value
1446 * @error
1447 * API_EC_DATA_DATABASE_ERROR
1448 * API_EC_PARAM
1449 * API_EC_PERMISSION
1450 * API_EC_DATA_INVALID_OPERATION
1451 * API_EC_DATA_QUOTA_EXCEEDED
1452 * API_EC_DATA_UNKNOWN_ERROR
1453 */
1454 public function &data_incHashValue($obj_type, $key, $prop_name, $increment = 1) {
1455 return $this->call_method
1456 ('facebook.data.incHashValue',
1457 array('obj_type' => $obj_type,
1458 'key' => $key,
1459 'prop_name' => $prop_name,
1460 'increment' => $increment));
1461 }
1462
1463 /**
1464 * Remove a hash key and its values.
1465 *
1466 * @param obj_type object type's name
1467 * @param key hash key
1468 * @error
1469 * API_EC_DATA_DATABASE_ERROR
1470 * API_EC_PARAM
1471 * API_EC_PERMISSION
1472 * API_EC_DATA_INVALID_OPERATION
1473 * API_EC_DATA_QUOTA_EXCEEDED
1474 * API_EC_DATA_UNKNOWN_ERROR
1475 */
1476 public function &data_removeHashKey($obj_type, $key) {
1477 return $this->call_method
1478 ('facebook.data.removeHashKey',
1479 array('obj_type' => $obj_type,
1480 'key' => $key));
1481 }
1482
1483 /**
1484 * Remove hash keys and their values.
1485 *
1486 * @param obj_type object type's name
1487 * @param keys hash keys
1488 * @error
1489 * API_EC_DATA_DATABASE_ERROR
1490 * API_EC_PARAM
1491 * API_EC_PERMISSION
1492 * API_EC_DATA_INVALID_OPERATION
1493 * API_EC_DATA_QUOTA_EXCEEDED
1494 * API_EC_DATA_UNKNOWN_ERROR
1495 */
1496 public function &data_removeHashKeys($obj_type, $keys) {
1497 return $this->call_method
1498 ('facebook.data.removeHashKeys',
1499 array('obj_type' => $obj_type,
1500 'keys' => json_encode($keys)));
1501 }
1502
1503
1504 /**
1505 * Define an object association.
1506 *
1507 * @param name name of this association
1508 * @param assoc_type 1: one-way 2: two-way symmetric 3: two-way asymmetric
1509 * @param assoc_info1 needed info about first object type
1510 * @param assoc_info2 needed info about second object type
1511 * @param inverse (optional) name of reverse association
1512 * @error
1513 * API_EC_DATA_DATABASE_ERROR
1514 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1515 * API_EC_PARAM
1516 * API_EC_PERMISSION
1517 * API_EC_DATA_INVALID_OPERATION
1518 * API_EC_DATA_QUOTA_EXCEEDED
1519 * API_EC_DATA_UNKNOWN_ERROR
1520 */
1521 public function &data_defineAssociation($name, $assoc_type, $assoc_info1,
1522 $assoc_info2, $inverse = null) {
1523 return $this->call_method
1524 ('facebook.data.defineAssociation',
1525 array('name' => $name,
1526 'assoc_type' => $assoc_type,
1527 'assoc_info1' => json_encode($assoc_info1),
1528 'assoc_info2' => json_encode($assoc_info2),
1529 'inverse' => $inverse));
1530 }
1531
1532 /**
1533 * Undefine an object association.
1534 *
1535 * @param name name of this association
1536 * @error
1537 * API_EC_DATA_DATABASE_ERROR
1538 * API_EC_DATA_OBJECT_NOT_FOUND
1539 * API_EC_PARAM
1540 * API_EC_PERMISSION
1541 * API_EC_DATA_INVALID_OPERATION
1542 * API_EC_DATA_QUOTA_EXCEEDED
1543 * API_EC_DATA_UNKNOWN_ERROR
1544 */
1545 public function &data_undefineAssociation($name) {
1546 return $this->call_method
1547 ('facebook.data.undefineAssociation',
1548 array('name' => $name));
1549 }
1550
1551 /**
1552 * Rename an object association or aliases.
1553 *
1554 * @param name name of this association
1555 * @param new_name (optional) new name of this association
1556 * @param new_alias1 (optional) new alias for object type 1
1557 * @param new_alias2 (optional) new alias for object type 2
1558 * @error
1559 * API_EC_DATA_DATABASE_ERROR
1560 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1561 * API_EC_DATA_OBJECT_NOT_FOUND
1562 * API_EC_PARAM
1563 * API_EC_PERMISSION
1564 * API_EC_DATA_INVALID_OPERATION
1565 * API_EC_DATA_QUOTA_EXCEEDED
1566 * API_EC_DATA_UNKNOWN_ERROR
1567 */
1568 public function &data_renameAssociation($name, $new_name, $new_alias1 = null,
1569 $new_alias2 = null) {
1570 return $this->call_method
1571 ('facebook.data.renameAssociation',
1572 array('name' => $name,
1573 'new_name' => $new_name,
1574 'new_alias1' => $new_alias1,
1575 'new_alias2' => $new_alias2));
1576 }
1577
1578 /**
1579 * Get definition of an object association.
1580 *
1581 * @param name name of this association
1582 * @return specified association
1583 * @error
1584 * API_EC_DATA_DATABASE_ERROR
1585 * API_EC_DATA_OBJECT_NOT_FOUND
1586 * API_EC_PARAM
1587 * API_EC_PERMISSION
1588 * API_EC_DATA_QUOTA_EXCEEDED
1589 * API_EC_DATA_UNKNOWN_ERROR
1590 */
1591 public function &data_getAssociationDefinition($name) {
1592 return $this->call_method
1593 ('facebook.data.getAssociationDefinition',
1594 array('name' => $name));
1595 }
1596
1597 /**
1598 * Get definition of all associations.
1599 *
1600 * @return all defined associations
1601 * @error
1602 * API_EC_DATA_DATABASE_ERROR
1603 * API_EC_PERMISSION
1604 * API_EC_DATA_QUOTA_EXCEEDED
1605 * API_EC_DATA_UNKNOWN_ERROR
1606 */
1607 public function &data_getAssociationDefinitions() {
1608 return $this->call_method
1609 ('facebook.data.getAssociationDefinitions',
1610 array());
1611 }
1612
1613 /**
1614 * Create or modify an association between two objects.
1615 *
1616 * @param name name of association
1617 * @param obj_id1 id of first object
1618 * @param obj_id2 id of second object
1619 * @param data (optional) extra string data to store
1620 * @param assoc_time (optional) extra time data; default to creation time
1621 * @error
1622 * API_EC_DATA_DATABASE_ERROR
1623 * API_EC_PARAM
1624 * API_EC_PERMISSION
1625 * API_EC_DATA_INVALID_OPERATION
1626 * API_EC_DATA_QUOTA_EXCEEDED
1627 * API_EC_DATA_UNKNOWN_ERROR
1628 */
1629 public function &data_setAssociation($name, $obj_id1, $obj_id2, $data = null,
1630 $assoc_time = null) {
1631 return $this->call_method
1632 ('facebook.data.setAssociation',
1633 array('name' => $name,
1634 'obj_id1' => $obj_id1,
1635 'obj_id2' => $obj_id2,
1636 'data' => $data,
1637 'assoc_time' => $assoc_time));
1638 }
1639
1640 /**
1641 * Create or modify associations between objects.
1642 *
1643 * @param assocs associations to set
1644 * @param name (optional) name of association
1645 * @error
1646 * API_EC_DATA_DATABASE_ERROR
1647 * API_EC_PARAM
1648 * API_EC_PERMISSION
1649 * API_EC_DATA_INVALID_OPERATION
1650 * API_EC_DATA_QUOTA_EXCEEDED
1651 * API_EC_DATA_UNKNOWN_ERROR
1652 */
1653 public function &data_setAssociations($assocs, $name = null) {
1654 return $this->call_method
1655 ('facebook.data.setAssociations',
1656 array('assocs' => json_encode($assocs),
1657 'name' => $name));
1658 }
1659
1660 /**
1661 * Remove an association between two objects.
1662 *
1663 * @param name name of association
1664 * @param obj_id1 id of first object
1665 * @param obj_id2 id of second object
1666 * @error
1667 * API_EC_DATA_DATABASE_ERROR
1668 * API_EC_DATA_OBJECT_NOT_FOUND
1669 * API_EC_PARAM
1670 * API_EC_PERMISSION
1671 * API_EC_DATA_QUOTA_EXCEEDED
1672 * API_EC_DATA_UNKNOWN_ERROR
1673 */
1674 public function &data_removeAssociation($name, $obj_id1, $obj_id2) {
1675 return $this->call_method
1676 ('facebook.data.removeAssociation',
1677 array('name' => $name,
1678 'obj_id1' => $obj_id1,
1679 'obj_id2' => $obj_id2));
1680 }
1681
1682 /**
1683 * Remove associations between objects by specifying pairs of object ids.
1684 *
1685 * @param assocs associations to remove
1686 * @param name (optional) name of association
1687 * @error
1688 * API_EC_DATA_DATABASE_ERROR
1689 * API_EC_DATA_OBJECT_NOT_FOUND
1690 * API_EC_PARAM
1691 * API_EC_PERMISSION
1692 * API_EC_DATA_QUOTA_EXCEEDED
1693 * API_EC_DATA_UNKNOWN_ERROR
1694 */
1695 public function &data_removeAssociations($assocs, $name = null) {
1696 return $this->call_method
1697 ('facebook.data.removeAssociations',
1698 array('assocs' => json_encode($assocs),
1699 'name' => $name));
1700 }
1701
1702 /**
1703 * Remove associations between objects by specifying one object id.
1704 *
1705 * @param name name of association
1706 * @param obj_id who's association to remove
1707 * @error
1708 * API_EC_DATA_DATABASE_ERROR
1709 * API_EC_DATA_OBJECT_NOT_FOUND
1710 * API_EC_PARAM
1711 * API_EC_PERMISSION
1712 * API_EC_DATA_INVALID_OPERATION
1713 * API_EC_DATA_QUOTA_EXCEEDED
1714 * API_EC_DATA_UNKNOWN_ERROR
1715 */
1716 public function &data_removeAssociatedObjects($name, $obj_id) {
1717 return $this->call_method
1718 ('facebook.data.removeAssociatedObjects',
1719 array('name' => $name,
1720 'obj_id' => $obj_id));
1721 }
1722
1723 /**
1724 * Retrieve a list of associated objects.
1725 *
1726 * @param name name of association
1727 * @param obj_id who's association to retrieve
1728 * @param no_data only return object ids
1729 * @return associated objects
1730 * @error
1731 * API_EC_DATA_DATABASE_ERROR
1732 * API_EC_DATA_OBJECT_NOT_FOUND
1733 * API_EC_PARAM
1734 * API_EC_PERMISSION
1735 * API_EC_DATA_INVALID_OPERATION
1736 * API_EC_DATA_QUOTA_EXCEEDED
1737 * API_EC_DATA_UNKNOWN_ERROR
1738 */
1739 public function &data_getAssociatedObjects($name, $obj_id, $no_data = true) {
1740 return $this->call_method
1741 ('facebook.data.getAssociatedObjects',
1742 array('name' => $name,
1743 'obj_id' => $obj_id,
1744 'no_data' => $no_data));
1745 }
1746
1747 /**
1748 * Count associated objects.
1749 *
1750 * @param name name of association
1751 * @param obj_id who's association to retrieve
1752 * @return associated object's count
1753 * @error
1754 * API_EC_DATA_DATABASE_ERROR
1755 * API_EC_DATA_OBJECT_NOT_FOUND
1756 * API_EC_PARAM
1757 * API_EC_PERMISSION
1758 * API_EC_DATA_INVALID_OPERATION
1759 * API_EC_DATA_QUOTA_EXCEEDED
1760 * API_EC_DATA_UNKNOWN_ERROR
1761 */
1762 public function &data_getAssociatedObjectCount($name, $obj_id) {
1763 return $this->call_method
1764 ('facebook.data.getAssociatedObjectCount',
1765 array('name' => $name,
1766 'obj_id' => $obj_id));
1767 }
1768
1769 /**
1770 * Get a list of associated object counts.
1771 *
1772 * @param name name of association
1773 * @param obj_ids whose association to retrieve
1774 * @return associated object counts
1775 * @error
1776 * API_EC_DATA_DATABASE_ERROR
1777 * API_EC_DATA_OBJECT_NOT_FOUND
1778 * API_EC_PARAM
1779 * API_EC_PERMISSION
1780 * API_EC_DATA_INVALID_OPERATION
1781 * API_EC_DATA_QUOTA_EXCEEDED
1782 * API_EC_DATA_UNKNOWN_ERROR
1783 */
1784 public function &data_getAssociatedObjectCounts($name, $obj_ids) {
1785 return $this->call_method
1786 ('facebook.data.getAssociatedObjectCounts',
1787 array('name' => $name,
1788 'obj_ids' => json_encode($obj_ids)));
1789 }
1790
1791 /**
1792 * Find all associations between two objects.
1793 *
1794 * @param obj_id1 id of first object
1795 * @param obj_id2 id of second object
1796 * @param no_data only return association names without data
1797 * @return all associations between objects
1798 * @error
1799 * API_EC_DATA_DATABASE_ERROR
1800 * API_EC_PARAM
1801 * API_EC_PERMISSION
1802 * API_EC_DATA_QUOTA_EXCEEDED
1803 * API_EC_DATA_UNKNOWN_ERROR
1804 */
1805 public function &data_getAssociations($obj_id1, $obj_id2, $no_data = true) {
1806 return $this->call_method
1807 ('facebook.data.getAssociations',
1808 array('obj_id1' => $obj_id1,
1809 'obj_id2' => $obj_id2,
1810 'no_data' => $no_data));
1811 }
1812
1813 /**
1814 * Get the properties that you have set for an app.
1815 *
1816 * @param properties list of properties names to fetch
1817 * @return a map from property name to value
1818 */
1819 public function admin_getAppProperties($properties) {
1820 return json_decode($this->call_method
1821 ('facebook.admin.getAppProperties',
1822 array('properties' => json_encode($properties))), true);
1823 }
1824
1825 /**
1826 * Set properties for an app.
1827 *
1828 * @param properties a map from property names to values
1829 * @return true on success
1830 */
1831 public function admin_setAppProperties($properties) {
1832 return $this->call_method
1833 ('facebook.admin.setAppProperties',
1834 array('properties' => json_encode($properties)));
1835 }
1836
1837 /**
1838 * Returns the allocation limit value for a specified integration point name
1839 * Integration point names are defined in lib/api/karma/constants.php in the limit_map
1840 * @param string $integration_point_name
1841 * @return integration point allocation value
1842 */
1843 public function &admin_getAllocation($integration_point_name) {
1844 return $this->call_method('facebook.admin.getAllocation', array('integration_point_name' => $integration_point_name));
1845 }
1846
1847 /**
1848 * Returns values for the specified metrics for the current
1849 * application, in the given time range. The metrics are collected
1850 * for fixed-length periods, and the times represent midnight at
1851 * the end of each period.
1852 *
1853 * @param start_time unix time for the start of the range
1854 * @param end_time unix time for the end of the range
1855 * @param period number of seconds in the desired period
1856 * @param metrics list of metrics to look up
1857 * @return a list of the values for those metrics
1858 */
1859 public function &admin_getMetrics($start_time, $end_time, $period, $metrics) {
1860 return $this->call_method('admin.getMetrics',
1861 array('start_time' => $start_time,
1862 'end_time' => $end_time,
1863 'period' => $period,
1864 'metrics' => json_encode($metrics)));
1865 }
1866
1867 /**
1868 * Sets application restriction info
1869 * Applications can restrict themselves to only a limted demography of users based on users' age and/or location
1870 * or based on static predefined types specified by facebook for specifying diff age restriction for diff locations
1871 *
1872 * @param restriction_info
1873 * @return bool
1874 */
1875 public function admin_setRestrictionInfo($restriction_info = null) {
1876 $restriction_str = null;
1877 if (!empty($restriction_info)) {
1878 $restriction_str = json_encode($restriction_info);
1879 }
1880 return $this->call_method('admin.setRestrictionInfo',
1881 array('restriction_str' => $restriction_str));
1882 }
1883
1884 /**
1885 * Gets application restriction info
1886 * Applications can restrict themselves to only a limted demography of users based on users' age and/or location
1887 * or based on static predefined types specified by facebook for specifying diff age restriction for diff locations
1888 *
1889 * @return bool
1890 */
1891 public function admin_getRestrictionInfo() {
1892 return json_decode($this->call_method(
1893 'admin.getRestrictionInfo',
1894 array()),
1895 true);
1896 }
1897
1898 /* UTILITY FUNCTIONS */
1899
1900 public function & call_method($method, $params) {
1901
1902 //Check if we are in batch mode
1903 if($this->batch_queue === null) {
1904 if ($this->call_as_apikey) {
1905 $params['call_as_apikey'] = $this->call_as_apikey;
1906 }
1907 $xml = $this->post_request($method, $params);
1908 $result = $this->convert_xml_to_result($xml, $method, $params);
1909 if (is_array($result) && isset($result['error_code'])) {
1910 throw new FacebookRestClientException($result['error_msg'], $result['error_code']);
1911 }
1912 }
1913 else {
1914 $result = null;
1915 $batch_item = array('m' => $method, 'p' => $params, 'r' => & $result);
1916 $this->batch_queue[] = $batch_item;
1917 }
1918
1919 return $result;
1920 }
1921
1922 private function convert_xml_to_result($xml, $method, $params) {
1923 $sxml = simplexml_load_string($xml);
1924 $result = self::convert_simplexml_to_array($sxml);
1925
1926
1927 if (!empty($GLOBALS['facebook_config']['debug'])) {
1928 // output the raw xml and its corresponding php object, for debugging:
1929 print '<div style="margin: 10px 30px; padding: 5px; border: 2px solid black; background: gray; color: white; font-size: 12px; font-weight: bold;">';
1930 $this->cur_id++;
1931 print $this->cur_id . ': Called ' . $method . ', show ' .
1932 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'params\');">Params</a> | '.
1933 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'xml\');">XML</a> | '.
1934 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'sxml\');">SXML</a> | '.
1935 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'php\');">PHP</a>';
1936 print '<pre id="params'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($params, true).'</pre>';
1937 print '<pre id="xml'.$this->cur_id.'" style="display: none; overflow: auto;">'.htmlspecialchars($xml).'</pre>';
1938 print '<pre id="php'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($result, true).'</pre>';
1939 print '<pre id="sxml'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($sxml, true).'</pre>';
1940 print '</div>';
1941 }
1942 return $result;
1943 }
1944
1945
1946
1947 private function create_post_string($method, $params) {
1948 $params['method'] = $method;
1949 $params['session_key'] = $this->session_key;
1950 $params['api_key'] = $this->api_key;
1951 $params['call_id'] = microtime(true);
1952 if ($params['call_id'] <= $this->last_call_id) {
1953 $params['call_id'] = $this->last_call_id + 0.001;
1954 }
1955 $this->last_call_id = $params['call_id'];
1956 if (!isset($params['v'])) {
1957 $params['v'] = '1.0';
1958 }
1959 $post_params = array();
1960 foreach ($params as $key => &$val) {
1961 if (is_array($val)) $val = implode(',', $val);
1962 $post_params[] = $key.'='.urlencode($val);
1963 }
1964 $secret = $this->secret;
1965 $post_params[] = 'sig='.Facebook::generate_sig($params, $secret);
1966 return implode('&', $post_params);
1967 }
1968
1969 public function post_request($method, $params) {
1970
1971 $post_string = $this->create_post_string($method, $params);
1972
1973 if (function_exists('curl_init')) {
1974 // Use CURL if installed...
1975 $ch = curl_init();
1976 curl_setopt($ch, CURLOPT_URL, $this->server_addr);
1977 curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);
1978 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
1979 curl_setopt($ch, CURLOPT_USERAGENT, 'Facebook API PHP5 Client 1.1 (curl) ' . phpversion());
1980 $result = curl_exec($ch);
1981 curl_close($ch);
1982 } else {
1983 // Non-CURL based version...
1984 $context =
1985 array('http' =>
1986 array('method' => 'POST',
1987 'header' => 'Content-type: application/x-www-form-urlencoded'."\r\n".
1988 'User-Agent: Facebook API PHP5 Client 1.1 (non-curl) '.phpversion()."\r\n".
1989 'Content-length: ' . strlen($post_string),
1990 'content' => $post_string));
1991 $contextid=stream_context_create($context);
1992 $sock=fopen($this->server_addr, 'r', false, $contextid);
1993 if ($sock) {
1994 $result='';
1995 while (!feof($sock))
1996 $result.=fgets($sock, 4096);
1997
1998 fclose($sock);
1999 }
2000 }
2001 return $result;
2002 }
2003
2004 public static function convert_simplexml_to_array($sxml) {
2005 $arr = array();
2006 if ($sxml) {
2007 foreach ($sxml as $k => $v) {
2008 if ($sxml['list']) {
2009 $arr[] = self::convert_simplexml_to_array($v);
2010 } else {
2011 $arr[$k] = self::convert_simplexml_to_array($v);
2012 }
2013 }
2014 }
2015 if (sizeof($arr) > 0) {
2016 return $arr;
2017 } else {
2018 return (string)$sxml;
2019 }
2020 }
2021
2022}
2023
2024
2025class FacebookRestClientException extends Exception {
2026}
2027
2028// Supporting methods and values------
2029
2030/**
2031 * Error codes and descriptions for the Facebook API.
2032 */
2033
2034class FacebookAPIErrorCodes {
2035
2036 const API_EC_SUCCESS = 0;
2037
2038 /*
2039 * GENERAL ERRORS
2040 */
2041 const API_EC_UNKNOWN = 1;
2042 const API_EC_SERVICE = 2;
2043 const API_EC_METHOD = 3;
2044 const API_EC_TOO_MANY_CALLS = 4;
2045 const API_EC_BAD_IP = 5;
2046
2047 /*
2048 * PARAMETER ERRORS
2049 */
2050 const API_EC_PARAM = 100;
2051 const API_EC_PARAM_API_KEY = 101;
2052 const API_EC_PARAM_SESSION_KEY = 102;
2053 const API_EC_PARAM_CALL_ID = 103;
2054 const API_EC_PARAM_SIGNATURE = 104;
2055 const API_EC_PARAM_USER_ID = 110;
2056 const API_EC_PARAM_USER_FIELD = 111;
2057 const API_EC_PARAM_SOCIAL_FIELD = 112;
2058 const API_EC_PARAM_ALBUM_ID = 120;
2059 const API_EC_PARAM_BAD_EID = 150;
2060 const API_EC_PARAM_UNKNOWN_CITY = 151;
2061
2062 /*
2063 * USER PERMISSIONS ERRORS
2064 */
2065 const API_EC_PERMISSION = 200;
2066 const API_EC_PERMISSION_USER = 210;
2067 const API_EC_PERMISSION_ALBUM = 220;
2068 const API_EC_PERMISSION_PHOTO = 221;
2069 const API_EC_PERMISSION_EVENT = 290;
2070 const API_EC_PERMISSION_RSVP_EVENT = 299;
2071
2072 const FQL_EC_PARSER = 601;
2073 const FQL_EC_UNKNOWN_FIELD = 602;
2074 const FQL_EC_UNKNOWN_TABLE = 603;
2075 const FQL_EC_NOT_INDEXABLE = 604;
2076
2077 /**
2078 * DATA STORE API ERRORS
2079 */
2080 const API_EC_DATA_UNKNOWN_ERROR = 800;
2081 const API_EC_DATA_INVALID_OPERATION = 801;
2082 const API_EC_DATA_QUOTA_EXCEEDED = 802;
2083 const API_EC_DATA_OBJECT_NOT_FOUND = 803;
2084 const API_EC_DATA_OBJECT_ALREADY_EXISTS = 804;
2085 const API_EC_DATA_DATABASE_ERROR = 805;
2086
2087
2088 /*
2089 * Batch ERROR
2090 */
2091 const API_EC_BATCH_ALREADY_STARTED = 900;
2092 const API_EC_BATCH_NOT_STARTED = 901;
2093 const API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE = 902;
2094
2095 public static $api_error_descriptions = array(
2096 API_EC_SUCCESS => 'Success',
2097 API_EC_UNKNOWN => 'An unknown error occurred',
2098 API_EC_SERVICE => 'Service temporarily unavailable',
2099 API_EC_METHOD => 'Unknown method',
2100 API_EC_TOO_MANY_CALLS => 'Application request limit reached',
2101 API_EC_BAD_IP => 'Unauthorized source IP address',
2102 API_EC_PARAM => 'Invalid parameter',
2103 API_EC_PARAM_API_KEY => 'Invalid API key',
2104 API_EC_PARAM_SESSION_KEY => 'Session key invalid or no longer valid',
2105 API_EC_PARAM_CALL_ID => 'Call_id must be greater than previous',
2106 API_EC_PARAM_SIGNATURE => 'Incorrect signature',
2107 API_EC_PARAM_USER_ID => 'Invalid user id',
2108 API_EC_PARAM_USER_FIELD => 'Invalid user info field',
2109 API_EC_PARAM_SOCIAL_FIELD => 'Invalid user field',
2110 API_EC_PARAM_ALBUM_ID => 'Invalid album id',
2111 API_EC_PARAM_BAD_EID => 'Invalid eid',
2112 API_EC_PARAM_UNKNOWN_CITY => 'Unknown city',
2113 API_EC_PERMISSION => 'Permissions error',
2114 API_EC_PERMISSION_USER => 'User not visible',
2115 API_EC_PERMISSION_ALBUM => 'Album not visible',
2116 API_EC_PERMISSION_PHOTO => 'Photo not visible',
2117 API_EC_PERMISSION_EVENT => 'Creating and modifying events required the extended permission create_event',
2118 API_EC_PERMISSION_RSVP_EVENT => 'RSVPing to events required the extended permission rsvp_event',
2119 FQL_EC_PARSER => 'FQL: Parser Error',
2120 FQL_EC_UNKNOWN_FIELD => 'FQL: Unknown Field',
2121 FQL_EC_UNKNOWN_TABLE => 'FQL: Unknown Table',
2122 FQL_EC_NOT_INDEXABLE => 'FQL: Statement not indexable',
2123 FQL_EC_UNKNOWN_FUNCTION => 'FQL: Attempted to call unknown function',
2124 FQL_EC_INVALID_PARAM => 'FQL: Invalid parameter passed in',
2125 API_EC_DATA_UNKNOWN_ERROR => 'Unknown data store API error',
2126 API_EC_DATA_INVALID_OPERATION => 'Invalid operation',
2127 API_EC_DATA_QUOTA_EXCEEDED => 'Data store allowable quota was exceeded',
2128 API_EC_DATA_OBJECT_NOT_FOUND => 'Specified object cannot be found',
2129 API_EC_DATA_OBJECT_ALREADY_EXISTS => 'Specified object already exists',
2130 API_EC_DATA_DATABASE_ERROR => 'A database error occurred. Please try again',
2131 API_EC_BATCH_ALREADY_STARTED => 'begin_batch already called, please make sure to call end_batch first',
2132 API_EC_BATCH_NOT_STARTED => 'end_batch called before start_batch',
2133 API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE => 'this method is not allowed in batch mode',
2134 );
2135}
Note: See TracBrowser for help on using the repository browser.