X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=extlib%2Ffacebook%2Ffacebookapi_php5_restlib.php;fp=extlib%2Ffacebook%2Ffacebookapi_php5_restlib.php;h=3fec06e8a2bf8abc39f0d31abdca994c18fc2b57;hb=6a2d22ddd83b1b914e2f5559f93d08b0d5f92242;hp=389f40a9d4f2d8c0e0ba5b0965fb450377d020a6;hpb=251fd2c232d96ea09db971a6608231c679395c01;p=quix0rs-gnu-social.git diff --git a/extlib/facebook/facebookapi_php5_restlib.php b/extlib/facebook/facebookapi_php5_restlib.php old mode 100644 new mode 100755 index 389f40a9d4..3fec06e8a2 --- a/extlib/facebook/facebookapi_php5_restlib.php +++ b/extlib/facebook/facebookapi_php5_restlib.php @@ -1,9 +1,10 @@ batch_mode = FacebookRestClient::BATCH_MODE_DEFAULT; $this->last_call_id = 0; $this->call_as_apikey = ''; - $this->server_addr = Facebook::get_facebook_url('api') . '/restserver.php'; + $this->use_curl_if_available = true; + $this->server_addr = Facebook::get_facebook_url('api') . '/restserver.php'; if (!empty($GLOBALS['facebook_config']['debug'])) { $this->cur_id = 0; @@ -122,40 +127,62 @@ function toggleDisplay(id, type) { $this->user = $uid; } + /** + * Normally, if the cURL library/PHP extension is available, it is used for + * HTTP transactions. This allows that behavior to be overridden, falling + * back to a vanilla-PHP implementation even if cURL is installed. + * + * @param $use_curl_if_available bool whether or not to use cURL if available + */ + public function set_use_curl_if_available($use_curl_if_available) { + $this->use_curl_if_available = $use_curl_if_available; + } + /** * Start a batch operation. */ public function begin_batch() { - if($this->batch_queue !== null) { + if ($this->pending_batch()) { $code = FacebookAPIErrorCodes::API_EC_BATCH_ALREADY_STARTED; - throw new FacebookRestClientException($code, - FacebookAPIErrorCodes::$api_error_descriptions[$code]); + $description = FacebookAPIErrorCodes::$api_error_descriptions[$code]; + throw new FacebookRestClientException($description, $code); } $this->batch_queue = array(); + $this->pending_batch = true; } /* * End current batch operation */ public function end_batch() { - if($this->batch_queue === null) { + if (!$this->pending_batch()) { $code = FacebookAPIErrorCodes::API_EC_BATCH_NOT_STARTED; - throw new FacebookRestClientException($code, - FacebookAPIErrorCodes::$api_error_descriptions[$code]); + $description = FacebookAPIErrorCodes::$api_error_descriptions[$code]; + throw new FacebookRestClientException($description, $code); } - $this->execute_server_side_batch(); + $this->pending_batch = false; + $this->execute_server_side_batch(); $this->batch_queue = null; } + /** + * are we currently queueing up calls for a batch? + */ + public function pending_batch() { + return $this->pending_batch; + } + private function execute_server_side_batch() { $item_count = count($this->batch_queue); $method_feed = array(); foreach($this->batch_queue as $batch_item) { - $method_feed[] = $this->create_post_string($batch_item['m'], - $batch_item['p']); + $method = $batch_item['m']; + $params = $batch_item['p']; + $this->finalize_params($method, $params); + $method_feed[] = $this->create_post_string($method, $params); } $method_feed_json = json_encode($method_feed); @@ -202,6 +229,18 @@ function toggleDisplay(id, type) { $this->call_as_apikey = ''; } + + /* + * If a page is loaded via HTTPS, then all images and static + * resources need to be printed with HTTPS urls to avoid + * mixed content warnings. If your page loads with an HTTPS + * url, then call set_use_ssl_resources to retrieve the correct + * urls. + */ + public function set_use_ssl_resources($is_ssl = true) { + $this->use_ssl_resources = $is_ssl; + } + /** * Returns public information for an application (as shown in the application * directory) by either application ID, API key, or canvas page name. @@ -231,7 +270,7 @@ function toggleDisplay(id, type) { * @return string An authentication token. */ public function auth_createToken() { - return $this->call_method('facebook.auth.createToken', array()); + return $this->call_method('facebook.auth.createToken'); } /** @@ -246,8 +285,7 @@ function toggleDisplay(id, type) { * @return array An assoc array containing session_key, uid */ public function auth_getSession($auth_token, $generate_session_secret=false) { - //Check if we are in batch mode - if($this->batch_queue === null) { + if (!$this->pending_batch()) { $result = $this->call_method('facebook.auth.getSession', array('auth_token' => $auth_token, 'generate_session_secret' => $generate_session_secret)); @@ -271,7 +309,7 @@ function toggleDisplay(id, type) { * API_EC_PARAM_UNKNOWN */ public function auth_promoteSession() { - return $this->call_method('facebook.auth.promoteSession', array()); + return $this->call_method('facebook.auth.promoteSession'); } /** @@ -282,7 +320,20 @@ function toggleDisplay(id, type) { * @return bool true if session expiration was successful, false otherwise */ public function auth_expireSession() { - return $this->call_method('facebook.auth.expireSession', array()); + return $this->call_method('facebook.auth.expireSession'); + } + + /** + * Revokes the given extended permission that the user granted at some + * prior time (for instance, offline_access or email). If no user is + * provided, it will be revoked for the user of the current session. + * + * @param string $perm The permission to revoke + * @param int $uid The user for whom to revoke the permission. + */ + public function auth_revokeExtendedPermission($perm, $uid=null) { + return $this->call_method('facebook.auth.revokeExtendedPermission', + array('perm' => $perm, 'uid' => $uid)); } /** @@ -302,6 +353,30 @@ function toggleDisplay(id, type) { array('uid' => $uid)); } + /** + * Get public key that is needed to verify digital signature + * an app may pass to other apps. The public key is only used by + * other apps for verification purposes. + * @param string API key of an app + * @return string The public key for the app. + */ + public function auth_getAppPublicKey($target_app_key) { + return $this->call_method('facebook.auth.getAppPublicKey', + array('target_app_key' => $target_app_key)); + } + + /** + * Get a structure that can be passed to another app + * as proof of session. The other app can verify it using public + * key of this app. + * + * @return signed public session data structure. + */ + public function auth_getSignedPublicSessionData() { + return $this->call_method('facebook.auth.getSignedPublicSessionData', + array()); + } + /** * Returns the number of unconnected friends that exist in this application. * This number is determined based on the accounts registered through @@ -363,8 +438,9 @@ function toggleDisplay(id, type) { * * @param int $uid (Optional) User associated with events. A null * parameter will default to the session user. - * @param array $eids (Optional) Filter by these event ids. A null - * parameter will get all events for the user. + * @param array/string $eids (Optional) Filter by these event + * ids. A null parameter will get all events for + * the user. (A csv list will work but is deprecated) * @param int $start_time (Optional) Filter with this unix time as lower * bound. A null or zero parameter indicates no * lower bound. @@ -718,12 +794,15 @@ function toggleDisplay(id, type) { * @param string $body_general (Optional) Additional markup that extends * the body of a short story. * @param int $story_size (Optional) A story size (see above) + * @param string $user_message (Optional) A user message for a short + * story. * * @return bool true on success */ public function &feed_publishUserAction( $template_bundle_id, $template_data, $target_ids='', $body_general='', - $story_size=FacebookRestClient::STORY_SIZE_ONE_LINE) { + $story_size=FacebookRestClient::STORY_SIZE_ONE_LINE, + $user_message='') { if (is_array($template_data)) { $template_data = json_encode($template_data); @@ -739,7 +818,107 @@ function toggleDisplay(id, type) { 'template_data' => $template_data, 'target_ids' => $target_ids, 'body_general' => $body_general, - 'story_size' => $story_size)); + 'story_size' => $story_size, + 'user_message' => $user_message)); + } + + + /** + * Publish a post to the user's stream. + * + * @param $message the user's message + * @param $attachment the post's attachment (optional) + * @param $action links the post's action links (optional) + * @param $target_id the user on whose wall the post will be posted + * (optional) + * @param $uid the actor (defaults to session user) + * @return string the post id + */ + public function stream_publish( + $message, $attachment = null, $action_links = null, $target_id = null, + $uid = null) { + + return $this->call_method( + 'facebook.stream.publish', + array('message' => $message, + 'attachment' => $attachment, + 'action_links' => $action_links, + 'target_id' => $target_id, + 'uid' => $this->get_uid($uid))); + } + + /** + * Remove a post from the user's stream. + * Currently, you may only remove stories you application created. + * + * @param $post_id the post id + * @param $uid the actor (defaults to session user) + * @return bool + */ + public function stream_remove($post_id, $uid = null) { + return $this->call_method( + 'facebook.stream.remove', + array('post_id' => $post_id, + 'uid' => $this->get_uid($uid))); + } + + /** + * Add a comment to a stream post + * + * @param $post_id the post id + * @param $comment the comment text + * @param $uid the actor (defaults to session user) + * @return string the id of the created comment + */ + public function stream_addComment($post_id, $comment, $uid = null) { + return $this->call_method( + 'facebook.stream.addComment', + array('post_id' => $post_id, + 'comment' => $comment, + 'uid' => $this->get_uid($uid))); + } + + + /** + * Remove a comment from a stream post + * + * @param $comment_id the comment id + * @param $uid the actor (defaults to session user) + * @return bool + */ + public function stream_removeComment($comment_id, $uid = null) { + return $this->call_method( + 'facebook.stream.removeComment', + array('comment_id' => $comment_id, + 'uid' => $this->get_uid($uid))); + } + + /** + * Add a like to a stream post + * + * @param $post_id the post id + * @param $uid the actor (defaults to session user) + * @return bool + */ + public function stream_addLike($post_id, $uid = null) { + return $this->call_method( + 'facebook.stream.addLike', + array('post_id' => $post_id, + 'uid' => $this->get_uid($uid))); + } + + /** + * Remove a like from a stream post + * + * @param $post_id the post id + * @param $uid the actor (defaults to session user) + * @return bool + */ + public function stream_removeLike($post_id, $uid = null) { + return $this->call_method( + 'facebook.stream.removeLike', + array('post_id' => $post_id, + 'uid' => $this->get_uid($uid))); } /** @@ -750,7 +929,7 @@ function toggleDisplay(id, type) { * @return array An array of feed story objects. */ public function &feed_getAppFriendStories() { - return $this->call_method('facebook.feed.getAppFriendStories', array()); + return $this->call_method('facebook.feed.getAppFriendStories'); } /** @@ -771,33 +950,42 @@ function toggleDisplay(id, type) { * Returns whether or not pairs of users are friends. * Note that the Facebook friend relationship is symmetric. * - * @param array $uids1 array of ids (id_1, id_2,...) of some length X - * @param array $uids2 array of ids (id_A, id_B,...) of SAME length X + * @param array/string $uids1 list of ids (id_1, id_2,...) + * of some length X (csv is deprecated) + * @param array/string $uids2 list of ids (id_A, id_B,...) + * of SAME length X (csv is deprecated) * * @return array An array with uid1, uid2, and bool if friends, e.g.: * array(0 => array('uid1' => id_1, 'uid2' => id_A, 'are_friends' => 1), * 1 => array('uid1' => id_2, 'uid2' => id_B, 'are_friends' => 0) * ...) + * @error + * API_EC_PARAM_USER_ID_LIST */ public function &friends_areFriends($uids1, $uids2) { return $this->call_method('facebook.friends.areFriends', - array('uids1' => $uids1, 'uids2' => $uids2)); + array('uids1' => $uids1, + 'uids2' => $uids2)); } /** * Returns the friends of the current session user. * * @param int $flid (Optional) Only return friends on this friend list. + * @param int $uid (Optional) Return friends for this user. * * @return array An array of friends */ - public function &friends_get($flid=null) { + public function &friends_get($flid=null, $uid = null) { if (isset($this->friends_list)) { return $this->friends_list; } $params = array(); - if (isset($this->canvas_user)) { - $params['uid'] = $this->canvas_user; + if (!$uid && isset($this->canvas_user)) { + $uid = $this->canvas_user; + } + if ($uid) { + $params['uid'] = $uid; } if ($flid) { $params['flid'] = $flid; @@ -812,7 +1000,7 @@ function toggleDisplay(id, type) { * @return array An array of friend list objects */ public function &friends_getLists() { - return $this->call_method('facebook.friends.getLists', array()); + return $this->call_method('facebook.friends.getLists'); } /** @@ -822,7 +1010,7 @@ function toggleDisplay(id, type) { * @return array An array of friends also using the app */ public function &friends_getAppUsers() { - return $this->call_method('facebook.friends.getAppUsers', array()); + return $this->call_method('facebook.friends.getAppUsers'); } /** @@ -830,8 +1018,9 @@ function toggleDisplay(id, type) { * * @param int $uid (Optional) User associated with groups. A null * parameter will default to the session user. - * @param array $gids (Optional) Group ids to query. A null parameter will - * get all groups for the user. + * @param array/string $gids (Optional) Array of group ids to query. A null + * parameter will get all groups for the user. + * (csv is deprecated) * * @return array An array of group objects */ @@ -889,6 +1078,40 @@ function toggleDisplay(id, type) { 'path' => $path)); } + /** + * Retrieves links posted by the given user. + * + * @param int $uid The user whose links you wish to retrieve + * @param int $limit The maximimum number of links to retrieve + * @param array $link_ids (Optional) Array of specific link + * IDs to retrieve by this user + * + * @return array An array of links. + */ + public function &links_get($uid, $limit, $link_ids = null) { + return $this->call_method('links.get', + array('uid' => $uid, + 'limit' => $limit, + 'link_ids' => $link_ids)); + } + + /** + * Posts a link on Facebook. + * + * @param string $url URL/link you wish to post + * @param string $comment (Optional) A comment about this link + * @param int $uid (Optional) User ID that is posting this link; + * defaults to current session user + * + * @return bool + */ + public function &links_post($url, $comment='', $uid = null) { + return $this->call_method('links.post', + array('uid' => $uid, + 'url' => $url, + 'comment' => $comment)); + } + /** * Permissions API */ @@ -945,6 +1168,78 @@ function toggleDisplay(id, type) { array('permissions_apikey' => $permissions_apikey)); } + /** + * Creates a note with the specified title and content. + * + * @param string $title Title of the note. + * @param string $content Content of the note. + * @param int $uid (Optional) The user for whom you are creating a + * note; defaults to current session user + * + * @return int The ID of the note that was just created. + */ + public function ¬es_create($title, $content, $uid = null) { + return $this->call_method('notes.create', + array('uid' => $uid, + 'title' => $title, + 'content' => $content)); + } + + /** + * Deletes the specified note. + * + * @param int $note_id ID of the note you wish to delete + * @param int $uid (Optional) Owner of the note you wish to delete; + * defaults to current session user + * + * @return bool + */ + public function ¬es_delete($note_id, $uid = null) { + return $this->call_method('notes.delete', + array('uid' => $uid, + 'note_id' => $note_id)); + } + + /** + * Edits a note, replacing its title and contents with the title + * and contents specified. + * + * @param int $note_id ID of the note you wish to edit + * @param string $title Replacement title for the note + * @param string $content Replacement content for the note + * @param int $uid (Optional) Owner of the note you wish to edit; + * defaults to current session user + * + * @return bool + */ + public function ¬es_edit($note_id, $title, $content, $uid = null) { + return $this->call_method('notes.edit', + array('uid' => $uid, + 'note_id' => $note_id, + 'title' => $title, + 'content' => $content)); + } + + /** + * Retrieves all notes by a user. If note_ids are specified, + * retrieves only those specific notes by that user. + * + * @param int $uid User whose notes you wish to retrieve + * @param array $note_ids (Optional) List of specific note + * IDs by this user to retrieve + * + * @return array A list of all of the given user's notes, or an empty list + * if the viewer lacks permissions or if there are no visible + * notes. + */ + public function ¬es_get($uid, $note_ids = null) { + + return $this->call_method('notes.get', + array('uid' => $uid, + 'note_ids' => $note_ids)); + } + + /** * Returns the outstanding notifications for the session user. * @@ -954,13 +1249,15 @@ function toggleDisplay(id, type) { * and an eid list of 'event_invites' */ public function ¬ifications_get() { - return $this->call_method('facebook.notifications.get', array()); + return $this->call_method('facebook.notifications.get'); } /** * Sends a notification to the specified users. * * @return A comma separated list of successful recipients + * @error + * API_EC_PARAM_USER_ID_LIST */ public function ¬ifications_send($to_ids, $notification, $type) { return $this->call_method('facebook.notifications.send', @@ -972,12 +1269,14 @@ function toggleDisplay(id, type) { /** * Sends an email to the specified user of the application. * - * @param array $recipients id of the recipients + * @param array/string $recipients array of ids of the recipients (csv is deprecated) * @param string $subject subject of the email * @param string $text (plain text) body of the email * @param string $fbml fbml markup for an html version of the email * * @return string A comma separated list of successful recipients + * @error + * API_EC_PARAM_USER_ID_LIST */ public function ¬ifications_sendEmail($recipients, $subject, @@ -993,9 +1292,9 @@ function toggleDisplay(id, type) { /** * Returns the requested info fields for the requested set of pages. * - * @param array $page_ids an array of page ids - * @param array $fields an array of strings describing the info fields - * desired + * @param array/string $page_ids an array of page ids (csv is deprecated) + * @param array/string $fields an array of strings describing the + * info fields desired (csv is deprecated) * @param int $uid (Optional) limit results to pages of which this * user is a fan. * @param string type limits results to a particular type of page. @@ -1090,7 +1389,7 @@ function toggleDisplay(id, type) { 'tag_text' => $tag_text, 'x' => $x, 'y' => $y, - 'tags' => json_encode($tags), + 'tags' => (is_array($tags)) ? json_encode($tags) : null, 'owner_uid' => $this->get_uid($owner_uid))); } @@ -1128,7 +1427,8 @@ function toggleDisplay(id, type) { * @param int $subj_id (Optional) Filter by uid of user tagged in the photos. * @param int $aid (Optional) Filter by an album, as returned by * photos_getAlbums. - * @param array $pids (Optional) Restrict to a list of pids + * @param array/string $pids (Optional) Restrict to an array of pids + * (csv is deprecated) * * Note that at least one of these parameters needs to be specified, or an * error is returned. @@ -1143,9 +1443,10 @@ function toggleDisplay(id, type) { /** * Returns the albums created by the given user. * - * @param int $uid (Optional) The uid of the user whose albums you want. - * A null will return the albums of the session user. - * @param array $aids (Optional) A list of aids to restrict the query. + * @param int $uid (Optional) The uid of the user whose albums you want. + * A null will return the albums of the session user. + * @param string $aids (Optional) An array of aids to restrict + * the query. (csv is deprecated) * * Note that at least one of the (uid, aids) parameters must be specified. * @@ -1171,17 +1472,67 @@ function toggleDisplay(id, type) { array('pids' => $pids)); } + /** + * Uploads a photo. + * + * @param string $file The location of the photo on the local filesystem. + * @param int $aid (Optional) The album into which to upload the + * photo. + * @param string $caption (Optional) A caption for the photo. + * @param int uid (Optional) The user ID of the user whose photo you + * are uploading + * + * @return array An array of user objects + */ + public function photos_upload($file, $aid=null, $caption=null, $uid=null) { + return $this->call_upload_method('facebook.photos.upload', + array('aid' => $aid, + 'caption' => $caption, + 'uid' => $uid), + $file); + } + + + /** + * Uploads a video. + * + * @param string $file The location of the video on the local filesystem. + * @param string $title (Optional) A title for the video. Titles over 65 characters in length will be truncated. + * @param string $description (Optional) A description for the video. + * + * @return array An array with the video's ID, title, description, and a link to view it on Facebook. + */ + public function video_upload($file, $title=null, $description=null) { + return $this->call_upload_method('facebook.video.upload', + array('title' => $title, + 'description' => $description), + $file, + Facebook::get_facebook_url('api-video') . '/restserver.php'); + } + + /** + * Returns an array with the video limitations imposed on the current session's + * associated user. Maximum length is measured in seconds; maximum size is + * measured in bytes. + * + * @return array Array with "length" and "size" keys + */ + public function &video_getUploadLimits() { + return $this->call_method('facebook.video.getUploadLimits'); + } + /** * Returns the requested info fields for the requested set of users. * - * @param array $uids An array of user ids - * @param array $fields An array of info field names desired + * @param array/string $uids An array of user ids (csv is deprecated) + * @param array/string $fields An array of info field names desired (csv is deprecated) * * @return array An array of user objects */ public function &users_getInfo($uids, $fields) { return $this->call_method('facebook.users.getInfo', - array('uids' => $uids, 'fields' => $fields)); + array('uids' => $uids, + 'fields' => $fields)); } /** @@ -1194,14 +1545,15 @@ function toggleDisplay(id, type) { * users, use users.getInfo instead, so that proper privacy rules will be * applied. * - * @param array $uids An array of user ids - * @param array $fields An array of info field names desired + * @param array/string $uids An array of user ids (csv is deprecated) + * @param array/string $fields An array of info field names desired (csv is deprecated) * * @return array An array of user objects */ public function &users_getStandardInfo($uids, $fields) { return $this->call_method('facebook.users.getStandardInfo', - array('uids' => $uids, 'fields' => $fields)); + array('uids' => $uids, + 'fields' => $fields)); } /** @@ -1210,7 +1562,7 @@ function toggleDisplay(id, type) { * @return integer User id */ public function &users_getLoggedInUser() { - return $this->call_method('facebook.users.getLoggedInUser', array()); + return $this->call_method('facebook.users.getLoggedInUser'); } /** @@ -1238,6 +1590,17 @@ function toggleDisplay(id, type) { return $this->call_method('facebook.users.isAppUser', array('uid' => $uid)); } + /** + * Returns whether or not the user corresponding to the current + * session object is verified by Facebook. See the documentation + * for Users.isVerified for details. + * + * @return boolean true if the user is verified + */ + public function &users_isVerified() { + return $this->call_method('facebook.users.isVerified'); + } + /** * Sets the users' current status message. Message does NOT contain the * word "is" , so make sure to include a verb. @@ -1268,6 +1631,69 @@ function toggleDisplay(id, type) { return $this->call_method('facebook.users.setStatus', $args); } + /** + * Gets the stream on behalf of a user using a set of users. This + * call will return the latest $limit queries between $start_time + * and $end_time. + * + * @param int $viewer_id user making the call (def: session) + * @param array $source_ids users/pages to look at (def: all connections) + * @param int $start_time start time to look for stories (def: 1 day ago) + * @param int $end_time end time to look for stories (def: now) + * @param int $limit number of stories to attempt to fetch (def: 30) + * @param string $filter_key key returned by stream.getFilters to fetch + * + * @return array( + * 'posts' => array of posts, + * 'profiles' => array of profile metadata of users/pages in posts + * 'albums' => array of album metadata in posts + * ) + */ + public function &stream_get($viewer_id = null, + $source_ids = null, + $start_time = 0, + $end_time = 0, + $limit = 30, + $filter_key = '') { + $args = array( + 'viewer_id' => $viewer_id, + 'source_ids' => $source_ids, + 'start_time' => $start_time, + 'end_time' => $end_time, + 'limit' => $limit, + 'filter_key' => $filter_key); + return $this->call_method('facebook.stream.get', $args); + } + + /** + * Gets the filters (with relevant filter keys for stream.get) for a + * particular user. These filters are typical things like news feed, + * friend lists, networks. They can be used to filter the stream + * without complex queries to determine which ids belong in which groups. + * + * @param int $uid user to get filters for + * + * @return array of stream filter objects + */ + public function &stream_getFilters($uid = null) { + $args = array('uid' => $uid); + return $this->call_method('facebook.stream.getFilters', $args); + } + + /** + * Gets the full comments given a post_id from stream.get or the + * stream FQL table. Initially, only a set of preview comments are + * returned because some posts can have many comments. + * + * @param string $post_id id of the post to get comments for + * + * @return array of comment objects + */ + public function &stream_getComments($post_id) { + $args = array('post_id' => $post_id); + return $this->call_method('facebook.stream.getComments', $args); + } + /** * Sets the FBML for the profile of the user attached to this session. * @@ -1690,7 +2116,7 @@ function toggleDisplay(id, type) { * API_EC_DATA_UNKNOWN_ERROR */ public function &data_getObjectTypes() { - return $this->call_method('facebook.data.getObjectTypes', array()); + return $this->call_method('facebook.data.getObjectTypes'); } /** @@ -2315,12 +2741,14 @@ function toggleDisplay(id, type) { * * @param string $integration_point_name Name of an integration point * (see developer wiki for list). + * @param int $uid Specific user to check the limit. * * @return int Integration point allocation value */ - public function &admin_getAllocation($integration_point_name) { + public function &admin_getAllocation($integration_point_name, $uid=null) { return $this->call_method('facebook.admin.getAllocation', - array('integration_point_name' => $integration_point_name)); + array('integration_point_name' => $integration_point_name, + 'uid' => $uid)); } /** @@ -2376,28 +2804,75 @@ function toggleDisplay(id, type) { */ public function admin_getRestrictionInfo() { return json_decode( - $this->call_method('admin.getRestrictionInfo', array()), + $this->call_method('admin.getRestrictionInfo'), true); } + + /** + * Bans a list of users from the app. Banned users can't + * access the app's canvas page and forums. + * + * @param array $uids an array of user ids + * @return bool true on success + */ + public function admin_banUsers($uids) { + return $this->call_method( + 'admin.banUsers', array('uids' => json_encode($uids))); + } + + /** + * Unban users that have been previously banned with + * admin_banUsers(). + * + * @param array $uids an array of user ids + * @return bool true on success + */ + public function admin_unbanUsers($uids) { + return $this->call_method( + 'admin.unbanUsers', array('uids' => json_encode($uids))); + } + + /** + * Gets the list of users that have been banned from the application. + * $uids is an optional parameter that filters the result with the list + * of provided user ids. If $uids is provided, + * only banned user ids that are contained in $uids are returned. + * + * @param array $uids an array of user ids to filter by + * @return bool true on success + */ + + public function admin_getBannedUsers($uids = null) { + return $this->call_method( + 'admin.getBannedUsers', + array('uids' => $uids ? json_encode($uids) : null)); + } + /* UTILITY FUNCTIONS */ /** - * Calls the specified method with the specified parameters. + * Calls the specified normal POST method with the specified parameters. * * @param string $method Name of the Facebook method to invoke * @param array $params A map of param names => param values * - * @return mixed Result of method call + * @return mixed Result of method call; this returns a reference to support + * 'delayed returns' when in a batch context. + * See: http://wiki.developers.facebook.com/index.php/Using_batching_API */ - public function & call_method($method, $params) { - //Check if we are in batch mode - if($this->batch_queue === null) { + public function &call_method($method, $params = array()) { + if (!$this->pending_batch()) { if ($this->call_as_apikey) { $params['call_as_apikey'] = $this->call_as_apikey; } - $xml = $this->post_request($method, $params); - $result = $this->convert_xml_to_result($xml, $method, $params); + $data = $this->post_request($method, $params); + if (empty($params['format']) || strtolower($params['format']) != 'json') { + $result = $this->convert_xml_to_result($data, $method, $params); + } + else { + $result = json_decode($data, true); + } if (is_array($result) && isset($result['error_code'])) { throw new FacebookRestClientException($result['error_msg'], @@ -2413,11 +2888,46 @@ function toggleDisplay(id, type) { return $result; } - private function convert_xml_to_result($xml, $method, $params) { + /** + * Calls the specified file-upload POST method with the specified parameters + * + * @param string $method Name of the Facebook method to invoke + * @param array $params A map of param names => param values + * @param string $file A path to the file to upload (required) + * + * @return array A dictionary representing the response. + */ + public function call_upload_method($method, $params, $file, $server_addr = null) { + if (!$this->pending_batch()) { + if (!file_exists($file)) { + $code = + FacebookAPIErrorCodes::API_EC_PARAM; + $description = FacebookAPIErrorCodes::$api_error_descriptions[$code]; + throw new FacebookRestClientException($description, $code); + } + + $xml = $this->post_upload_request($method, $params, $file, $server_addr); + $result = $this->convert_xml_to_result($xml, $method, $params); + + if (is_array($result) && isset($result['error_code'])) { + throw new FacebookRestClientException($result['error_msg'], + $result['error_code']); + } + } + else { + $code = + FacebookAPIErrorCodes::API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE; + $description = FacebookAPIErrorCodes::$api_error_descriptions[$code]; + throw new FacebookRestClientException($description, $code); + } + + return $result; + } + + protected function convert_xml_to_result($xml, $method, $params) { $sxml = simplexml_load_string($xml); $result = self::convert_simplexml_to_array($sxml); - if (!empty($GLOBALS['facebook_config']['debug'])) { // output the raw xml and its corresponding php object, for debugging: print '