3 // +---------------------------------------------------------------------------+
4 // | Facebook Platform PHP5 client |
5 // +---------------------------------------------------------------------------+
6 // | Copyright (c) 2007-2008 Facebook, Inc. |
7 // | All rights reserved. |
9 // | Redistribution and use in source and binary forms, with or without |
10 // | modification, are permitted provided that the following conditions |
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. |
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 // +---------------------------------------------------------------------------+
34 include_once 'jsonwrapper/jsonwrapper.php';
35 class FacebookRestClient {
39 // to save making the friends.get api call, this will get prepopulated on
43 // to save making the pages.isAppAdded api call, this will get prepopulated
47 // we don't pass friends list to iframes, but we want to make
48 // friends_get really simple in the canvas_user (non-logged in) case.
49 // So we use the canvas_user as default arg to friends_get
53 private $call_as_apikey;
55 const BATCH_MODE_DEFAULT = 0;
56 const BATCH_MODE_SERVER_PARALLEL = 0;
57 const BATCH_MODE_SERIAL_ONLY = 2;
61 * @param string $session_key if you haven't gotten a session key yet, leave
62 * this as null and then set it later by just
63 * directly accessing the $session_key member
66 public function __construct($api_key, $secret, $session_key=null) {
67 $this->secret = $secret;
68 $this->session_key = $session_key;
69 $this->api_key = $api_key;
70 $this->batch_mode = FacebookRestClient::BATCH_MODE_DEFAULT;
71 $this->last_call_id = 0;
72 $this->call_as_apikey = '';
73 $this->server_addr = Facebook::get_facebook_url('api') . '/restserver.php';
75 if (!empty($GLOBALS['facebook_config']['debug'])) {
78 <script type="text/javascript">
79 var types = ['params', 'xml', 'php', 'sxml'];
80 function getStyle(elem, style) {
82 return elem.getStyle(style);
84 return elem.style[style];
87 function setStyle(elem, style, value) {
89 elem.setStyle(style, value);
91 elem.style[style] = value;
94 function toggleDisplay(id, type) {
95 for (var i = 0; i < types.length; i++) {
97 var pre = document.getElementById(t + id);
99 if (t != type || getStyle(pre, 'display') == 'block') {
100 setStyle(pre, 'display', 'none');
102 setStyle(pre, 'display', 'block');
114 * Set the default user id for methods that allow the caller
115 * to pass an uid parameter to identify the target user
116 * instead of a session key. This currently applies to
117 * the user preferences methods.
119 * @param $uid int the user id
121 public function set_user($uid) {
126 * Start a batch operation.
128 public function begin_batch() {
129 if($this->batch_queue !== null) {
130 $code = FacebookAPIErrorCodes::API_EC_BATCH_ALREADY_STARTED;
131 throw new FacebookRestClientException($code,
132 FacebookAPIErrorCodes::$api_error_descriptions[$code]);
135 $this->batch_queue = array();
139 * End current batch operation
141 public function end_batch() {
142 if($this->batch_queue === null) {
143 $code = FacebookAPIErrorCodes::API_EC_BATCH_NOT_STARTED;
144 throw new FacebookRestClientException($code,
145 FacebookAPIErrorCodes::$api_error_descriptions[$code]);
148 $this->execute_server_side_batch();
150 $this->batch_queue = null;
153 private function execute_server_side_batch() {
154 $item_count = count($this->batch_queue);
155 $method_feed = array();
156 foreach($this->batch_queue as $batch_item) {
157 $method_feed[] = $this->create_post_string($batch_item['m'],
161 $method_feed_json = json_encode($method_feed);
164 ($this->batch_mode == FacebookRestClient::BATCH_MODE_SERIAL_ONLY);
165 $params = array('method_feed' => $method_feed_json,
166 'serial_only' => $serial_only);
167 if ($this->call_as_apikey) {
168 $params['call_as_apikey'] = $this->call_as_apikey;
171 $xml = $this->post_request('batch.run', $params);
173 $result = $this->convert_xml_to_result($xml, 'batch.run', $params);
176 if (is_array($result) && isset($result['error_code'])) {
177 throw new FacebookRestClientException($result['error_msg'],
178 $result['error_code']);
181 for($i = 0; $i < $item_count; $i++) {
182 $batch_item = $this->batch_queue[$i];
183 $batch_item_result_xml = $result[$i];
184 $batch_item_result = $this->convert_xml_to_result($batch_item_result_xml,
188 if (is_array($batch_item_result) &&
189 isset($batch_item_result['error_code'])) {
190 throw new FacebookRestClientException($batch_item_result['error_msg'],
191 $batch_item_result['error_code']);
193 $batch_item['r'] = $batch_item_result;
197 public function begin_permissions_mode($permissions_apikey) {
198 $this->call_as_apikey = $permissions_apikey;
201 public function end_permissions_mode() {
202 $this->call_as_apikey = '';
206 * Returns public information for an application (as shown in the application
207 * directory) by either application ID, API key, or canvas page name.
209 * @param int $application_id (Optional) app id
210 * @param string $application_api_key (Optional) api key
211 * @param string $application_canvas_name (Optional) canvas name
213 * Exactly one argument must be specified, otherwise it is an error.
215 * @return array An array of public information about the application.
217 public function application_getPublicInfo($application_id=null,
218 $application_api_key=null,
219 $application_canvas_name=null) {
220 return $this->call_method('facebook.application.getPublicInfo',
221 array('application_id' => $application_id,
222 'application_api_key' => $application_api_key,
223 'application_canvas_name' => $application_canvas_name));
227 * Creates an authentication token to be used as part of the desktop login
228 * flow. For more information, please see
229 * http://wiki.developers.facebook.com/index.php/Auth.createToken.
231 * @return string An authentication token.
233 public function auth_createToken() {
234 return $this->call_method('facebook.auth.createToken', array());
238 * Returns the session information available after current user logs in.
240 * @param string $auth_token the token returned by
241 * auth_createToken or passed back to
243 * @param bool $generate_session_secret whether the session returned should
244 * include a session secret
246 * @return array An assoc array containing session_key, uid
248 public function auth_getSession($auth_token, $generate_session_secret=false) {
249 //Check if we are in batch mode
250 if($this->batch_queue === null) {
251 $result = $this->call_method('facebook.auth.getSession',
252 array('auth_token' => $auth_token,
253 'generate_session_secret' => $generate_session_secret));
254 $this->session_key = $result['session_key'];
256 if (!empty($result['secret']) && !$generate_session_secret) {
257 // desktop apps have a special secret
258 $this->secret = $result['secret'];
265 * Generates a session-specific secret. This is for integration with
266 * client-side API calls, such as the JS library.
268 * @return array A session secret for the current promoted session
270 * @error API_EC_PARAM_SESSION_KEY
271 * API_EC_PARAM_UNKNOWN
273 public function auth_promoteSession() {
274 return $this->call_method('facebook.auth.promoteSession', array());
278 * Expires the session that is currently being used. If this call is
279 * successful, no further calls to the API (which require a session) can be
280 * made until a valid session is created.
282 * @return bool true if session expiration was successful, false otherwise
284 public function auth_expireSession() {
285 return $this->call_method('facebook.auth.expireSession', array());
289 * Revokes the user's agreement to the Facebook Terms of Service for your
290 * application. If you call this method for one of your users, you will no
291 * longer be able to make API requests on their behalf until they again
292 * authorize your application. Use with care. Note that if this method is
293 * called without a user parameter, then it will revoke access for the
294 * current session's user.
296 * @param int $uid (Optional) User to revoke
298 * @return bool true if revocation succeeds, false otherwise
300 public function auth_revokeAuthorization($uid=null) {
301 return $this->call_method('facebook.auth.revokeAuthorization',
302 array('uid' => $uid));
306 * Returns the number of unconnected friends that exist in this application.
307 * This number is determined based on the accounts registered through
308 * connect.registerUsers() (see below).
310 public function connect_getUnconnectedFriendsCount() {
311 return $this->call_method('facebook.connect.getUnconnectedFriendsCount',
316 * This method is used to create an association between an external user
317 * account and a Facebook user account, as per Facebook Connect.
319 * This method takes an array of account data, including a required email_hash
320 * and optional account data. For each connected account, if the user exists,
321 * the information is added to the set of the user's connected accounts.
322 * If the user has already authorized the site, the connected account is added
323 * in the confirmed state. If the user has not yet authorized the site, the
324 * connected account is added in the pending state.
326 * This is designed to help Facebook Connect recognize when two Facebook
327 * friends are both members of a external site, but perhaps are not aware of
328 * it. The Connect dialog (see fb:connect-form) is used when friends can be
329 * identified through these email hashes. See the following url for details:
331 * http://wiki.developers.facebook.com/index.php/Connect.registerUsers
333 * @param mixed $accounts A (JSON-encoded) array of arrays, where each array
334 * has three properties:
335 * 'email_hash' (req) - public email hash of account
336 * 'account_id' (opt) - remote account id;
337 * 'account_url' (opt) - url to remote account;
339 * @return array The list of email hashes for the successfully registered
342 public function connect_registerUsers($accounts) {
343 return $this->call_method('facebook.connect.registerUsers',
344 array('accounts' => $accounts));
348 * Unregisters a set of accounts registered using connect.registerUsers.
350 * @param array $email_hashes The (JSON-encoded) list of email hashes to be
353 * @return array The list of email hashes which have been successfully
356 public function connect_unregisterUsers($email_hashes) {
357 return $this->call_method('facebook.connect.unregisterUsers',
358 array('email_hashes' => $email_hashes));
362 * Returns events according to the filters specified.
364 * @param int $uid (Optional) User associated with events. A null
365 * parameter will default to the session user.
366 * @param array $eids (Optional) Filter by these event ids. A null
367 * parameter will get all events for the user.
368 * @param int $start_time (Optional) Filter with this unix time as lower
369 * bound. A null or zero parameter indicates no
371 * @param int $end_time (Optional) Filter with this UTC as upper bound.
372 * A null or zero parameter indicates no upper
374 * @param string $rsvp_status (Optional) Only show events where the given uid
375 * has this rsvp status. This only works if you
376 * have specified a value for $uid. Values are as
377 * in events.getMembers. Null indicates to ignore
378 * rsvp status when filtering.
380 * @return array The events matching the query.
382 public function &events_get($uid=null,
387 return $this->call_method('facebook.events.get',
390 'start_time' => $start_time,
391 'end_time' => $end_time,
392 'rsvp_status' => $rsvp_status));
396 * Returns membership list data associated with an event.
398 * @param int $eid event id
400 * @return array An assoc array of four membership lists, with keys
401 * 'attending', 'unsure', 'declined', and 'not_replied'
403 public function &events_getMembers($eid) {
404 return $this->call_method('facebook.events.getMembers',
405 array('eid' => $eid));
409 * RSVPs the current user to this event.
411 * @param int $eid event id
412 * @param string $rsvp_status 'attending', 'unsure', or 'declined'
414 * @return bool true if successful
416 public function &events_rsvp($eid, $rsvp_status) {
417 return $this->call_method('facebook.events.rsvp',
420 'rsvp_status' => $rsvp_status));
424 * Cancels an event. Only works for events where application is the admin.
426 * @param int $eid event id
427 * @param string $cancel_message (Optional) message to send to members of
428 * the event about why it is cancelled
430 * @return bool true if successful
432 public function &events_cancel($eid, $cancel_message='') {
433 return $this->call_method('facebook.events.cancel',
435 'cancel_message' => $cancel_message));
439 * Creates an event on behalf of the user is there is a session, otherwise on
440 * behalf of app. Successful creation guarantees app will be admin.
442 * @param assoc array $event_info json encoded event information
444 * @return int event id
446 public function &events_create($event_info) {
447 return $this->call_method('facebook.events.create',
448 array('event_info' => $event_info));
452 * Edits an existing event. Only works for events where application is admin.
454 * @param int $eid event id
455 * @param assoc array $event_info json encoded event information
457 * @return bool true if successful
459 public function &events_edit($eid, $event_info) {
460 return $this->call_method('facebook.events.edit',
462 'event_info' => $event_info));
466 * Fetches and re-caches the image stored at the given URL, for use in images
467 * published to non-canvas pages via the API (for example, to user profiles
468 * via profile.setFBML, or to News Feed via feed.publishUserAction).
470 * @param string $url The absolute URL from which to refresh the image.
472 * @return bool true on success
474 public function &fbml_refreshImgSrc($url) {
475 return $this->call_method('facebook.fbml.refreshImgSrc',
476 array('url' => $url));
480 * Fetches and re-caches the content stored at the given URL, for use in an
483 * @param string $url The absolute URL from which to fetch content. This URL
484 * should be used in a fb:ref FBML tag.
486 * @return bool true on success
488 public function &fbml_refreshRefUrl($url) {
489 return $this->call_method('facebook.fbml.refreshRefUrl',
490 array('url' => $url));
494 * Lets you insert text strings in their native language into the Facebook
495 * Translations database so they can be translated.
497 * @param array $native_strings An array of maps, where each map has a 'text'
498 * field and a 'description' field.
500 * @return int Number of strings uploaded.
502 public function &fbml_uploadNativeStrings($native_strings) {
503 return $this->call_method('facebook.fbml.uploadNativeStrings',
504 array('native_strings' => json_encode($native_strings)));
508 * Associates a given "handle" with FBML markup so that the handle can be
509 * used within the fb:ref FBML tag. A handle is unique within an application
510 * and allows an application to publish identical FBML to many user profiles
511 * and do subsequent updates without having to republish FBML on behalf of
514 * @param string $handle The handle to associate with the given FBML.
515 * @param string $fbml The FBML to associate with the given handle.
517 * @return bool true on success
519 public function &fbml_setRefHandle($handle, $fbml) {
520 return $this->call_method('facebook.fbml.setRefHandle',
521 array('handle' => $handle, 'fbml' => $fbml));
525 * Register custom tags for the application. Custom tags can be used
526 * to extend the set of tags available to applications in FBML
529 * Before you call this function,
530 * make sure you read the full documentation at
532 * http://wiki.developers.facebook.com/index.php/Fbml.RegisterCustomTags
534 * IMPORTANT: This function overwrites the values of
535 * existing tags if the names match. Use this function with care because
536 * it may break the FBML of any application that is using the
537 * existing version of the tags.
539 * @param mixed $tags an array of tag objects (the full description is on the
542 * @return int the number of tags that were registered
544 public function &fbml_registerCustomTags($tags) {
545 $tags = json_encode($tags);
546 return $this->call_method('facebook.fbml.registerCustomTags',
547 array('tags' => $tags));
551 * Get the custom tags for an application. If $app_id
552 * is not specified, the calling app's tags are returned.
553 * If $app_id is different from the id of the calling app,
554 * only the app's public tags are returned.
555 * The return value is an array of the same type as
556 * the $tags parameter of fbml_registerCustomTags().
558 * @param int $app_id the application's id (optional)
560 * @return mixed an array containing the custom tag objects
562 public function &fbml_getCustomTags($app_id = null) {
563 return $this->call_method('facebook.fbml.getCustomTags',
564 array('app_id' => $app_id));
569 * Delete custom tags the application has registered. If
570 * $tag_names is null, all the application's custom tags will be
573 * IMPORTANT: If your application has registered public tags
574 * that other applications may be using, don't delete those tags!
575 * Doing so can break the FBML ofapplications that are using them.
577 * @param array $tag_names the names of the tags to delete (optinal)
578 * @return bool true on success
580 public function &fbml_deleteCustomTags($tag_names = null) {
581 return $this->call_method('facebook.fbml.deleteCustomTags',
582 array('tag_names' => json_encode($tag_names)));
588 * This method is deprecated for calls made on behalf of users. This method
589 * works only for publishing stories on a Facebook Page that has installed
590 * your application. To publish stories to a user's profile, use
591 * feed.publishUserAction instead.
593 * For more details on this call, please visit the wiki page:
595 * http://wiki.developers.facebook.com/index.php/Feed.publishTemplatizedAction
597 public function &feed_publishTemplatizedAction($title_template,
611 $page_actor_id=null) {
612 return $this->call_method('facebook.feed.publishTemplatizedAction',
613 array('title_template' => $title_template,
614 'title_data' => $title_data,
615 'body_template' => $body_template,
616 'body_data' => $body_data,
617 'body_general' => $body_general,
618 'image_1' => $image_1,
619 'image_1_link' => $image_1_link,
620 'image_2' => $image_2,
621 'image_2_link' => $image_2_link,
622 'image_3' => $image_3,
623 'image_3_link' => $image_3_link,
624 'image_4' => $image_4,
625 'image_4_link' => $image_4_link,
626 'target_ids' => $target_ids,
627 'page_actor_id' => $page_actor_id));
631 * Registers a template bundle. Template bundles are somewhat involved, so
632 * it's recommended you check out the wiki for more details:
634 * http://wiki.developers.facebook.com/index.php/Feed.registerTemplateBundle
636 * @return string A template bundle id
638 public function &feed_registerTemplateBundle($one_line_story_templates,
639 $short_story_templates = array(),
640 $full_story_template = null,
641 $action_links = array()) {
643 $one_line_story_templates = json_encode($one_line_story_templates);
645 if (!empty($short_story_templates)) {
646 $short_story_templates = json_encode($short_story_templates);
649 if (isset($full_story_template)) {
650 $full_story_template = json_encode($full_story_template);
653 if (isset($action_links)) {
654 $action_links = json_encode($action_links);
657 return $this->call_method('facebook.feed.registerTemplateBundle',
658 array('one_line_story_templates' => $one_line_story_templates,
659 'short_story_templates' => $short_story_templates,
660 'full_story_template' => $full_story_template,
661 'action_links' => $action_links));
665 * Retrieves the full list of active template bundles registered by the
666 * requesting application.
668 * @return array An array of template bundles
670 public function &feed_getRegisteredTemplateBundles() {
671 return $this->call_method('facebook.feed.getRegisteredTemplateBundles',
676 * Retrieves information about a specified template bundle previously
677 * registered by the requesting application.
679 * @param string $template_bundle_id The template bundle id
681 * @return array Template bundle
683 public function &feed_getRegisteredTemplateBundleByID($template_bundle_id) {
684 return $this->call_method('facebook.feed.getRegisteredTemplateBundleByID',
685 array('template_bundle_id' => $template_bundle_id));
689 * Deactivates a previously registered template bundle.
691 * @param string $template_bundle_id The template bundle id
693 * @return bool true on success
695 public function &feed_deactivateTemplateBundleByID($template_bundle_id) {
696 return $this->call_method('facebook.feed.deactivateTemplateBundleByID',
697 array('template_bundle_id' => $template_bundle_id));
700 const STORY_SIZE_ONE_LINE = 1;
701 const STORY_SIZE_SHORT = 2;
702 const STORY_SIZE_FULL = 4;
705 * Publishes a story on behalf of the user owning the session, using the
706 * specified template bundle. This method requires an active session key in
707 * order to be called.
709 * The parameters to this method ($templata_data in particular) are somewhat
710 * involved. It's recommended you visit the wiki for details:
712 * http://wiki.developers.facebook.com/index.php/Feed.publishUserAction
714 * @param int $template_bundle_id A template bundle id previously registered
715 * @param array $template_data See wiki article for syntax
716 * @param array $target_ids (Optional) An array of friend uids of the
717 * user who shared in this action.
718 * @param string $body_general (Optional) Additional markup that extends
719 * the body of a short story.
720 * @param int $story_size (Optional) A story size (see above)
722 * @return bool true on success
724 public function &feed_publishUserAction(
725 $template_bundle_id, $template_data, $target_ids='', $body_general='',
726 $story_size=FacebookRestClient::STORY_SIZE_ONE_LINE) {
728 if (is_array($template_data)) {
729 $template_data = json_encode($template_data);
730 } // allow client to either pass in JSON or an assoc that we JSON for them
732 if (is_array($target_ids)) {
733 $target_ids = json_encode($target_ids);
734 $target_ids = trim($target_ids, "[]"); // we don't want square brackets
737 return $this->call_method('facebook.feed.publishUserAction',
738 array('template_bundle_id' => $template_bundle_id,
739 'template_data' => $template_data,
740 'target_ids' => $target_ids,
741 'body_general' => $body_general,
742 'story_size' => $story_size));
746 * For the current user, retrieves stories generated by the user's friends
747 * while using this application. This can be used to easily create a
748 * "News Feed" like experience.
750 * @return array An array of feed story objects.
752 public function &feed_getAppFriendStories() {
753 return $this->call_method('facebook.feed.getAppFriendStories', array());
757 * Makes an FQL query. This is a generalized way of accessing all the data
758 * in the API, as an alternative to most of the other method calls. More
759 * info at http://developers.facebook.com/documentation.php?v=1.0&doc=fql
761 * @param string $query the query to evaluate
763 * @return array generalized array representing the results
765 public function &fql_query($query) {
766 return $this->call_method('facebook.fql.query',
767 array('query' => $query));
771 * Returns whether or not pairs of users are friends.
772 * Note that the Facebook friend relationship is symmetric.
774 * @param array $uids1 array of ids (id_1, id_2,...) of some length X
775 * @param array $uids2 array of ids (id_A, id_B,...) of SAME length X
777 * @return array An array with uid1, uid2, and bool if friends, e.g.:
778 * array(0 => array('uid1' => id_1, 'uid2' => id_A, 'are_friends' => 1),
779 * 1 => array('uid1' => id_2, 'uid2' => id_B, 'are_friends' => 0)
782 public function &friends_areFriends($uids1, $uids2) {
783 return $this->call_method('facebook.friends.areFriends',
784 array('uids1' => $uids1, 'uids2' => $uids2));
788 * Returns the friends of the current session user.
790 * @param int $flid (Optional) Only return friends on this friend list.
792 * @return array An array of friends
794 public function &friends_get($flid=null) {
795 if (isset($this->friends_list)) {
796 return $this->friends_list;
799 if (isset($this->canvas_user)) {
800 $params['uid'] = $this->canvas_user;
803 $params['flid'] = $flid;
805 return $this->call_method('facebook.friends.get', $params);
810 * Returns the set of friend lists for the current session user.
812 * @return array An array of friend list objects
814 public function &friends_getLists() {
815 return $this->call_method('facebook.friends.getLists', array());
819 * Returns the friends of the session user, who are also users
820 * of the calling application.
822 * @return array An array of friends also using the app
824 public function &friends_getAppUsers() {
825 return $this->call_method('facebook.friends.getAppUsers', array());
829 * Returns groups according to the filters specified.
831 * @param int $uid (Optional) User associated with groups. A null
832 * parameter will default to the session user.
833 * @param array $gids (Optional) Group ids to query. A null parameter will
834 * get all groups for the user.
836 * @return array An array of group objects
838 public function &groups_get($uid, $gids) {
839 return $this->call_method('facebook.groups.get',
845 * Returns the membership list of a group.
847 * @param int $gid Group id
849 * @return array An array with four membership lists, with keys 'members',
850 * 'admins', 'officers', and 'not_replied'
852 public function &groups_getMembers($gid) {
853 return $this->call_method('facebook.groups.getMembers',
854 array('gid' => $gid));
858 * Returns cookies according to the filters specified.
860 * @param int $uid User for which the cookies are needed.
861 * @param string $name (Optional) A null parameter will get all cookies
864 * @return array Cookies! Nom nom nom nom nom.
866 public function data_getCookies($uid, $name) {
867 return $this->call_method('facebook.data.getCookies',
873 * Sets cookies according to the params specified.
875 * @param int $uid User for which the cookies are needed.
876 * @param string $name Name of the cookie
877 * @param string $value (Optional) if expires specified and is in the past
878 * @param int $expires (Optional) Expiry time
879 * @param string $path (Optional) Url path to associate with (default is /)
881 * @return bool true on success
883 public function data_setCookie($uid, $name, $value, $expires, $path) {
884 return $this->call_method('facebook.data.setCookie',
888 'expires' => $expires,
897 * Checks API-access granted by self to the specified application.
899 * @param string $permissions_apikey Other application key
901 * @return array API methods/namespaces which are allowed access
903 public function permissions_checkGrantedApiAccess($permissions_apikey) {
904 return $this->call_method('facebook.permissions.checkGrantedApiAccess',
905 array('permissions_apikey' => $permissions_apikey));
909 * Checks API-access granted to self by the specified application.
911 * @param string $permissions_apikey Other application key
913 * @return array API methods/namespaces which are allowed access
915 public function permissions_checkAvailableApiAccess($permissions_apikey) {
916 return $this->call_method('facebook.permissions.checkAvailableApiAccess',
917 array('permissions_apikey' => $permissions_apikey));
921 * Grant API-access to the specified methods/namespaces to the specified
924 * @param string $permissions_apikey Other application key
925 * @param array(string) $method_arr (Optional) API methods/namespaces
928 * @return array API methods/namespaces which are allowed access
930 public function permissions_grantApiAccess($permissions_apikey, $method_arr) {
931 return $this->call_method('facebook.permissions.grantApiAccess',
932 array('permissions_apikey' => $permissions_apikey,
933 'method_arr' => $method_arr));
937 * Revoke API-access granted to the specified application.
939 * @param string $permissions_apikey Other application key
941 * @return bool true on success
943 public function permissions_revokeApiAccess($permissions_apikey) {
944 return $this->call_method('facebook.permissions.revokeApiAccess',
945 array('permissions_apikey' => $permissions_apikey));
949 * Returns the outstanding notifications for the session user.
951 * @return array An assoc array of notification count objects for
952 * 'messages', 'pokes' and 'shares', a uid list of
953 * 'friend_requests', a gid list of 'group_invites',
954 * and an eid list of 'event_invites'
956 public function ¬ifications_get() {
957 return $this->call_method('facebook.notifications.get', array());
961 * Sends a notification to the specified users.
963 * @return A comma separated list of successful recipients
965 public function ¬ifications_send($to_ids, $notification, $type) {
966 return $this->call_method('facebook.notifications.send',
967 array('to_ids' => $to_ids,
968 'notification' => $notification,
973 * Sends an email to the specified user of the application.
975 * @param array $recipients id of the recipients
976 * @param string $subject subject of the email
977 * @param string $text (plain text) body of the email
978 * @param string $fbml fbml markup for an html version of the email
980 * @return string A comma separated list of successful recipients
982 public function ¬ifications_sendEmail($recipients,
986 return $this->call_method('facebook.notifications.sendEmail',
987 array('recipients' => $recipients,
988 'subject' => $subject,
994 * Returns the requested info fields for the requested set of pages.
996 * @param array $page_ids an array of page ids
997 * @param array $fields an array of strings describing the info fields
999 * @param int $uid (Optional) limit results to pages of which this
1001 * @param string type limits results to a particular type of page.
1003 * @return array An array of pages
1005 public function &pages_getInfo($page_ids, $fields, $uid, $type) {
1006 return $this->call_method('facebook.pages.getInfo',
1007 array('page_ids' => $page_ids,
1008 'fields' => $fields,
1014 * Returns true if the given user is an admin for the passed page.
1016 * @param int $page_id target page id
1017 * @param int $uid (Optional) user id (defaults to the logged-in user)
1019 * @return bool true on success
1021 public function &pages_isAdmin($page_id, $uid = null) {
1022 return $this->call_method('facebook.pages.isAdmin',
1023 array('page_id' => $page_id,
1028 * Returns whether or not the given page has added the application.
1030 * @param int $page_id target page id
1032 * @return bool true on success
1034 public function &pages_isAppAdded($page_id) {
1035 return $this->call_method('facebook.pages.isAppAdded',
1036 array('page_id' => $page_id));
1040 * Returns true if logged in user is a fan for the passed page.
1042 * @param int $page_id target page id
1043 * @param int $uid user to compare. If empty, the logged in user.
1045 * @return bool true on success
1047 public function &pages_isFan($page_id, $uid = null) {
1048 return $this->call_method('facebook.pages.isFan',
1049 array('page_id' => $page_id,
1054 * Adds a tag with the given information to a photo. See the wiki for details:
1056 * http://wiki.developers.facebook.com/index.php/Photos.addTag
1058 * @param int $pid The ID of the photo to be tagged
1059 * @param int $tag_uid The ID of the user being tagged. You must specify
1060 * either the $tag_uid or the $tag_text parameter
1061 * (unless $tags is specified).
1062 * @param string $tag_text Some text identifying the person being tagged.
1063 * You must specify either the $tag_uid or $tag_text
1064 * parameter (unless $tags is specified).
1065 * @param float $x The horizontal position of the tag, as a
1066 * percentage from 0 to 100, from the left of the
1068 * @param float $y The vertical position of the tag, as a percentage
1069 * from 0 to 100, from the top of the photo.
1070 * @param array $tags (Optional) An array of maps, where each map
1071 * can contain the tag_uid, tag_text, x, and y
1072 * parameters defined above. If specified, the
1073 * individual arguments are ignored.
1074 * @param int $owner_uid (Optional) The user ID of the user whose photo
1075 * you are tagging. If this parameter is not
1076 * specified, then it defaults to the session user.
1078 * @return bool true on success
1080 public function &photos_addTag($pid,
1087 return $this->call_method('facebook.photos.addTag',
1088 array('pid' => $pid,
1089 'tag_uid' => $tag_uid,
1090 'tag_text' => $tag_text,
1093 'tags' => json_encode($tags),
1094 'owner_uid' => $this->get_uid($owner_uid)));
1098 * Creates and returns a new album owned by the specified user or the current
1101 * @param string $name The name of the album.
1102 * @param string $description (Optional) A description of the album.
1103 * @param string $location (Optional) A description of the location.
1104 * @param string $visible (Optional) A privacy setting for the album.
1105 * One of 'friends', 'friends-of-friends',
1106 * 'networks', or 'everyone'. Default 'everyone'.
1107 * @param int $uid (Optional) User id for creating the album; if
1108 * not specified, the session user is used.
1110 * @return array An album object
1112 public function &photos_createAlbum($name,
1117 return $this->call_method('facebook.photos.createAlbum',
1118 array('name' => $name,
1119 'description' => $description,
1120 'location' => $location,
1121 'visible' => $visible,
1122 'uid' => $this->get_uid($uid)));
1126 * Returns photos according to the filters specified.
1128 * @param int $subj_id (Optional) Filter by uid of user tagged in the photos.
1129 * @param int $aid (Optional) Filter by an album, as returned by
1131 * @param array $pids (Optional) Restrict to a list of pids
1133 * Note that at least one of these parameters needs to be specified, or an
1134 * error is returned.
1136 * @return array An array of photo objects.
1138 public function &photos_get($subj_id, $aid, $pids) {
1139 return $this->call_method('facebook.photos.get',
1140 array('subj_id' => $subj_id, 'aid' => $aid, 'pids' => $pids));
1144 * Returns the albums created by the given user.
1146 * @param int $uid (Optional) The uid of the user whose albums you want.
1147 * A null will return the albums of the session user.
1148 * @param array $aids (Optional) A list of aids to restrict the query.
1150 * Note that at least one of the (uid, aids) parameters must be specified.
1152 * @returns an array of album objects.
1154 public function &photos_getAlbums($uid, $aids) {
1155 return $this->call_method('facebook.photos.getAlbums',
1156 array('uid' => $uid,
1161 * Returns the tags on all photos specified.
1163 * @param string $pids A list of pids to query
1165 * @return array An array of photo tag objects, which include pid,
1166 * subject uid, and two floating-point numbers (xcoord, ycoord)
1167 * for tag pixel location.
1169 public function &photos_getTags($pids) {
1170 return $this->call_method('facebook.photos.getTags',
1171 array('pids' => $pids));
1175 * Returns the requested info fields for the requested set of users.
1177 * @param array $uids An array of user ids
1178 * @param array $fields An array of info field names desired
1180 * @return array An array of user objects
1182 public function &users_getInfo($uids, $fields) {
1183 return $this->call_method('facebook.users.getInfo',
1184 array('uids' => $uids, 'fields' => $fields));
1188 * Returns the requested info fields for the requested set of users. A
1189 * session key must not be specified. Only data about users that have
1190 * authorized your application will be returned.
1192 * Check the wiki for fields that can be queried through this API call.
1193 * Data returned from here should not be used for rendering to application
1194 * users, use users.getInfo instead, so that proper privacy rules will be
1197 * @param array $uids An array of user ids
1198 * @param array $fields An array of info field names desired
1200 * @return array An array of user objects
1202 public function &users_getStandardInfo($uids, $fields) {
1203 return $this->call_method('facebook.users.getStandardInfo',
1204 array('uids' => $uids, 'fields' => $fields));
1208 * Returns the user corresponding to the current session object.
1210 * @return integer User id
1212 public function &users_getLoggedInUser() {
1213 return $this->call_method('facebook.users.getLoggedInUser', array());
1217 * Returns 1 if the user has the specified permission, 0 otherwise.
1218 * http://wiki.developers.facebook.com/index.php/Users.hasAppPermission
1220 * @return integer 1 or 0
1222 public function &users_hasAppPermission($ext_perm, $uid=null) {
1223 return $this->call_method('facebook.users.hasAppPermission',
1224 array('ext_perm' => $ext_perm, 'uid' => $uid));
1228 * Returns whether or not the user corresponding to the current
1229 * session object has the give the app basic authorization.
1231 * @return boolean true if the user has authorized the app
1233 public function &users_isAppUser($uid=null) {
1234 if ($uid === null && isset($this->is_user)) {
1235 return $this->is_user;
1238 return $this->call_method('facebook.users.isAppUser', array('uid' => $uid));
1242 * Sets the users' current status message. Message does NOT contain the
1243 * word "is" , so make sure to include a verb.
1245 * Example: setStatus("is loving the API!")
1246 * will produce the status "Luke is loving the API!"
1248 * @param string $status text-only message to set
1249 * @param int $uid user to set for (defaults to the
1251 * @param bool $clear whether or not to clear the status,
1252 * instead of setting it
1253 * @param bool $status_includes_verb if true, the word "is" will *not* be
1254 * prepended to the status message
1258 public function &users_setStatus($status,
1261 $status_includes_verb = true) {
1263 'status' => $status,
1266 'status_includes_verb' => $status_includes_verb,
1268 return $this->call_method('facebook.users.setStatus', $args);
1272 * Sets the FBML for the profile of the user attached to this session.
1274 * @param string $markup The FBML that describes the profile
1275 * presence of this app for the user
1276 * @param int $uid The user
1277 * @param string $profile Profile FBML
1278 * @param string $profile_action Profile action FBML (deprecated)
1279 * @param string $mobile_profile Mobile profile FBML
1280 * @param string $profile_main Main Tab profile FBML
1282 * @return array A list of strings describing any compile errors for the
1285 function profile_setFBML($markup,
1291 return $this->call_method('facebook.profile.setFBML',
1292 array('markup' => $markup,
1294 'profile' => $profile,
1295 'profile_action' => $profile_action,
1296 'mobile_profile' => $mobile_profile,
1297 'profile_main' => $profile_main));
1301 * Gets the FBML for the profile box that is currently set for a user's
1302 * profile (your application set the FBML previously by calling the
1303 * profile.setFBML method).
1305 * @param int $uid (Optional) User id to lookup; defaults to session.
1306 * @param int $type (Optional) 1 for original style, 2 for profile_main boxes
1308 * @return string The FBML
1310 public function &profile_getFBML($uid=null, $type=null) {
1311 return $this->call_method('facebook.profile.getFBML',
1312 array('uid' => $uid,
1317 * Returns the specified user's application info section for the calling
1318 * application. These info sections have either been set via a previous
1319 * profile.setInfo call or by the user editing them directly.
1321 * @param int $uid (Optional) User id to lookup; defaults to session.
1323 * @return array Info fields for the current user. See wiki for structure:
1325 * http://wiki.developers.facebook.com/index.php/Profile.getInfo
1328 public function &profile_getInfo($uid=null) {
1329 return $this->call_method('facebook.profile.getInfo',
1330 array('uid' => $uid));
1334 * Returns the options associated with the specified info field for an
1335 * application info section.
1337 * @param string $field The title of the field
1339 * @return array An array of info options.
1341 public function &profile_getInfoOptions($field) {
1342 return $this->call_method('facebook.profile.getInfoOptions',
1343 array('field' => $field));
1347 * Configures an application info section that the specified user can install
1348 * on the Info tab of her profile. For details on the structure of an info
1349 * field, please see:
1351 * http://wiki.developers.facebook.com/index.php/Profile.setInfo
1353 * @param string $title Title / header of the info section
1354 * @param int $type 1 for text-only, 5 for thumbnail views
1355 * @param array $info_fields An array of info fields. See wiki for details.
1356 * @param int $uid (Optional)
1358 * @return bool true on success
1360 public function &profile_setInfo($title, $type, $info_fields, $uid=null) {
1361 return $this->call_method('facebook.profile.setInfo',
1362 array('uid' => $uid,
1365 'info_fields' => json_encode($info_fields)));
1369 * Specifies the objects for a field for an application info section. These
1370 * options populate the typeahead for a thumbnail.
1372 * @param string $field The title of the field
1373 * @param array $options An array of items for a thumbnail, including
1374 * 'label', 'link', and optionally 'image',
1375 * 'description' and 'sublabel'
1377 * @return bool true on success
1379 public function profile_setInfoOptions($field, $options) {
1380 return $this->call_method('facebook.profile.setInfoOptions',
1381 array('field' => $field,
1382 'options' => json_encode($options)));
1386 * Get all the marketplace categories.
1388 * @return array A list of category names
1390 function marketplace_getCategories() {
1391 return $this->call_method('facebook.marketplace.getCategories',
1396 * Get all the marketplace subcategories for a particular category.
1398 * @param category The category for which we are pulling subcategories
1400 * @return array A list of subcategory names
1402 function marketplace_getSubCategories($category) {
1403 return $this->call_method('facebook.marketplace.getSubCategories',
1404 array('category' => $category));
1408 * Get listings by either listing_id or user.
1410 * @param listing_ids An array of listing_ids (optional)
1411 * @param uids An array of user ids (optional)
1413 * @return array The data for matched listings
1415 function marketplace_getListings($listing_ids, $uids) {
1416 return $this->call_method('facebook.marketplace.getListings',
1417 array('listing_ids' => $listing_ids, 'uids' => $uids));
1421 * Search for Marketplace listings. All arguments are optional, though at
1422 * least one must be filled out to retrieve results.
1424 * @param category The category in which to search (optional)
1425 * @param subcategory The subcategory in which to search (optional)
1426 * @param query A query string (optional)
1428 * @return array The data for matched listings
1430 function marketplace_search($category, $subcategory, $query) {
1431 return $this->call_method('facebook.marketplace.search',
1432 array('category' => $category,
1433 'subcategory' => $subcategory,
1434 'query' => $query));
1438 * Remove a listing from Marketplace.
1440 * @param listing_id The id of the listing to be removed
1441 * @param status 'SUCCESS', 'NOT_SUCCESS', or 'DEFAULT'
1443 * @return bool True on success
1445 function marketplace_removeListing($listing_id,
1448 return $this->call_method('facebook.marketplace.removeListing',
1449 array('listing_id' => $listing_id,
1450 'status' => $status,
1455 * Create/modify a Marketplace listing for the loggedinuser.
1457 * @param int listing_id The id of a listing to be modified, 0
1458 * for a new listing.
1459 * @param show_on_profile bool Should we show this listing on the
1461 * @param listing_attrs array An array of the listing data
1463 * @return int The listing_id (unchanged if modifying an existing listing).
1465 function marketplace_createListing($listing_id,
1469 return $this->call_method('facebook.marketplace.createListing',
1470 array('listing_id' => $listing_id,
1471 'show_on_profile' => $show_on_profile,
1472 'listing_attrs' => json_encode($attrs),
1476 /////////////////////////////////////////////////////////////////////////////
1480 * Set a user preference.
1482 * @param pref_id preference identifier (0-200)
1483 * @param value preferece's value
1484 * @param uid the user id (defaults to current session user)
1486 * API_EC_DATA_DATABASE_ERROR
1488 * API_EC_DATA_QUOTA_EXCEEDED
1489 * API_EC_DATA_UNKNOWN_ERROR
1490 * API_EC_PERMISSION_OTHER_USER
1492 public function &data_setUserPreference($pref_id, $value, $uid = null) {
1493 return $this->call_method('facebook.data.setUserPreference',
1494 array('pref_id' => $pref_id,
1496 'uid' => $this->get_uid($uid)));
1500 * Set a user's all preferences for this application.
1502 * @param values preferece values in an associative arrays
1503 * @param replace whether to replace all existing preferences or
1505 * @param uid the user id (defaults to current session user)
1507 * API_EC_DATA_DATABASE_ERROR
1509 * API_EC_DATA_QUOTA_EXCEEDED
1510 * API_EC_DATA_UNKNOWN_ERROR
1511 * API_EC_PERMISSION_OTHER_USER
1513 public function &data_setUserPreferences($values,
1516 return $this->call_method('facebook.data.setUserPreferences',
1517 array('values' => json_encode($values),
1518 'replace' => $replace,
1519 'uid' => $this->get_uid($uid)));
1523 * Get a user preference.
1525 * @param pref_id preference identifier (0-200)
1526 * @param uid the user id (defaults to current session user)
1527 * @return preference's value
1529 * API_EC_DATA_DATABASE_ERROR
1531 * API_EC_DATA_QUOTA_EXCEEDED
1532 * API_EC_DATA_UNKNOWN_ERROR
1533 * API_EC_PERMISSION_OTHER_USER
1535 public function &data_getUserPreference($pref_id, $uid = null) {
1536 return $this->call_method('facebook.data.getUserPreference',
1537 array('pref_id' => $pref_id,
1538 'uid' => $this->get_uid($uid)));
1542 * Get a user preference.
1544 * @param uid the user id (defaults to current session user)
1545 * @return preference values
1547 * API_EC_DATA_DATABASE_ERROR
1548 * API_EC_DATA_QUOTA_EXCEEDED
1549 * API_EC_DATA_UNKNOWN_ERROR
1550 * API_EC_PERMISSION_OTHER_USER
1552 public function &data_getUserPreferences($uid = null) {
1553 return $this->call_method('facebook.data.getUserPreferences',
1554 array('uid' => $this->get_uid($uid)));
1558 * Create a new object type.
1560 * @param name object type's name
1562 * API_EC_DATA_DATABASE_ERROR
1563 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1566 * API_EC_DATA_INVALID_OPERATION
1567 * API_EC_DATA_QUOTA_EXCEEDED
1568 * API_EC_DATA_UNKNOWN_ERROR
1570 public function &data_createObjectType($name) {
1571 return $this->call_method('facebook.data.createObjectType',
1572 array('name' => $name));
1576 * Delete an object type.
1578 * @param obj_type object type's name
1580 * API_EC_DATA_DATABASE_ERROR
1581 * API_EC_DATA_OBJECT_NOT_FOUND
1584 * API_EC_DATA_INVALID_OPERATION
1585 * API_EC_DATA_QUOTA_EXCEEDED
1586 * API_EC_DATA_UNKNOWN_ERROR
1588 public function &data_dropObjectType($obj_type) {
1589 return $this->call_method('facebook.data.dropObjectType',
1590 array('obj_type' => $obj_type));
1594 * Rename an object type.
1596 * @param obj_type object type's name
1597 * @param new_name new object type's name
1599 * API_EC_DATA_DATABASE_ERROR
1600 * API_EC_DATA_OBJECT_NOT_FOUND
1601 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1604 * API_EC_DATA_INVALID_OPERATION
1605 * API_EC_DATA_QUOTA_EXCEEDED
1606 * API_EC_DATA_UNKNOWN_ERROR
1608 public function &data_renameObjectType($obj_type, $new_name) {
1609 return $this->call_method('facebook.data.renameObjectType',
1610 array('obj_type' => $obj_type,
1611 'new_name' => $new_name));
1615 * Add a new property to an object type.
1617 * @param obj_type object type's name
1618 * @param prop_name name of the property to add
1619 * @param prop_type 1: integer; 2: string; 3: text blob
1621 * API_EC_DATA_DATABASE_ERROR
1622 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1625 * API_EC_DATA_INVALID_OPERATION
1626 * API_EC_DATA_QUOTA_EXCEEDED
1627 * API_EC_DATA_UNKNOWN_ERROR
1629 public function &data_defineObjectProperty($obj_type,
1632 return $this->call_method('facebook.data.defineObjectProperty',
1633 array('obj_type' => $obj_type,
1634 'prop_name' => $prop_name,
1635 'prop_type' => $prop_type));
1639 * Remove a previously defined property from an object type.
1641 * @param obj_type object type's name
1642 * @param prop_name name of the property to remove
1644 * API_EC_DATA_DATABASE_ERROR
1645 * API_EC_DATA_OBJECT_NOT_FOUND
1648 * API_EC_DATA_INVALID_OPERATION
1649 * API_EC_DATA_QUOTA_EXCEEDED
1650 * API_EC_DATA_UNKNOWN_ERROR
1652 public function &data_undefineObjectProperty($obj_type, $prop_name) {
1653 return $this->call_method('facebook.data.undefineObjectProperty',
1654 array('obj_type' => $obj_type,
1655 'prop_name' => $prop_name));
1659 * Rename a previously defined property of an object type.
1661 * @param obj_type object type's name
1662 * @param prop_name name of the property to rename
1663 * @param new_name new name to use
1665 * API_EC_DATA_DATABASE_ERROR
1666 * API_EC_DATA_OBJECT_NOT_FOUND
1667 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1670 * API_EC_DATA_INVALID_OPERATION
1671 * API_EC_DATA_QUOTA_EXCEEDED
1672 * API_EC_DATA_UNKNOWN_ERROR
1674 public function &data_renameObjectProperty($obj_type, $prop_name,
1676 return $this->call_method('facebook.data.renameObjectProperty',
1677 array('obj_type' => $obj_type,
1678 'prop_name' => $prop_name,
1679 'new_name' => $new_name));
1683 * Retrieve a list of all object types that have defined for the application.
1685 * @return a list of object type names
1687 * API_EC_DATA_DATABASE_ERROR
1689 * API_EC_DATA_QUOTA_EXCEEDED
1690 * API_EC_DATA_UNKNOWN_ERROR
1692 public function &data_getObjectTypes() {
1693 return $this->call_method('facebook.data.getObjectTypes', array());
1697 * Get definitions of all properties of an object type.
1699 * @param obj_type object type's name
1700 * @return pairs of property name and property types
1702 * API_EC_DATA_DATABASE_ERROR
1705 * API_EC_DATA_OBJECT_NOT_FOUND
1706 * API_EC_DATA_QUOTA_EXCEEDED
1707 * API_EC_DATA_UNKNOWN_ERROR
1709 public function &data_getObjectType($obj_type) {
1710 return $this->call_method('facebook.data.getObjectType',
1711 array('obj_type' => $obj_type));
1715 * Create a new object.
1717 * @param obj_type object type's name
1718 * @param properties (optional) properties to set initially
1719 * @return newly created object's id
1721 * API_EC_DATA_DATABASE_ERROR
1724 * API_EC_DATA_INVALID_OPERATION
1725 * API_EC_DATA_QUOTA_EXCEEDED
1726 * API_EC_DATA_UNKNOWN_ERROR
1728 public function &data_createObject($obj_type, $properties = null) {
1729 return $this->call_method('facebook.data.createObject',
1730 array('obj_type' => $obj_type,
1731 'properties' => json_encode($properties)));
1735 * Update an existing object.
1737 * @param obj_id object's id
1738 * @param properties new properties
1739 * @param replace true for replacing existing properties;
1742 * API_EC_DATA_DATABASE_ERROR
1743 * API_EC_DATA_OBJECT_NOT_FOUND
1746 * API_EC_DATA_INVALID_OPERATION
1747 * API_EC_DATA_QUOTA_EXCEEDED
1748 * API_EC_DATA_UNKNOWN_ERROR
1750 public function &data_updateObject($obj_id, $properties, $replace = false) {
1751 return $this->call_method('facebook.data.updateObject',
1752 array('obj_id' => $obj_id,
1753 'properties' => json_encode($properties),
1754 'replace' => $replace));
1758 * Delete an existing object.
1760 * @param obj_id object's id
1762 * API_EC_DATA_DATABASE_ERROR
1763 * API_EC_DATA_OBJECT_NOT_FOUND
1766 * API_EC_DATA_INVALID_OPERATION
1767 * API_EC_DATA_QUOTA_EXCEEDED
1768 * API_EC_DATA_UNKNOWN_ERROR
1770 public function &data_deleteObject($obj_id) {
1771 return $this->call_method('facebook.data.deleteObject',
1772 array('obj_id' => $obj_id));
1776 * Delete a list of objects.
1778 * @param obj_ids objects to delete
1780 * API_EC_DATA_DATABASE_ERROR
1783 * API_EC_DATA_INVALID_OPERATION
1784 * API_EC_DATA_QUOTA_EXCEEDED
1785 * API_EC_DATA_UNKNOWN_ERROR
1787 public function &data_deleteObjects($obj_ids) {
1788 return $this->call_method('facebook.data.deleteObjects',
1789 array('obj_ids' => json_encode($obj_ids)));
1793 * Get a single property value of an object.
1795 * @param obj_id object's id
1796 * @param prop_name individual property's name
1797 * @return individual property's value
1799 * API_EC_DATA_DATABASE_ERROR
1800 * API_EC_DATA_OBJECT_NOT_FOUND
1803 * API_EC_DATA_INVALID_OPERATION
1804 * API_EC_DATA_QUOTA_EXCEEDED
1805 * API_EC_DATA_UNKNOWN_ERROR
1807 public function &data_getObjectProperty($obj_id, $prop_name) {
1808 return $this->call_method('facebook.data.getObjectProperty',
1809 array('obj_id' => $obj_id,
1810 'prop_name' => $prop_name));
1814 * Get properties of an object.
1816 * @param obj_id object's id
1817 * @param prop_names (optional) properties to return; null for all.
1818 * @return specified properties of an object
1820 * API_EC_DATA_DATABASE_ERROR
1821 * API_EC_DATA_OBJECT_NOT_FOUND
1824 * API_EC_DATA_INVALID_OPERATION
1825 * API_EC_DATA_QUOTA_EXCEEDED
1826 * API_EC_DATA_UNKNOWN_ERROR
1828 public function &data_getObject($obj_id, $prop_names = null) {
1829 return $this->call_method('facebook.data.getObject',
1830 array('obj_id' => $obj_id,
1831 'prop_names' => json_encode($prop_names)));
1835 * Get properties of a list of objects.
1837 * @param obj_ids object ids
1838 * @param prop_names (optional) properties to return; null for all.
1839 * @return specified properties of an object
1841 * API_EC_DATA_DATABASE_ERROR
1842 * API_EC_DATA_OBJECT_NOT_FOUND
1845 * API_EC_DATA_INVALID_OPERATION
1846 * API_EC_DATA_QUOTA_EXCEEDED
1847 * API_EC_DATA_UNKNOWN_ERROR
1849 public function &data_getObjects($obj_ids, $prop_names = null) {
1850 return $this->call_method('facebook.data.getObjects',
1851 array('obj_ids' => json_encode($obj_ids),
1852 'prop_names' => json_encode($prop_names)));
1856 * Set a single property value of an object.
1858 * @param obj_id object's id
1859 * @param prop_name individual property's name
1860 * @param prop_value new value to set
1862 * API_EC_DATA_DATABASE_ERROR
1863 * API_EC_DATA_OBJECT_NOT_FOUND
1866 * API_EC_DATA_INVALID_OPERATION
1867 * API_EC_DATA_QUOTA_EXCEEDED
1868 * API_EC_DATA_UNKNOWN_ERROR
1870 public function &data_setObjectProperty($obj_id, $prop_name,
1872 return $this->call_method('facebook.data.setObjectProperty',
1873 array('obj_id' => $obj_id,
1874 'prop_name' => $prop_name,
1875 'prop_value' => $prop_value));
1879 * Read hash value by key.
1881 * @param obj_type object type's name
1882 * @param key hash key
1883 * @param prop_name (optional) individual property's name
1884 * @return hash value
1886 * API_EC_DATA_DATABASE_ERROR
1889 * API_EC_DATA_INVALID_OPERATION
1890 * API_EC_DATA_QUOTA_EXCEEDED
1891 * API_EC_DATA_UNKNOWN_ERROR
1893 public function &data_getHashValue($obj_type, $key, $prop_name = null) {
1894 return $this->call_method('facebook.data.getHashValue',
1895 array('obj_type' => $obj_type,
1897 'prop_name' => $prop_name));
1901 * Write hash value by key.
1903 * @param obj_type object type's name
1904 * @param key hash key
1905 * @param value hash value
1906 * @param prop_name (optional) individual property's name
1908 * API_EC_DATA_DATABASE_ERROR
1911 * API_EC_DATA_INVALID_OPERATION
1912 * API_EC_DATA_QUOTA_EXCEEDED
1913 * API_EC_DATA_UNKNOWN_ERROR
1915 public function &data_setHashValue($obj_type,
1918 $prop_name = null) {
1919 return $this->call_method('facebook.data.setHashValue',
1920 array('obj_type' => $obj_type,
1923 'prop_name' => $prop_name));
1927 * Increase a hash value by specified increment atomically.
1929 * @param obj_type object type's name
1930 * @param key hash key
1931 * @param prop_name individual property's name
1932 * @param increment (optional) default is 1
1933 * @return incremented hash value
1935 * API_EC_DATA_DATABASE_ERROR
1938 * API_EC_DATA_INVALID_OPERATION
1939 * API_EC_DATA_QUOTA_EXCEEDED
1940 * API_EC_DATA_UNKNOWN_ERROR
1942 public function &data_incHashValue($obj_type,
1946 return $this->call_method('facebook.data.incHashValue',
1947 array('obj_type' => $obj_type,
1949 'prop_name' => $prop_name,
1950 'increment' => $increment));
1954 * Remove a hash key and its values.
1956 * @param obj_type object type's name
1957 * @param key hash key
1959 * API_EC_DATA_DATABASE_ERROR
1962 * API_EC_DATA_INVALID_OPERATION
1963 * API_EC_DATA_QUOTA_EXCEEDED
1964 * API_EC_DATA_UNKNOWN_ERROR
1966 public function &data_removeHashKey($obj_type, $key) {
1967 return $this->call_method('facebook.data.removeHashKey',
1968 array('obj_type' => $obj_type,
1973 * Remove hash keys and their values.
1975 * @param obj_type object type's name
1976 * @param keys hash keys
1978 * API_EC_DATA_DATABASE_ERROR
1981 * API_EC_DATA_INVALID_OPERATION
1982 * API_EC_DATA_QUOTA_EXCEEDED
1983 * API_EC_DATA_UNKNOWN_ERROR
1985 public function &data_removeHashKeys($obj_type, $keys) {
1986 return $this->call_method('facebook.data.removeHashKeys',
1987 array('obj_type' => $obj_type,
1988 'keys' => json_encode($keys)));
1992 * Define an object association.
1994 * @param name name of this association
1995 * @param assoc_type 1: one-way 2: two-way symmetric 3: two-way asymmetric
1996 * @param assoc_info1 needed info about first object type
1997 * @param assoc_info2 needed info about second object type
1998 * @param inverse (optional) name of reverse association
2000 * API_EC_DATA_DATABASE_ERROR
2001 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2004 * API_EC_DATA_INVALID_OPERATION
2005 * API_EC_DATA_QUOTA_EXCEEDED
2006 * API_EC_DATA_UNKNOWN_ERROR
2008 public function &data_defineAssociation($name, $assoc_type, $assoc_info1,
2009 $assoc_info2, $inverse = null) {
2010 return $this->call_method('facebook.data.defineAssociation',
2011 array('name' => $name,
2012 'assoc_type' => $assoc_type,
2013 'assoc_info1' => json_encode($assoc_info1),
2014 'assoc_info2' => json_encode($assoc_info2),
2015 'inverse' => $inverse));
2019 * Undefine an object association.
2021 * @param name name of this association
2023 * API_EC_DATA_DATABASE_ERROR
2024 * API_EC_DATA_OBJECT_NOT_FOUND
2027 * API_EC_DATA_INVALID_OPERATION
2028 * API_EC_DATA_QUOTA_EXCEEDED
2029 * API_EC_DATA_UNKNOWN_ERROR
2031 public function &data_undefineAssociation($name) {
2032 return $this->call_method('facebook.data.undefineAssociation',
2033 array('name' => $name));
2037 * Rename an object association or aliases.
2039 * @param name name of this association
2040 * @param new_name (optional) new name of this association
2041 * @param new_alias1 (optional) new alias for object type 1
2042 * @param new_alias2 (optional) new alias for object type 2
2044 * API_EC_DATA_DATABASE_ERROR
2045 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2046 * API_EC_DATA_OBJECT_NOT_FOUND
2049 * API_EC_DATA_INVALID_OPERATION
2050 * API_EC_DATA_QUOTA_EXCEEDED
2051 * API_EC_DATA_UNKNOWN_ERROR
2053 public function &data_renameAssociation($name, $new_name, $new_alias1 = null,
2054 $new_alias2 = null) {
2055 return $this->call_method('facebook.data.renameAssociation',
2056 array('name' => $name,
2057 'new_name' => $new_name,
2058 'new_alias1' => $new_alias1,
2059 'new_alias2' => $new_alias2));
2063 * Get definition of an object association.
2065 * @param name name of this association
2066 * @return specified association
2068 * API_EC_DATA_DATABASE_ERROR
2069 * API_EC_DATA_OBJECT_NOT_FOUND
2072 * API_EC_DATA_QUOTA_EXCEEDED
2073 * API_EC_DATA_UNKNOWN_ERROR
2075 public function &data_getAssociationDefinition($name) {
2076 return $this->call_method('facebook.data.getAssociationDefinition',
2077 array('name' => $name));
2081 * Get definition of all associations.
2083 * @return all defined associations
2085 * API_EC_DATA_DATABASE_ERROR
2087 * API_EC_DATA_QUOTA_EXCEEDED
2088 * API_EC_DATA_UNKNOWN_ERROR
2090 public function &data_getAssociationDefinitions() {
2091 return $this->call_method('facebook.data.getAssociationDefinitions',
2096 * Create or modify an association between two objects.
2098 * @param name name of association
2099 * @param obj_id1 id of first object
2100 * @param obj_id2 id of second object
2101 * @param data (optional) extra string data to store
2102 * @param assoc_time (optional) extra time data; default to creation time
2104 * API_EC_DATA_DATABASE_ERROR
2107 * API_EC_DATA_INVALID_OPERATION
2108 * API_EC_DATA_QUOTA_EXCEEDED
2109 * API_EC_DATA_UNKNOWN_ERROR
2111 public function &data_setAssociation($name, $obj_id1, $obj_id2, $data = null,
2112 $assoc_time = null) {
2113 return $this->call_method('facebook.data.setAssociation',
2114 array('name' => $name,
2115 'obj_id1' => $obj_id1,
2116 'obj_id2' => $obj_id2,
2118 'assoc_time' => $assoc_time));
2122 * Create or modify associations between objects.
2124 * @param assocs associations to set
2125 * @param name (optional) name of association
2127 * API_EC_DATA_DATABASE_ERROR
2130 * API_EC_DATA_INVALID_OPERATION
2131 * API_EC_DATA_QUOTA_EXCEEDED
2132 * API_EC_DATA_UNKNOWN_ERROR
2134 public function &data_setAssociations($assocs, $name = null) {
2135 return $this->call_method('facebook.data.setAssociations',
2136 array('assocs' => json_encode($assocs),
2141 * Remove an association between two objects.
2143 * @param name name of association
2144 * @param obj_id1 id of first object
2145 * @param obj_id2 id of second object
2147 * API_EC_DATA_DATABASE_ERROR
2148 * API_EC_DATA_OBJECT_NOT_FOUND
2151 * API_EC_DATA_QUOTA_EXCEEDED
2152 * API_EC_DATA_UNKNOWN_ERROR
2154 public function &data_removeAssociation($name, $obj_id1, $obj_id2) {
2155 return $this->call_method('facebook.data.removeAssociation',
2156 array('name' => $name,
2157 'obj_id1' => $obj_id1,
2158 'obj_id2' => $obj_id2));
2162 * Remove associations between objects by specifying pairs of object ids.
2164 * @param assocs associations to remove
2165 * @param name (optional) name of association
2167 * API_EC_DATA_DATABASE_ERROR
2168 * API_EC_DATA_OBJECT_NOT_FOUND
2171 * API_EC_DATA_QUOTA_EXCEEDED
2172 * API_EC_DATA_UNKNOWN_ERROR
2174 public function &data_removeAssociations($assocs, $name = null) {
2175 return $this->call_method('facebook.data.removeAssociations',
2176 array('assocs' => json_encode($assocs),
2181 * Remove associations between objects by specifying one object id.
2183 * @param name name of association
2184 * @param obj_id who's association to remove
2186 * API_EC_DATA_DATABASE_ERROR
2187 * API_EC_DATA_OBJECT_NOT_FOUND
2190 * API_EC_DATA_INVALID_OPERATION
2191 * API_EC_DATA_QUOTA_EXCEEDED
2192 * API_EC_DATA_UNKNOWN_ERROR
2194 public function &data_removeAssociatedObjects($name, $obj_id) {
2195 return $this->call_method('facebook.data.removeAssociatedObjects',
2196 array('name' => $name,
2197 'obj_id' => $obj_id));
2201 * Retrieve a list of associated objects.
2203 * @param name name of association
2204 * @param obj_id who's association to retrieve
2205 * @param no_data only return object ids
2206 * @return associated objects
2208 * API_EC_DATA_DATABASE_ERROR
2209 * API_EC_DATA_OBJECT_NOT_FOUND
2212 * API_EC_DATA_INVALID_OPERATION
2213 * API_EC_DATA_QUOTA_EXCEEDED
2214 * API_EC_DATA_UNKNOWN_ERROR
2216 public function &data_getAssociatedObjects($name, $obj_id, $no_data = true) {
2217 return $this->call_method('facebook.data.getAssociatedObjects',
2218 array('name' => $name,
2219 'obj_id' => $obj_id,
2220 'no_data' => $no_data));
2224 * Count associated objects.
2226 * @param name name of association
2227 * @param obj_id who's association to retrieve
2228 * @return associated object's count
2230 * API_EC_DATA_DATABASE_ERROR
2231 * API_EC_DATA_OBJECT_NOT_FOUND
2234 * API_EC_DATA_INVALID_OPERATION
2235 * API_EC_DATA_QUOTA_EXCEEDED
2236 * API_EC_DATA_UNKNOWN_ERROR
2238 public function &data_getAssociatedObjectCount($name, $obj_id) {
2239 return $this->call_method('facebook.data.getAssociatedObjectCount',
2240 array('name' => $name,
2241 'obj_id' => $obj_id));
2245 * Get a list of associated object counts.
2247 * @param name name of association
2248 * @param obj_ids whose association to retrieve
2249 * @return associated object counts
2251 * API_EC_DATA_DATABASE_ERROR
2252 * API_EC_DATA_OBJECT_NOT_FOUND
2255 * API_EC_DATA_INVALID_OPERATION
2256 * API_EC_DATA_QUOTA_EXCEEDED
2257 * API_EC_DATA_UNKNOWN_ERROR
2259 public function &data_getAssociatedObjectCounts($name, $obj_ids) {
2260 return $this->call_method('facebook.data.getAssociatedObjectCounts',
2261 array('name' => $name,
2262 'obj_ids' => json_encode($obj_ids)));
2266 * Find all associations between two objects.
2268 * @param obj_id1 id of first object
2269 * @param obj_id2 id of second object
2270 * @param no_data only return association names without data
2271 * @return all associations between objects
2273 * API_EC_DATA_DATABASE_ERROR
2276 * API_EC_DATA_QUOTA_EXCEEDED
2277 * API_EC_DATA_UNKNOWN_ERROR
2279 public function &data_getAssociations($obj_id1, $obj_id2, $no_data = true) {
2280 return $this->call_method('facebook.data.getAssociations',
2281 array('obj_id1' => $obj_id1,
2282 'obj_id2' => $obj_id2,
2283 'no_data' => $no_data));
2287 * Get the properties that you have set for an app.
2289 * @param properties List of properties names to fetch
2291 * @return array A map from property name to value
2293 public function admin_getAppProperties($properties) {
2295 $this->call_method('facebook.admin.getAppProperties',
2296 array('properties' => json_encode($properties))), true);
2300 * Set properties for an app.
2302 * @param properties A map from property names to values
2304 * @return bool true on success
2306 public function admin_setAppProperties($properties) {
2307 return $this->call_method('facebook.admin.setAppProperties',
2308 array('properties' => json_encode($properties)));
2312 * Returns the allocation limit value for a specified integration point name
2313 * Integration point names are defined in lib/api/karma/constants.php in the
2316 * @param string $integration_point_name Name of an integration point
2317 * (see developer wiki for list).
2319 * @return int Integration point allocation value
2321 public function &admin_getAllocation($integration_point_name) {
2322 return $this->call_method('facebook.admin.getAllocation',
2323 array('integration_point_name' => $integration_point_name));
2327 * Returns values for the specified metrics for the current application, in
2328 * the given time range. The metrics are collected for fixed-length periods,
2329 * and the times represent midnight at the end of each period.
2331 * @param start_time unix time for the start of the range
2332 * @param end_time unix time for the end of the range
2333 * @param period number of seconds in the desired period
2334 * @param metrics list of metrics to look up
2336 * @return array A map of the names and values for those metrics
2338 public function &admin_getMetrics($start_time, $end_time, $period, $metrics) {
2339 return $this->call_method('admin.getMetrics',
2340 array('start_time' => $start_time,
2341 'end_time' => $end_time,
2342 'period' => $period,
2343 'metrics' => json_encode($metrics)));
2347 * Sets application restriction info.
2349 * Applications can restrict themselves to only a limited user demographic
2350 * based on users' age and/or location or based on static predefined types
2351 * specified by facebook for specifying diff age restriction for diff
2354 * @param array $restriction_info The age restriction settings to set.
2356 * @return bool true on success
2358 public function admin_setRestrictionInfo($restriction_info = null) {
2359 $restriction_str = null;
2360 if (!empty($restriction_info)) {
2361 $restriction_str = json_encode($restriction_info);
2363 return $this->call_method('admin.setRestrictionInfo',
2364 array('restriction_str' => $restriction_str));
2368 * Gets application restriction info.
2370 * Applications can restrict themselves to only a limited user demographic
2371 * based on users' age and/or location or based on static predefined types
2372 * specified by facebook for specifying diff age restriction for diff
2375 * @return array The age restriction settings for this application.
2377 public function admin_getRestrictionInfo() {
2379 $this->call_method('admin.getRestrictionInfo', array()),
2383 /* UTILITY FUNCTIONS */
2386 * Calls the specified method with the specified parameters.
2388 * @param string $method Name of the Facebook method to invoke
2389 * @param array $params A map of param names => param values
2391 * @return mixed Result of method call
2393 public function & call_method($method, $params) {
2394 //Check if we are in batch mode
2395 if($this->batch_queue === null) {
2396 if ($this->call_as_apikey) {
2397 $params['call_as_apikey'] = $this->call_as_apikey;
2399 $xml = $this->post_request($method, $params);
2400 $result = $this->convert_xml_to_result($xml, $method, $params);
2402 if (is_array($result) && isset($result['error_code'])) {
2403 throw new FacebookRestClientException($result['error_msg'],
2404 $result['error_code']);
2409 $batch_item = array('m' => $method, 'p' => $params, 'r' => & $result);
2410 $this->batch_queue[] = $batch_item;
2416 private function convert_xml_to_result($xml, $method, $params) {
2417 $sxml = simplexml_load_string($xml);
2418 $result = self::convert_simplexml_to_array($sxml);
2421 if (!empty($GLOBALS['facebook_config']['debug'])) {
2422 // output the raw xml and its corresponding php object, for debugging:
2423 print '<div style="margin: 10px 30px; padding: 5px; border: 2px solid black; background: gray; color: white; font-size: 12px; font-weight: bold;">';
2425 print $this->cur_id . ': Called ' . $method . ', show ' .
2426 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'params\');">Params</a> | '.
2427 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'xml\');">XML</a> | '.
2428 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'sxml\');">SXML</a> | '.
2429 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'php\');">PHP</a>';
2430 print '<pre id="params'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($params, true).'</pre>';
2431 print '<pre id="xml'.$this->cur_id.'" style="display: none; overflow: auto;">'.htmlspecialchars($xml).'</pre>';
2432 print '<pre id="php'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($result, true).'</pre>';
2433 print '<pre id="sxml'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($sxml, true).'</pre>';
2439 private function create_post_string($method, $params) {
2440 $params['method'] = $method;
2441 $params['session_key'] = $this->session_key;
2442 $params['api_key'] = $this->api_key;
2443 $params['call_id'] = microtime(true);
2444 if ($params['call_id'] <= $this->last_call_id) {
2445 $params['call_id'] = $this->last_call_id + 0.001;
2447 $this->last_call_id = $params['call_id'];
2448 if (!isset($params['v'])) {
2449 $params['v'] = '1.0';
2451 $post_params = array();
2452 foreach ($params as $key => &$val) {
2453 if (is_array($val)) $val = implode(',', $val);
2454 $post_params[] = $key.'='.urlencode($val);
2456 $secret = $this->secret;
2457 $post_params[] = 'sig='.Facebook::generate_sig($params, $secret);
2458 return implode('&', $post_params);
2461 public function post_request($method, $params) {
2463 $post_string = $this->create_post_string($method, $params);
2465 if (function_exists('curl_init')) {
2466 // Use CURL if installed...
2467 $useragent = 'Facebook API PHP5 Client 1.1 (curl) ' . phpversion();
2469 curl_setopt($ch, CURLOPT_URL, $this->server_addr);
2470 curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);
2471 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
2472 curl_setopt($ch, CURLOPT_USERAGENT, $useragent);
2473 $result = curl_exec($ch);
2476 // Non-CURL based version...
2477 $content_type = 'application/x-www-form-urlencoded';
2478 $user_agent = 'Facebook API PHP5 Client 1.1 (non-curl) '.phpversion();
2481 array('method' => 'POST',
2482 'header' => 'Content-type: '.$content_type."\r\n".
2483 'User-Agent: '.$user_agent."\r\n".
2484 'Content-length: ' . strlen($post_string),
2485 'content' => $post_string));
2486 $contextid=stream_context_create($context);
2487 $sock=fopen($this->server_addr, 'r', false, $contextid);
2490 while (!feof($sock))
2491 $result.=fgets($sock, 4096);
2499 public static function convert_simplexml_to_array($sxml) {
2502 foreach ($sxml as $k => $v) {
2503 if ($sxml['list']) {
2504 $arr[] = self::convert_simplexml_to_array($v);
2506 $arr[$k] = self::convert_simplexml_to_array($v);
2510 if (sizeof($arr) > 0) {
2513 return (string)$sxml;
2517 private function get_uid($uid) {
2518 return $uid ? $uid : $this->user;
2523 class FacebookRestClientException extends Exception {
2526 // Supporting methods and values------
2529 * Error codes and descriptions for the Facebook API.
2532 class FacebookAPIErrorCodes {
2534 const API_EC_SUCCESS = 0;
2539 const API_EC_UNKNOWN = 1;
2540 const API_EC_SERVICE = 2;
2541 const API_EC_METHOD = 3;
2542 const API_EC_TOO_MANY_CALLS = 4;
2543 const API_EC_BAD_IP = 5;
2548 const API_EC_PARAM = 100;
2549 const API_EC_PARAM_API_KEY = 101;
2550 const API_EC_PARAM_SESSION_KEY = 102;
2551 const API_EC_PARAM_CALL_ID = 103;
2552 const API_EC_PARAM_SIGNATURE = 104;
2553 const API_EC_PARAM_USER_ID = 110;
2554 const API_EC_PARAM_USER_FIELD = 111;
2555 const API_EC_PARAM_SOCIAL_FIELD = 112;
2556 const API_EC_PARAM_ALBUM_ID = 120;
2557 const API_EC_PARAM_BAD_EID = 150;
2558 const API_EC_PARAM_UNKNOWN_CITY = 151;
2561 * USER PERMISSIONS ERRORS
2563 const API_EC_PERMISSION = 200;
2564 const API_EC_PERMISSION_USER = 210;
2565 const API_EC_PERMISSION_ALBUM = 220;
2566 const API_EC_PERMISSION_PHOTO = 221;
2567 const API_EC_PERMISSION_EVENT = 290;
2568 const API_EC_PERMISSION_RSVP_EVENT = 299;
2570 const FQL_EC_PARSER = 601;
2571 const FQL_EC_UNKNOWN_FIELD = 602;
2572 const FQL_EC_UNKNOWN_TABLE = 603;
2573 const FQL_EC_NOT_INDEXABLE = 604;
2576 * DATA STORE API ERRORS
2578 const API_EC_DATA_UNKNOWN_ERROR = 800;
2579 const API_EC_DATA_INVALID_OPERATION = 801;
2580 const API_EC_DATA_QUOTA_EXCEEDED = 802;
2581 const API_EC_DATA_OBJECT_NOT_FOUND = 803;
2582 const API_EC_DATA_OBJECT_ALREADY_EXISTS = 804;
2583 const API_EC_DATA_DATABASE_ERROR = 805;
2588 const API_EC_BATCH_ALREADY_STARTED = 900;
2589 const API_EC_BATCH_NOT_STARTED = 901;
2590 const API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE = 902;
2592 public static $api_error_descriptions = array(
2593 API_EC_SUCCESS => 'Success',
2594 API_EC_UNKNOWN => 'An unknown error occurred',
2595 API_EC_SERVICE => 'Service temporarily unavailable',
2596 API_EC_METHOD => 'Unknown method',
2597 API_EC_TOO_MANY_CALLS => 'Application request limit reached',
2598 API_EC_BAD_IP => 'Unauthorized source IP address',
2599 API_EC_PARAM => 'Invalid parameter',
2600 API_EC_PARAM_API_KEY => 'Invalid API key',
2601 API_EC_PARAM_SESSION_KEY => 'Session key invalid or no longer valid',
2602 API_EC_PARAM_CALL_ID => 'Call_id must be greater than previous',
2603 API_EC_PARAM_SIGNATURE => 'Incorrect signature',
2604 API_EC_PARAM_USER_ID => 'Invalid user id',
2605 API_EC_PARAM_USER_FIELD => 'Invalid user info field',
2606 API_EC_PARAM_SOCIAL_FIELD => 'Invalid user field',
2607 API_EC_PARAM_ALBUM_ID => 'Invalid album id',
2608 API_EC_PARAM_BAD_EID => 'Invalid eid',
2609 API_EC_PARAM_UNKNOWN_CITY => 'Unknown city',
2610 API_EC_PERMISSION => 'Permissions error',
2611 API_EC_PERMISSION_USER => 'User not visible',
2612 API_EC_PERMISSION_ALBUM => 'Album not visible',
2613 API_EC_PERMISSION_PHOTO => 'Photo not visible',
2614 API_EC_PERMISSION_EVENT => 'Creating and modifying events required the extended permission create_event',
2615 API_EC_PERMISSION_RSVP_EVENT => 'RSVPing to events required the extended permission rsvp_event',
2616 FQL_EC_PARSER => 'FQL: Parser Error',
2617 FQL_EC_UNKNOWN_FIELD => 'FQL: Unknown Field',
2618 FQL_EC_UNKNOWN_TABLE => 'FQL: Unknown Table',
2619 FQL_EC_NOT_INDEXABLE => 'FQL: Statement not indexable',
2620 FQL_EC_UNKNOWN_FUNCTION => 'FQL: Attempted to call unknown function',
2621 FQL_EC_INVALID_PARAM => 'FQL: Invalid parameter passed in',
2622 API_EC_DATA_UNKNOWN_ERROR => 'Unknown data store API error',
2623 API_EC_DATA_INVALID_OPERATION => 'Invalid operation',
2624 API_EC_DATA_QUOTA_EXCEEDED => 'Data store allowable quota was exceeded',
2625 API_EC_DATA_OBJECT_NOT_FOUND => 'Specified object cannot be found',
2626 API_EC_DATA_OBJECT_ALREADY_EXISTS => 'Specified object already exists',
2627 API_EC_DATA_DATABASE_ERROR => 'A database error occurred. Please try again',
2628 API_EC_BATCH_ALREADY_STARTED => 'begin_batch already called, please make sure to call end_batch first',
2629 API_EC_BATCH_NOT_STARTED => 'end_batch called before start_batch',
2630 API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE => 'This method is not allowed in batch mode',