2 // Copyright 2004-2009 Facebook. All Rights Reserved.
4 // +---------------------------------------------------------------------------+
5 // | Facebook Platform PHP5 client |
6 // +---------------------------------------------------------------------------+
7 // | Copyright (c) 2007-2009 Facebook, Inc. |
8 // | All rights reserved. |
10 // | Redistribution and use in source and binary forms, with or without |
11 // | modification, are permitted provided that the following conditions |
14 // | 1. Redistributions of source code must retain the above copyright |
15 // | notice, this list of conditions and the following disclaimer. |
16 // | 2. Redistributions in binary form must reproduce the above copyright |
17 // | notice, this list of conditions and the following disclaimer in the |
18 // | documentation and/or other materials provided with the distribution. |
20 // | THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
21 // | IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
22 // | OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
23 // | IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
24 // | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
25 // | NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
26 // | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
27 // | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
28 // | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
29 // | THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
30 // +---------------------------------------------------------------------------+
31 // | For help with this library, contact developers-help@facebook.com |
32 // +---------------------------------------------------------------------------+
35 include_once 'jsonwrapper/jsonwrapper.php';
37 class FacebookRestClient {
41 // to save making the friends.get api call, this will get prepopulated on
45 // to save making the pages.isAppAdded api call, this will get prepopulated
49 // we don't pass friends list to iframes, but we want to make
50 // friends_get really simple in the canvas_user (non-logged in) case.
51 // So we use the canvas_user as default arg to friends_get
55 private $pending_batch;
56 private $call_as_apikey;
57 private $use_curl_if_available;
59 const BATCH_MODE_DEFAULT = 0;
60 const BATCH_MODE_SERVER_PARALLEL = 0;
61 const BATCH_MODE_SERIAL_ONLY = 2;
65 * @param string $session_key if you haven't gotten a session key yet, leave
66 * this as null and then set it later by just
67 * directly accessing the $session_key member
70 public function __construct($api_key, $secret, $session_key=null) {
71 $this->secret = $secret;
72 $this->session_key = $session_key;
73 $this->api_key = $api_key;
74 $this->batch_mode = FacebookRestClient::BATCH_MODE_DEFAULT;
75 $this->last_call_id = 0;
76 $this->call_as_apikey = '';
77 $this->use_curl_if_available = true;
78 $this->server_addr = Facebook::get_facebook_url('api') . '/restserver.php';
80 if (!empty($GLOBALS['facebook_config']['debug'])) {
83 <script type="text/javascript">
84 var types = ['params', 'xml', 'php', 'sxml'];
85 function getStyle(elem, style) {
87 return elem.getStyle(style);
89 return elem.style[style];
92 function setStyle(elem, style, value) {
94 elem.setStyle(style, value);
96 elem.style[style] = value;
99 function toggleDisplay(id, type) {
100 for (var i = 0; i < types.length; i++) {
102 var pre = document.getElementById(t + id);
104 if (t != type || getStyle(pre, 'display') == 'block') {
105 setStyle(pre, 'display', 'none');
107 setStyle(pre, 'display', 'block');
119 * Set the default user id for methods that allow the caller
120 * to pass an uid parameter to identify the target user
121 * instead of a session key. This currently applies to
122 * the user preferences methods.
124 * @param $uid int the user id
126 public function set_user($uid) {
131 * Normally, if the cURL library/PHP extension is available, it is used for
132 * HTTP transactions. This allows that behavior to be overridden, falling
133 * back to a vanilla-PHP implementation even if cURL is installed.
135 * @param $use_curl_if_available bool whether or not to use cURL if available
137 public function set_use_curl_if_available($use_curl_if_available) {
138 $this->use_curl_if_available = $use_curl_if_available;
142 * Start a batch operation.
144 public function begin_batch() {
145 if ($this->pending_batch()) {
146 $code = FacebookAPIErrorCodes::API_EC_BATCH_ALREADY_STARTED;
147 $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
148 throw new FacebookRestClientException($description, $code);
151 $this->batch_queue = array();
152 $this->pending_batch = true;
156 * End current batch operation
158 public function end_batch() {
159 if (!$this->pending_batch()) {
160 $code = FacebookAPIErrorCodes::API_EC_BATCH_NOT_STARTED;
161 $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
162 throw new FacebookRestClientException($description, $code);
165 $this->pending_batch = false;
167 $this->execute_server_side_batch();
168 $this->batch_queue = null;
172 * are we currently queueing up calls for a batch?
174 public function pending_batch() {
175 return $this->pending_batch;
178 private function execute_server_side_batch() {
179 $item_count = count($this->batch_queue);
180 $method_feed = array();
181 foreach($this->batch_queue as $batch_item) {
182 $method = $batch_item['m'];
183 $params = $batch_item['p'];
184 $this->finalize_params($method, $params);
185 $method_feed[] = $this->create_post_string($method, $params);
188 $method_feed_json = json_encode($method_feed);
191 ($this->batch_mode == FacebookRestClient::BATCH_MODE_SERIAL_ONLY);
192 $params = array('method_feed' => $method_feed_json,
193 'serial_only' => $serial_only);
194 if ($this->call_as_apikey) {
195 $params['call_as_apikey'] = $this->call_as_apikey;
198 $xml = $this->post_request('batch.run', $params);
200 $result = $this->convert_xml_to_result($xml, 'batch.run', $params);
203 if (is_array($result) && isset($result['error_code'])) {
204 throw new FacebookRestClientException($result['error_msg'],
205 $result['error_code']);
208 for($i = 0; $i < $item_count; $i++) {
209 $batch_item = $this->batch_queue[$i];
210 $batch_item_result_xml = $result[$i];
211 $batch_item_result = $this->convert_xml_to_result($batch_item_result_xml,
215 if (is_array($batch_item_result) &&
216 isset($batch_item_result['error_code'])) {
217 throw new FacebookRestClientException($batch_item_result['error_msg'],
218 $batch_item_result['error_code']);
220 $batch_item['r'] = $batch_item_result;
224 public function begin_permissions_mode($permissions_apikey) {
225 $this->call_as_apikey = $permissions_apikey;
228 public function end_permissions_mode() {
229 $this->call_as_apikey = '';
234 * If a page is loaded via HTTPS, then all images and static
235 * resources need to be printed with HTTPS urls to avoid
236 * mixed content warnings. If your page loads with an HTTPS
237 * url, then call set_use_ssl_resources to retrieve the correct
240 public function set_use_ssl_resources($is_ssl = true) {
241 $this->use_ssl_resources = $is_ssl;
245 * Returns public information for an application (as shown in the application
246 * directory) by either application ID, API key, or canvas page name.
248 * @param int $application_id (Optional) app id
249 * @param string $application_api_key (Optional) api key
250 * @param string $application_canvas_name (Optional) canvas name
252 * Exactly one argument must be specified, otherwise it is an error.
254 * @return array An array of public information about the application.
256 public function application_getPublicInfo($application_id=null,
257 $application_api_key=null,
258 $application_canvas_name=null) {
259 return $this->call_method('facebook.application.getPublicInfo',
260 array('application_id' => $application_id,
261 'application_api_key' => $application_api_key,
262 'application_canvas_name' => $application_canvas_name));
266 * Creates an authentication token to be used as part of the desktop login
267 * flow. For more information, please see
268 * http://wiki.developers.facebook.com/index.php/Auth.createToken.
270 * @return string An authentication token.
272 public function auth_createToken() {
273 return $this->call_method('facebook.auth.createToken');
277 * Returns the session information available after current user logs in.
279 * @param string $auth_token the token returned by
280 * auth_createToken or passed back to
282 * @param bool $generate_session_secret whether the session returned should
283 * include a session secret
285 * @return array An assoc array containing session_key, uid
287 public function auth_getSession($auth_token, $generate_session_secret=false) {
288 if (!$this->pending_batch()) {
289 $result = $this->call_method('facebook.auth.getSession',
290 array('auth_token' => $auth_token,
291 'generate_session_secret' => $generate_session_secret));
292 $this->session_key = $result['session_key'];
294 if (!empty($result['secret']) && !$generate_session_secret) {
295 // desktop apps have a special secret
296 $this->secret = $result['secret'];
303 * Generates a session-specific secret. This is for integration with
304 * client-side API calls, such as the JS library.
306 * @return array A session secret for the current promoted session
308 * @error API_EC_PARAM_SESSION_KEY
309 * API_EC_PARAM_UNKNOWN
311 public function auth_promoteSession() {
312 return $this->call_method('facebook.auth.promoteSession');
316 * Expires the session that is currently being used. If this call is
317 * successful, no further calls to the API (which require a session) can be
318 * made until a valid session is created.
320 * @return bool true if session expiration was successful, false otherwise
322 public function auth_expireSession() {
323 return $this->call_method('facebook.auth.expireSession');
327 * Revokes the given extended permission that the user granted at some
328 * prior time (for instance, offline_access or email). If no user is
329 * provided, it will be revoked for the user of the current session.
331 * @param string $perm The permission to revoke
332 * @param int $uid The user for whom to revoke the permission.
334 public function auth_revokeExtendedPermission($perm, $uid=null) {
335 return $this->call_method('facebook.auth.revokeExtendedPermission',
336 array('perm' => $perm, 'uid' => $uid));
340 * Revokes the user's agreement to the Facebook Terms of Service for your
341 * application. If you call this method for one of your users, you will no
342 * longer be able to make API requests on their behalf until they again
343 * authorize your application. Use with care. Note that if this method is
344 * called without a user parameter, then it will revoke access for the
345 * current session's user.
347 * @param int $uid (Optional) User to revoke
349 * @return bool true if revocation succeeds, false otherwise
351 public function auth_revokeAuthorization($uid=null) {
352 return $this->call_method('facebook.auth.revokeAuthorization',
353 array('uid' => $uid));
357 * Get public key that is needed to verify digital signature
358 * an app may pass to other apps. The public key is only used by
359 * other apps for verification purposes.
360 * @param string API key of an app
361 * @return string The public key for the app.
363 public function auth_getAppPublicKey($target_app_key) {
364 return $this->call_method('facebook.auth.getAppPublicKey',
365 array('target_app_key' => $target_app_key));
369 * Get a structure that can be passed to another app
370 * as proof of session. The other app can verify it using public
373 * @return signed public session data structure.
375 public function auth_getSignedPublicSessionData() {
376 return $this->call_method('facebook.auth.getSignedPublicSessionData',
381 * Returns the number of unconnected friends that exist in this application.
382 * This number is determined based on the accounts registered through
383 * connect.registerUsers() (see below).
385 public function connect_getUnconnectedFriendsCount() {
386 return $this->call_method('facebook.connect.getUnconnectedFriendsCount',
391 * This method is used to create an association between an external user
392 * account and a Facebook user account, as per Facebook Connect.
394 * This method takes an array of account data, including a required email_hash
395 * and optional account data. For each connected account, if the user exists,
396 * the information is added to the set of the user's connected accounts.
397 * If the user has already authorized the site, the connected account is added
398 * in the confirmed state. If the user has not yet authorized the site, the
399 * connected account is added in the pending state.
401 * This is designed to help Facebook Connect recognize when two Facebook
402 * friends are both members of a external site, but perhaps are not aware of
403 * it. The Connect dialog (see fb:connect-form) is used when friends can be
404 * identified through these email hashes. See the following url for details:
406 * http://wiki.developers.facebook.com/index.php/Connect.registerUsers
408 * @param mixed $accounts A (JSON-encoded) array of arrays, where each array
409 * has three properties:
410 * 'email_hash' (req) - public email hash of account
411 * 'account_id' (opt) - remote account id;
412 * 'account_url' (opt) - url to remote account;
414 * @return array The list of email hashes for the successfully registered
417 public function connect_registerUsers($accounts) {
418 return $this->call_method('facebook.connect.registerUsers',
419 array('accounts' => $accounts));
423 * Unregisters a set of accounts registered using connect.registerUsers.
425 * @param array $email_hashes The (JSON-encoded) list of email hashes to be
428 * @return array The list of email hashes which have been successfully
431 public function connect_unregisterUsers($email_hashes) {
432 return $this->call_method('facebook.connect.unregisterUsers',
433 array('email_hashes' => $email_hashes));
437 * Returns events according to the filters specified.
439 * @param int $uid (Optional) User associated with events. A null
440 * parameter will default to the session user.
441 * @param array/string $eids (Optional) Filter by these event
442 * ids. A null parameter will get all events for
443 * the user. (A csv list will work but is deprecated)
444 * @param int $start_time (Optional) Filter with this unix time as lower
445 * bound. A null or zero parameter indicates no
447 * @param int $end_time (Optional) Filter with this UTC as upper bound.
448 * A null or zero parameter indicates no upper
450 * @param string $rsvp_status (Optional) Only show events where the given uid
451 * has this rsvp status. This only works if you
452 * have specified a value for $uid. Values are as
453 * in events.getMembers. Null indicates to ignore
454 * rsvp status when filtering.
456 * @return array The events matching the query.
458 public function &events_get($uid=null,
463 return $this->call_method('facebook.events.get',
466 'start_time' => $start_time,
467 'end_time' => $end_time,
468 'rsvp_status' => $rsvp_status));
472 * Returns membership list data associated with an event.
474 * @param int $eid event id
476 * @return array An assoc array of four membership lists, with keys
477 * 'attending', 'unsure', 'declined', and 'not_replied'
479 public function &events_getMembers($eid) {
480 return $this->call_method('facebook.events.getMembers',
481 array('eid' => $eid));
485 * RSVPs the current user to this event.
487 * @param int $eid event id
488 * @param string $rsvp_status 'attending', 'unsure', or 'declined'
490 * @return bool true if successful
492 public function &events_rsvp($eid, $rsvp_status) {
493 return $this->call_method('facebook.events.rsvp',
496 'rsvp_status' => $rsvp_status));
500 * Cancels an event. Only works for events where application is the admin.
502 * @param int $eid event id
503 * @param string $cancel_message (Optional) message to send to members of
504 * the event about why it is cancelled
506 * @return bool true if successful
508 public function &events_cancel($eid, $cancel_message='') {
509 return $this->call_method('facebook.events.cancel',
511 'cancel_message' => $cancel_message));
515 * Creates an event on behalf of the user is there is a session, otherwise on
516 * behalf of app. Successful creation guarantees app will be admin.
518 * @param assoc array $event_info json encoded event information
520 * @return int event id
522 public function &events_create($event_info) {
523 return $this->call_method('facebook.events.create',
524 array('event_info' => $event_info));
528 * Edits an existing event. Only works for events where application is admin.
530 * @param int $eid event id
531 * @param assoc array $event_info json encoded event information
533 * @return bool true if successful
535 public function &events_edit($eid, $event_info) {
536 return $this->call_method('facebook.events.edit',
538 'event_info' => $event_info));
542 * Fetches and re-caches the image stored at the given URL, for use in images
543 * published to non-canvas pages via the API (for example, to user profiles
544 * via profile.setFBML, or to News Feed via feed.publishUserAction).
546 * @param string $url The absolute URL from which to refresh the image.
548 * @return bool true on success
550 public function &fbml_refreshImgSrc($url) {
551 return $this->call_method('facebook.fbml.refreshImgSrc',
552 array('url' => $url));
556 * Fetches and re-caches the content stored at the given URL, for use in an
559 * @param string $url The absolute URL from which to fetch content. This URL
560 * should be used in a fb:ref FBML tag.
562 * @return bool true on success
564 public function &fbml_refreshRefUrl($url) {
565 return $this->call_method('facebook.fbml.refreshRefUrl',
566 array('url' => $url));
570 * Lets you insert text strings in their native language into the Facebook
571 * Translations database so they can be translated.
573 * @param array $native_strings An array of maps, where each map has a 'text'
574 * field and a 'description' field.
576 * @return int Number of strings uploaded.
578 public function &fbml_uploadNativeStrings($native_strings) {
579 return $this->call_method('facebook.fbml.uploadNativeStrings',
580 array('native_strings' => json_encode($native_strings)));
584 * Associates a given "handle" with FBML markup so that the handle can be
585 * used within the fb:ref FBML tag. A handle is unique within an application
586 * and allows an application to publish identical FBML to many user profiles
587 * and do subsequent updates without having to republish FBML on behalf of
590 * @param string $handle The handle to associate with the given FBML.
591 * @param string $fbml The FBML to associate with the given handle.
593 * @return bool true on success
595 public function &fbml_setRefHandle($handle, $fbml) {
596 return $this->call_method('facebook.fbml.setRefHandle',
597 array('handle' => $handle, 'fbml' => $fbml));
601 * Register custom tags for the application. Custom tags can be used
602 * to extend the set of tags available to applications in FBML
605 * Before you call this function,
606 * make sure you read the full documentation at
608 * http://wiki.developers.facebook.com/index.php/Fbml.RegisterCustomTags
610 * IMPORTANT: This function overwrites the values of
611 * existing tags if the names match. Use this function with care because
612 * it may break the FBML of any application that is using the
613 * existing version of the tags.
615 * @param mixed $tags an array of tag objects (the full description is on the
618 * @return int the number of tags that were registered
620 public function &fbml_registerCustomTags($tags) {
621 $tags = json_encode($tags);
622 return $this->call_method('facebook.fbml.registerCustomTags',
623 array('tags' => $tags));
627 * Get the custom tags for an application. If $app_id
628 * is not specified, the calling app's tags are returned.
629 * If $app_id is different from the id of the calling app,
630 * only the app's public tags are returned.
631 * The return value is an array of the same type as
632 * the $tags parameter of fbml_registerCustomTags().
634 * @param int $app_id the application's id (optional)
636 * @return mixed an array containing the custom tag objects
638 public function &fbml_getCustomTags($app_id = null) {
639 return $this->call_method('facebook.fbml.getCustomTags',
640 array('app_id' => $app_id));
645 * Delete custom tags the application has registered. If
646 * $tag_names is null, all the application's custom tags will be
649 * IMPORTANT: If your application has registered public tags
650 * that other applications may be using, don't delete those tags!
651 * Doing so can break the FBML ofapplications that are using them.
653 * @param array $tag_names the names of the tags to delete (optinal)
654 * @return bool true on success
656 public function &fbml_deleteCustomTags($tag_names = null) {
657 return $this->call_method('facebook.fbml.deleteCustomTags',
658 array('tag_names' => json_encode($tag_names)));
664 * This method is deprecated for calls made on behalf of users. This method
665 * works only for publishing stories on a Facebook Page that has installed
666 * your application. To publish stories to a user's profile, use
667 * feed.publishUserAction instead.
669 * For more details on this call, please visit the wiki page:
671 * http://wiki.developers.facebook.com/index.php/Feed.publishTemplatizedAction
673 public function &feed_publishTemplatizedAction($title_template,
687 $page_actor_id=null) {
688 return $this->call_method('facebook.feed.publishTemplatizedAction',
689 array('title_template' => $title_template,
690 'title_data' => $title_data,
691 'body_template' => $body_template,
692 'body_data' => $body_data,
693 'body_general' => $body_general,
694 'image_1' => $image_1,
695 'image_1_link' => $image_1_link,
696 'image_2' => $image_2,
697 'image_2_link' => $image_2_link,
698 'image_3' => $image_3,
699 'image_3_link' => $image_3_link,
700 'image_4' => $image_4,
701 'image_4_link' => $image_4_link,
702 'target_ids' => $target_ids,
703 'page_actor_id' => $page_actor_id));
707 * Registers a template bundle. Template bundles are somewhat involved, so
708 * it's recommended you check out the wiki for more details:
710 * http://wiki.developers.facebook.com/index.php/Feed.registerTemplateBundle
712 * @return string A template bundle id
714 public function &feed_registerTemplateBundle($one_line_story_templates,
715 $short_story_templates = array(),
716 $full_story_template = null,
717 $action_links = array()) {
719 $one_line_story_templates = json_encode($one_line_story_templates);
721 if (!empty($short_story_templates)) {
722 $short_story_templates = json_encode($short_story_templates);
725 if (isset($full_story_template)) {
726 $full_story_template = json_encode($full_story_template);
729 if (isset($action_links)) {
730 $action_links = json_encode($action_links);
733 return $this->call_method('facebook.feed.registerTemplateBundle',
734 array('one_line_story_templates' => $one_line_story_templates,
735 'short_story_templates' => $short_story_templates,
736 'full_story_template' => $full_story_template,
737 'action_links' => $action_links));
741 * Retrieves the full list of active template bundles registered by the
742 * requesting application.
744 * @return array An array of template bundles
746 public function &feed_getRegisteredTemplateBundles() {
747 return $this->call_method('facebook.feed.getRegisteredTemplateBundles',
752 * Retrieves information about a specified template bundle previously
753 * registered by the requesting application.
755 * @param string $template_bundle_id The template bundle id
757 * @return array Template bundle
759 public function &feed_getRegisteredTemplateBundleByID($template_bundle_id) {
760 return $this->call_method('facebook.feed.getRegisteredTemplateBundleByID',
761 array('template_bundle_id' => $template_bundle_id));
765 * Deactivates a previously registered template bundle.
767 * @param string $template_bundle_id The template bundle id
769 * @return bool true on success
771 public function &feed_deactivateTemplateBundleByID($template_bundle_id) {
772 return $this->call_method('facebook.feed.deactivateTemplateBundleByID',
773 array('template_bundle_id' => $template_bundle_id));
776 const STORY_SIZE_ONE_LINE = 1;
777 const STORY_SIZE_SHORT = 2;
778 const STORY_SIZE_FULL = 4;
781 * Publishes a story on behalf of the user owning the session, using the
782 * specified template bundle. This method requires an active session key in
783 * order to be called.
785 * The parameters to this method ($templata_data in particular) are somewhat
786 * involved. It's recommended you visit the wiki for details:
788 * http://wiki.developers.facebook.com/index.php/Feed.publishUserAction
790 * @param int $template_bundle_id A template bundle id previously registered
791 * @param array $template_data See wiki article for syntax
792 * @param array $target_ids (Optional) An array of friend uids of the
793 * user who shared in this action.
794 * @param string $body_general (Optional) Additional markup that extends
795 * the body of a short story.
796 * @param int $story_size (Optional) A story size (see above)
797 * @param string $user_message (Optional) A user message for a short
800 * @return bool true on success
802 public function &feed_publishUserAction(
803 $template_bundle_id, $template_data, $target_ids='', $body_general='',
804 $story_size=FacebookRestClient::STORY_SIZE_ONE_LINE,
807 if (is_array($template_data)) {
808 $template_data = json_encode($template_data);
809 } // allow client to either pass in JSON or an assoc that we JSON for them
811 if (is_array($target_ids)) {
812 $target_ids = json_encode($target_ids);
813 $target_ids = trim($target_ids, "[]"); // we don't want square brackets
816 return $this->call_method('facebook.feed.publishUserAction',
817 array('template_bundle_id' => $template_bundle_id,
818 'template_data' => $template_data,
819 'target_ids' => $target_ids,
820 'body_general' => $body_general,
821 'story_size' => $story_size,
822 'user_message' => $user_message));
827 * Publish a post to the user's stream.
829 * @param $message the user's message
830 * @param $attachment the post's attachment (optional)
831 * @param $action links the post's action links (optional)
832 * @param $target_id the user on whose wall the post will be posted
834 * @param $uid the actor (defaults to session user)
835 * @return string the post id
837 public function stream_publish(
838 $message, $attachment = null, $action_links = null, $target_id = null,
841 return $this->call_method(
842 'facebook.stream.publish',
843 array('message' => $message,
844 'attachment' => $attachment,
845 'action_links' => $action_links,
846 'target_id' => $target_id,
847 'uid' => $this->get_uid($uid)));
851 * Remove a post from the user's stream.
852 * Currently, you may only remove stories you application created.
854 * @param $post_id the post id
855 * @param $uid the actor (defaults to session user)
858 public function stream_remove($post_id, $uid = null) {
859 return $this->call_method(
860 'facebook.stream.remove',
861 array('post_id' => $post_id,
862 'uid' => $this->get_uid($uid)));
866 * Add a comment to a stream post
868 * @param $post_id the post id
869 * @param $comment the comment text
870 * @param $uid the actor (defaults to session user)
871 * @return string the id of the created comment
873 public function stream_addComment($post_id, $comment, $uid = null) {
874 return $this->call_method(
875 'facebook.stream.addComment',
876 array('post_id' => $post_id,
877 'comment' => $comment,
878 'uid' => $this->get_uid($uid)));
883 * Remove a comment from a stream post
885 * @param $comment_id the comment id
886 * @param $uid the actor (defaults to session user)
889 public function stream_removeComment($comment_id, $uid = null) {
890 return $this->call_method(
891 'facebook.stream.removeComment',
892 array('comment_id' => $comment_id,
893 'uid' => $this->get_uid($uid)));
897 * Add a like to a stream post
899 * @param $post_id the post id
900 * @param $uid the actor (defaults to session user)
903 public function stream_addLike($post_id, $uid = null) {
904 return $this->call_method(
905 'facebook.stream.addLike',
906 array('post_id' => $post_id,
907 'uid' => $this->get_uid($uid)));
911 * Remove a like from a stream post
913 * @param $post_id the post id
914 * @param $uid the actor (defaults to session user)
917 public function stream_removeLike($post_id, $uid = null) {
918 return $this->call_method(
919 'facebook.stream.removeLike',
920 array('post_id' => $post_id,
921 'uid' => $this->get_uid($uid)));
925 * For the current user, retrieves stories generated by the user's friends
926 * while using this application. This can be used to easily create a
927 * "News Feed" like experience.
929 * @return array An array of feed story objects.
931 public function &feed_getAppFriendStories() {
932 return $this->call_method('facebook.feed.getAppFriendStories');
936 * Makes an FQL query. This is a generalized way of accessing all the data
937 * in the API, as an alternative to most of the other method calls. More
938 * info at http://developers.facebook.com/documentation.php?v=1.0&doc=fql
940 * @param string $query the query to evaluate
942 * @return array generalized array representing the results
944 public function &fql_query($query) {
945 return $this->call_method('facebook.fql.query',
946 array('query' => $query));
950 * Returns whether or not pairs of users are friends.
951 * Note that the Facebook friend relationship is symmetric.
953 * @param array/string $uids1 list of ids (id_1, id_2,...)
954 * of some length X (csv is deprecated)
955 * @param array/string $uids2 list of ids (id_A, id_B,...)
956 * of SAME length X (csv is deprecated)
958 * @return array An array with uid1, uid2, and bool if friends, e.g.:
959 * array(0 => array('uid1' => id_1, 'uid2' => id_A, 'are_friends' => 1),
960 * 1 => array('uid1' => id_2, 'uid2' => id_B, 'are_friends' => 0)
963 * API_EC_PARAM_USER_ID_LIST
965 public function &friends_areFriends($uids1, $uids2) {
966 return $this->call_method('facebook.friends.areFriends',
967 array('uids1' => $uids1,
972 * Returns the friends of the current session user.
974 * @param int $flid (Optional) Only return friends on this friend list.
975 * @param int $uid (Optional) Return friends for this user.
977 * @return array An array of friends
979 public function &friends_get($flid=null, $uid = null) {
980 if (isset($this->friends_list)) {
981 return $this->friends_list;
984 if (!$uid && isset($this->canvas_user)) {
985 $uid = $this->canvas_user;
988 $params['uid'] = $uid;
991 $params['flid'] = $flid;
993 return $this->call_method('facebook.friends.get', $params);
998 * Returns the set of friend lists for the current session user.
1000 * @return array An array of friend list objects
1002 public function &friends_getLists() {
1003 return $this->call_method('facebook.friends.getLists');
1007 * Returns the friends of the session user, who are also users
1008 * of the calling application.
1010 * @return array An array of friends also using the app
1012 public function &friends_getAppUsers() {
1013 return $this->call_method('facebook.friends.getAppUsers');
1017 * Returns groups according to the filters specified.
1019 * @param int $uid (Optional) User associated with groups. A null
1020 * parameter will default to the session user.
1021 * @param array/string $gids (Optional) Array of group ids to query. A null
1022 * parameter will get all groups for the user.
1023 * (csv is deprecated)
1025 * @return array An array of group objects
1027 public function &groups_get($uid, $gids) {
1028 return $this->call_method('facebook.groups.get',
1029 array('uid' => $uid,
1034 * Returns the membership list of a group.
1036 * @param int $gid Group id
1038 * @return array An array with four membership lists, with keys 'members',
1039 * 'admins', 'officers', and 'not_replied'
1041 public function &groups_getMembers($gid) {
1042 return $this->call_method('facebook.groups.getMembers',
1043 array('gid' => $gid));
1047 * Returns cookies according to the filters specified.
1049 * @param int $uid User for which the cookies are needed.
1050 * @param string $name (Optional) A null parameter will get all cookies
1053 * @return array Cookies! Nom nom nom nom nom.
1055 public function data_getCookies($uid, $name) {
1056 return $this->call_method('facebook.data.getCookies',
1057 array('uid' => $uid,
1062 * Sets cookies according to the params specified.
1064 * @param int $uid User for which the cookies are needed.
1065 * @param string $name Name of the cookie
1066 * @param string $value (Optional) if expires specified and is in the past
1067 * @param int $expires (Optional) Expiry time
1068 * @param string $path (Optional) Url path to associate with (default is /)
1070 * @return bool true on success
1072 public function data_setCookie($uid, $name, $value, $expires, $path) {
1073 return $this->call_method('facebook.data.setCookie',
1074 array('uid' => $uid,
1077 'expires' => $expires,
1082 * Retrieves links posted by the given user.
1084 * @param int $uid The user whose links you wish to retrieve
1085 * @param int $limit The maximimum number of links to retrieve
1086 * @param array $link_ids (Optional) Array of specific link
1087 * IDs to retrieve by this user
1089 * @return array An array of links.
1091 public function &links_get($uid, $limit, $link_ids = null) {
1092 return $this->call_method('links.get',
1093 array('uid' => $uid,
1095 'link_ids' => $link_ids));
1099 * Posts a link on Facebook.
1101 * @param string $url URL/link you wish to post
1102 * @param string $comment (Optional) A comment about this link
1103 * @param int $uid (Optional) User ID that is posting this link;
1104 * defaults to current session user
1108 public function &links_post($url, $comment='', $uid = null) {
1109 return $this->call_method('links.post',
1110 array('uid' => $uid,
1112 'comment' => $comment));
1120 * Checks API-access granted by self to the specified application.
1122 * @param string $permissions_apikey Other application key
1124 * @return array API methods/namespaces which are allowed access
1126 public function permissions_checkGrantedApiAccess($permissions_apikey) {
1127 return $this->call_method('facebook.permissions.checkGrantedApiAccess',
1128 array('permissions_apikey' => $permissions_apikey));
1132 * Checks API-access granted to self by the specified application.
1134 * @param string $permissions_apikey Other application key
1136 * @return array API methods/namespaces which are allowed access
1138 public function permissions_checkAvailableApiAccess($permissions_apikey) {
1139 return $this->call_method('facebook.permissions.checkAvailableApiAccess',
1140 array('permissions_apikey' => $permissions_apikey));
1144 * Grant API-access to the specified methods/namespaces to the specified
1147 * @param string $permissions_apikey Other application key
1148 * @param array(string) $method_arr (Optional) API methods/namespaces
1151 * @return array API methods/namespaces which are allowed access
1153 public function permissions_grantApiAccess($permissions_apikey, $method_arr) {
1154 return $this->call_method('facebook.permissions.grantApiAccess',
1155 array('permissions_apikey' => $permissions_apikey,
1156 'method_arr' => $method_arr));
1160 * Revoke API-access granted to the specified application.
1162 * @param string $permissions_apikey Other application key
1164 * @return bool true on success
1166 public function permissions_revokeApiAccess($permissions_apikey) {
1167 return $this->call_method('facebook.permissions.revokeApiAccess',
1168 array('permissions_apikey' => $permissions_apikey));
1172 * Creates a note with the specified title and content.
1174 * @param string $title Title of the note.
1175 * @param string $content Content of the note.
1176 * @param int $uid (Optional) The user for whom you are creating a
1177 * note; defaults to current session user
1179 * @return int The ID of the note that was just created.
1181 public function ¬es_create($title, $content, $uid = null) {
1182 return $this->call_method('notes.create',
1183 array('uid' => $uid,
1185 'content' => $content));
1189 * Deletes the specified note.
1191 * @param int $note_id ID of the note you wish to delete
1192 * @param int $uid (Optional) Owner of the note you wish to delete;
1193 * defaults to current session user
1197 public function ¬es_delete($note_id, $uid = null) {
1198 return $this->call_method('notes.delete',
1199 array('uid' => $uid,
1200 'note_id' => $note_id));
1204 * Edits a note, replacing its title and contents with the title
1205 * and contents specified.
1207 * @param int $note_id ID of the note you wish to edit
1208 * @param string $title Replacement title for the note
1209 * @param string $content Replacement content for the note
1210 * @param int $uid (Optional) Owner of the note you wish to edit;
1211 * defaults to current session user
1215 public function ¬es_edit($note_id, $title, $content, $uid = null) {
1216 return $this->call_method('notes.edit',
1217 array('uid' => $uid,
1218 'note_id' => $note_id,
1220 'content' => $content));
1224 * Retrieves all notes by a user. If note_ids are specified,
1225 * retrieves only those specific notes by that user.
1227 * @param int $uid User whose notes you wish to retrieve
1228 * @param array $note_ids (Optional) List of specific note
1229 * IDs by this user to retrieve
1231 * @return array A list of all of the given user's notes, or an empty list
1232 * if the viewer lacks permissions or if there are no visible
1235 public function ¬es_get($uid, $note_ids = null) {
1237 return $this->call_method('notes.get',
1238 array('uid' => $uid,
1239 'note_ids' => $note_ids));
1244 * Returns the outstanding notifications for the session user.
1246 * @return array An assoc array of notification count objects for
1247 * 'messages', 'pokes' and 'shares', a uid list of
1248 * 'friend_requests', a gid list of 'group_invites',
1249 * and an eid list of 'event_invites'
1251 public function ¬ifications_get() {
1252 return $this->call_method('facebook.notifications.get');
1256 * Sends a notification to the specified users.
1258 * @return A comma separated list of successful recipients
1260 * API_EC_PARAM_USER_ID_LIST
1262 public function ¬ifications_send($to_ids, $notification, $type) {
1263 return $this->call_method('facebook.notifications.send',
1264 array('to_ids' => $to_ids,
1265 'notification' => $notification,
1270 * Sends an email to the specified user of the application.
1272 * @param array/string $recipients array of ids of the recipients (csv is deprecated)
1273 * @param string $subject subject of the email
1274 * @param string $text (plain text) body of the email
1275 * @param string $fbml fbml markup for an html version of the email
1277 * @return string A comma separated list of successful recipients
1279 * API_EC_PARAM_USER_ID_LIST
1281 public function ¬ifications_sendEmail($recipients,
1285 return $this->call_method('facebook.notifications.sendEmail',
1286 array('recipients' => $recipients,
1287 'subject' => $subject,
1293 * Returns the requested info fields for the requested set of pages.
1295 * @param array/string $page_ids an array of page ids (csv is deprecated)
1296 * @param array/string $fields an array of strings describing the
1297 * info fields desired (csv is deprecated)
1298 * @param int $uid (Optional) limit results to pages of which this
1300 * @param string type limits results to a particular type of page.
1302 * @return array An array of pages
1304 public function &pages_getInfo($page_ids, $fields, $uid, $type) {
1305 return $this->call_method('facebook.pages.getInfo',
1306 array('page_ids' => $page_ids,
1307 'fields' => $fields,
1313 * Returns true if the given user is an admin for the passed page.
1315 * @param int $page_id target page id
1316 * @param int $uid (Optional) user id (defaults to the logged-in user)
1318 * @return bool true on success
1320 public function &pages_isAdmin($page_id, $uid = null) {
1321 return $this->call_method('facebook.pages.isAdmin',
1322 array('page_id' => $page_id,
1327 * Returns whether or not the given page has added the application.
1329 * @param int $page_id target page id
1331 * @return bool true on success
1333 public function &pages_isAppAdded($page_id) {
1334 return $this->call_method('facebook.pages.isAppAdded',
1335 array('page_id' => $page_id));
1339 * Returns true if logged in user is a fan for the passed page.
1341 * @param int $page_id target page id
1342 * @param int $uid user to compare. If empty, the logged in user.
1344 * @return bool true on success
1346 public function &pages_isFan($page_id, $uid = null) {
1347 return $this->call_method('facebook.pages.isFan',
1348 array('page_id' => $page_id,
1353 * Adds a tag with the given information to a photo. See the wiki for details:
1355 * http://wiki.developers.facebook.com/index.php/Photos.addTag
1357 * @param int $pid The ID of the photo to be tagged
1358 * @param int $tag_uid The ID of the user being tagged. You must specify
1359 * either the $tag_uid or the $tag_text parameter
1360 * (unless $tags is specified).
1361 * @param string $tag_text Some text identifying the person being tagged.
1362 * You must specify either the $tag_uid or $tag_text
1363 * parameter (unless $tags is specified).
1364 * @param float $x The horizontal position of the tag, as a
1365 * percentage from 0 to 100, from the left of the
1367 * @param float $y The vertical position of the tag, as a percentage
1368 * from 0 to 100, from the top of the photo.
1369 * @param array $tags (Optional) An array of maps, where each map
1370 * can contain the tag_uid, tag_text, x, and y
1371 * parameters defined above. If specified, the
1372 * individual arguments are ignored.
1373 * @param int $owner_uid (Optional) The user ID of the user whose photo
1374 * you are tagging. If this parameter is not
1375 * specified, then it defaults to the session user.
1377 * @return bool true on success
1379 public function &photos_addTag($pid,
1386 return $this->call_method('facebook.photos.addTag',
1387 array('pid' => $pid,
1388 'tag_uid' => $tag_uid,
1389 'tag_text' => $tag_text,
1392 'tags' => (is_array($tags)) ? json_encode($tags) : null,
1393 'owner_uid' => $this->get_uid($owner_uid)));
1397 * Creates and returns a new album owned by the specified user or the current
1400 * @param string $name The name of the album.
1401 * @param string $description (Optional) A description of the album.
1402 * @param string $location (Optional) A description of the location.
1403 * @param string $visible (Optional) A privacy setting for the album.
1404 * One of 'friends', 'friends-of-friends',
1405 * 'networks', or 'everyone'. Default 'everyone'.
1406 * @param int $uid (Optional) User id for creating the album; if
1407 * not specified, the session user is used.
1409 * @return array An album object
1411 public function &photos_createAlbum($name,
1416 return $this->call_method('facebook.photos.createAlbum',
1417 array('name' => $name,
1418 'description' => $description,
1419 'location' => $location,
1420 'visible' => $visible,
1421 'uid' => $this->get_uid($uid)));
1425 * Returns photos according to the filters specified.
1427 * @param int $subj_id (Optional) Filter by uid of user tagged in the photos.
1428 * @param int $aid (Optional) Filter by an album, as returned by
1430 * @param array/string $pids (Optional) Restrict to an array of pids
1431 * (csv is deprecated)
1433 * Note that at least one of these parameters needs to be specified, or an
1434 * error is returned.
1436 * @return array An array of photo objects.
1438 public function &photos_get($subj_id, $aid, $pids) {
1439 return $this->call_method('facebook.photos.get',
1440 array('subj_id' => $subj_id, 'aid' => $aid, 'pids' => $pids));
1444 * Returns the albums created by the given user.
1446 * @param int $uid (Optional) The uid of the user whose albums you want.
1447 * A null will return the albums of the session user.
1448 * @param string $aids (Optional) An array of aids to restrict
1449 * the query. (csv is deprecated)
1451 * Note that at least one of the (uid, aids) parameters must be specified.
1453 * @returns an array of album objects.
1455 public function &photos_getAlbums($uid, $aids) {
1456 return $this->call_method('facebook.photos.getAlbums',
1457 array('uid' => $uid,
1462 * Returns the tags on all photos specified.
1464 * @param string $pids A list of pids to query
1466 * @return array An array of photo tag objects, which include pid,
1467 * subject uid, and two floating-point numbers (xcoord, ycoord)
1468 * for tag pixel location.
1470 public function &photos_getTags($pids) {
1471 return $this->call_method('facebook.photos.getTags',
1472 array('pids' => $pids));
1478 * @param string $file The location of the photo on the local filesystem.
1479 * @param int $aid (Optional) The album into which to upload the
1481 * @param string $caption (Optional) A caption for the photo.
1482 * @param int uid (Optional) The user ID of the user whose photo you
1485 * @return array An array of user objects
1487 public function photos_upload($file, $aid=null, $caption=null, $uid=null) {
1488 return $this->call_upload_method('facebook.photos.upload',
1489 array('aid' => $aid,
1490 'caption' => $caption,
1499 * @param string $file The location of the video on the local filesystem.
1500 * @param string $title (Optional) A title for the video. Titles over 65 characters in length will be truncated.
1501 * @param string $description (Optional) A description for the video.
1503 * @return array An array with the video's ID, title, description, and a link to view it on Facebook.
1505 public function video_upload($file, $title=null, $description=null) {
1506 return $this->call_upload_method('facebook.video.upload',
1507 array('title' => $title,
1508 'description' => $description),
1510 Facebook::get_facebook_url('api-video') . '/restserver.php');
1514 * Returns an array with the video limitations imposed on the current session's
1515 * associated user. Maximum length is measured in seconds; maximum size is
1516 * measured in bytes.
1518 * @return array Array with "length" and "size" keys
1520 public function &video_getUploadLimits() {
1521 return $this->call_method('facebook.video.getUploadLimits');
1525 * Returns the requested info fields for the requested set of users.
1527 * @param array/string $uids An array of user ids (csv is deprecated)
1528 * @param array/string $fields An array of info field names desired (csv is deprecated)
1530 * @return array An array of user objects
1532 public function &users_getInfo($uids, $fields) {
1533 return $this->call_method('facebook.users.getInfo',
1534 array('uids' => $uids,
1535 'fields' => $fields));
1539 * Returns the requested info fields for the requested set of users. A
1540 * session key must not be specified. Only data about users that have
1541 * authorized your application will be returned.
1543 * Check the wiki for fields that can be queried through this API call.
1544 * Data returned from here should not be used for rendering to application
1545 * users, use users.getInfo instead, so that proper privacy rules will be
1548 * @param array/string $uids An array of user ids (csv is deprecated)
1549 * @param array/string $fields An array of info field names desired (csv is deprecated)
1551 * @return array An array of user objects
1553 public function &users_getStandardInfo($uids, $fields) {
1554 return $this->call_method('facebook.users.getStandardInfo',
1555 array('uids' => $uids,
1556 'fields' => $fields));
1560 * Returns the user corresponding to the current session object.
1562 * @return integer User id
1564 public function &users_getLoggedInUser() {
1565 return $this->call_method('facebook.users.getLoggedInUser');
1569 * Returns 1 if the user has the specified permission, 0 otherwise.
1570 * http://wiki.developers.facebook.com/index.php/Users.hasAppPermission
1572 * @return integer 1 or 0
1574 public function &users_hasAppPermission($ext_perm, $uid=null) {
1575 return $this->call_method('facebook.users.hasAppPermission',
1576 array('ext_perm' => $ext_perm, 'uid' => $uid));
1580 * Returns whether or not the user corresponding to the current
1581 * session object has the give the app basic authorization.
1583 * @return boolean true if the user has authorized the app
1585 public function &users_isAppUser($uid=null) {
1586 if ($uid === null && isset($this->is_user)) {
1587 return $this->is_user;
1590 return $this->call_method('facebook.users.isAppUser', array('uid' => $uid));
1594 * Returns whether or not the user corresponding to the current
1595 * session object is verified by Facebook. See the documentation
1596 * for Users.isVerified for details.
1598 * @return boolean true if the user is verified
1600 public function &users_isVerified() {
1601 return $this->call_method('facebook.users.isVerified');
1605 * Sets the users' current status message. Message does NOT contain the
1606 * word "is" , so make sure to include a verb.
1608 * Example: setStatus("is loving the API!")
1609 * will produce the status "Luke is loving the API!"
1611 * @param string $status text-only message to set
1612 * @param int $uid user to set for (defaults to the
1614 * @param bool $clear whether or not to clear the status,
1615 * instead of setting it
1616 * @param bool $status_includes_verb if true, the word "is" will *not* be
1617 * prepended to the status message
1621 public function &users_setStatus($status,
1624 $status_includes_verb = true) {
1626 'status' => $status,
1629 'status_includes_verb' => $status_includes_verb,
1631 return $this->call_method('facebook.users.setStatus', $args);
1635 * Gets the stream on behalf of a user using a set of users. This
1636 * call will return the latest $limit queries between $start_time
1639 * @param int $viewer_id user making the call (def: session)
1640 * @param array $source_ids users/pages to look at (def: all connections)
1641 * @param int $start_time start time to look for stories (def: 1 day ago)
1642 * @param int $end_time end time to look for stories (def: now)
1643 * @param int $limit number of stories to attempt to fetch (def: 30)
1644 * @param string $filter_key key returned by stream.getFilters to fetch
1647 * 'posts' => array of posts,
1648 * 'profiles' => array of profile metadata of users/pages in posts
1649 * 'albums' => array of album metadata in posts
1652 public function &stream_get($viewer_id = null,
1659 'viewer_id' => $viewer_id,
1660 'source_ids' => $source_ids,
1661 'start_time' => $start_time,
1662 'end_time' => $end_time,
1664 'filter_key' => $filter_key);
1665 return $this->call_method('facebook.stream.get', $args);
1669 * Gets the filters (with relevant filter keys for stream.get) for a
1670 * particular user. These filters are typical things like news feed,
1671 * friend lists, networks. They can be used to filter the stream
1672 * without complex queries to determine which ids belong in which groups.
1674 * @param int $uid user to get filters for
1676 * @return array of stream filter objects
1678 public function &stream_getFilters($uid = null) {
1679 $args = array('uid' => $uid);
1680 return $this->call_method('facebook.stream.getFilters', $args);
1684 * Gets the full comments given a post_id from stream.get or the
1685 * stream FQL table. Initially, only a set of preview comments are
1686 * returned because some posts can have many comments.
1688 * @param string $post_id id of the post to get comments for
1690 * @return array of comment objects
1692 public function &stream_getComments($post_id) {
1693 $args = array('post_id' => $post_id);
1694 return $this->call_method('facebook.stream.getComments', $args);
1698 * Sets the FBML for the profile of the user attached to this session.
1700 * @param string $markup The FBML that describes the profile
1701 * presence of this app for the user
1702 * @param int $uid The user
1703 * @param string $profile Profile FBML
1704 * @param string $profile_action Profile action FBML (deprecated)
1705 * @param string $mobile_profile Mobile profile FBML
1706 * @param string $profile_main Main Tab profile FBML
1708 * @return array A list of strings describing any compile errors for the
1711 function profile_setFBML($markup,
1717 return $this->call_method('facebook.profile.setFBML',
1718 array('markup' => $markup,
1720 'profile' => $profile,
1721 'profile_action' => $profile_action,
1722 'mobile_profile' => $mobile_profile,
1723 'profile_main' => $profile_main));
1727 * Gets the FBML for the profile box that is currently set for a user's
1728 * profile (your application set the FBML previously by calling the
1729 * profile.setFBML method).
1731 * @param int $uid (Optional) User id to lookup; defaults to session.
1732 * @param int $type (Optional) 1 for original style, 2 for profile_main boxes
1734 * @return string The FBML
1736 public function &profile_getFBML($uid=null, $type=null) {
1737 return $this->call_method('facebook.profile.getFBML',
1738 array('uid' => $uid,
1743 * Returns the specified user's application info section for the calling
1744 * application. These info sections have either been set via a previous
1745 * profile.setInfo call or by the user editing them directly.
1747 * @param int $uid (Optional) User id to lookup; defaults to session.
1749 * @return array Info fields for the current user. See wiki for structure:
1751 * http://wiki.developers.facebook.com/index.php/Profile.getInfo
1754 public function &profile_getInfo($uid=null) {
1755 return $this->call_method('facebook.profile.getInfo',
1756 array('uid' => $uid));
1760 * Returns the options associated with the specified info field for an
1761 * application info section.
1763 * @param string $field The title of the field
1765 * @return array An array of info options.
1767 public function &profile_getInfoOptions($field) {
1768 return $this->call_method('facebook.profile.getInfoOptions',
1769 array('field' => $field));
1773 * Configures an application info section that the specified user can install
1774 * on the Info tab of her profile. For details on the structure of an info
1775 * field, please see:
1777 * http://wiki.developers.facebook.com/index.php/Profile.setInfo
1779 * @param string $title Title / header of the info section
1780 * @param int $type 1 for text-only, 5 for thumbnail views
1781 * @param array $info_fields An array of info fields. See wiki for details.
1782 * @param int $uid (Optional)
1784 * @return bool true on success
1786 public function &profile_setInfo($title, $type, $info_fields, $uid=null) {
1787 return $this->call_method('facebook.profile.setInfo',
1788 array('uid' => $uid,
1791 'info_fields' => json_encode($info_fields)));
1795 * Specifies the objects for a field for an application info section. These
1796 * options populate the typeahead for a thumbnail.
1798 * @param string $field The title of the field
1799 * @param array $options An array of items for a thumbnail, including
1800 * 'label', 'link', and optionally 'image',
1801 * 'description' and 'sublabel'
1803 * @return bool true on success
1805 public function profile_setInfoOptions($field, $options) {
1806 return $this->call_method('facebook.profile.setInfoOptions',
1807 array('field' => $field,
1808 'options' => json_encode($options)));
1812 * Get all the marketplace categories.
1814 * @return array A list of category names
1816 function marketplace_getCategories() {
1817 return $this->call_method('facebook.marketplace.getCategories',
1822 * Get all the marketplace subcategories for a particular category.
1824 * @param category The category for which we are pulling subcategories
1826 * @return array A list of subcategory names
1828 function marketplace_getSubCategories($category) {
1829 return $this->call_method('facebook.marketplace.getSubCategories',
1830 array('category' => $category));
1834 * Get listings by either listing_id or user.
1836 * @param listing_ids An array of listing_ids (optional)
1837 * @param uids An array of user ids (optional)
1839 * @return array The data for matched listings
1841 function marketplace_getListings($listing_ids, $uids) {
1842 return $this->call_method('facebook.marketplace.getListings',
1843 array('listing_ids' => $listing_ids, 'uids' => $uids));
1847 * Search for Marketplace listings. All arguments are optional, though at
1848 * least one must be filled out to retrieve results.
1850 * @param category The category in which to search (optional)
1851 * @param subcategory The subcategory in which to search (optional)
1852 * @param query A query string (optional)
1854 * @return array The data for matched listings
1856 function marketplace_search($category, $subcategory, $query) {
1857 return $this->call_method('facebook.marketplace.search',
1858 array('category' => $category,
1859 'subcategory' => $subcategory,
1860 'query' => $query));
1864 * Remove a listing from Marketplace.
1866 * @param listing_id The id of the listing to be removed
1867 * @param status 'SUCCESS', 'NOT_SUCCESS', or 'DEFAULT'
1869 * @return bool True on success
1871 function marketplace_removeListing($listing_id,
1874 return $this->call_method('facebook.marketplace.removeListing',
1875 array('listing_id' => $listing_id,
1876 'status' => $status,
1881 * Create/modify a Marketplace listing for the loggedinuser.
1883 * @param int listing_id The id of a listing to be modified, 0
1884 * for a new listing.
1885 * @param show_on_profile bool Should we show this listing on the
1887 * @param listing_attrs array An array of the listing data
1889 * @return int The listing_id (unchanged if modifying an existing listing).
1891 function marketplace_createListing($listing_id,
1895 return $this->call_method('facebook.marketplace.createListing',
1896 array('listing_id' => $listing_id,
1897 'show_on_profile' => $show_on_profile,
1898 'listing_attrs' => json_encode($attrs),
1902 /////////////////////////////////////////////////////////////////////////////
1906 * Set a user preference.
1908 * @param pref_id preference identifier (0-200)
1909 * @param value preferece's value
1910 * @param uid the user id (defaults to current session user)
1912 * API_EC_DATA_DATABASE_ERROR
1914 * API_EC_DATA_QUOTA_EXCEEDED
1915 * API_EC_DATA_UNKNOWN_ERROR
1916 * API_EC_PERMISSION_OTHER_USER
1918 public function &data_setUserPreference($pref_id, $value, $uid = null) {
1919 return $this->call_method('facebook.data.setUserPreference',
1920 array('pref_id' => $pref_id,
1922 'uid' => $this->get_uid($uid)));
1926 * Set a user's all preferences for this application.
1928 * @param values preferece values in an associative arrays
1929 * @param replace whether to replace all existing preferences or
1931 * @param uid the user id (defaults to current session user)
1933 * API_EC_DATA_DATABASE_ERROR
1935 * API_EC_DATA_QUOTA_EXCEEDED
1936 * API_EC_DATA_UNKNOWN_ERROR
1937 * API_EC_PERMISSION_OTHER_USER
1939 public function &data_setUserPreferences($values,
1942 return $this->call_method('facebook.data.setUserPreferences',
1943 array('values' => json_encode($values),
1944 'replace' => $replace,
1945 'uid' => $this->get_uid($uid)));
1949 * Get a user preference.
1951 * @param pref_id preference identifier (0-200)
1952 * @param uid the user id (defaults to current session user)
1953 * @return preference's value
1955 * API_EC_DATA_DATABASE_ERROR
1957 * API_EC_DATA_QUOTA_EXCEEDED
1958 * API_EC_DATA_UNKNOWN_ERROR
1959 * API_EC_PERMISSION_OTHER_USER
1961 public function &data_getUserPreference($pref_id, $uid = null) {
1962 return $this->call_method('facebook.data.getUserPreference',
1963 array('pref_id' => $pref_id,
1964 'uid' => $this->get_uid($uid)));
1968 * Get a user preference.
1970 * @param uid the user id (defaults to current session user)
1971 * @return preference values
1973 * API_EC_DATA_DATABASE_ERROR
1974 * API_EC_DATA_QUOTA_EXCEEDED
1975 * API_EC_DATA_UNKNOWN_ERROR
1976 * API_EC_PERMISSION_OTHER_USER
1978 public function &data_getUserPreferences($uid = null) {
1979 return $this->call_method('facebook.data.getUserPreferences',
1980 array('uid' => $this->get_uid($uid)));
1984 * Create a new object type.
1986 * @param name object type's name
1988 * API_EC_DATA_DATABASE_ERROR
1989 * API_EC_DATA_OBJECT_ALREADY_EXISTS
1992 * API_EC_DATA_INVALID_OPERATION
1993 * API_EC_DATA_QUOTA_EXCEEDED
1994 * API_EC_DATA_UNKNOWN_ERROR
1996 public function &data_createObjectType($name) {
1997 return $this->call_method('facebook.data.createObjectType',
1998 array('name' => $name));
2002 * Delete an object type.
2004 * @param obj_type object type's name
2006 * API_EC_DATA_DATABASE_ERROR
2007 * API_EC_DATA_OBJECT_NOT_FOUND
2010 * API_EC_DATA_INVALID_OPERATION
2011 * API_EC_DATA_QUOTA_EXCEEDED
2012 * API_EC_DATA_UNKNOWN_ERROR
2014 public function &data_dropObjectType($obj_type) {
2015 return $this->call_method('facebook.data.dropObjectType',
2016 array('obj_type' => $obj_type));
2020 * Rename an object type.
2022 * @param obj_type object type's name
2023 * @param new_name new object type's name
2025 * API_EC_DATA_DATABASE_ERROR
2026 * API_EC_DATA_OBJECT_NOT_FOUND
2027 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2030 * API_EC_DATA_INVALID_OPERATION
2031 * API_EC_DATA_QUOTA_EXCEEDED
2032 * API_EC_DATA_UNKNOWN_ERROR
2034 public function &data_renameObjectType($obj_type, $new_name) {
2035 return $this->call_method('facebook.data.renameObjectType',
2036 array('obj_type' => $obj_type,
2037 'new_name' => $new_name));
2041 * Add a new property to an object type.
2043 * @param obj_type object type's name
2044 * @param prop_name name of the property to add
2045 * @param prop_type 1: integer; 2: string; 3: text blob
2047 * API_EC_DATA_DATABASE_ERROR
2048 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2051 * API_EC_DATA_INVALID_OPERATION
2052 * API_EC_DATA_QUOTA_EXCEEDED
2053 * API_EC_DATA_UNKNOWN_ERROR
2055 public function &data_defineObjectProperty($obj_type,
2058 return $this->call_method('facebook.data.defineObjectProperty',
2059 array('obj_type' => $obj_type,
2060 'prop_name' => $prop_name,
2061 'prop_type' => $prop_type));
2065 * Remove a previously defined property from an object type.
2067 * @param obj_type object type's name
2068 * @param prop_name name of the property to remove
2070 * API_EC_DATA_DATABASE_ERROR
2071 * API_EC_DATA_OBJECT_NOT_FOUND
2074 * API_EC_DATA_INVALID_OPERATION
2075 * API_EC_DATA_QUOTA_EXCEEDED
2076 * API_EC_DATA_UNKNOWN_ERROR
2078 public function &data_undefineObjectProperty($obj_type, $prop_name) {
2079 return $this->call_method('facebook.data.undefineObjectProperty',
2080 array('obj_type' => $obj_type,
2081 'prop_name' => $prop_name));
2085 * Rename a previously defined property of an object type.
2087 * @param obj_type object type's name
2088 * @param prop_name name of the property to rename
2089 * @param new_name new name to use
2091 * API_EC_DATA_DATABASE_ERROR
2092 * API_EC_DATA_OBJECT_NOT_FOUND
2093 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2096 * API_EC_DATA_INVALID_OPERATION
2097 * API_EC_DATA_QUOTA_EXCEEDED
2098 * API_EC_DATA_UNKNOWN_ERROR
2100 public function &data_renameObjectProperty($obj_type, $prop_name,
2102 return $this->call_method('facebook.data.renameObjectProperty',
2103 array('obj_type' => $obj_type,
2104 'prop_name' => $prop_name,
2105 'new_name' => $new_name));
2109 * Retrieve a list of all object types that have defined for the application.
2111 * @return a list of object type names
2113 * API_EC_DATA_DATABASE_ERROR
2115 * API_EC_DATA_QUOTA_EXCEEDED
2116 * API_EC_DATA_UNKNOWN_ERROR
2118 public function &data_getObjectTypes() {
2119 return $this->call_method('facebook.data.getObjectTypes');
2123 * Get definitions of all properties of an object type.
2125 * @param obj_type object type's name
2126 * @return pairs of property name and property types
2128 * API_EC_DATA_DATABASE_ERROR
2131 * API_EC_DATA_OBJECT_NOT_FOUND
2132 * API_EC_DATA_QUOTA_EXCEEDED
2133 * API_EC_DATA_UNKNOWN_ERROR
2135 public function &data_getObjectType($obj_type) {
2136 return $this->call_method('facebook.data.getObjectType',
2137 array('obj_type' => $obj_type));
2141 * Create a new object.
2143 * @param obj_type object type's name
2144 * @param properties (optional) properties to set initially
2145 * @return newly created object's id
2147 * API_EC_DATA_DATABASE_ERROR
2150 * API_EC_DATA_INVALID_OPERATION
2151 * API_EC_DATA_QUOTA_EXCEEDED
2152 * API_EC_DATA_UNKNOWN_ERROR
2154 public function &data_createObject($obj_type, $properties = null) {
2155 return $this->call_method('facebook.data.createObject',
2156 array('obj_type' => $obj_type,
2157 'properties' => json_encode($properties)));
2161 * Update an existing object.
2163 * @param obj_id object's id
2164 * @param properties new properties
2165 * @param replace true for replacing existing properties;
2168 * API_EC_DATA_DATABASE_ERROR
2169 * API_EC_DATA_OBJECT_NOT_FOUND
2172 * API_EC_DATA_INVALID_OPERATION
2173 * API_EC_DATA_QUOTA_EXCEEDED
2174 * API_EC_DATA_UNKNOWN_ERROR
2176 public function &data_updateObject($obj_id, $properties, $replace = false) {
2177 return $this->call_method('facebook.data.updateObject',
2178 array('obj_id' => $obj_id,
2179 'properties' => json_encode($properties),
2180 'replace' => $replace));
2184 * Delete an existing object.
2186 * @param obj_id object's id
2188 * API_EC_DATA_DATABASE_ERROR
2189 * API_EC_DATA_OBJECT_NOT_FOUND
2192 * API_EC_DATA_INVALID_OPERATION
2193 * API_EC_DATA_QUOTA_EXCEEDED
2194 * API_EC_DATA_UNKNOWN_ERROR
2196 public function &data_deleteObject($obj_id) {
2197 return $this->call_method('facebook.data.deleteObject',
2198 array('obj_id' => $obj_id));
2202 * Delete a list of objects.
2204 * @param obj_ids objects to delete
2206 * API_EC_DATA_DATABASE_ERROR
2209 * API_EC_DATA_INVALID_OPERATION
2210 * API_EC_DATA_QUOTA_EXCEEDED
2211 * API_EC_DATA_UNKNOWN_ERROR
2213 public function &data_deleteObjects($obj_ids) {
2214 return $this->call_method('facebook.data.deleteObjects',
2215 array('obj_ids' => json_encode($obj_ids)));
2219 * Get a single property value of an object.
2221 * @param obj_id object's id
2222 * @param prop_name individual property's name
2223 * @return individual property's value
2225 * API_EC_DATA_DATABASE_ERROR
2226 * API_EC_DATA_OBJECT_NOT_FOUND
2229 * API_EC_DATA_INVALID_OPERATION
2230 * API_EC_DATA_QUOTA_EXCEEDED
2231 * API_EC_DATA_UNKNOWN_ERROR
2233 public function &data_getObjectProperty($obj_id, $prop_name) {
2234 return $this->call_method('facebook.data.getObjectProperty',
2235 array('obj_id' => $obj_id,
2236 'prop_name' => $prop_name));
2240 * Get properties of an object.
2242 * @param obj_id object's id
2243 * @param prop_names (optional) properties to return; null for all.
2244 * @return specified properties of an object
2246 * API_EC_DATA_DATABASE_ERROR
2247 * API_EC_DATA_OBJECT_NOT_FOUND
2250 * API_EC_DATA_INVALID_OPERATION
2251 * API_EC_DATA_QUOTA_EXCEEDED
2252 * API_EC_DATA_UNKNOWN_ERROR
2254 public function &data_getObject($obj_id, $prop_names = null) {
2255 return $this->call_method('facebook.data.getObject',
2256 array('obj_id' => $obj_id,
2257 'prop_names' => json_encode($prop_names)));
2261 * Get properties of a list of objects.
2263 * @param obj_ids object ids
2264 * @param prop_names (optional) properties to return; null for all.
2265 * @return specified properties of an object
2267 * API_EC_DATA_DATABASE_ERROR
2268 * API_EC_DATA_OBJECT_NOT_FOUND
2271 * API_EC_DATA_INVALID_OPERATION
2272 * API_EC_DATA_QUOTA_EXCEEDED
2273 * API_EC_DATA_UNKNOWN_ERROR
2275 public function &data_getObjects($obj_ids, $prop_names = null) {
2276 return $this->call_method('facebook.data.getObjects',
2277 array('obj_ids' => json_encode($obj_ids),
2278 'prop_names' => json_encode($prop_names)));
2282 * Set a single property value of an object.
2284 * @param obj_id object's id
2285 * @param prop_name individual property's name
2286 * @param prop_value new value to set
2288 * API_EC_DATA_DATABASE_ERROR
2289 * API_EC_DATA_OBJECT_NOT_FOUND
2292 * API_EC_DATA_INVALID_OPERATION
2293 * API_EC_DATA_QUOTA_EXCEEDED
2294 * API_EC_DATA_UNKNOWN_ERROR
2296 public function &data_setObjectProperty($obj_id, $prop_name,
2298 return $this->call_method('facebook.data.setObjectProperty',
2299 array('obj_id' => $obj_id,
2300 'prop_name' => $prop_name,
2301 'prop_value' => $prop_value));
2305 * Read hash value by key.
2307 * @param obj_type object type's name
2308 * @param key hash key
2309 * @param prop_name (optional) individual property's name
2310 * @return hash value
2312 * API_EC_DATA_DATABASE_ERROR
2315 * API_EC_DATA_INVALID_OPERATION
2316 * API_EC_DATA_QUOTA_EXCEEDED
2317 * API_EC_DATA_UNKNOWN_ERROR
2319 public function &data_getHashValue($obj_type, $key, $prop_name = null) {
2320 return $this->call_method('facebook.data.getHashValue',
2321 array('obj_type' => $obj_type,
2323 'prop_name' => $prop_name));
2327 * Write hash value by key.
2329 * @param obj_type object type's name
2330 * @param key hash key
2331 * @param value hash value
2332 * @param prop_name (optional) individual property's name
2334 * API_EC_DATA_DATABASE_ERROR
2337 * API_EC_DATA_INVALID_OPERATION
2338 * API_EC_DATA_QUOTA_EXCEEDED
2339 * API_EC_DATA_UNKNOWN_ERROR
2341 public function &data_setHashValue($obj_type,
2344 $prop_name = null) {
2345 return $this->call_method('facebook.data.setHashValue',
2346 array('obj_type' => $obj_type,
2349 'prop_name' => $prop_name));
2353 * Increase a hash value by specified increment atomically.
2355 * @param obj_type object type's name
2356 * @param key hash key
2357 * @param prop_name individual property's name
2358 * @param increment (optional) default is 1
2359 * @return incremented hash value
2361 * API_EC_DATA_DATABASE_ERROR
2364 * API_EC_DATA_INVALID_OPERATION
2365 * API_EC_DATA_QUOTA_EXCEEDED
2366 * API_EC_DATA_UNKNOWN_ERROR
2368 public function &data_incHashValue($obj_type,
2372 return $this->call_method('facebook.data.incHashValue',
2373 array('obj_type' => $obj_type,
2375 'prop_name' => $prop_name,
2376 'increment' => $increment));
2380 * Remove a hash key and its values.
2382 * @param obj_type object type's name
2383 * @param key hash key
2385 * API_EC_DATA_DATABASE_ERROR
2388 * API_EC_DATA_INVALID_OPERATION
2389 * API_EC_DATA_QUOTA_EXCEEDED
2390 * API_EC_DATA_UNKNOWN_ERROR
2392 public function &data_removeHashKey($obj_type, $key) {
2393 return $this->call_method('facebook.data.removeHashKey',
2394 array('obj_type' => $obj_type,
2399 * Remove hash keys and their values.
2401 * @param obj_type object type's name
2402 * @param keys hash keys
2404 * API_EC_DATA_DATABASE_ERROR
2407 * API_EC_DATA_INVALID_OPERATION
2408 * API_EC_DATA_QUOTA_EXCEEDED
2409 * API_EC_DATA_UNKNOWN_ERROR
2411 public function &data_removeHashKeys($obj_type, $keys) {
2412 return $this->call_method('facebook.data.removeHashKeys',
2413 array('obj_type' => $obj_type,
2414 'keys' => json_encode($keys)));
2418 * Define an object association.
2420 * @param name name of this association
2421 * @param assoc_type 1: one-way 2: two-way symmetric 3: two-way asymmetric
2422 * @param assoc_info1 needed info about first object type
2423 * @param assoc_info2 needed info about second object type
2424 * @param inverse (optional) name of reverse association
2426 * API_EC_DATA_DATABASE_ERROR
2427 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2430 * API_EC_DATA_INVALID_OPERATION
2431 * API_EC_DATA_QUOTA_EXCEEDED
2432 * API_EC_DATA_UNKNOWN_ERROR
2434 public function &data_defineAssociation($name, $assoc_type, $assoc_info1,
2435 $assoc_info2, $inverse = null) {
2436 return $this->call_method('facebook.data.defineAssociation',
2437 array('name' => $name,
2438 'assoc_type' => $assoc_type,
2439 'assoc_info1' => json_encode($assoc_info1),
2440 'assoc_info2' => json_encode($assoc_info2),
2441 'inverse' => $inverse));
2445 * Undefine an object association.
2447 * @param name name of this association
2449 * API_EC_DATA_DATABASE_ERROR
2450 * API_EC_DATA_OBJECT_NOT_FOUND
2453 * API_EC_DATA_INVALID_OPERATION
2454 * API_EC_DATA_QUOTA_EXCEEDED
2455 * API_EC_DATA_UNKNOWN_ERROR
2457 public function &data_undefineAssociation($name) {
2458 return $this->call_method('facebook.data.undefineAssociation',
2459 array('name' => $name));
2463 * Rename an object association or aliases.
2465 * @param name name of this association
2466 * @param new_name (optional) new name of this association
2467 * @param new_alias1 (optional) new alias for object type 1
2468 * @param new_alias2 (optional) new alias for object type 2
2470 * API_EC_DATA_DATABASE_ERROR
2471 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2472 * API_EC_DATA_OBJECT_NOT_FOUND
2475 * API_EC_DATA_INVALID_OPERATION
2476 * API_EC_DATA_QUOTA_EXCEEDED
2477 * API_EC_DATA_UNKNOWN_ERROR
2479 public function &data_renameAssociation($name, $new_name, $new_alias1 = null,
2480 $new_alias2 = null) {
2481 return $this->call_method('facebook.data.renameAssociation',
2482 array('name' => $name,
2483 'new_name' => $new_name,
2484 'new_alias1' => $new_alias1,
2485 'new_alias2' => $new_alias2));
2489 * Get definition of an object association.
2491 * @param name name of this association
2492 * @return specified association
2494 * API_EC_DATA_DATABASE_ERROR
2495 * API_EC_DATA_OBJECT_NOT_FOUND
2498 * API_EC_DATA_QUOTA_EXCEEDED
2499 * API_EC_DATA_UNKNOWN_ERROR
2501 public function &data_getAssociationDefinition($name) {
2502 return $this->call_method('facebook.data.getAssociationDefinition',
2503 array('name' => $name));
2507 * Get definition of all associations.
2509 * @return all defined associations
2511 * API_EC_DATA_DATABASE_ERROR
2513 * API_EC_DATA_QUOTA_EXCEEDED
2514 * API_EC_DATA_UNKNOWN_ERROR
2516 public function &data_getAssociationDefinitions() {
2517 return $this->call_method('facebook.data.getAssociationDefinitions',
2522 * Create or modify an association between two objects.
2524 * @param name name of association
2525 * @param obj_id1 id of first object
2526 * @param obj_id2 id of second object
2527 * @param data (optional) extra string data to store
2528 * @param assoc_time (optional) extra time data; default to creation time
2530 * API_EC_DATA_DATABASE_ERROR
2533 * API_EC_DATA_INVALID_OPERATION
2534 * API_EC_DATA_QUOTA_EXCEEDED
2535 * API_EC_DATA_UNKNOWN_ERROR
2537 public function &data_setAssociation($name, $obj_id1, $obj_id2, $data = null,
2538 $assoc_time = null) {
2539 return $this->call_method('facebook.data.setAssociation',
2540 array('name' => $name,
2541 'obj_id1' => $obj_id1,
2542 'obj_id2' => $obj_id2,
2544 'assoc_time' => $assoc_time));
2548 * Create or modify associations between objects.
2550 * @param assocs associations to set
2551 * @param name (optional) name of association
2553 * API_EC_DATA_DATABASE_ERROR
2556 * API_EC_DATA_INVALID_OPERATION
2557 * API_EC_DATA_QUOTA_EXCEEDED
2558 * API_EC_DATA_UNKNOWN_ERROR
2560 public function &data_setAssociations($assocs, $name = null) {
2561 return $this->call_method('facebook.data.setAssociations',
2562 array('assocs' => json_encode($assocs),
2567 * Remove an association between two objects.
2569 * @param name name of association
2570 * @param obj_id1 id of first object
2571 * @param obj_id2 id of second object
2573 * API_EC_DATA_DATABASE_ERROR
2574 * API_EC_DATA_OBJECT_NOT_FOUND
2577 * API_EC_DATA_QUOTA_EXCEEDED
2578 * API_EC_DATA_UNKNOWN_ERROR
2580 public function &data_removeAssociation($name, $obj_id1, $obj_id2) {
2581 return $this->call_method('facebook.data.removeAssociation',
2582 array('name' => $name,
2583 'obj_id1' => $obj_id1,
2584 'obj_id2' => $obj_id2));
2588 * Remove associations between objects by specifying pairs of object ids.
2590 * @param assocs associations to remove
2591 * @param name (optional) name of association
2593 * API_EC_DATA_DATABASE_ERROR
2594 * API_EC_DATA_OBJECT_NOT_FOUND
2597 * API_EC_DATA_QUOTA_EXCEEDED
2598 * API_EC_DATA_UNKNOWN_ERROR
2600 public function &data_removeAssociations($assocs, $name = null) {
2601 return $this->call_method('facebook.data.removeAssociations',
2602 array('assocs' => json_encode($assocs),
2607 * Remove associations between objects by specifying one object id.
2609 * @param name name of association
2610 * @param obj_id who's association to remove
2612 * API_EC_DATA_DATABASE_ERROR
2613 * API_EC_DATA_OBJECT_NOT_FOUND
2616 * API_EC_DATA_INVALID_OPERATION
2617 * API_EC_DATA_QUOTA_EXCEEDED
2618 * API_EC_DATA_UNKNOWN_ERROR
2620 public function &data_removeAssociatedObjects($name, $obj_id) {
2621 return $this->call_method('facebook.data.removeAssociatedObjects',
2622 array('name' => $name,
2623 'obj_id' => $obj_id));
2627 * Retrieve a list of associated objects.
2629 * @param name name of association
2630 * @param obj_id who's association to retrieve
2631 * @param no_data only return object ids
2632 * @return associated objects
2634 * API_EC_DATA_DATABASE_ERROR
2635 * API_EC_DATA_OBJECT_NOT_FOUND
2638 * API_EC_DATA_INVALID_OPERATION
2639 * API_EC_DATA_QUOTA_EXCEEDED
2640 * API_EC_DATA_UNKNOWN_ERROR
2642 public function &data_getAssociatedObjects($name, $obj_id, $no_data = true) {
2643 return $this->call_method('facebook.data.getAssociatedObjects',
2644 array('name' => $name,
2645 'obj_id' => $obj_id,
2646 'no_data' => $no_data));
2650 * Count associated objects.
2652 * @param name name of association
2653 * @param obj_id who's association to retrieve
2654 * @return associated object's count
2656 * API_EC_DATA_DATABASE_ERROR
2657 * API_EC_DATA_OBJECT_NOT_FOUND
2660 * API_EC_DATA_INVALID_OPERATION
2661 * API_EC_DATA_QUOTA_EXCEEDED
2662 * API_EC_DATA_UNKNOWN_ERROR
2664 public function &data_getAssociatedObjectCount($name, $obj_id) {
2665 return $this->call_method('facebook.data.getAssociatedObjectCount',
2666 array('name' => $name,
2667 'obj_id' => $obj_id));
2671 * Get a list of associated object counts.
2673 * @param name name of association
2674 * @param obj_ids whose association to retrieve
2675 * @return associated object counts
2677 * API_EC_DATA_DATABASE_ERROR
2678 * API_EC_DATA_OBJECT_NOT_FOUND
2681 * API_EC_DATA_INVALID_OPERATION
2682 * API_EC_DATA_QUOTA_EXCEEDED
2683 * API_EC_DATA_UNKNOWN_ERROR
2685 public function &data_getAssociatedObjectCounts($name, $obj_ids) {
2686 return $this->call_method('facebook.data.getAssociatedObjectCounts',
2687 array('name' => $name,
2688 'obj_ids' => json_encode($obj_ids)));
2692 * Find all associations between two objects.
2694 * @param obj_id1 id of first object
2695 * @param obj_id2 id of second object
2696 * @param no_data only return association names without data
2697 * @return all associations between objects
2699 * API_EC_DATA_DATABASE_ERROR
2702 * API_EC_DATA_QUOTA_EXCEEDED
2703 * API_EC_DATA_UNKNOWN_ERROR
2705 public function &data_getAssociations($obj_id1, $obj_id2, $no_data = true) {
2706 return $this->call_method('facebook.data.getAssociations',
2707 array('obj_id1' => $obj_id1,
2708 'obj_id2' => $obj_id2,
2709 'no_data' => $no_data));
2713 * Get the properties that you have set for an app.
2715 * @param properties List of properties names to fetch
2717 * @return array A map from property name to value
2719 public function admin_getAppProperties($properties) {
2721 $this->call_method('facebook.admin.getAppProperties',
2722 array('properties' => json_encode($properties))), true);
2726 * Set properties for an app.
2728 * @param properties A map from property names to values
2730 * @return bool true on success
2732 public function admin_setAppProperties($properties) {
2733 return $this->call_method('facebook.admin.setAppProperties',
2734 array('properties' => json_encode($properties)));
2738 * Returns the allocation limit value for a specified integration point name
2739 * Integration point names are defined in lib/api/karma/constants.php in the
2742 * @param string $integration_point_name Name of an integration point
2743 * (see developer wiki for list).
2744 * @param int $uid Specific user to check the limit.
2746 * @return int Integration point allocation value
2748 public function &admin_getAllocation($integration_point_name, $uid=null) {
2749 return $this->call_method('facebook.admin.getAllocation',
2750 array('integration_point_name' => $integration_point_name,
2755 * Returns values for the specified metrics for the current application, in
2756 * the given time range. The metrics are collected for fixed-length periods,
2757 * and the times represent midnight at the end of each period.
2759 * @param start_time unix time for the start of the range
2760 * @param end_time unix time for the end of the range
2761 * @param period number of seconds in the desired period
2762 * @param metrics list of metrics to look up
2764 * @return array A map of the names and values for those metrics
2766 public function &admin_getMetrics($start_time, $end_time, $period, $metrics) {
2767 return $this->call_method('admin.getMetrics',
2768 array('start_time' => $start_time,
2769 'end_time' => $end_time,
2770 'period' => $period,
2771 'metrics' => json_encode($metrics)));
2775 * Sets application restriction info.
2777 * Applications can restrict themselves to only a limited user demographic
2778 * based on users' age and/or location or based on static predefined types
2779 * specified by facebook for specifying diff age restriction for diff
2782 * @param array $restriction_info The age restriction settings to set.
2784 * @return bool true on success
2786 public function admin_setRestrictionInfo($restriction_info = null) {
2787 $restriction_str = null;
2788 if (!empty($restriction_info)) {
2789 $restriction_str = json_encode($restriction_info);
2791 return $this->call_method('admin.setRestrictionInfo',
2792 array('restriction_str' => $restriction_str));
2796 * Gets application restriction info.
2798 * Applications can restrict themselves to only a limited user demographic
2799 * based on users' age and/or location or based on static predefined types
2800 * specified by facebook for specifying diff age restriction for diff
2803 * @return array The age restriction settings for this application.
2805 public function admin_getRestrictionInfo() {
2807 $this->call_method('admin.getRestrictionInfo'),
2813 * Bans a list of users from the app. Banned users can't
2814 * access the app's canvas page and forums.
2816 * @param array $uids an array of user ids
2817 * @return bool true on success
2819 public function admin_banUsers($uids) {
2820 return $this->call_method(
2821 'admin.banUsers', array('uids' => json_encode($uids)));
2825 * Unban users that have been previously banned with
2828 * @param array $uids an array of user ids
2829 * @return bool true on success
2831 public function admin_unbanUsers($uids) {
2832 return $this->call_method(
2833 'admin.unbanUsers', array('uids' => json_encode($uids)));
2837 * Gets the list of users that have been banned from the application.
2838 * $uids is an optional parameter that filters the result with the list
2839 * of provided user ids. If $uids is provided,
2840 * only banned user ids that are contained in $uids are returned.
2842 * @param array $uids an array of user ids to filter by
2843 * @return bool true on success
2846 public function admin_getBannedUsers($uids = null) {
2847 return $this->call_method(
2848 'admin.getBannedUsers',
2849 array('uids' => $uids ? json_encode($uids) : null));
2852 /* UTILITY FUNCTIONS */
2855 * Calls the specified normal POST method with the specified parameters.
2857 * @param string $method Name of the Facebook method to invoke
2858 * @param array $params A map of param names => param values
2860 * @return mixed Result of method call; this returns a reference to support
2861 * 'delayed returns' when in a batch context.
2862 * See: http://wiki.developers.facebook.com/index.php/Using_batching_API
2864 public function &call_method($method, $params = array()) {
2865 if (!$this->pending_batch()) {
2866 if ($this->call_as_apikey) {
2867 $params['call_as_apikey'] = $this->call_as_apikey;
2869 $data = $this->post_request($method, $params);
2870 if (empty($params['format']) || strtolower($params['format']) != 'json') {
2871 $result = $this->convert_xml_to_result($data, $method, $params);
2874 $result = json_decode($data, true);
2877 if (is_array($result) && isset($result['error_code'])) {
2878 throw new FacebookRestClientException($result['error_msg'],
2879 $result['error_code']);
2884 $batch_item = array('m' => $method, 'p' => $params, 'r' => & $result);
2885 $this->batch_queue[] = $batch_item;
2892 * Calls the specified file-upload POST method with the specified parameters
2894 * @param string $method Name of the Facebook method to invoke
2895 * @param array $params A map of param names => param values
2896 * @param string $file A path to the file to upload (required)
2898 * @return array A dictionary representing the response.
2900 public function call_upload_method($method, $params, $file, $server_addr = null) {
2901 if (!$this->pending_batch()) {
2902 if (!file_exists($file)) {
2904 FacebookAPIErrorCodes::API_EC_PARAM;
2905 $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
2906 throw new FacebookRestClientException($description, $code);
2909 $xml = $this->post_upload_request($method, $params, $file, $server_addr);
2910 $result = $this->convert_xml_to_result($xml, $method, $params);
2912 if (is_array($result) && isset($result['error_code'])) {
2913 throw new FacebookRestClientException($result['error_msg'],
2914 $result['error_code']);
2919 FacebookAPIErrorCodes::API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE;
2920 $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
2921 throw new FacebookRestClientException($description, $code);
2927 protected function convert_xml_to_result($xml, $method, $params) {
2928 $sxml = simplexml_load_string($xml);
2929 $result = self::convert_simplexml_to_array($sxml);
2931 if (!empty($GLOBALS['facebook_config']['debug'])) {
2932 // output the raw xml and its corresponding php object, for debugging:
2933 print '<div style="margin: 10px 30px; padding: 5px; border: 2px solid black; background: gray; color: white; font-size: 12px; font-weight: bold;">';
2935 print $this->cur_id . ': Called ' . $method . ', show ' .
2936 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'params\');">Params</a> | '.
2937 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'xml\');">XML</a> | '.
2938 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'sxml\');">SXML</a> | '.
2939 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'php\');">PHP</a>';
2940 print '<pre id="params'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($params, true).'</pre>';
2941 print '<pre id="xml'.$this->cur_id.'" style="display: none; overflow: auto;">'.htmlspecialchars($xml).'</pre>';
2942 print '<pre id="php'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($result, true).'</pre>';
2943 print '<pre id="sxml'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($sxml, true).'</pre>';
2949 private function finalize_params($method, &$params) {
2950 $this->add_standard_params($method, $params);
2951 // we need to do this before signing the params
2952 $this->convert_array_values_to_json($params);
2953 $params['sig'] = Facebook::generate_sig($params, $this->secret);
2956 private function convert_array_values_to_json(&$params) {
2957 foreach ($params as $key => &$val) {
2958 if (is_array($val)) {
2959 $val = json_encode($val);
2964 private function add_standard_params($method, &$params) {
2965 if ($this->call_as_apikey) {
2966 $params['call_as_apikey'] = $this->call_as_apikey;
2968 $params['method'] = $method;
2969 $params['session_key'] = $this->session_key;
2970 $params['api_key'] = $this->api_key;
2971 $params['call_id'] = microtime(true);
2972 if ($params['call_id'] <= $this->last_call_id) {
2973 $params['call_id'] = $this->last_call_id + 0.001;
2975 $this->last_call_id = $params['call_id'];
2976 if (!isset($params['v'])) {
2977 $params['v'] = '1.0';
2979 if (isset($this->use_ssl_resources) &&
2980 $this->use_ssl_resources) {
2981 $params['return_ssl_resources'] = true;
2985 private function create_post_string($method, $params) {
2986 $post_params = array();
2987 foreach ($params as $key => &$val) {
2988 $post_params[] = $key.'='.urlencode($val);
2990 return implode('&', $post_params);
2993 private function run_multipart_http_transaction($method, $params, $file, $server_addr) {
2995 // the format of this message is specified in RFC1867/RFC1341.
2996 // we add twenty pseudo-random digits to the end of the boundary string.
2997 $boundary = '--------------------------FbMuLtIpArT' .
2998 sprintf("%010d", mt_rand()) .
2999 sprintf("%010d", mt_rand());
3000 $content_type = 'multipart/form-data; boundary=' . $boundary;
3001 // within the message, we prepend two extra hyphens.
3002 $delimiter = '--' . $boundary;
3003 $close_delimiter = $delimiter . '--';
3004 $content_lines = array();
3005 foreach ($params as $key => &$val) {
3006 $content_lines[] = $delimiter;
3007 $content_lines[] = 'Content-Disposition: form-data; name="' . $key . '"';
3008 $content_lines[] = '';
3009 $content_lines[] = $val;
3011 // now add the file data
3012 $content_lines[] = $delimiter;
3014 'Content-Disposition: form-data; filename="' . $file . '"';
3015 $content_lines[] = 'Content-Type: application/octet-stream';
3016 $content_lines[] = '';
3017 $content_lines[] = file_get_contents($file);
3018 $content_lines[] = $close_delimiter;
3019 $content_lines[] = '';
3020 $content = implode("\r\n", $content_lines);
3021 return $this->run_http_post_transaction($content_type, $content, $server_addr);
3024 public function post_request($method, $params) {
3025 $this->finalize_params($method, $params);
3026 $post_string = $this->create_post_string($method, $params);
3027 if ($this->use_curl_if_available && function_exists('curl_init')) {
3028 $useragent = 'Facebook API PHP5 Client 1.1 (curl) ' . phpversion();
3030 curl_setopt($ch, CURLOPT_URL, $this->server_addr);
3031 curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);
3032 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
3033 curl_setopt($ch, CURLOPT_USERAGENT, $useragent);
3034 curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
3035 curl_setopt($ch, CURLOPT_TIMEOUT, 30);
3036 $result = curl_exec($ch);
3039 $content_type = 'application/x-www-form-urlencoded';
3040 $content = $post_string;
3041 $result = $this->run_http_post_transaction($content_type,
3043 $this->server_addr);
3048 private function post_upload_request($method, $params, $file, $server_addr = null) {
3049 $server_addr = $server_addr ? $server_addr : $this->server_addr;
3050 $this->finalize_params($method, $params);
3051 if ($this->use_curl_if_available && function_exists('curl_init')) {
3052 // prepending '@' causes cURL to upload the file; the key is ignored.
3053 $params['_file'] = '@' . $file;
3054 $useragent = 'Facebook API PHP5 Client 1.1 (curl) ' . phpversion();
3056 curl_setopt($ch, CURLOPT_URL, $server_addr);
3057 // this has to come before the POSTFIELDS set!
3058 curl_setopt($ch, CURLOPT_POST, 1 );
3059 // passing an array gets curl to use the multipart/form-data content type
3060 curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
3061 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
3062 curl_setopt($ch, CURLOPT_USERAGENT, $useragent);
3063 $result = curl_exec($ch);
3066 $result = $this->run_multipart_http_transaction($method, $params, $file, $server_addr);
3071 private function run_http_post_transaction($content_type, $content, $server_addr) {
3073 $user_agent = 'Facebook API PHP5 Client 1.1 (non-curl) ' . phpversion();
3074 $content_length = strlen($content);
3077 array('method' => 'POST',
3078 'user_agent' => $user_agent,
3079 'header' => 'Content-Type: ' . $content_type . "\r\n" .
3080 'Content-Length: ' . $content_length,
3081 'content' => $content));
3082 $context_id = stream_context_create($context);
3083 $sock = fopen($server_addr, 'r', false, $context_id);
3087 while (!feof($sock)) {
3088 $result .= fgets($sock, 4096);
3095 public static function convert_simplexml_to_array($sxml) {
3098 foreach ($sxml as $k => $v) {
3099 if ($sxml['list']) {
3100 $arr[] = self::convert_simplexml_to_array($v);
3102 $arr[$k] = self::convert_simplexml_to_array($v);
3106 if (sizeof($arr) > 0) {
3109 return (string)$sxml;
3113 private function get_uid($uid) {
3114 return $uid ? $uid : $this->user;
3119 class FacebookRestClientException extends Exception {
3122 // Supporting methods and values------
3125 * Error codes and descriptions for the Facebook API.
3128 class FacebookAPIErrorCodes {
3130 const API_EC_SUCCESS = 0;
3135 const API_EC_UNKNOWN = 1;
3136 const API_EC_SERVICE = 2;
3137 const API_EC_METHOD = 3;
3138 const API_EC_TOO_MANY_CALLS = 4;
3139 const API_EC_BAD_IP = 5;
3140 const API_EC_HOST_API = 6;
3141 const API_EC_HOST_UP = 7;
3142 const API_EC_SECURE = 8;
3143 const API_EC_RATE = 9;
3144 const API_EC_PERMISSION_DENIED = 10;
3145 const API_EC_DEPRECATED = 11;
3146 const API_EC_VERSION = 12;
3147 const API_EC_INTERNAL_FQL_ERROR = 13;
3152 const API_EC_PARAM = 100;
3153 const API_EC_PARAM_API_KEY = 101;
3154 const API_EC_PARAM_SESSION_KEY = 102;
3155 const API_EC_PARAM_CALL_ID = 103;
3156 const API_EC_PARAM_SIGNATURE = 104;
3157 const API_EC_PARAM_TOO_MANY = 105;
3158 const API_EC_PARAM_USER_ID = 110;
3159 const API_EC_PARAM_USER_FIELD = 111;
3160 const API_EC_PARAM_SOCIAL_FIELD = 112;
3161 const API_EC_PARAM_EMAIL = 113;
3162 const API_EC_PARAM_USER_ID_LIST = 114;
3163 const API_EC_PARAM_FIELD_LIST = 115;
3164 const API_EC_PARAM_ALBUM_ID = 120;
3165 const API_EC_PARAM_PHOTO_ID = 121;
3166 const API_EC_PARAM_FEED_PRIORITY = 130;
3167 const API_EC_PARAM_CATEGORY = 140;
3168 const API_EC_PARAM_SUBCATEGORY = 141;
3169 const API_EC_PARAM_TITLE = 142;
3170 const API_EC_PARAM_DESCRIPTION = 143;
3171 const API_EC_PARAM_BAD_JSON = 144;
3172 const API_EC_PARAM_BAD_EID = 150;
3173 const API_EC_PARAM_UNKNOWN_CITY = 151;
3174 const API_EC_PARAM_BAD_PAGE_TYPE = 152;
3177 * USER PERMISSIONS ERRORS
3179 const API_EC_PERMISSION = 200;
3180 const API_EC_PERMISSION_USER = 210;
3181 const API_EC_PERMISSION_NO_DEVELOPERS = 211;
3182 const API_EC_PERMISSION_ALBUM = 220;
3183 const API_EC_PERMISSION_PHOTO = 221;
3184 const API_EC_PERMISSION_MESSAGE = 230;
3185 const API_EC_PERMISSION_OTHER_USER = 240;
3186 const API_EC_PERMISSION_STATUS_UPDATE = 250;
3187 const API_EC_PERMISSION_PHOTO_UPLOAD = 260;
3188 const API_EC_PERMISSION_VIDEO_UPLOAD = 261;
3189 const API_EC_PERMISSION_SMS = 270;
3190 const API_EC_PERMISSION_CREATE_LISTING = 280;
3191 const API_EC_PERMISSION_CREATE_NOTE = 281;
3192 const API_EC_PERMISSION_SHARE_ITEM = 282;
3193 const API_EC_PERMISSION_EVENT = 290;
3194 const API_EC_PERMISSION_LARGE_FBML_TEMPLATE = 291;
3195 const API_EC_PERMISSION_LIVEMESSAGE = 292;
3196 const API_EC_PERMISSION_RSVP_EVENT = 299;
3201 const API_EC_EDIT = 300;
3202 const API_EC_EDIT_USER_DATA = 310;
3203 const API_EC_EDIT_PHOTO = 320;
3204 const API_EC_EDIT_ALBUM_SIZE = 321;
3205 const API_EC_EDIT_PHOTO_TAG_SUBJECT = 322;
3206 const API_EC_EDIT_PHOTO_TAG_PHOTO = 323;
3207 const API_EC_EDIT_PHOTO_FILE = 324;
3208 const API_EC_EDIT_PHOTO_PENDING_LIMIT = 325;
3209 const API_EC_EDIT_PHOTO_TAG_LIMIT = 326;
3210 const API_EC_EDIT_ALBUM_REORDER_PHOTO_NOT_IN_ALBUM = 327;
3211 const API_EC_EDIT_ALBUM_REORDER_TOO_FEW_PHOTOS = 328;
3213 const API_EC_MALFORMED_MARKUP = 329;
3214 const API_EC_EDIT_MARKUP = 330;
3216 const API_EC_EDIT_FEED_TOO_MANY_USER_CALLS = 340;
3217 const API_EC_EDIT_FEED_TOO_MANY_USER_ACTION_CALLS = 341;
3218 const API_EC_EDIT_FEED_TITLE_LINK = 342;
3219 const API_EC_EDIT_FEED_TITLE_LENGTH = 343;
3220 const API_EC_EDIT_FEED_TITLE_NAME = 344;
3221 const API_EC_EDIT_FEED_TITLE_BLANK = 345;
3222 const API_EC_EDIT_FEED_BODY_LENGTH = 346;
3223 const API_EC_EDIT_FEED_PHOTO_SRC = 347;
3224 const API_EC_EDIT_FEED_PHOTO_LINK = 348;
3226 const API_EC_EDIT_VIDEO_SIZE = 350;
3227 const API_EC_EDIT_VIDEO_INVALID_FILE = 351;
3228 const API_EC_EDIT_VIDEO_INVALID_TYPE = 352;
3229 const API_EC_EDIT_VIDEO_FILE = 353;
3231 const API_EC_EDIT_FEED_TITLE_ARRAY = 360;
3232 const API_EC_EDIT_FEED_TITLE_PARAMS = 361;
3233 const API_EC_EDIT_FEED_BODY_ARRAY = 362;
3234 const API_EC_EDIT_FEED_BODY_PARAMS = 363;
3235 const API_EC_EDIT_FEED_PHOTO = 364;
3236 const API_EC_EDIT_FEED_TEMPLATE = 365;
3237 const API_EC_EDIT_FEED_TARGET = 366;
3238 const API_EC_EDIT_FEED_MARKUP = 367;
3243 const API_EC_SESSION_TIMED_OUT = 450;
3244 const API_EC_SESSION_METHOD = 451;
3245 const API_EC_SESSION_INVALID = 452;
3246 const API_EC_SESSION_REQUIRED = 453;
3247 const API_EC_SESSION_REQUIRED_FOR_SECRET = 454;
3248 const API_EC_SESSION_CANNOT_USE_SESSION_SECRET = 455;
3254 const FQL_EC_UNKNOWN_ERROR = 600;
3255 const FQL_EC_PARSER = 601; // backwards compatibility
3256 const FQL_EC_PARSER_ERROR = 601;
3257 const FQL_EC_UNKNOWN_FIELD = 602;
3258 const FQL_EC_UNKNOWN_TABLE = 603;
3259 const FQL_EC_NOT_INDEXABLE = 604; // backwards compatibility
3260 const FQL_EC_NO_INDEX = 604;
3261 const FQL_EC_UNKNOWN_FUNCTION = 605;
3262 const FQL_EC_INVALID_PARAM = 606;
3263 const FQL_EC_INVALID_FIELD = 607;
3264 const FQL_EC_INVALID_SESSION = 608;
3265 const FQL_EC_UNSUPPORTED_APP_TYPE = 609;
3266 const FQL_EC_SESSION_SECRET_NOT_ALLOWED = 610;
3267 const FQL_EC_DEPRECATED_TABLE = 611;
3268 const FQL_EC_EXTENDED_PERMISSION = 612;
3269 const FQL_EC_RATE_LIMIT_EXCEEDED = 613;
3271 const API_EC_REF_SET_FAILED = 700;
3274 * DATA STORE API ERRORS
3276 const API_EC_DATA_UNKNOWN_ERROR = 800;
3277 const API_EC_DATA_INVALID_OPERATION = 801;
3278 const API_EC_DATA_QUOTA_EXCEEDED = 802;
3279 const API_EC_DATA_OBJECT_NOT_FOUND = 803;
3280 const API_EC_DATA_OBJECT_ALREADY_EXISTS = 804;
3281 const API_EC_DATA_DATABASE_ERROR = 805;
3282 const API_EC_DATA_CREATE_TEMPLATE_ERROR = 806;
3283 const API_EC_DATA_TEMPLATE_EXISTS_ERROR = 807;
3284 const API_EC_DATA_TEMPLATE_HANDLE_TOO_LONG = 808;
3285 const API_EC_DATA_TEMPLATE_HANDLE_ALREADY_IN_USE = 809;
3286 const API_EC_DATA_TOO_MANY_TEMPLATE_BUNDLES = 810;
3287 const API_EC_DATA_MALFORMED_ACTION_LINK = 811;
3288 const API_EC_DATA_TEMPLATE_USES_RESERVED_TOKEN = 812;
3291 * APPLICATION INFO ERRORS
3293 const API_EC_NO_SUCH_APP = 900;
3298 const API_EC_BATCH_TOO_MANY_ITEMS = 950;
3299 const API_EC_BATCH_ALREADY_STARTED = 951;
3300 const API_EC_BATCH_NOT_STARTED = 952;
3301 const API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE = 953;
3306 const API_EC_EVENT_INVALID_TIME = 1000;
3311 const API_EC_INFO_NO_INFORMATION = 1050;
3312 const API_EC_INFO_SET_FAILED = 1051;
3315 * LIVEMESSAGE API ERRORS
3317 const API_EC_LIVEMESSAGE_SEND_FAILED = 1100;
3318 const API_EC_LIVEMESSAGE_EVENT_NAME_TOO_LONG = 1101;
3319 const API_EC_LIVEMESSAGE_MESSAGE_TOO_LONG = 1102;
3322 * CONNECT SESSION ERRORS
3324 const API_EC_CONNECT_FEED_DISABLED = 1300;
3327 * Platform tag bundles errors
3329 const API_EC_TAG_BUNDLE_QUOTA = 1400;
3334 const API_EC_SHARE_BAD_URL = 1500;
3339 const API_EC_NOTE_CANNOT_MODIFY = 1600;
3344 const API_EC_COMMENTS_UNKNOWN = 1700;
3345 const API_EC_COMMENTS_POST_TOO_LONG = 1701;
3346 const API_EC_COMMENTS_DB_DOWN = 1702;
3347 const API_EC_COMMENTS_INVALID_XID = 1703;
3348 const API_EC_COMMENTS_INVALID_UID = 1704;
3349 const API_EC_COMMENTS_INVALID_POST = 1705;
3352 * This array is no longer maintained; to view the description of an error
3353 * code, please look at the message element of the API response or visit
3354 * the developer wiki at http://wiki.developers.facebook.com/.
3356 public static $api_error_descriptions = array(
3357 self::API_EC_SUCCESS => 'Success',
3358 self::API_EC_UNKNOWN => 'An unknown error occurred',
3359 self::API_EC_SERVICE => 'Service temporarily unavailable',
3360 self::API_EC_METHOD => 'Unknown method',
3361 self::API_EC_TOO_MANY_CALLS => 'Application request limit reached',
3362 self::API_EC_BAD_IP => 'Unauthorized source IP address',
3363 self::API_EC_PARAM => 'Invalid parameter',
3364 self::API_EC_PARAM_API_KEY => 'Invalid API key',
3365 self::API_EC_PARAM_SESSION_KEY => 'Session key invalid or no longer valid',
3366 self::API_EC_PARAM_CALL_ID => 'Call_id must be greater than previous',
3367 self::API_EC_PARAM_SIGNATURE => 'Incorrect signature',
3368 self::API_EC_PARAM_USER_ID => 'Invalid user id',
3369 self::API_EC_PARAM_USER_FIELD => 'Invalid user info field',
3370 self::API_EC_PARAM_SOCIAL_FIELD => 'Invalid user field',
3371 self::API_EC_PARAM_USER_ID_LIST => 'Invalid user id list',
3372 self::API_EC_PARAM_FIELD_LIST => 'Invalid field list',
3373 self::API_EC_PARAM_ALBUM_ID => 'Invalid album id',
3374 self::API_EC_PARAM_BAD_EID => 'Invalid eid',
3375 self::API_EC_PARAM_UNKNOWN_CITY => 'Unknown city',
3376 self::API_EC_PERMISSION => 'Permissions error',
3377 self::API_EC_PERMISSION_USER => 'User not visible',
3378 self::API_EC_PERMISSION_NO_DEVELOPERS => 'Application has no developers',
3379 self::API_EC_PERMISSION_ALBUM => 'Album not visible',
3380 self::API_EC_PERMISSION_PHOTO => 'Photo not visible',
3381 self::API_EC_PERMISSION_EVENT => 'Creating and modifying events required the extended permission create_event',
3382 self::API_EC_PERMISSION_RSVP_EVENT => 'RSVPing to events required the extended permission rsvp_event',
3383 self::API_EC_EDIT_ALBUM_SIZE => 'Album is full',
3384 self::FQL_EC_PARSER => 'FQL: Parser Error',
3385 self::FQL_EC_UNKNOWN_FIELD => 'FQL: Unknown Field',
3386 self::FQL_EC_UNKNOWN_TABLE => 'FQL: Unknown Table',
3387 self::FQL_EC_NOT_INDEXABLE => 'FQL: Statement not indexable',
3388 self::FQL_EC_UNKNOWN_FUNCTION => 'FQL: Attempted to call unknown function',
3389 self::FQL_EC_INVALID_PARAM => 'FQL: Invalid parameter passed in',
3390 self::API_EC_DATA_UNKNOWN_ERROR => 'Unknown data store API error',
3391 self::API_EC_DATA_INVALID_OPERATION => 'Invalid operation',
3392 self::API_EC_DATA_QUOTA_EXCEEDED => 'Data store allowable quota was exceeded',
3393 self::API_EC_DATA_OBJECT_NOT_FOUND => 'Specified object cannot be found',
3394 self::API_EC_DATA_OBJECT_ALREADY_EXISTS => 'Specified object already exists',
3395 self::API_EC_DATA_DATABASE_ERROR => 'A database error occurred. Please try again',
3396 self::API_EC_BATCH_ALREADY_STARTED => 'begin_batch already called, please make sure to call end_batch first',
3397 self::API_EC_BATCH_NOT_STARTED => 'end_batch called before begin_batch',
3398 self::API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE => 'This method is not allowed in batch mode'