fbd Modules

FacebookClient
FacebookError
FacebookTypes FacebookUser

fbd.FacebookClient

License zlib/libpng
Authors Carlos Santander
Date December 14, 2007
Version 0.1
See Also Facebook Developers website
class FacebookClient;

Handles the connection to Facebook.

This implementation works with the Facebook API version 1.0.

Examples 
 char [] apikey, secret;
 // get your api key and secret

 auto fbClient = new FacebookClient (apikey, secret);
 fbClient.authenticate ();
 auto loginUrl = fbClient.loginURL ();

 // log in to Facebook using loginUrl

 fbClient.getSession ();
 auto user = fbClient.getThisUserInfo (FacebookUser.Fields.FIRST_NAME, FacebookUser.Fields.STATUS);
 // use user.firstName and user.status
Bugs This isn't exactly an fbd bug, but rather a consequence of how it is implemented. The Facebook API is REST-based, but fbd uses an HTTP client to connect to Facebook. This causes problems sometimes because Tango's HttpClient expects a Content-Length header, which Facebook does not send. The problem is that, apparently, the server sometimes closes the socket before all the data has been received by the client. In turn, this results in an empty or incomplete transmission, and the XML parser will throw an exception. For the application, this means that the request has to be made again, hoping that this time it will work. After many retries, Facebook returns with an error "too many requests," and the application has to wait before it sends another request.

Now, since this happens mostly when large responses are involved (ie, when requesting all the fields from user info), the workaround is to make smaller requests. There are two problems to that solution: it increases the chances of a "too many requests" error, and there are some responses that just are big (ie, getFriends) and there is no workaround for that.

Bugs These methods are not implemented yet:
  • events.get
  • events.getMembers
  • fbml.refreshImgSrc
  • fbml.refreshRefUrl
  • fbml.setRefHandle
  • fql.query -- this probably will not be implemented
  • friends.areFriends
  • groups.get
  • groups.getMembers
  • notifications.send
  • notifications.sendRequest
  • photos.addTag
  • photos.createAlbum
  • photos.get
  • photos.getAlbums
  • photos.getTags
  • photos.upload
  • profile.setFBML
  • profile.getFBML
  • users.getLoggedInUser -- this probably will not be implemented

The Data Store API is not fully implemented yet either.

this(char[] apiKey, char[] secret);

Initializes a new connection to Facebook.

apiKey and secret are given by Facebook to the creator of the application. To get your own apiKey and secret, go to http://developers.facebook.com/get_started.php.

void authenticate();

Authenticates the application to Facebook.

This function calls the Facebook facebook.auth.createToken method.

char[] loginURL();

Gets the login URL that the application has to direct to user to login to Facebook.

fbd doesn't perform this operation for two reasons:

  1. It is extremely platform-dependent.
  2. There are too many possibilities of what the application wants to do, so it should be the application the one who does this.
void getSession();

Gets a new Facebook session.

This function calls the Facebook facebook.auth.getSession method.

FacebookUser getThisUserInfo(char[][] fields...);

Gets the user info for the logged-in user.

This function acts as a wrapper for getUserInfo.

FacebookUser getUserInfo(char[] userId, char[][] fields...);

Gets the user info for the specified user.

This function acts as a wrapper for getUsersInfo.

FacebookUser[] getUsersInfo(char[][] userIds, char[][] fields);

Gets the user info for the specified users.

This function calls the Facebook facebook.users.getInfo method.

According to the Facebook docs, the information returned is "limited by the view of the current user," so there is a chance that not all requested fields will be returned for all users.

Parameters
char[][] userIds array with the user ids to request
char[][] fields array with the names of the fields to request. Use the constants in FacebookUser.Fields.
char[][] getFriends();

Gets the user ids of the friends of the logged-in user.

This function calls the Facebook facebook.friends.get method.

bool isAppAdded();

Returns whether the logged-in user has added the calling application.

This function calls the Facebook facebook.users.isAppAdded method.

bool publishStory(char[] title);

Publishes a news feed story to the logged-in user.

This function acts as a wrapper for publishStory.

bool publishStory(char[] title, char[] bodyMarkup);

Publishes a news feed story to the logged-in user.

This function acts as a wrapper for publishStory.

bool publishStory(char[] title, PublishData data);

Publishes a news feed story to the logged-in user.

This function calls the Facebook facebook.feed.publishStoryToUser method.

bool publishAction(char[] title);

Publishes a Mini-Feed story to the logged-in user, and publishes news feed stories to the friends of that user.

This function acts as a wrapper for publishAction.

