extlib/facebook/facebookapi_php5_restlib.php

   1 <?php
   2 // Copyright 2004-2009 Facebook. All Rights Reserved.
   3 //
   4 // +---------------------------------------------------------------------------+
   5 // | Facebook Platform PHP5 client                                             |
   6 // +---------------------------------------------------------------------------+
   7 // | Copyright (c) 2007-2009 Facebook, Inc.                                    |
   8 // | All rights reserved.                                                      |
   9 // |                                                                           |
  10 // | Redistribution and use in source and binary forms, with or without        |
  11 // | modification, are permitted provided that the following conditions        |
  12 // | are met:                                                                  |
  13 // |                                                                           |
  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.   |
  19 // |                                                                           |
  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 // +---------------------------------------------------------------------------+
  33 //
  34
  35 include_once 'jsonwrapper/jsonwrapper.php';
  36
  37 class FacebookRestClient {
  38   public $secret;
  39   public $session_key;
  40   public $api_key;
  41   // to save making the friends.get api call, this will get prepopulated on
  42   // canvas pages
  43   public $friends_list;
  44   public $user;
  45   // to save making the pages.isAppAdded api call, this will get prepopulated
  46   // on canvas pages
  47   public $added;
  48   public $is_user;
  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
  52   public $canvas_user;
  53   public $batch_mode;
  54   private $batch_queue;
  55   private $pending_batch;
  56   private $call_as_apikey;
  57   private $use_curl_if_available;
  58
  59   const BATCH_MODE_DEFAULT = 0;
  60   const BATCH_MODE_SERVER_PARALLEL = 0;
  61   const BATCH_MODE_SERIAL_ONLY = 2;
  62
  63   /**
  64    * Create the client.
  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
  68    *                            variable.
  69    */
  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';
  79
  80     if (!empty($GLOBALS['facebook_config']['debug'])) {
  81       $this->cur_id = 0;
  82       ?>
  83 <script type="text/javascript">
  84 var types = ['params', 'xml', 'php', 'sxml'];
  85 function getStyle(elem, style) {
  86   if (elem.getStyle) {
  87     return elem.getStyle(style);
  88   } else {
  89     return elem.style[style];
  90   }
  91 }
  92 function setStyle(elem, style, value) {
  93   if (elem.setStyle) {
  94     elem.setStyle(style, value);
  95   } else {
  96     elem.style[style] = value;
  97   }
  98 }
  99 function toggleDisplay(id, type) {
 100   for (var i = 0; i < types.length; i++) {
 101     var t = types[i];
 102     var pre = document.getElementById(t + id);
 103     if (pre) {
 104       if (t != type || getStyle(pre, 'display') == 'block') {
 105         setStyle(pre, 'display', 'none');
 106       } else {
 107         setStyle(pre, 'display', 'block');
 108       }
 109     }
 110   }
 111   return false;
 112 }
 113 </script>
 114 <?php
 115     }
 116   }
 117
 118   /**
 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.
 123    *
 124    * @param $uid int the user id
 125    */
 126   public function set_user($uid) {
 127     $this->user = $uid;
 128   }
 129
 130   /**
 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.
 134    *
 135    * @param $use_curl_if_available bool whether or not to use cURL if available
 136    */
 137   public function set_use_curl_if_available($use_curl_if_available) {
 138     $this->use_curl_if_available = $use_curl_if_available;
 139   }
 140
 141   /**
 142    * Start a batch operation.
 143    */
 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);
 149     }
 150
 151     $this->batch_queue = array();
 152     $this->pending_batch = true;
 153   }
 154
 155   /*
 156    * End current batch operation
 157    */
 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);
 163     }
 164
 165     $this->pending_batch = false;
 166
 167     $this->execute_server_side_batch();
 168     $this->batch_queue = null;
 169   }
 170
 171   /**
 172    * are we currently queueing up calls for a batch?
 173    */
 174   public function pending_batch() {
 175     return $this->pending_batch;
 176   }
 177
 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);
 186     }
 187
 188     $method_feed_json = json_encode($method_feed);
 189
 190     $serial_only =
 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;
 196     }
 197
 198     $xml = $this->post_request('batch.run', $params);
 199
 200     $result = $this->convert_xml_to_result($xml, 'batch.run', $params);
 201
 202
 203     if (is_array($result) && isset($result['error_code'])) {
 204       throw new FacebookRestClientException($result['error_msg'],
 205                                             $result['error_code']);
 206     }
 207
 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,
 212                                                         $batch_item['m'],
 213                                                         $batch_item['p']);
 214
 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']);
 219       }
 220       $batch_item['r'] = $batch_item_result;
 221     }
 222   }
 223
 224   public function begin_permissions_mode($permissions_apikey) {
 225     $this->call_as_apikey = $permissions_apikey;
 226   }
 227
 228   public function end_permissions_mode() {
 229     $this->call_as_apikey = '';
 230   }
 231
 232
 233   /*
 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
 238    * urls.
 239    */
 240   public function set_use_ssl_resources($is_ssl = true) {
 241     $this->use_ssl_resources = $is_ssl;
 242   }
 243
 244   /**
 245    * Returns public information for an application (as shown in the application
 246    * directory) by either application ID, API key, or canvas page name.
 247    *
 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
 251    *
 252    * Exactly one argument must be specified, otherwise it is an error.
 253    *
 254    * @return array  An array of public information about the application.
 255    */
 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));
 263   }
 264
 265   /**
 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.
 269    *
 270    * @return string  An authentication token.
 271    */
 272   public function auth_createToken() {
 273     return $this->call_method('facebook.auth.createToken');
 274   }
 275
 276   /**
 277    * Returns the session information available after current user logs in.
 278    *
 279    * @param string $auth_token             the token returned by
 280    *                                       auth_createToken or passed back to
 281    *                                       your callback_url.
 282    * @param bool $generate_session_secret  whether the session returned should
 283    *                                       include a session secret
 284    *
 285    * @return array  An assoc array containing session_key, uid
 286    */
 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'];
 293
 294     if (!empty($result['secret']) && !$generate_session_secret) {
 295       // desktop apps have a special secret
 296       $this->secret = $result['secret'];
 297     }
 298       return $result;
 299     }
 300   }
 301
 302   /**
 303    * Generates a session-specific secret. This is for integration with
 304    * client-side API calls, such as the JS library.
 305    *
 306    * @return array  A session secret for the current promoted session
 307    *
 308    * @error API_EC_PARAM_SESSION_KEY
 309    *        API_EC_PARAM_UNKNOWN
 310    */
 311   public function auth_promoteSession() {
 312       return $this->call_method('facebook.auth.promoteSession');
 313   }
 314
 315   /**
 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.
 319    *
 320    * @return bool  true if session expiration was successful, false otherwise
 321    */
 322   public function auth_expireSession() {
 323       return $this->call_method('facebook.auth.expireSession');
 324   }
 325
 326   /**
 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.
 330    *
 331    *  @param  string  $perm  The permission to revoke
 332    *  @param  int     $uid   The user for whom to revoke the permission.
 333    */
 334   public function auth_revokeExtendedPermission($perm, $uid=null) {
 335     return $this->call_method('facebook.auth.revokeExtendedPermission',
 336         array('perm' => $perm, 'uid' => $uid));
 337   }
 338
 339   /**
 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.
 346    *
 347    * @param int $uid  (Optional) User to revoke
 348    *
 349    * @return bool  true if revocation succeeds, false otherwise
 350    */
 351   public function auth_revokeAuthorization($uid=null) {
 352       return $this->call_method('facebook.auth.revokeAuthorization',
 353           array('uid' => $uid));
 354   }
 355
 356   /**
 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.
 362    */
 363   public function auth_getAppPublicKey($target_app_key) {
 364     return $this->call_method('facebook.auth.getAppPublicKey',
 365           array('target_app_key' => $target_app_key));
 366   }
 367
 368   /**
 369    * Get a structure that can be passed to another app
 370    * as proof of session. The other app can verify it using public
 371    * key of this app.
 372    *
 373    * @return signed public session data structure.
 374    */
 375   public function auth_getSignedPublicSessionData() {
 376     return $this->call_method('facebook.auth.getSignedPublicSessionData',
 377                               array());
 378   }
 379
 380   /**
 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).
 384    */
 385   public function connect_getUnconnectedFriendsCount() {
 386     return $this->call_method('facebook.connect.getUnconnectedFriendsCount',
 387         array());
 388   }
 389
 390  /**
 391   * This method is used to create an association between an external user
 392   * account and a Facebook user account, as per Facebook Connect.
 393   *
 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.
 400   *
 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:
 405   *
 406   *   http://wiki.developers.facebook.com/index.php/Connect.registerUsers
 407   *
 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;
 413   *
 414   * @return array  The list of email hashes for the successfully registered
 415   *                accounts.
 416   */
 417   public function connect_registerUsers($accounts) {
 418     return $this->call_method('facebook.connect.registerUsers',
 419         array('accounts' => $accounts));
 420   }
 421
 422  /**
 423   * Unregisters a set of accounts registered using connect.registerUsers.
 424   *
 425   * @param array $email_hashes  The (JSON-encoded) list of email hashes to be
 426   *                             unregistered.
 427   *
 428   * @return array  The list of email hashes which have been successfully
 429   *                unregistered.
 430   */
 431   public function connect_unregisterUsers($email_hashes) {
 432     return $this->call_method('facebook.connect.unregisterUsers',
 433         array('email_hashes' => $email_hashes));
 434   }
 435
 436   /**
 437    * Returns events according to the filters specified.
 438    *
 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
 446    *                            lower bound.
 447    * @param int $end_time       (Optional) Filter with this UTC as upper bound.
 448    *                            A null or zero parameter indicates no upper
 449    *                            bound.
 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.
 455    *
 456    * @return array  The events matching the query.
 457    */
 458   public function &events_get($uid=null,
 459                               $eids=null,
 460                               $start_time=null,
 461                               $end_time=null,
 462                               $rsvp_status=null) {
 463     return $this->call_method('facebook.events.get',
 464         array('uid' => $uid,
 465               'eids' => $eids,
 466               'start_time' => $start_time,
 467               'end_time' => $end_time,
 468               'rsvp_status' => $rsvp_status));
 469   }
 470
 471   /**
 472    * Returns membership list data associated with an event.
 473    *
 474    * @param int $eid  event id
 475    *
 476    * @return array  An assoc array of four membership lists, with keys
 477    *                'attending', 'unsure', 'declined', and 'not_replied'
 478    */
 479   public function &events_getMembers($eid) {
 480     return $this->call_method('facebook.events.getMembers',
 481       array('eid' => $eid));
 482   }
 483
 484   /**
 485    * RSVPs the current user to this event.
 486    *
 487    * @param int $eid             event id
 488    * @param string $rsvp_status  'attending', 'unsure', or 'declined'
 489    *
 490    * @return bool  true if successful
 491    */
 492   public function &events_rsvp($eid, $rsvp_status) {
 493     return $this->call_method('facebook.events.rsvp',
 494         array(
 495         'eid' => $eid,
 496         'rsvp_status' => $rsvp_status));
 497   }
 498
 499   /**
 500    * Cancels an event. Only works for events where application is the admin.
 501    *
 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
 505    *
 506    * @return bool  true if successful
 507    */
 508   public function &events_cancel($eid, $cancel_message='') {
 509     return $this->call_method('facebook.events.cancel',
 510         array('eid' => $eid,
 511               'cancel_message' => $cancel_message));
 512   }
 513
 514   /**
 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.
 517    *
 518    * @param assoc array $event_info  json encoded event information
 519    *
 520    * @return int  event id
 521    */
 522   public function &events_create($event_info) {
 523     return $this->call_method('facebook.events.create',
 524         array('event_info' => $event_info));
 525   }
 526
 527   /**
 528    * Edits an existing event. Only works for events where application is admin.
 529    *
 530    * @param int $eid                 event id
 531    * @param assoc array $event_info  json encoded event information
 532    *
 533    * @return bool  true if successful
 534    */
 535   public function &events_edit($eid, $event_info) {
 536     return $this->call_method('facebook.events.edit',
 537         array('eid' => $eid,
 538               'event_info' => $event_info));
 539   }
 540
 541   /**
 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).
 545    *
 546    * @param string $url  The absolute URL from which to refresh the image.
 547    *
 548    * @return bool  true on success
 549    */
 550   public function &fbml_refreshImgSrc($url) {
 551     return $this->call_method('facebook.fbml.refreshImgSrc',
 552         array('url' => $url));
 553   }
 554
 555   /**
 556    * Fetches and re-caches the content stored at the given URL, for use in an
 557    * fb:ref FBML tag.
 558    *
 559    * @param string $url  The absolute URL from which to fetch content. This URL
 560    *                     should be used in a fb:ref FBML tag.
 561    *
 562    * @return bool  true on success
 563    */
 564   public function &fbml_refreshRefUrl($url) {
 565     return $this->call_method('facebook.fbml.refreshRefUrl',
 566         array('url' => $url));
 567   }
 568
 569   /**
 570    * Lets you insert text strings in their native language into the Facebook
 571    * Translations database so they can be translated.
 572    *
 573    * @param array $native_strings  An array of maps, where each map has a 'text'
 574    *                               field and a 'description' field.
 575    *
 576    * @return int  Number of strings uploaded.
 577    */
 578   public function &fbml_uploadNativeStrings($native_strings) {
 579     return $this->call_method('facebook.fbml.uploadNativeStrings',
 580         array('native_strings' => json_encode($native_strings)));
 581   }
 582
 583   /**
 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
 588    * each user.
 589    *
 590    * @param string $handle  The handle to associate with the given FBML.
 591    * @param string $fbml    The FBML to associate with the given handle.
 592    *
 593    * @return bool  true on success
 594    */
 595   public function &fbml_setRefHandle($handle, $fbml) {
 596     return $this->call_method('facebook.fbml.setRefHandle',
 597         array('handle' => $handle, 'fbml' => $fbml));
 598   }
 599
 600   /**
 601    * Register custom tags for the application. Custom tags can be used
 602    * to extend the set of tags available to applications in FBML
 603    * markup.
 604    *
 605    * Before you call this function,
 606    * make sure you read the full documentation at
 607    *
 608    * http://wiki.developers.facebook.com/index.php/Fbml.RegisterCustomTags
 609    *
 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.
 614    *
 615    * @param mixed $tags an array of tag objects (the full description is on the
 616    *   wiki page)
 617    *
 618    * @return int  the number of tags that were registered
 619    */
 620   public function &fbml_registerCustomTags($tags) {
 621     $tags = json_encode($tags);
 622     return $this->call_method('facebook.fbml.registerCustomTags',
 623                               array('tags' => $tags));
 624   }
 625
 626   /**
 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().
 633    *
 634    * @param int $app_id the application's id (optional)
 635    *
 636    * @return mixed  an array containing the custom tag  objects
 637    */
 638   public function &fbml_getCustomTags($app_id = null) {
 639     return $this->call_method('facebook.fbml.getCustomTags',
 640                               array('app_id' => $app_id));
 641   }
 642
 643
 644   /**
 645    * Delete custom tags the application has registered. If
 646    * $tag_names is null, all the application's custom tags will be
 647    * deleted.
 648    *
 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.
 652    *
 653    * @param array $tag_names the names of the tags to delete (optinal)
 654    * @return bool true on success
 655    */
 656   public function &fbml_deleteCustomTags($tag_names = null) {
 657     return $this->call_method('facebook.fbml.deleteCustomTags',
 658                               array('tag_names' => json_encode($tag_names)));
 659   }
 660
 661
 662
 663   /**
 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.
 668    *
 669    * For more details on this call, please visit the wiki page:
 670    *
 671    * http://wiki.developers.facebook.com/index.php/Feed.publishTemplatizedAction
 672    */
 673   public function &feed_publishTemplatizedAction($title_template,
 674                                                  $title_data,
 675                                                  $body_template,
 676                                                  $body_data,
 677                                                  $body_general,
 678                                                  $image_1=null,
 679                                                  $image_1_link=null,
 680                                                  $image_2=null,
 681                                                  $image_2_link=null,
 682                                                  $image_3=null,
 683                                                  $image_3_link=null,
 684                                                  $image_4=null,
 685                                                  $image_4_link=null,
 686                                                  $target_ids='',
 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));
 704   }
 705
 706   /**
 707    * Registers a template bundle.  Template bundles are somewhat involved, so
 708    * it's recommended you check out the wiki for more details:
 709    *
 710    *  http://wiki.developers.facebook.com/index.php/Feed.registerTemplateBundle
 711    *
 712    * @return string  A template bundle id
 713    */
 714   public function &feed_registerTemplateBundle($one_line_story_templates,
 715                                                $short_story_templates = array(),
 716                                                $full_story_template = null,
 717                                                $action_links = array()) {
 718
 719     $one_line_story_templates = json_encode($one_line_story_templates);
 720
 721     if (!empty($short_story_templates)) {
 722       $short_story_templates = json_encode($short_story_templates);
 723     }
 724
 725     if (isset($full_story_template)) {
 726       $full_story_template = json_encode($full_story_template);
 727     }
 728
 729     if (isset($action_links)) {
 730       $action_links = json_encode($action_links);
 731     }
 732
 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));
 738   }
 739
 740   /**
 741    * Retrieves the full list of active template bundles registered by the
 742    * requesting application.
 743    *
 744    * @return array  An array of template bundles
 745    */
 746   public function &feed_getRegisteredTemplateBundles() {
 747     return $this->call_method('facebook.feed.getRegisteredTemplateBundles',
 748         array());
 749   }
 750
 751   /**
 752    * Retrieves information about a specified template bundle previously
 753    * registered by the requesting application.
 754    *
 755    * @param string $template_bundle_id  The template bundle id
 756    *
 757    * @return array  Template bundle
 758    */
 759   public function &feed_getRegisteredTemplateBundleByID($template_bundle_id) {
 760     return $this->call_method('facebook.feed.getRegisteredTemplateBundleByID',
 761         array('template_bundle_id' => $template_bundle_id));
 762   }
 763
 764   /**
 765    * Deactivates a previously registered template bundle.
 766    *
 767    * @param string $template_bundle_id  The template bundle id
 768    *
 769    * @return bool  true on success
 770    */
 771   public function &feed_deactivateTemplateBundleByID($template_bundle_id) {
 772     return $this->call_method('facebook.feed.deactivateTemplateBundleByID',
 773         array('template_bundle_id' => $template_bundle_id));
 774   }
 775
 776   const STORY_SIZE_ONE_LINE = 1;
 777   const STORY_SIZE_SHORT = 2;
 778   const STORY_SIZE_FULL = 4;
 779
 780   /**
 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.
 784    *
 785    * The parameters to this method ($templata_data in particular) are somewhat
 786    * involved.  It's recommended you visit the wiki for details:
 787    *
 788    *  http://wiki.developers.facebook.com/index.php/Feed.publishUserAction
 789    *
 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
 798    *                                 story.
 799    *
 800    * @return bool  true on success
 801    */
 802   public function &feed_publishUserAction(
 803       $template_bundle_id, $template_data, $target_ids='', $body_general='',
 804       $story_size=FacebookRestClient::STORY_SIZE_ONE_LINE,
 805       $user_message='') {
 806
 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
 810
 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
 814     }
 815
 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));
 823   }
 824
 825
 826   /**
 827    * Publish a post to the user's stream.
 828    *
 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
 833    *                        (optional)
 834    * @param $uid            the actor (defaults to session user)
 835    * @return string the post id
 836    */
 837   public function stream_publish(
 838     $message, $attachment = null, $action_links = null, $target_id = null,
 839     $uid = null) {
 840
 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)));
 848   }
 849
 850   /**
 851    * Remove a post from the user's stream.
 852    * Currently, you may only remove stories you application created.
 853    *
 854    * @param $post_id  the post id
 855    * @param $uid      the actor (defaults to session user)
 856    * @return bool
 857    */
 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)));
 863   }
 864
 865   /**
 866    * Add a comment to a stream post
 867    *
 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
 872    */
 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)));
 879   }
 880
 881
 882   /**
 883    * Remove a comment from a stream post
 884    *
 885    * @param $comment_id  the comment id
 886    * @param $uid      the actor (defaults to session user)
 887    * @return bool
 888    */
 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)));
 894   }
 895
 896   /**
 897    * Add a like to a stream post
 898    *
 899    * @param $post_id  the post id
 900    * @param $uid      the actor (defaults to session user)
 901    * @return bool
 902    */
 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)));
 908   }
 909
 910   /**
 911    * Remove a like from a stream post
 912    *
 913    * @param $post_id  the post id
 914    * @param $uid      the actor (defaults to session user)
 915    * @return bool
 916    */
 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)));
 922   }
 923
 924   /**
 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.
 928    *
 929    * @return array  An array of feed story objects.
 930    */
 931   public function &feed_getAppFriendStories() {
 932     return $this->call_method('facebook.feed.getAppFriendStories');
 933   }
 934
 935   /**
 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
 939    *
 940    * @param string $query  the query to evaluate
 941    *
 942    * @return array  generalized array representing the results
 943    */
 944   public function &fql_query($query) {
 945     return $this->call_method('facebook.fql.query',
 946       array('query' => $query));
 947   }
 948
 949   /**
 950    * Returns whether or not pairs of users are friends.
 951    * Note that the Facebook friend relationship is symmetric.
 952    *
 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)
 957    *
 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)
 961    *         ...)
 962    * @error
 963    *    API_EC_PARAM_USER_ID_LIST
 964    */
 965   public function &friends_areFriends($uids1, $uids2) {
 966     return $this->call_method('facebook.friends.areFriends',
 967                  array('uids1' => $uids1,
 968                        'uids2' => $uids2));
 969   }
 970
 971   /**
 972    * Returns the friends of the current session user.
 973    *
 974    * @param int $flid  (Optional) Only return friends on this friend list.
 975    * @param int $uid   (Optional) Return friends for this user.
 976    *
 977    * @return array  An array of friends
 978    */
 979   public function &friends_get($flid=null, $uid = null) {
 980     if (isset($this->friends_list)) {
 981       return $this->friends_list;
 982     }
 983     $params = array();
 984     if (!$uid && isset($this->canvas_user)) {
 985       $uid = $this->canvas_user;
 986     }
 987     if ($uid) {
 988       $params['uid'] = $uid;
 989     }
 990     if ($flid) {
 991       $params['flid'] = $flid;
 992     }
 993     return $this->call_method('facebook.friends.get', $params);
 994
 995   }
 996
 997   /**
 998    * Returns the set of friend lists for the current session user.
 999    *
1000    * @return array  An array of friend list objects
1001    */
1002   public function &friends_getLists() {
1003     return $this->call_method('facebook.friends.getLists');
1004   }
1005
1006   /**
1007    * Returns the friends of the session user, who are also users
1008    * of the calling application.
1009    *
1010    * @return array  An array of friends also using the app
1011    */
1012   public function &friends_getAppUsers() {
1013     return $this->call_method('facebook.friends.getAppUsers');
1014   }
1015
1016   /**
1017    * Returns groups according to the filters specified.
1018    *
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)
1024    *
1025    * @return array  An array of group objects
1026    */
1027   public function &groups_get($uid, $gids) {
1028     return $this->call_method('facebook.groups.get',
1029         array('uid' => $uid,
1030               'gids' => $gids));
1031   }
1032
1033   /**
1034    * Returns the membership list of a group.
1035    *
1036    * @param int $gid  Group id
1037    *
1038    * @return array  An array with four membership lists, with keys 'members',
1039    *                'admins', 'officers', and 'not_replied'
1040    */
1041   public function &groups_getMembers($gid) {
1042     return $this->call_method('facebook.groups.getMembers',
1043       array('gid' => $gid));
1044   }
1045
1046   /**
1047    * Returns cookies according to the filters specified.
1048    *
1049    * @param int $uid     User for which the cookies are needed.
1050    * @param string $name (Optional) A null parameter will get all cookies
1051    *                     for the user.
1052    *
1053    * @return array  Cookies!  Nom nom nom nom nom.
1054    */
1055   public function data_getCookies($uid, $name) {
1056     return $this->call_method('facebook.data.getCookies',
1057         array('uid' => $uid,
1058               'name' => $name));
1059   }
1060
1061   /**
1062    * Sets cookies according to the params specified.
1063    *
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 /)
1069    *
1070    * @return bool  true on success
1071    */
1072   public function data_setCookie($uid, $name, $value, $expires, $path) {
1073     return $this->call_method('facebook.data.setCookie',
1074         array('uid' => $uid,
1075               'name' => $name,
1076               'value' => $value,
1077               'expires' => $expires,
1078               'path' => $path));
1079   }
1080
1081   /**
1082    * Retrieves links posted by the given user.
1083    *
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
1088    *
1089    * @return array  An array of links.
1090    */
1091   public function &links_get($uid, $limit, $link_ids = null) {
1092     return $this->call_method('links.get',
1093         array('uid' => $uid,
1094               'limit' => $limit,
1095               'link_ids' => $link_ids));
1096   }
1097
1098   /**
1099    * Posts a link on Facebook.
1100    *
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
1105    *
1106    * @return bool
1107    */
1108   public function &links_post($url, $comment='', $uid = null) {
1109     return $this->call_method('links.post',
1110         array('uid' => $uid,
1111               'url' => $url,
1112               'comment' => $comment));
1113   }
1114
1115   /**
1116    * Permissions API
1117    */
1118
1119   /**
1120    * Checks API-access granted by self to the specified application.
1121    *
1122    * @param string $permissions_apikey  Other application key
1123    *
1124    * @return array  API methods/namespaces which are allowed access
1125    */
1126   public function permissions_checkGrantedApiAccess($permissions_apikey) {
1127     return $this->call_method('facebook.permissions.checkGrantedApiAccess',
1128         array('permissions_apikey' => $permissions_apikey));
1129   }
1130
1131   /**
1132    * Checks API-access granted to self by the specified application.
1133    *
1134    * @param string $permissions_apikey  Other application key
1135    *
1136    * @return array  API methods/namespaces which are allowed access
1137    */
1138   public function permissions_checkAvailableApiAccess($permissions_apikey) {
1139     return $this->call_method('facebook.permissions.checkAvailableApiAccess',
1140         array('permissions_apikey' => $permissions_apikey));
1141   }
1142
1143   /**
1144    * Grant API-access to the specified methods/namespaces to the specified
1145    * application.
1146    *
1147    * @param string $permissions_apikey  Other application key
1148    * @param array(string) $method_arr   (Optional) API methods/namespaces
1149    *                                    allowed
1150    *
1151    * @return array  API methods/namespaces which are allowed access
1152    */
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));
1157   }
1158
1159   /**
1160    * Revoke API-access granted to the specified application.
1161    *
1162    * @param string $permissions_apikey  Other application key
1163    *
1164    * @return bool  true on success
1165    */
1166   public function permissions_revokeApiAccess($permissions_apikey) {
1167     return $this->call_method('facebook.permissions.revokeApiAccess',
1168         array('permissions_apikey' => $permissions_apikey));
1169   }
1170
1171   /**
1172    * Creates a note with the specified title and content.
1173    *
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
1178    *
1179    * @return int   The ID of the note that was just created.
1180    */
1181   public function &notes_create($title, $content, $uid = null) {
1182     return $this->call_method('notes.create',
1183         array('uid' => $uid,
1184               'title' => $title,
1185               'content' => $content));
1186   }
1187
1188   /**
1189    * Deletes the specified note.
1190    *
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
1194    *
1195    * @return bool
1196    */
1197   public function &notes_delete($note_id, $uid = null) {
1198     return $this->call_method('notes.delete',
1199         array('uid' => $uid,
1200               'note_id' => $note_id));
1201   }
1202
1203   /**
1204    * Edits a note, replacing its title and contents with the title
1205    * and contents specified.
1206    *
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
1212    *
1213    * @return bool
1214    */
1215   public function &notes_edit($note_id, $title, $content, $uid = null) {
1216     return $this->call_method('notes.edit',
1217         array('uid' => $uid,
1218               'note_id' => $note_id,
1219               'title' => $title,
1220               'content' => $content));
1221   }
1222
1223   /**
1224    * Retrieves all notes by a user. If note_ids are specified,
1225    * retrieves only those specific notes by that user.
1226    *
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
1230    *
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
1233    *               notes.
1234    */
1235   public function &notes_get($uid, $note_ids = null) {
1236
1237     return $this->call_method('notes.get',
1238         array('uid' => $uid,
1239               'note_ids' => $note_ids));
1240   }
1241
1242
1243   /**
1244    * Returns the outstanding notifications for the session user.
1245    *
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'
1250    */
1251   public function &notifications_get() {
1252     return $this->call_method('facebook.notifications.get');
1253   }
1254
1255   /**
1256    * Sends a notification to the specified users.
1257    *
1258    * @return A comma separated list of successful recipients
1259    * @error
1260    *    API_EC_PARAM_USER_ID_LIST
1261    */
1262   public function &notifications_send($to_ids, $notification, $type) {
1263     return $this->call_method('facebook.notifications.send',
1264         array('to_ids' => $to_ids,
1265               'notification' => $notification,
1266               'type' => $type));
1267   }
1268
1269   /**
1270    * Sends an email to the specified user of the application.
1271    *
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
1276    *
1277    * @return string  A comma separated list of successful recipients
1278    * @error
1279    *    API_EC_PARAM_USER_ID_LIST
1280    */
1281   public function &notifications_sendEmail($recipients,
1282                                            $subject,
1283                                            $text,
1284                                            $fbml) {
1285     return $this->call_method('facebook.notifications.sendEmail',
1286         array('recipients' => $recipients,
1287               'subject' => $subject,
1288               'text' => $text,
1289               'fbml' => $fbml));
1290   }
1291
1292   /**
1293    * Returns the requested info fields for the requested set of pages.
1294    *
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
1299    *                          user is a fan.
1300    * @param string type       limits results to a particular type of page.
1301    *
1302    * @return array  An array of pages
1303    */
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,
1308               'uid' => $uid,
1309               'type' => $type));
1310   }
1311
1312   /**
1313    * Returns true if the given user is an admin for the passed page.
1314    *
1315    * @param int $page_id  target page id
1316    * @param int $uid      (Optional) user id (defaults to the logged-in user)
1317    *
1318    * @return bool  true on success
1319    */
1320   public function &pages_isAdmin($page_id, $uid = null) {
1321     return $this->call_method('facebook.pages.isAdmin',
1322         array('page_id' => $page_id,
1323               'uid' => $uid));
1324   }
1325
1326   /**
1327    * Returns whether or not the given page has added the application.
1328    *
1329    * @param int $page_id  target page id
1330    *
1331    * @return bool  true on success
1332    */
1333   public function &pages_isAppAdded($page_id) {
1334     return $this->call_method('facebook.pages.isAppAdded',
1335         array('page_id' => $page_id));
1336   }
1337
1338   /**
1339    * Returns true if logged in user is a fan for the passed page.
1340    *
1341    * @param int $page_id target page id
1342    * @param int $uid user to compare.  If empty, the logged in user.
1343    *
1344    * @return bool  true on success
1345    */
1346   public function &pages_isFan($page_id, $uid = null) {
1347     return $this->call_method('facebook.pages.isFan',
1348         array('page_id' => $page_id,
1349               'uid' => $uid));
1350   }
1351
1352   /**
1353    * Adds a tag with the given information to a photo. See the wiki for details:
1354    *
1355    *  http://wiki.developers.facebook.com/index.php/Photos.addTag
1356    *
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
1366    *                          photo.
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.
1376    *
1377    * @return bool  true on success
1378    */
1379   public function &photos_addTag($pid,
1380                                  $tag_uid,
1381                                  $tag_text,
1382                                  $x,
1383                                  $y,
1384                                  $tags,
1385                                  $owner_uid=0) {
1386     return $this->call_method('facebook.photos.addTag',
1387         array('pid' => $pid,
1388               'tag_uid' => $tag_uid,
1389               'tag_text' => $tag_text,
1390               'x' => $x,
1391               'y' => $y,
1392               'tags' => (is_array($tags)) ? json_encode($tags) : null,
1393               'owner_uid' => $this->get_uid($owner_uid)));
1394   }
1395
1396   /**
1397    * Creates and returns a new album owned by the specified user or the current
1398    * session user.
1399    *
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.
1408    *
1409    * @return array  An album object
1410    */
1411   public function &photos_createAlbum($name,
1412                                       $description='',
1413                                       $location='',
1414                                       $visible='',
1415                                       $uid=0) {
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)));
1422   }
1423
1424   /**
1425    * Returns photos according to the filters specified.
1426    *
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
1429    *                      photos_getAlbums.
1430    * @param array/string $pids   (Optional) Restrict to an array of pids
1431    *                             (csv is deprecated)
1432    *
1433    * Note that at least one of these parameters needs to be specified, or an
1434    * error is returned.
1435    *
1436    * @return array  An array of photo objects.
1437    */
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));
1441   }
1442
1443   /**
1444    * Returns the albums created by the given user.
1445    *
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)
1450    *
1451    * Note that at least one of the (uid, aids) parameters must be specified.
1452    *
1453    * @returns an array of album objects.
1454    */
1455   public function &photos_getAlbums($uid, $aids) {
1456     return $this->call_method('facebook.photos.getAlbums',
1457       array('uid' => $uid,
1458             'aids' => $aids));
1459   }
1460
1461   /**
1462    * Returns the tags on all photos specified.
1463    *
1464    * @param string $pids  A list of pids to query
1465    *
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.
1469    */
1470   public function &photos_getTags($pids) {
1471     return $this->call_method('facebook.photos.getTags',
1472       array('pids' => $pids));
1473   }
1474
1475   /**
1476    * Uploads a photo.
1477    *
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
1480    *                         photo.
1481    * @param string $caption  (Optional) A caption for the photo.
1482    * @param int uid          (Optional) The user ID of the user whose photo you
1483    *                         are uploading
1484    *
1485    * @return array  An array of user objects
1486    */
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,
1491                                            'uid' => $uid),
1492                                      $file);
1493   }
1494
1495
1496   /**
1497    * Uploads a video.
1498    *
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.
1502    *
1503    * @return array  An array with the video's ID, title, description, and a link to view it on Facebook.
1504    */
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),
1509                                      $file,
1510                                      Facebook::get_facebook_url('api-video') . '/restserver.php');
1511   }
1512
1513   /**
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.
1517    *
1518    * @return array  Array with "length" and "size" keys
1519    */
1520   public function &video_getUploadLimits() {
1521     return $this->call_method('facebook.video.getUploadLimits');
1522   }
1523
1524   /**
1525    * Returns the requested info fields for the requested set of users.
1526    *
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)
1529    *
1530    * @return array  An array of user objects
1531    */
1532   public function &users_getInfo($uids, $fields) {
1533     return $this->call_method('facebook.users.getInfo',
1534                   array('uids' => $uids,
1535                         'fields' => $fields));
1536   }
1537
1538   /**
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.
1542    *
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
1546    * applied.
1547    *
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)
1550    *
1551    * @return array  An array of user objects
1552    */
1553   public function &users_getStandardInfo($uids, $fields) {
1554     return $this->call_method('facebook.users.getStandardInfo',
1555                               array('uids' => $uids,
1556                                     'fields' => $fields));
1557   }
1558
1559   /**
1560    * Returns the user corresponding to the current session object.
1561    *
1562    * @return integer  User id
1563    */
1564   public function &users_getLoggedInUser() {
1565     return $this->call_method('facebook.users.getLoggedInUser');
1566   }
1567
1568   /**
1569    * Returns 1 if the user has the specified permission, 0 otherwise.
1570    * http://wiki.developers.facebook.com/index.php/Users.hasAppPermission
1571    *
1572    * @return integer  1 or 0
1573    */
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));
1577   }
1578
1579   /**
1580    * Returns whether or not the user corresponding to the current
1581    * session object has the give the app basic authorization.
1582    *
1583    * @return boolean  true if the user has authorized the app
1584    */
1585   public function &users_isAppUser($uid=null) {
1586     if ($uid === null && isset($this->is_user)) {
1587       return $this->is_user;
1588     }
1589
1590     return $this->call_method('facebook.users.isAppUser', array('uid' => $uid));
1591   }
1592
1593   /**
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.
1597    *
1598    * @return boolean  true if the user is verified
1599    */
1600   public function &users_isVerified() {
1601     return $this->call_method('facebook.users.isVerified');
1602   }
1603
1604   /**
1605    * Sets the users' current status message. Message does NOT contain the
1606    * word "is" , so make sure to include a verb.
1607    *
1608    * Example: setStatus("is loving the API!")
1609    * will produce the status "Luke is loving the API!"
1610    *
1611    * @param string $status                text-only message to set
1612    * @param int    $uid                   user to set for (defaults to the
1613    *                                      logged-in user)
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
1618    *
1619    * @return boolean
1620    */
1621   public function &users_setStatus($status,
1622                                    $uid = null,
1623                                    $clear = false,
1624                                    $status_includes_verb = true) {
1625     $args = array(
1626       'status' => $status,
1627       'uid' => $uid,
1628       'clear' => $clear,
1629       'status_includes_verb' => $status_includes_verb,
1630     );
1631     return $this->call_method('facebook.users.setStatus', $args);
1632   }
1633
1634   /**
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
1637    * and $end_time.
1638    *
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
1645    *
1646    * @return array(
1647    *           'posts'    => array of posts,
1648    *           'profiles' => array of profile metadata of users/pages in posts
1649    *           'albums'   => array of album metadata in posts
1650    *         )
1651    */
1652   public function &stream_get($viewer_id = null,
1653                               $source_ids = null,
1654                               $start_time = 0,
1655                               $end_time = 0,
1656                               $limit = 30,
1657                               $filter_key = '') {
1658     $args = array(
1659       'viewer_id'  => $viewer_id,
1660       'source_ids' => $source_ids,
1661       'start_time' => $start_time,
1662       'end_time'   => $end_time,
1663       'limit'      => $limit,
1664       'filter_key' => $filter_key);
1665     return $this->call_method('facebook.stream.get', $args);
1666   }
1667
1668   /**
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.
1673    *
1674    * @param int $uid user to get filters for
1675    *
1676    * @return array of stream filter objects
1677    */
1678   public function &stream_getFilters($uid = null) {
1679     $args = array('uid' => $uid);
1680     return $this->call_method('facebook.stream.getFilters', $args);
1681   }
1682
1683   /**
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.
1687    *
1688    * @param string $post_id id of the post to get comments for
1689    *
1690    * @return array of comment objects
1691    */
1692   public function &stream_getComments($post_id) {
1693     $args = array('post_id' => $post_id);
1694     return $this->call_method('facebook.stream.getComments', $args);
1695   }
1696
1697   /**
1698    * Sets the FBML for the profile of the user attached to this session.
1699    *
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
1707    *
1708    * @return  array  A list of strings describing any compile errors for the
1709    *                 submitted FBML
1710    */
1711   function profile_setFBML($markup,
1712                            $uid=null,
1713                            $profile='',
1714                            $profile_action='',
1715                            $mobile_profile='',
1716                            $profile_main='') {
1717     return $this->call_method('facebook.profile.setFBML',
1718         array('markup' => $markup,
1719               'uid' => $uid,
1720               'profile' => $profile,
1721               'profile_action' => $profile_action,
1722               'mobile_profile' => $mobile_profile,
1723               'profile_main' => $profile_main));
1724   }
1725
1726   /**
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).
1730    *
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
1733    *
1734    * @return string  The FBML
1735    */
1736   public function &profile_getFBML($uid=null, $type=null) {
1737     return $this->call_method('facebook.profile.getFBML',
1738         array('uid' => $uid,
1739               'type' => $type));
1740   }
1741
1742   /**
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.
1746    *
1747    * @param int $uid  (Optional) User id to lookup; defaults to session.
1748    *
1749    * @return array  Info fields for the current user.  See wiki for structure:
1750    *
1751    *  http://wiki.developers.facebook.com/index.php/Profile.getInfo
1752    *
1753    */
1754   public function &profile_getInfo($uid=null) {
1755     return $this->call_method('facebook.profile.getInfo',
1756         array('uid' => $uid));
1757   }
1758
1759   /**
1760    * Returns the options associated with the specified info field for an
1761    * application info section.
1762    *
1763    * @param string $field  The title of the field
1764    *
1765    * @return array  An array of info options.
1766    */
1767   public function &profile_getInfoOptions($field) {
1768     return $this->call_method('facebook.profile.getInfoOptions',
1769         array('field' => $field));
1770   }
1771
1772   /**
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:
1776    *
1777    *  http://wiki.developers.facebook.com/index.php/Profile.setInfo
1778    *
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)
1783    *
1784    * @return bool  true on success
1785    */
1786   public function &profile_setInfo($title, $type, $info_fields, $uid=null) {
1787     return $this->call_method('facebook.profile.setInfo',
1788         array('uid' => $uid,
1789               'type' => $type,
1790               'title'   => $title,
1791               'info_fields' => json_encode($info_fields)));
1792   }
1793
1794   /**
1795    * Specifies the objects for a field for an application info section. These
1796    * options populate the typeahead for a thumbnail.
1797    *
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'
1802    *
1803    * @return bool  true on success
1804    */
1805   public function profile_setInfoOptions($field, $options) {
1806     return $this->call_method('facebook.profile.setInfoOptions',
1807         array('field'   => $field,
1808               'options' => json_encode($options)));
1809   }
1810
1811   /**
1812    * Get all the marketplace categories.
1813    *
1814    * @return array  A list of category names
1815    */
1816   function marketplace_getCategories() {
1817     return $this->call_method('facebook.marketplace.getCategories',
1818         array());
1819   }
1820
1821   /**
1822    * Get all the marketplace subcategories for a particular category.
1823    *
1824    * @param  category  The category for which we are pulling subcategories
1825    *
1826    * @return array A list of subcategory names
1827    */
1828   function marketplace_getSubCategories($category) {
1829     return $this->call_method('facebook.marketplace.getSubCategories',
1830         array('category' => $category));
1831   }
1832
1833   /**
1834    * Get listings by either listing_id or user.
1835    *
1836    * @param listing_ids   An array of listing_ids (optional)
1837    * @param uids          An array of user ids (optional)
1838    *
1839    * @return array  The data for matched listings
1840    */
1841   function marketplace_getListings($listing_ids, $uids) {
1842     return $this->call_method('facebook.marketplace.getListings',
1843         array('listing_ids' => $listing_ids, 'uids' => $uids));
1844   }
1845
1846   /**
1847    * Search for Marketplace listings.  All arguments are optional, though at
1848    * least one must be filled out to retrieve results.
1849    *
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)
1853    *
1854    * @return array  The data for matched listings
1855    */
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));
1861   }
1862
1863   /**
1864    * Remove a listing from Marketplace.
1865    *
1866    * @param listing_id  The id of the listing to be removed
1867    * @param status      'SUCCESS', 'NOT_SUCCESS', or 'DEFAULT'
1868    *
1869    * @return bool  True on success
1870    */
1871   function marketplace_removeListing($listing_id,
1872                                      $status='DEFAULT',
1873                                      $uid=null) {
1874     return $this->call_method('facebook.marketplace.removeListing',
1875         array('listing_id' => $listing_id,
1876               'status' => $status,
1877               'uid' => $uid));
1878   }
1879
1880   /**
1881    * Create/modify a Marketplace listing for the loggedinuser.
1882    *
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
1886    *                                     user's profile
1887    * @param listing_attrs    array       An array of the listing data
1888    *
1889    * @return int  The listing_id (unchanged if modifying an existing listing).
1890    */
1891   function marketplace_createListing($listing_id,
1892                                      $show_on_profile,
1893                                      $attrs,
1894                                      $uid=null) {
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),
1899               'uid' => $uid));
1900   }
1901
1902   /////////////////////////////////////////////////////////////////////////////
1903   // Data Store API
1904
1905   /**
1906    * Set a user preference.
1907    *
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)
1911    * @error
1912    *    API_EC_DATA_DATABASE_ERROR
1913    *    API_EC_PARAM
1914    *    API_EC_DATA_QUOTA_EXCEEDED
1915    *    API_EC_DATA_UNKNOWN_ERROR
1916    *    API_EC_PERMISSION_OTHER_USER
1917    */
1918   public function &data_setUserPreference($pref_id, $value, $uid = null) {
1919     return $this->call_method('facebook.data.setUserPreference',
1920        array('pref_id' => $pref_id,
1921              'value' => $value,
1922              'uid' => $this->get_uid($uid)));
1923   }
1924
1925   /**
1926    * Set a user's all preferences for this application.
1927    *
1928    * @param  values     preferece values in an associative arrays
1929    * @param  replace    whether to replace all existing preferences or
1930    *                    merge into them.
1931    * @param  uid        the user id (defaults to current session user)
1932    * @error
1933    *    API_EC_DATA_DATABASE_ERROR
1934    *    API_EC_PARAM
1935    *    API_EC_DATA_QUOTA_EXCEEDED
1936    *    API_EC_DATA_UNKNOWN_ERROR
1937    *    API_EC_PERMISSION_OTHER_USER
1938    */
1939   public function &data_setUserPreferences($values,
1940                                            $replace = false,
1941                                            $uid = null) {
1942     return $this->call_method('facebook.data.setUserPreferences',
1943        array('values' => json_encode($values),
1944              'replace' => $replace,
1945              'uid' => $this->get_uid($uid)));
1946   }
1947
1948   /**
1949    * Get a user preference.
1950    *
1951    * @param  pref_id    preference identifier (0-200)
1952    * @param  uid        the user id (defaults to current session user)
1953    * @return            preference's value
1954    * @error
1955    *    API_EC_DATA_DATABASE_ERROR
1956    *    API_EC_PARAM
1957    *    API_EC_DATA_QUOTA_EXCEEDED
1958    *    API_EC_DATA_UNKNOWN_ERROR
1959    *    API_EC_PERMISSION_OTHER_USER
1960    */
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)));
1965   }
1966
1967   /**
1968    * Get a user preference.
1969    *
1970    * @param  uid        the user id (defaults to current session user)
1971    * @return            preference values
1972    * @error
1973    *    API_EC_DATA_DATABASE_ERROR
1974    *    API_EC_DATA_QUOTA_EXCEEDED
1975    *    API_EC_DATA_UNKNOWN_ERROR
1976    *    API_EC_PERMISSION_OTHER_USER
1977    */
1978   public function &data_getUserPreferences($uid = null) {
1979     return $this->call_method('facebook.data.getUserPreferences',
1980        array('uid' => $this->get_uid($uid)));
1981   }
1982
1983   /**
1984    * Create a new object type.
1985    *
1986    * @param  name       object type's name
1987    * @error
1988    *    API_EC_DATA_DATABASE_ERROR
1989    *    API_EC_DATA_OBJECT_ALREADY_EXISTS
1990    *    API_EC_PARAM
1991    *    API_EC_PERMISSION
1992    *    API_EC_DATA_INVALID_OPERATION
1993    *    API_EC_DATA_QUOTA_EXCEEDED
1994    *    API_EC_DATA_UNKNOWN_ERROR
1995    */
1996   public function &data_createObjectType($name) {
1997     return $this->call_method('facebook.data.createObjectType',
1998        array('name' => $name));
1999   }
2000
2001   /**
2002    * Delete an object type.
2003    *
2004    * @param  obj_type       object type's name
2005    * @error
2006    *    API_EC_DATA_DATABASE_ERROR
2007    *    API_EC_DATA_OBJECT_NOT_FOUND
2008    *    API_EC_PARAM
2009    *    API_EC_PERMISSION
2010    *    API_EC_DATA_INVALID_OPERATION
2011    *    API_EC_DATA_QUOTA_EXCEEDED
2012    *    API_EC_DATA_UNKNOWN_ERROR
2013    */
2014   public function &data_dropObjectType($obj_type) {
2015     return $this->call_method('facebook.data.dropObjectType',
2016        array('obj_type' => $obj_type));
2017   }
2018
2019   /**
2020    * Rename an object type.
2021    *
2022    * @param  obj_type       object type's name
2023    * @param  new_name       new object type's name
2024    * @error
2025    *    API_EC_DATA_DATABASE_ERROR
2026    *    API_EC_DATA_OBJECT_NOT_FOUND
2027    *    API_EC_DATA_OBJECT_ALREADY_EXISTS
2028    *    API_EC_PARAM
2029    *    API_EC_PERMISSION
2030    *    API_EC_DATA_INVALID_OPERATION
2031    *    API_EC_DATA_QUOTA_EXCEEDED
2032    *    API_EC_DATA_UNKNOWN_ERROR
2033    */
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));
2038   }
2039
2040   /**
2041    * Add a new property to an object type.
2042    *
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
2046    * @error
2047    *    API_EC_DATA_DATABASE_ERROR
2048    *    API_EC_DATA_OBJECT_ALREADY_EXISTS
2049    *    API_EC_PARAM
2050    *    API_EC_PERMISSION
2051    *    API_EC_DATA_INVALID_OPERATION
2052    *    API_EC_DATA_QUOTA_EXCEEDED
2053    *    API_EC_DATA_UNKNOWN_ERROR
2054    */
2055   public function &data_defineObjectProperty($obj_type,
2056                                              $prop_name,
2057                                              $prop_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));
2062   }
2063
2064   /**
2065    * Remove a previously defined property from an object type.
2066    *
2067    * @param  obj_type      object type's name
2068    * @param  prop_name     name of the property to remove
2069    * @error
2070    *    API_EC_DATA_DATABASE_ERROR
2071    *    API_EC_DATA_OBJECT_NOT_FOUND
2072    *    API_EC_PARAM
2073    *    API_EC_PERMISSION
2074    *    API_EC_DATA_INVALID_OPERATION
2075    *    API_EC_DATA_QUOTA_EXCEEDED
2076    *    API_EC_DATA_UNKNOWN_ERROR
2077    */
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));
2082   }
2083
2084   /**
2085    * Rename a previously defined property of an object type.
2086    *
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
2090    * @error
2091    *    API_EC_DATA_DATABASE_ERROR
2092    *    API_EC_DATA_OBJECT_NOT_FOUND
2093    *    API_EC_DATA_OBJECT_ALREADY_EXISTS
2094    *    API_EC_PARAM
2095    *    API_EC_PERMISSION
2096    *    API_EC_DATA_INVALID_OPERATION
2097    *    API_EC_DATA_QUOTA_EXCEEDED
2098    *    API_EC_DATA_UNKNOWN_ERROR
2099    */
2100   public function &data_renameObjectProperty($obj_type, $prop_name,
2101                                             $new_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));
2106   }
2107
2108   /**
2109    * Retrieve a list of all object types that have defined for the application.
2110    *
2111    * @return               a list of object type names
2112    * @error
2113    *    API_EC_DATA_DATABASE_ERROR
2114    *    API_EC_PERMISSION
2115    *    API_EC_DATA_QUOTA_EXCEEDED
2116    *    API_EC_DATA_UNKNOWN_ERROR
2117    */
2118   public function &data_getObjectTypes() {
2119     return $this->call_method('facebook.data.getObjectTypes');
2120   }
2121
2122   /**
2123    * Get definitions of all properties of an object type.
2124    *
2125    * @param obj_type       object type's name
2126    * @return               pairs of property name and property types
2127    * @error
2128    *    API_EC_DATA_DATABASE_ERROR
2129    *    API_EC_PARAM
2130    *    API_EC_PERMISSION
2131    *    API_EC_DATA_OBJECT_NOT_FOUND
2132    *    API_EC_DATA_QUOTA_EXCEEDED
2133    *    API_EC_DATA_UNKNOWN_ERROR
2134    */
2135   public function &data_getObjectType($obj_type) {
2136     return $this->call_method('facebook.data.getObjectType',
2137        array('obj_type' => $obj_type));
2138   }
2139
2140   /**
2141    * Create a new object.
2142    *
2143    * @param  obj_type      object type's name
2144    * @param  properties    (optional) properties to set initially
2145    * @return               newly created object's id
2146    * @error
2147    *    API_EC_DATA_DATABASE_ERROR
2148    *    API_EC_PARAM
2149    *    API_EC_PERMISSION
2150    *    API_EC_DATA_INVALID_OPERATION
2151    *    API_EC_DATA_QUOTA_EXCEEDED
2152    *    API_EC_DATA_UNKNOWN_ERROR
2153    */
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)));
2158   }
2159
2160   /**
2161    * Update an existing object.
2162    *
2163    * @param  obj_id        object's id
2164    * @param  properties    new properties
2165    * @param  replace       true for replacing existing properties;
2166    *                       false for merging
2167    * @error
2168    *    API_EC_DATA_DATABASE_ERROR
2169    *    API_EC_DATA_OBJECT_NOT_FOUND
2170    *    API_EC_PARAM
2171    *    API_EC_PERMISSION
2172    *    API_EC_DATA_INVALID_OPERATION
2173    *    API_EC_DATA_QUOTA_EXCEEDED
2174    *    API_EC_DATA_UNKNOWN_ERROR
2175    */
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));
2181   }
2182
2183   /**
2184    * Delete an existing object.
2185    *
2186    * @param  obj_id        object's id
2187    * @error
2188    *    API_EC_DATA_DATABASE_ERROR
2189    *    API_EC_DATA_OBJECT_NOT_FOUND
2190    *    API_EC_PARAM
2191    *    API_EC_PERMISSION
2192    *    API_EC_DATA_INVALID_OPERATION
2193    *    API_EC_DATA_QUOTA_EXCEEDED
2194    *    API_EC_DATA_UNKNOWN_ERROR
2195    */
2196   public function &data_deleteObject($obj_id) {
2197     return $this->call_method('facebook.data.deleteObject',
2198        array('obj_id' => $obj_id));
2199   }
2200
2201   /**
2202    * Delete a list of objects.
2203    *
2204    * @param  obj_ids       objects to delete
2205    * @error
2206    *    API_EC_DATA_DATABASE_ERROR
2207    *    API_EC_PARAM
2208    *    API_EC_PERMISSION
2209    *    API_EC_DATA_INVALID_OPERATION
2210    *    API_EC_DATA_QUOTA_EXCEEDED
2211    *    API_EC_DATA_UNKNOWN_ERROR
2212    */
2213   public function &data_deleteObjects($obj_ids) {
2214     return $this->call_method('facebook.data.deleteObjects',
2215        array('obj_ids' => json_encode($obj_ids)));
2216   }
2217
2218   /**
2219    * Get a single property value of an object.
2220    *
2221    * @param  obj_id        object's id
2222    * @param  prop_name     individual property's name
2223    * @return               individual property's value
2224    * @error
2225    *    API_EC_DATA_DATABASE_ERROR
2226    *    API_EC_DATA_OBJECT_NOT_FOUND
2227    *    API_EC_PARAM
2228    *    API_EC_PERMISSION
2229    *    API_EC_DATA_INVALID_OPERATION
2230    *    API_EC_DATA_QUOTA_EXCEEDED
2231    *    API_EC_DATA_UNKNOWN_ERROR
2232    */
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));
2237   }
2238
2239   /**
2240    * Get properties of an object.
2241    *
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
2245    * @error
2246    *    API_EC_DATA_DATABASE_ERROR
2247    *    API_EC_DATA_OBJECT_NOT_FOUND
2248    *    API_EC_PARAM
2249    *    API_EC_PERMISSION
2250    *    API_EC_DATA_INVALID_OPERATION
2251    *    API_EC_DATA_QUOTA_EXCEEDED
2252    *    API_EC_DATA_UNKNOWN_ERROR
2253    */
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)));
2258   }
2259
2260   /**
2261    * Get properties of a list of objects.
2262    *
2263    * @param  obj_ids     object ids
2264    * @param  prop_names  (optional) properties to return; null for all.
2265    * @return             specified properties of an object
2266    * @error
2267    *    API_EC_DATA_DATABASE_ERROR
2268    *    API_EC_DATA_OBJECT_NOT_FOUND
2269    *    API_EC_PARAM
2270    *    API_EC_PERMISSION
2271    *    API_EC_DATA_INVALID_OPERATION
2272    *    API_EC_DATA_QUOTA_EXCEEDED
2273    *    API_EC_DATA_UNKNOWN_ERROR
2274    */
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)));
2279   }
2280
2281   /**
2282    * Set a single property value of an object.
2283    *
2284    * @param  obj_id        object's id
2285    * @param  prop_name     individual property's name
2286    * @param  prop_value    new value to set
2287    * @error
2288    *    API_EC_DATA_DATABASE_ERROR
2289    *    API_EC_DATA_OBJECT_NOT_FOUND
2290    *    API_EC_PARAM
2291    *    API_EC_PERMISSION
2292    *    API_EC_DATA_INVALID_OPERATION
2293    *    API_EC_DATA_QUOTA_EXCEEDED
2294    *    API_EC_DATA_UNKNOWN_ERROR
2295    */
2296   public function &data_setObjectProperty($obj_id, $prop_name,
2297                                          $prop_value) {
2298     return $this->call_method('facebook.data.setObjectProperty',
2299        array('obj_id' => $obj_id,
2300              'prop_name' => $prop_name,
2301              'prop_value' => $prop_value));
2302   }
2303
2304   /**
2305    * Read hash value by key.
2306    *
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
2311    * @error
2312    *    API_EC_DATA_DATABASE_ERROR
2313    *    API_EC_PARAM
2314    *    API_EC_PERMISSION
2315    *    API_EC_DATA_INVALID_OPERATION
2316    *    API_EC_DATA_QUOTA_EXCEEDED
2317    *    API_EC_DATA_UNKNOWN_ERROR
2318    */
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,
2322              'key' => $key,
2323              'prop_name' => $prop_name));
2324   }
2325
2326   /**
2327    * Write hash value by key.
2328    *
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
2333    * @error
2334    *    API_EC_DATA_DATABASE_ERROR
2335    *    API_EC_PARAM
2336    *    API_EC_PERMISSION
2337    *    API_EC_DATA_INVALID_OPERATION
2338    *    API_EC_DATA_QUOTA_EXCEEDED
2339    *    API_EC_DATA_UNKNOWN_ERROR
2340    */
2341   public function &data_setHashValue($obj_type,
2342                                      $key,
2343                                      $value,
2344                                      $prop_name = null) {
2345     return $this->call_method('facebook.data.setHashValue',
2346        array('obj_type' => $obj_type,
2347              'key' => $key,
2348              'value' => $value,
2349              'prop_name' => $prop_name));
2350   }
2351
2352   /**
2353    * Increase a hash value by specified increment atomically.
2354    *
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
2360    * @error
2361    *    API_EC_DATA_DATABASE_ERROR
2362    *    API_EC_PARAM
2363    *    API_EC_PERMISSION
2364    *    API_EC_DATA_INVALID_OPERATION
2365    *    API_EC_DATA_QUOTA_EXCEEDED
2366    *    API_EC_DATA_UNKNOWN_ERROR
2367    */
2368   public function &data_incHashValue($obj_type,
2369                                      $key,
2370                                      $prop_name,
2371                                      $increment = 1) {
2372     return $this->call_method('facebook.data.incHashValue',
2373        array('obj_type' => $obj_type,
2374              'key' => $key,
2375              'prop_name' => $prop_name,
2376              'increment' => $increment));
2377   }
2378
2379   /**
2380    * Remove a hash key and its values.
2381    *
2382    * @param  obj_type    object type's name
2383    * @param  key         hash key
2384    * @error
2385    *    API_EC_DATA_DATABASE_ERROR
2386    *    API_EC_PARAM
2387    *    API_EC_PERMISSION
2388    *    API_EC_DATA_INVALID_OPERATION
2389    *    API_EC_DATA_QUOTA_EXCEEDED
2390    *    API_EC_DATA_UNKNOWN_ERROR
2391    */
2392   public function &data_removeHashKey($obj_type, $key) {
2393     return $this->call_method('facebook.data.removeHashKey',
2394        array('obj_type' => $obj_type,
2395              'key' => $key));
2396   }
2397
2398   /**
2399    * Remove hash keys and their values.
2400    *
2401    * @param  obj_type    object type's name
2402    * @param  keys        hash keys
2403    * @error
2404    *    API_EC_DATA_DATABASE_ERROR
2405    *    API_EC_PARAM
2406    *    API_EC_PERMISSION
2407    *    API_EC_DATA_INVALID_OPERATION
2408    *    API_EC_DATA_QUOTA_EXCEEDED
2409    *    API_EC_DATA_UNKNOWN_ERROR
2410    */
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)));
2415   }
2416
2417   /**
2418    * Define an object association.
2419    *
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
2425    * @error
2426    *    API_EC_DATA_DATABASE_ERROR
2427    *    API_EC_DATA_OBJECT_ALREADY_EXISTS
2428    *    API_EC_PARAM
2429    *    API_EC_PERMISSION
2430    *    API_EC_DATA_INVALID_OPERATION
2431    *    API_EC_DATA_QUOTA_EXCEEDED
2432    *    API_EC_DATA_UNKNOWN_ERROR
2433    */
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));
2442   }
2443
2444   /**
2445    * Undefine an object association.
2446    *
2447    * @param  name        name of this association
2448    * @error
2449    *    API_EC_DATA_DATABASE_ERROR
2450    *    API_EC_DATA_OBJECT_NOT_FOUND
2451    *    API_EC_PARAM
2452    *    API_EC_PERMISSION
2453    *    API_EC_DATA_INVALID_OPERATION
2454    *    API_EC_DATA_QUOTA_EXCEEDED
2455    *    API_EC_DATA_UNKNOWN_ERROR
2456    */
2457   public function &data_undefineAssociation($name) {
2458     return $this->call_method('facebook.data.undefineAssociation',
2459        array('name' => $name));
2460   }
2461
2462   /**
2463    * Rename an object association or aliases.
2464    *
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
2469    * @error
2470    *    API_EC_DATA_DATABASE_ERROR
2471    *    API_EC_DATA_OBJECT_ALREADY_EXISTS
2472    *    API_EC_DATA_OBJECT_NOT_FOUND
2473    *    API_EC_PARAM
2474    *    API_EC_PERMISSION
2475    *    API_EC_DATA_INVALID_OPERATION
2476    *    API_EC_DATA_QUOTA_EXCEEDED
2477    *    API_EC_DATA_UNKNOWN_ERROR
2478    */
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));
2486   }
2487
2488   /**
2489    * Get definition of an object association.
2490    *
2491    * @param  name        name of this association
2492    * @return             specified association
2493    * @error
2494    *    API_EC_DATA_DATABASE_ERROR
2495    *    API_EC_DATA_OBJECT_NOT_FOUND
2496    *    API_EC_PARAM
2497    *    API_EC_PERMISSION
2498    *    API_EC_DATA_QUOTA_EXCEEDED
2499    *    API_EC_DATA_UNKNOWN_ERROR
2500    */
2501   public function &data_getAssociationDefinition($name) {
2502     return $this->call_method('facebook.data.getAssociationDefinition',
2503        array('name' => $name));
2504   }
2505
2506   /**
2507    * Get definition of all associations.
2508    *
2509    * @return             all defined associations
2510    * @error
2511    *    API_EC_DATA_DATABASE_ERROR
2512    *    API_EC_PERMISSION
2513    *    API_EC_DATA_QUOTA_EXCEEDED
2514    *    API_EC_DATA_UNKNOWN_ERROR
2515    */
2516   public function &data_getAssociationDefinitions() {
2517     return $this->call_method('facebook.data.getAssociationDefinitions',
2518        array());
2519   }
2520
2521   /**
2522    * Create or modify an association between two objects.
2523    *
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
2529    * @error
2530    *    API_EC_DATA_DATABASE_ERROR
2531    *    API_EC_PARAM
2532    *    API_EC_PERMISSION
2533    *    API_EC_DATA_INVALID_OPERATION
2534    *    API_EC_DATA_QUOTA_EXCEEDED
2535    *    API_EC_DATA_UNKNOWN_ERROR
2536    */
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,
2543              'data' => $data,
2544              'assoc_time' => $assoc_time));
2545   }
2546
2547   /**
2548    * Create or modify associations between objects.
2549    *
2550    * @param  assocs      associations to set
2551    * @param  name        (optional) name of association
2552    * @error
2553    *    API_EC_DATA_DATABASE_ERROR
2554    *    API_EC_PARAM
2555    *    API_EC_PERMISSION
2556    *    API_EC_DATA_INVALID_OPERATION
2557    *    API_EC_DATA_QUOTA_EXCEEDED
2558    *    API_EC_DATA_UNKNOWN_ERROR
2559    */
2560   public function &data_setAssociations($assocs, $name = null) {
2561     return $this->call_method('facebook.data.setAssociations',
2562        array('assocs' => json_encode($assocs),
2563              'name' => $name));
2564   }
2565
2566   /**
2567    * Remove an association between two objects.
2568    *
2569    * @param  name        name of association
2570    * @param  obj_id1     id of first object
2571    * @param  obj_id2     id of second object
2572    * @error
2573    *    API_EC_DATA_DATABASE_ERROR
2574    *    API_EC_DATA_OBJECT_NOT_FOUND
2575    *    API_EC_PARAM
2576    *    API_EC_PERMISSION
2577    *    API_EC_DATA_QUOTA_EXCEEDED
2578    *    API_EC_DATA_UNKNOWN_ERROR
2579    */
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));
2585   }
2586
2587   /**
2588    * Remove associations between objects by specifying pairs of object ids.
2589    *
2590    * @param  assocs      associations to remove
2591    * @param  name        (optional) name of association
2592    * @error
2593    *    API_EC_DATA_DATABASE_ERROR
2594    *    API_EC_DATA_OBJECT_NOT_FOUND
2595    *    API_EC_PARAM
2596    *    API_EC_PERMISSION
2597    *    API_EC_DATA_QUOTA_EXCEEDED
2598    *    API_EC_DATA_UNKNOWN_ERROR
2599    */
2600   public function &data_removeAssociations($assocs, $name = null) {
2601     return $this->call_method('facebook.data.removeAssociations',
2602        array('assocs' => json_encode($assocs),
2603              'name' => $name));
2604   }
2605
2606   /**
2607    * Remove associations between objects by specifying one object id.
2608    *
2609    * @param  name        name of association
2610    * @param  obj_id      who's association to remove
2611    * @error
2612    *    API_EC_DATA_DATABASE_ERROR
2613    *    API_EC_DATA_OBJECT_NOT_FOUND
2614    *    API_EC_PARAM
2615    *    API_EC_PERMISSION
2616    *    API_EC_DATA_INVALID_OPERATION
2617    *    API_EC_DATA_QUOTA_EXCEEDED
2618    *    API_EC_DATA_UNKNOWN_ERROR
2619    */
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));
2624   }
2625
2626   /**
2627    * Retrieve a list of associated objects.
2628    *
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
2633    * @error
2634    *    API_EC_DATA_DATABASE_ERROR
2635    *    API_EC_DATA_OBJECT_NOT_FOUND
2636    *    API_EC_PARAM
2637    *    API_EC_PERMISSION
2638    *    API_EC_DATA_INVALID_OPERATION
2639    *    API_EC_DATA_QUOTA_EXCEEDED
2640    *    API_EC_DATA_UNKNOWN_ERROR
2641    */
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));
2647   }
2648
2649   /**
2650    * Count associated objects.
2651    *
2652    * @param  name        name of association
2653    * @param  obj_id      who's association to retrieve
2654    * @return             associated object's count
2655    * @error
2656    *    API_EC_DATA_DATABASE_ERROR
2657    *    API_EC_DATA_OBJECT_NOT_FOUND
2658    *    API_EC_PARAM
2659    *    API_EC_PERMISSION
2660    *    API_EC_DATA_INVALID_OPERATION
2661    *    API_EC_DATA_QUOTA_EXCEEDED
2662    *    API_EC_DATA_UNKNOWN_ERROR
2663    */
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));
2668   }
2669
2670   /**
2671    * Get a list of associated object counts.
2672    *
2673    * @param  name        name of association
2674    * @param  obj_ids     whose association to retrieve
2675    * @return             associated object counts
2676    * @error
2677    *    API_EC_DATA_DATABASE_ERROR
2678    *    API_EC_DATA_OBJECT_NOT_FOUND
2679    *    API_EC_PARAM
2680    *    API_EC_PERMISSION
2681    *    API_EC_DATA_INVALID_OPERATION
2682    *    API_EC_DATA_QUOTA_EXCEEDED
2683    *    API_EC_DATA_UNKNOWN_ERROR
2684    */
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)));
2689   }
2690
2691   /**
2692    * Find all associations between two objects.
2693    *
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
2698    * @error
2699    *    API_EC_DATA_DATABASE_ERROR
2700    *    API_EC_PARAM
2701    *    API_EC_PERMISSION
2702    *    API_EC_DATA_QUOTA_EXCEEDED
2703    *    API_EC_DATA_UNKNOWN_ERROR
2704    */
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));
2710   }
2711
2712   /**
2713    * Get the properties that you have set for an app.
2714    *
2715    * @param properties  List of properties names to fetch
2716    *
2717    * @return array  A map from property name to value
2718    */
2719   public function admin_getAppProperties($properties) {
2720     return json_decode(
2721         $this->call_method('facebook.admin.getAppProperties',
2722             array('properties' => json_encode($properties))), true);
2723   }
2724
2725   /**
2726    * Set properties for an app.
2727    *
2728    * @param properties  A map from property names to values
2729    *
2730    * @return bool  true on success
2731    */
2732   public function admin_setAppProperties($properties) {
2733     return $this->call_method('facebook.admin.setAppProperties',
2734        array('properties' => json_encode($properties)));
2735   }
2736
2737   /**
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
2740    * limit_map.
2741    *
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.
2745    *
2746    * @return int  Integration point allocation value
2747    */
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,
2751               'uid' => $uid));
2752   }
2753
2754   /**
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.
2758    *
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
2763    *
2764    * @return array  A map of the names and values for those metrics
2765    */
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)));
2772   }
2773
2774   /**
2775    * Sets application restriction info.
2776    *
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
2780    * locations.
2781    *
2782    * @param array $restriction_info  The age restriction settings to set.
2783    *
2784    * @return bool  true on success
2785    */
2786   public function admin_setRestrictionInfo($restriction_info = null) {
2787     $restriction_str = null;
2788     if (!empty($restriction_info)) {
2789       $restriction_str = json_encode($restriction_info);
2790     }
2791     return $this->call_method('admin.setRestrictionInfo',
2792         array('restriction_str' => $restriction_str));
2793   }
2794
2795   /**
2796    * Gets application restriction info.
2797    *
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
2801    * locations.
2802    *
2803    * @return array  The age restriction settings for this application.
2804    */
2805   public function admin_getRestrictionInfo() {
2806     return json_decode(
2807         $this->call_method('admin.getRestrictionInfo'),
2808         true);
2809   }
2810
2811
2812   /**
2813    * Bans a list of users from the app. Banned users can't
2814    * access the app's canvas page and forums.
2815    *
2816    * @param array $uids an array of user ids
2817    * @return bool true on success
2818    */
2819   public function admin_banUsers($uids) {
2820     return $this->call_method(
2821       'admin.banUsers', array('uids' => json_encode($uids)));
2822   }
2823
2824   /**
2825    * Unban users that have been previously banned with
2826    * admin_banUsers().
2827    *
2828    * @param array $uids an array of user ids
2829    * @return bool true on success
2830    */
2831   public function admin_unbanUsers($uids) {
2832     return $this->call_method(
2833       'admin.unbanUsers', array('uids' => json_encode($uids)));
2834   }
2835
2836   /**
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.
2841    *
2842    * @param array $uids an array of user ids to filter by
2843    * @return bool true on success
2844    */
2845
2846   public function admin_getBannedUsers($uids = null) {
2847     return $this->call_method(
2848       'admin.getBannedUsers',
2849       array('uids' => $uids ? json_encode($uids) : null));
2850   }
2851
2852   /* UTILITY FUNCTIONS */
2853
2854   /**
2855    * Calls the specified normal POST method with the specified parameters.
2856    *
2857    * @param string $method  Name of the Facebook method to invoke
2858    * @param array $params   A map of param names => param values
2859    *
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
2863    */
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;
2868       }
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);
2872       }
2873       else {
2874         $result = json_decode($data, true);
2875       }
2876
2877       if (is_array($result) && isset($result['error_code'])) {
2878         throw new FacebookRestClientException($result['error_msg'],
2879                                               $result['error_code']);
2880       }
2881     }
2882     else {
2883       $result = null;
2884       $batch_item = array('m' => $method, 'p' => $params, 'r' => & $result);
2885       $this->batch_queue[] = $batch_item;
2886     }
2887
2888     return $result;
2889   }
2890
2891   /**
2892    * Calls the specified file-upload POST method with the specified parameters
2893    *
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)
2897    *
2898    * @return array A dictionary representing the response.
2899    */
2900   public function call_upload_method($method, $params, $file, $server_addr = null) {
2901     if (!$this->pending_batch()) {
2902       if (!file_exists($file)) {
2903         $code =
2904           FacebookAPIErrorCodes::API_EC_PARAM;
2905         $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
2906         throw new FacebookRestClientException($description, $code);
2907       }
2908
2909       $xml = $this->post_upload_request($method, $params, $file, $server_addr);
2910       $result = $this->convert_xml_to_result($xml, $method, $params);
2911
2912       if (is_array($result) && isset($result['error_code'])) {
2913         throw new FacebookRestClientException($result['error_msg'],
2914                                               $result['error_code']);
2915       }
2916     }
2917     else {
2918       $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);
2922     }
2923
2924     return $result;
2925   }
2926
2927   protected function convert_xml_to_result($xml, $method, $params) {
2928     $sxml = simplexml_load_string($xml);
2929     $result = self::convert_simplexml_to_array($sxml);
2930
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;">';
2934       $this->cur_id++;
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>';
2944       print '</div>';
2945     }
2946     return $result;
2947   }
2948
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);
2954   }
2955
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);
2960       }
2961     }
2962   }
2963
2964   private function add_standard_params($method, &$params) {
2965     if ($this->call_as_apikey) {
2966       $params['call_as_apikey'] = $this->call_as_apikey;
2967     }
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;
2974     }
2975     $this->last_call_id = $params['call_id'];
2976     if (!isset($params['v'])) {
2977       $params['v'] = '1.0';
2978     }
2979     if (isset($this->use_ssl_resources) &&
2980         $this->use_ssl_resources) {
2981       $params['return_ssl_resources'] = true;
2982     }
2983   }
2984
2985   private function create_post_string($method, $params) {
2986     $post_params = array();
2987     foreach ($params as $key => &$val) {
2988       $post_params[] = $key.'='.urlencode($val);
2989     }
2990     return implode('&', $post_params);
2991   }
2992
2993   private function run_multipart_http_transaction($method, $params, $file, $server_addr) {
2994
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;
3010     }
3011     // now add the file data
3012     $content_lines[] = $delimiter;
3013     $content_lines[] =
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);
3022   }
3023
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();
3029       $ch = curl_init();
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);
3037       curl_close($ch);
3038     } else {
3039       $content_type = 'application/x-www-form-urlencoded';
3040       $content = $post_string;
3041       $result = $this->run_http_post_transaction($content_type,
3042                                                  $content,
3043                                                  $this->server_addr);
3044     }
3045     return $result;
3046   }
3047
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();
3055       $ch = curl_init();
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);
3064       curl_close($ch);
3065     } else {
3066       $result = $this->run_multipart_http_transaction($method, $params, $file, $server_addr);
3067     }
3068     return $result;
3069   }
3070
3071   private function run_http_post_transaction($content_type, $content, $server_addr) {
3072
3073     $user_agent = 'Facebook API PHP5 Client 1.1 (non-curl) ' . phpversion();
3074     $content_length = strlen($content);
3075     $context =
3076       array('http' =>
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);
3084
3085     $result = '';
3086     if ($sock) {
3087       while (!feof($sock)) {
3088         $result .= fgets($sock, 4096);
3089       }
3090       fclose($sock);
3091     }
3092     return $result;
3093   }
3094
3095   public static function convert_simplexml_to_array($sxml) {
3096     $arr = array();
3097     if ($sxml) {
3098       foreach ($sxml as $k => $v) {
3099         if ($sxml['list']) {
3100           $arr[] = self::convert_simplexml_to_array($v);
3101         } else {
3102           $arr[$k] = self::convert_simplexml_to_array($v);
3103         }
3104       }
3105     }
3106     if (sizeof($arr) > 0) {
3107       return $arr;
3108     } else {
3109       return (string)$sxml;
3110     }
3111   }
3112
3113   private function get_uid($uid) {
3114     return $uid ? $uid : $this->user;
3115   }
3116 }
3117
3118
3119 class FacebookRestClientException extends Exception {
3120 }
3121
3122 // Supporting methods and values------
3123
3124 /**
3125  * Error codes and descriptions for the Facebook API.
3126  */
3127
3128 class FacebookAPIErrorCodes {
3129
3130   const API_EC_SUCCESS = 0;
3131
3132   /*
3133    * GENERAL ERRORS
3134    */
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;
3148
3149   /*
3150    * PARAMETER ERRORS
3151    */
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;
3175
3176   /*
3177    * USER PERMISSIONS ERRORS
3178    */
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;
3197
3198   /*
3199    * DATA EDIT ERRORS
3200    */
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;
3212
3213   const API_EC_MALFORMED_MARKUP = 329;
3214   const API_EC_EDIT_MARKUP = 330;
3215
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;
3225
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;
3230
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;
3239
3240   /**
3241    * SESSION ERRORS
3242    */
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;
3249
3250
3251   /**
3252    * FQL ERRORS
3253    */
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;
3270
3271   const API_EC_REF_SET_FAILED = 700;
3272
3273   /**
3274    * DATA STORE API ERRORS
3275    */
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;
3289
3290   /*
3291    * APPLICATION INFO ERRORS
3292    */
3293   const API_EC_NO_SUCH_APP = 900;
3294
3295   /*
3296    * BATCH ERRORS
3297    */
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;
3302
3303   /*
3304    * EVENT API ERRORS
3305    */
3306   const API_EC_EVENT_INVALID_TIME = 1000;
3307
3308   /*
3309    * INFO BOX ERRORS
3310    */
3311   const API_EC_INFO_NO_INFORMATION = 1050;
3312   const API_EC_INFO_SET_FAILED = 1051;
3313
3314   /*
3315    * LIVEMESSAGE API ERRORS
3316    */
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;
3320
3321   /*
3322    * CONNECT SESSION ERRORS
3323    */
3324   const API_EC_CONNECT_FEED_DISABLED = 1300;
3325
3326   /*
3327    * Platform tag bundles errors
3328    */
3329   const API_EC_TAG_BUNDLE_QUOTA = 1400;
3330
3331   /*
3332    * SHARE
3333    */
3334   const API_EC_SHARE_BAD_URL = 1500;
3335
3336   /*
3337    * NOTES
3338    */
3339   const API_EC_NOTE_CANNOT_MODIFY = 1600;
3340
3341   /*
3342    * COMMENTS
3343    */
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;
3350
3351   /**
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/.
3355    */
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'
3399   );
3400 }