bool publishAction(char[] title, char[] bodyMarkup);

Publishes a Mini-Feed story to the logged-in user, and publishes news feed stories to the friends of that user.

This function acts as a wrapper for publishAction.

bool publishAction(char[] title, PublishData data);

Publishes a Mini-Feed story to the logged-in user, and publishes news feed stories to the friends of that user.

This function calls the Facebook facebook.feed.publishActionOfUser method.

char[][] getFriendsAppUsers();

Gets the user ids of the friends of the logged-in user who are signed up for the specific calling application.

This function calls the Facebook facebook.friends.getAppUsers method.

Notifications getNotifications();

Returns information on outstanding Facebook notifications for the logged-in user.

This function calls the Facebook facebook.notifications.get method.

Photo [] getThisUserPhotos();

Returns all visible photos in which the currently authenticated user is tagged.

This function acts as a wrapper for getUserInfo.

Photo [] getUserPhotos(char[] uid);

Returns all visible photos in which the specified user is tagged.

This function calls the Facebook facebook.photos.get method.

Photo [] getPhotosById(char[][] pids...);

Returns all visible photos by specific photo ids.

This function calls the Facebook facebook.photos.get method.

Photo [] getAlbumPhotos(char[] aid);

Returns all visible photos in the specified album.

This function calls the Facebook facebook.photos.get method.

Album [] getThisUserAlbums();

Returns metadata about all of the photo albums uploaded by the currently authenticated user.

This function acts as a wrapper for getUserAlbums.

Album [] getUserAlbums(char[] uid);

Returns metadata about all of the photo albums uploaded by the specified user.

This function calls the Facebook facebook.photos.getAlbums method.

void setUserPreference(int id, char[] value);

Sets currently authenticated user's preference.

Notice that each preference is a string of maximum 128 characters and each of them has a numeric identifier ranged from 0 to 200.

This function calls the Facebook facebook.data.setUserPreference method.

void setUserPreferences(int[] ids, char[][] values, bool replace);

Sets currently authenticated user's preferences in batch.

Notice that each preference is a string of maximum 128 characters and each of them has a numeric identifier ranged from 0 to 200.

This function calls the Facebook facebook.data.setUserPreferences method.

char[] getUserPreference(int id);

Gets currently authenticated user's preference.

This function calls the Facebook facebook.data.getUserPreference method.

char[][] getUserPreferences();

Gets currently authenticated user's all preferences.

This function calls the Facebook facebook.data.getUserPreferences method.

void createObjectType(char[] name);

Creates an object type.

An object type is like a "table" in SQL terminology, or a "class" in object-oriented programming concepts. Each object type has a unique human-readable "name" that will be used to identify itself throughout the API. Each object type also has a list of properties that one has to define individually. Each property is like a "column" in an SQL table, or a "data member" in an object class.

This function calls the Facebook facebook.data.createObjectType method.

void dropObjectType(char[] name);

Removes a previously defined object type.

This will also delete ALL objects of this type. This deletion is NOT reversible.

This function calls the Facebook facebook.data.dropObjectType method.

void renameObjectType(char[] oldName, char[] newName);

Renames a previously defined object type.

This function calls the Facebook facebook.data.renameObjectType method.

void defineObjectProperty(char[] objType, char[] propName, PropertyType propType);

Adds a new object property to an object type.

This function calls the Facebook facebook.data.defineObjectProperty method.

void undefineObjectProperty(char[] objType, char[] propName);

Removes a previously defined property of an object type.

This will remove ALL values of this property of ALL objects of this type. This removal is NOT reversible.

This function calls the Facebook facebook.data.undefineObjectProperty method.

void renameObjectProperty(char[] objType, char[] propName, char[] newName);

Renames a previously defined object property.

This function calls the Facebook facebook.data.renameObjectProperty method.

char[][] getObjectTypes();

Gets a list of all previously defined object types.

This function calls the Facebook facebook.data.getObjectTypes method.

PropertyInfo [] getObjectType(char[] objType);

Gets detailed definitions of an object type, including all its properties and their types.

This function calls the Facebook facebook.data.getObjectType method.

long createObject(char[] objType, char[][] properties, char[][] values);

Creates a new object.

This function calls the Facebook facebook.data.createObject method.

Returns Numeric identifier of newly created object
char[] getObjectProperty(long objId, char[] property);

Gets a single property of an object.

This function calls the Facebook facebook.data.getObjectProperty method.

void setObjectProperty(long objId, char[] property, char[] value);

Sets a single property of an object.

This function calls the Facebook facebook.data.setObjectProperty method.