You are on page 1of 52

Facebook Developer Toolkit

Developed for Microsoft By Clarity Consulting Inc. www.claritycon.com

Table Of Contents Leveraging the Facebook API in 5 minutes.................................................................4 Desktop Development............................................................................. ................4 Web Development............................................................................... ....................7 Pre-requisites................................................................................................... .........12 Introduction...................................................................................... ........................12 Overview.................................................................................. ................................13 Facebook API Overview......................................................................................... .13 Using the FacebookService to Access the API........................................................13 Infinite Sessions.................................................................................................13 Facebook Desktop Development...........................................................................13 Facebook Web Development.................................................................................14 Using LINQ................................................................................................... ..........15 Detailed Class Design ................................................................................ ..............16 Facebook.Components..........................................................................................16 FacebookService Class.......................................................................................16 Facebook Data Objects..........................................................................................32 Album Class..................................................................................................... ...32 Photo Class.................................................................................................. .......34 FacebookEvent Class..........................................................................................35 Group Class................................................................................... .....................38 GroupUser Class.................................................................................. ...............40 User Class..........................................................................................................41 SchoolHistory Class............................................................................................45 HighSchool Class............................................................................... .................45 HigherEducation Class...................................................................................... ..46 Network Class................................................................................................... .46 Location Class...................................................................................................47 Work Class.................................................................................................. .......48 Code Snippets.......................................................................................................... .49 Windows Form: Application Setup.........................................................................49 Windows Form: Retrieving Friends.........................................................................49

Windows Form: Utilizing the FriendList Control......................................................49 Windows Form: Hooking a FriendList Control to a Profile Control..........................50 Web Application: Authentication Process...............................................................51

Leveraging the Facebook API in 5 minutes
Desktop Development
• • Satisfy Pre-requisites described below Start a new Windows application project o o
Visual C#

File – New – Project Windows Application

Visual Basic

Add the FacebookService component from the toolbox to the Form’s component tray

Provide the API Key and Secret values

Drag a FriendList from the toolbox onto the design surface for the form

Hook up the form Load Event o Find Load in the Event list in the property window, type Form_Load. Press Enter.

In the generated Form_Load method, set the Friends property of the FriendList control to the Collection returned by calling the GetFriends method of the FacebookService. As shown here:
Visual C# private void Form_Load(object sender, EventArgs e) { friendList1.Friends = FacebookService1.GetFriends(); }

Visual Basic

Private Overloads Sub OnLoad() friendList1.Friends = FacebookService1.GetFriends() End Sub

Press F5 to run the application

Web Development
• • Satisfy Pre-requisites described below In Visual Web Developer 2005 Express edition o
Visual C#

File – New – Web Site

Visual Basic

Switch to Design View of Default.aspx

On Default.aspx, drag a friendlist from the toolbox

• •

Add the following code to the Default.aspx Configure the API key and secret
Visual C# public partial class _Default : Page {

Facebook.Components.FacebookService _fbService = new Facebook.Components.FacebookService(); protected void Page_Load(object sender, EventArgs e) { // ApplicationKey and Secret are acquired when you sign up for _fbService.ApplicationKey = "YOURKEYHERE"; _fbService.Secret = "YOURSECRETHERE"; Visual Basic Public Partial Class _Default Inherits Page Private _fbService As Facebook.Components.FacebookService = New Facebook.Components.FacebookService() Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs) ' ApplicationKey and Secret are acquired when you sign up for _fbService.ApplicationKey = "YOURKEYHERE" _fbService.Secret = "YOURSECRETHERE"

Set the IsDesktopApplication property of the FacebookService component
Visual C# _fbService.IsDesktopApplication = false; Visual Basic _fbService.IsDesktopApplication = False

Check if we have already stored the Facebook session information or if the auth_token is in the query params. We will store what we know about the current user’s Facebook Session in a server side variable. We will then check that variable to see if we already have established a Facebook session on behalf of the current user.
Visual C# string sessionKey = Session["Facebook_session_key"] as String; string userId = Session["Facebook_userId"] as String; // When the user uses the Facebook login page, the redirect back here will will have the auth_token in the query params string authToken = Request.QueryString["auth_token"];

Visual Basic Dim sessionKey As String = TryCast(Session("Facebook_session_key"), String) Dim userId As String = TryCast(Session("Facebook_userId"), String) ' When the user uses the Facebook login page, the redirect back here will will have the auth_token in the query params

Dim authToken As String = Request.QueryString("auth_token")

If we have an established session, set it into our instance of the service
Visual C# if (!String.IsNullOrEmpty(sessionKey)) { _fbService.SessionKey = sessionKey; _fbService.UserId = userId; } Visual Basic ' We have already established a session on behalf of this user If (Not String.IsNullOrEmpty(sessionKey)) Then _fbService.SessionKey = sessionKey _fbService.UserId = userId

If not, check if we have the auth_token in the query params. If we do, it means we just got called from the Facebook login page.
Visual C# else if (!String.IsNullOrEmpty(authToken)) { _fbService.CreateSession(authToken); Session["Facebook_session_key"] = _fbService.SessionKey; Session["Facebook_userId"] = _fbService.UserId; Session["Facebook_session_expires"] = _fbService.SessionExpires; }

Visual Basic ' This will be executed when Facebook login redirects to our page ElseIf (Not String.IsNullOrEmpty(authToken)) Then _fbService.CreateSession(authToken) Session("Facebook_session_key") = _fbService.SessionKey Session("Facebook_userId") = _fbService.UserId Session("Facebook_session_expires") = _fbService.SessionExpires

If neither, we need to redirect the user to the Facebook hosted login page

Visual C# else { Response.Redirect(@"http://www.Facebook.com/login.php?api_key=" + _fbService.ApplicationKey + @"&v=1.0"); } Visual Basic Else

Response.Redirect("http://www.Facebook.com/login.php?api_key=" & _fbService.ApplicationKey & "&v=1.0") End If

Set the friends property of the friendlist
Visual C# if (!IsPostBack) { // Use the FacebookService Component to populate Friends MyFriendList.Friends = _fbService.GetFriends(); } Visual Basic If (Not IsPostBack) Then ' Use the FacebookService Component to populate Friends MyFriendList.Friends = _fbService.GetFriends() End If

Pre-requisites
First, you download one of the Visual Studio Express products . To develop a desktop application, you can use Visual C# 2005 Express Edition (or later) or Visual Basic 2005 Express Edition (or later). If you want to build a web application, you can use Visual Web Developer 2005 Express Edition (or later). Next, in order to use the Facebook API, you must first register for a developer account with Facebook at http://developers.Facebook.com/account.php. You will need to specify whether your application is a Website or a Desktop application. After registering for your developer account, you will receive and API key and secret. These are critical for using the Facebook API and you should keep this readily available

Introduction
This document outlines the components and controls that are available for to help simplify development against the Facebook API. The main component is the FacebookService component. The FacebookService wraps the Facebook API and provides an easy to use interface for calling the different methods currently available in the 1.0 version of the Facebook API. In addition, some Windows and web controls were installed which will provide a quick way to start leveraging the Facebook data in your application. We’ve also provided you with some cool fun samples. These can be found in <INSERT DIRECTORY HERE>. Additionally, we’ve provide all the source code for the API, components, controls and samples for you to explore.

Overview
All of the sections below assume that the developer has signed up for a Facebook developer account and received an API key and secret from Facebook.

Facebook API Overview
The Facebook API is a REST interface allowing applications to post a specific HTTP address and receive structured XML representing the requested Facebook data. The 1.0 version of the API contains primarily Get operations, and does not provide personal or contact information for Facebook users. The only Set type operations that are available are CreateAlbum, UploadPhoto and AddTag. For more information on the available functions, see the API documentation at http://developers.Facebook.com/documentation.php?v=1.0

Using the FacebookService to Access the API
The Facebook.dll that was installed at %Program Files%\Coding4Fun\Facebook\Binaries contains the FacebookService component. This component contains all the methods that wrap the available API calls. To use this component, each application must programmatically set their application key and secret. For specifics on interacting with the FacebookService see the Desktop and Web Development below. The methods within the FacebookService return strongly typed data objects representing the data. These objects are intended to simplify the developer experience using the API.

Infinite Sessions
The Facebook API supports Infinite Sessions. What this means is that users of custom developed Facebook desktop applications have the ability to save their credentials and not be required to login to the application on subsequent uses. In order for an application to take advantage of infinite sessions, the application should check SessionExpires property of the Facebook Service after a Session is initiated. If this property is false, the application can store the userId and SessionKey that are associated with the user and set them on the FacebookService whenever this user returns.

Facebook Desktop Development
To start utilizing the Facebook API, you will need to add the FacebookService component to your project. To do this just drag an instance of FacebookService from the toolbox onto the component tray and enter your API Key and Secret.

The FacebookService component contains methods that wrap all of the methods of the Facebook API. The following provides an example for getting all the friends of the logged in user. This method returns a generic collection of User objects. The User object is a strongly typed representation of a Facebook User profile.
Visual C# using System.Collections.Generic; using System.Collections.ObjectModel; … Collection<User> friends = FacebookService1.GetFriends(); Visual Basic Imports System.Collections.Generic Imports System.Collections.ObjectModel … Dim friends As Collection(Of User) = FacebookService1.GetFriends()

Facebook Web Development
The authentication process for a Web Application is more involved than for a Windows application. When the developer account is setup, the developer must choose whether their application is a Web application or Desktop application. In the case of a web application, the developer must specify a return url. This is the url that users of the web application will be redirected to after logging in on the Facebook hosted login page. For the sample web site, it is setup to return to http://localhost/FacebookWebSample/default.aspx. To run and debug the FacebookWebSample project, you must configure your Visual Studio Web Project to start your web application using this address. Because of this requirement, the simplest way to configure to run the WebSample is using IIS. (Since it runs on port 80 and handles addresses like the above) 1. Create an IIS Virtual Directory called FacebookWebSample pointed at the location of your FacebookWebSample.

2. Set the Web Project to start using this website. a. Right Click FacebookWebSample in Visual Studio – Select Property Pages b. Select Start Options c. Click Start URL radio button – Enter http://localhost/FacebookWebSample/default.aspx

3. Write code to handle 3 states. a. If we don’t have an auth_token, redirect to the Facebook hosted login page. b. If we have an auth_token, start a session on behalf of the user. c. Store the user’s session information for making calls to the Facebook service. See the Code Snippets section for more details.

Using LINQ
The toolkit contains some sample code showing (both a web application and Windows application version) how LINQ and Orcas can be used to provide a richer

set of development features against the Facebook API data. The samples included will only work in “Orcas” (the codename for the next version of Visual Studio) and show how we can right code using a syntax similar to SQL to filter and search through the friends that are returned from Facebook. The samples leverage LINQ over XML and run the filtering directly against the returned XML. Alternatively, the LINQ code could just as easily have been written against the Generic Collections returned by the our toolkit. For more information on LINQ, check out http://msdn2.microsoft.com/en-us/netframework/aa904594.aspx. If you want to download Orcas and try out LINQ and the enclosed samples, you can do so here, http://msdn.microsoft.com/vstudio/express/future. The source for these samples is installed to C:\Program Files\Coding4Fun\Facebook\LINQ Samples

Detailed Class Design
Facebook.Components
FacebookService Class
This class contains methods that wrap the Facebook API and return strongly typed objects representing Facebook data. Additionally, this class has functionality to encapsulate the Facebook login process for both Microsoft Windows-based clients and ASP.NET web based clients.

Figure 1: FacebookService Class

1.1.1.1Property: ApplicationKey
This property is required to be set by all consuming applications. This property should be set to the API key acquired from Facebook when developer signed up for a Facebook developer account. Definition: public string ApplicationKey

1.1.1.2Property: IsDesktopApplication This property is an indicator used to determine if the consuming application is a desktop (Windows) or web based application. This is needed because the application secret is handled differently for Windows and web applications. Definition: public bool IsDesktopApplication 1.1.1.3Property: Secret This property is required to be set by all consuming applications. This is the secret used to encrypt parameters passed to the Facebook API. For web applications, the secret is constant and set at the beginning of interaction with the service. For Windows applications, an initial secret is required to establish a session, but a new secret is acquired that coincides with each session. Definition: public string Secret 1.1.1.4Property: SessionExpires This property is an indicator of whether the current session is an infinite session or not. The value is determined after a user of the consuming application logs in on the Facebook hosted web page. Consuming applications can leverage an infinite session by storing the session information locally and by passing the logon process in subsequent interactions with the user. Definition: public bool SessionExpires 1.1.1.5Property: SessionKey This property stores the session key for the current user session. This can either be set by the consuming application (which would typically be done when the consuming application recognizes a user that has an infinite session established) or will be set by the FacebookService after the logon process is complete Definition: public string SessionKey 1.1.1.6Property: UserId This property is stored the Facebook userid. Similar to the SessionKey, in the case of infinite sessions the comsuming application will set this property with the known UserId, otherwise this property will be set by the logon process. Definition: public string ApplicationKey

1.1.1.7Method: AddTag
This method wraps the Facebook API method photos.addTag. This method is used to add tags to any “pending” photos. A pending photo is a photo that has been uploaded but not yet confirmed. Definition: public void AddTag(string photoId, string tagText, string
tagUserId, int xCoord, int yCoord)

Parameters:
Parameter photoId tagText tagUserId xCoord yCoord Description The Facebook identifier of the pending photo to be tagged The message that should be associated with the tag. Use this OR tag User Id. Not both. The Facebook userid of the person the tag points to The X coord (in pixels) where the tag should begin in the specified picture The Y coord (in pixels) where the tag should begin in the specified picture

Return Type: N/A Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshhold

 

  

1.1.1.8Method: AreFriends
This method wraps the Facebook API method friends.areFriends. This method is used to determine if two Facebook users are friends or not.

Definition (1): public bool AreFriends(string userId1, string userId2) Definition (2): public bool AreFriends(User user1, User user2)

Parameters (1):
Parameter userId1 userId2 Description The Facebook identifier of the first user The Facebook identifier of the second user

Parameters (2):
Parameter user1 user2 Description The a strongly typed instance of a User representing the first Facebook user The a strongly typed instance of a User representing the second Facebook user

Return Type: bool: true if 2 users are currently Facebook friends, otherwise false. Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

 

  

1.1.1.9Method: ConnectToFacebook This method is not typically used by the consuming application. The FacebookService will check if there is a valid session that it can use to make API calls, if not it will invoke the ConnectToFacebook method. This

method is only needed by desktop applications and uses a hosted web browser to allow the user to login to the Facebook hosted login page. Definition: public void ConnectToFacebook() Parameters:
Parameter None None Description

Return Type: N/A Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

 

  

1.1.1.10Method: CreateSession This method has a public version and a private version. The private version is used for Windows applications and is called from ConnectToFacebook. The public version takes in an auth token and is used by web based applications. Web based applications get the auth token as a url parameter after the user logins on the Facebook hosted webpage. The web application then needs to start the session using this method and passing in the auth token. Definition (1): private void CreateSession() Definition (2): public void CreateSession(string authToken) Parameters (1):
Parameter none None Description

Parameters (2):
Parameter authToken Description The authentication token returned to the web application from the Facebook login page.

Return Type: N/A Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

 

  

1.1.1.11Method: GetEventMembers This method wraps the Facebook API method events.getMembers. This method is used to return all the users that have been invited to an event and their current rsvp status. Definition: public Collection<EventUser> GetEventMembers(string
eventId)

Parameters:
Parameter eventId Description The Facebook identifier of the event

Return

Type: Collection<EventUser>: A collection of EventUser. EventUser is a simple wrapper to the User class that adds RSVP status.

Exceptions:

 

  

FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

1.1.1.12Method: GetEvents This method wraps the Facebook API method events.get. This method is used to retrieve event information. There are overrides supporting get by event id, user id and date. Definition (1): public Collection<FacebookEvent> GetEvents() Definition (2): public Collection<FacebookEvent> GetEvents(string
userId)

Definition (3): public Collection<FacebookEvent>
GetEvents(Collection<string> eventList)

Definition (4): public Collection<FacebookEvent>
GetEvents(Collection<string> eventList, string userId)

Definition (5): public Collection<FacebookEvent>
GetEvents(Collection<string> eventList, string userId, DateTime? startDate, DateTime? endDate)

Parameters (1):
Parameter None Description Get Events that the logged in user is invited to

Parameters (2):
Parameter userId Description The Facebook userId that events are retrieved for. Will return all events this person is invited to.

Parameters (3):
Parameter Description

eventList

A collection of eventIds. Will return the event information for each event matching an event id passed in.

Parameters (4):
Parameter userId Description The Facebook userId that events are retrieved for. Will return events this person is invited to that are also specified in the eventList. A collection of eventIds. Will return the event information for each event matching an event id passed in that has the specified UserId invited.

eventList

Parameters (5):
Parameter userId Description The Facebook userId that events are retrieved for. Will return events this person is invited to that are also specified in the eventList. A collection of eventIds. Will return the event information for each event matching an event id passed in that has the specified UserId invited. Only retrieve events matching the above criteria and starting after this date. Only retrieve events matching the above criteria and ending before this date.

eventList

startDate endDate

Return Type: Collection<FacebookEvent> Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

 

  

1.1.1.13Method: GetFriends This method wraps the Facebook API method friends.get. This method is used to get all the friends of the logged in user. Definition: public Collection<User> GetFriends() Parameters:
Parameter none Description Get friends of the logged in user

Return Type: Collection<User>: A collection of populated user objects representing each of the logged in user’s friends. Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

 

  

1.1.1.14Method: GetFriendsAppUsers
This method wraps the Facebook API method friends.getAppUsers. This method is used to get all the friends of the logged in user that are also users of this consuming application. Definition: public Collection<User> GetFriendsAppUsers() Parameters:
Parameter none Description Get friends of the logged in user that are users of this application

Return Type: Collection<User>: A collection of populated user objects representing each of the logged in user’s friends that are also users of this application. Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

 

  

1.1.1.15Method: GetGroupMembers This method wraps the Facebook API method groups.getMembers. This method is to retrieve profile information about all Facebook users that are members of a particular group. Definition: public Collection<GroupUser> GetGroupMembers(string
groupId)

Parameters:
Parameter groupId Description The Facebook identifier of the group

Return Type: Collection<GroupUser> - GroupUser is a lightweight wrapper to user that adds a property for the users position in the group Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid.

  

FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

1.1.1.16Method: GetGroups This method wraps the Facebook API method groups.get. This method is used to retrieve the groups matching a specific criteria. Definition (1): public Collection<Group> GetGroups() Definition (2): public Collection<Group> GetGroups(string userId) Definition (3): public Collection<Group> GetGroups(Collection<string>
groupsList)

Definition (4): public Collection<Group> GetGroups(string userId,
Collection<string> groupsList)

Parameters (1):
Parameter None Description Get all groups for the logged in user

Parameters (2):
Parameter userId Description The Facebook userId to return groups for

Parameters (3):
Parameter groupList Description A collection of group ids. Return all groups matching a group id in the list.

Parameters (4):
Parameter userId groupList Description The Facebook userId to return groups for A collection of group ids. Return all groups matching a group id in the list.

Return Type: Collection<Group> Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

 

  

1.1.1.17Method: GetPhotoAlbums This method wraps the Facebook API method photos.getAlbums. This method is used to get photo album details based on search criteria Definition (1): public Collection<Album> GetPhotoAlbums() Definition (2): public Collection<Album> GetPhotoAlbums(string userId) Definition (3): public Collection<Album>
GetPhotoAlbums(Collection<string> albumList)

Definition (4): public Collection<Album> GetPhotoAlbums(string userId,
Collection<string> albumList)

Parameters (1):
Parameter None Description Get all albums for the logged in user

Parameters (2):
Parameter userId Description Facebook userid to retrieve all albums for

Parameters (3):
Parameter albumList Description Collection of Facebook album ids to retrieve

Parameters (4):

Parameter userId albumList

Description Facebook userid to retrieve albums for Collection of Facebook album ids to retrieve

Return Type: Collection<Album> Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

 

  

1.1.1.18Method: GetPhotos This method wraps the Facebook API method photos.get. This method is used to get photos based on search criteria. Definition (1): public Collection<Photo> GetPhotos(string albumId) Definition (2): public Collection<Photo> GetPhotos(Collection<string>
photoList)

Definition (3): public Collection<Photo> GetPhotos(string albumId,
Collection<string> photoList)

Parameters (1):
Parameter albumId Description The Facebook identifier of the album to retrieve photos for

Parameters (2):
Parameter photoList Description Collection of Facebook photo identifier to return information about

Parameters (3):
Parameter albumId photoList Description The Facebook identifier of the album to retrieve photos for Collection of Facebook photo identifier to return information about

Return Type: Collection<Photo> Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

 

  

1.1.1.19Method: GetTags This method wraps the Facebook API method photos.getTags. This method is used to retrieve all tags for a particular photo. Definition: public Collection<PhotoTag> GetTags(Collection<string>
photoList)

Parameters:
Parameter photoList Description Collection of Facebook photo identifiers to return tags for

Return Type: Collection<PhotoTag> Exceptions:

 

  

FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

1.1.1.20Method: GetUserInfo This method wraps the Facebook API method users.getInfo. This method is used to retrieve profile information for a set of users. Definition(1): public User GetUserInfo() Definition(2): public Collection<User> GetUserInfo(string userIds) Parameters(1):
Parameter none Description Get the user profile for the logged in user

Parameters(2):
Parameter userIds Description Comma separated list of Facebook user identifiers

Return Type: User Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.

 

 

FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

1.1.1.21Method: UploadPhoto This method wraps the Facebook API method photos.upload. This method is used to upload a new photo. The uploaded photo will be considered pending until the user utilizes the website to confirm the photo. Definition: public void UploadPhoto(string albumId, FileInfo
uploadFile)

Parameters:
Parameter albumId uploadFile Description The album identifier to upload the photo to. If null, then will upload to default album File containing the photo to upload.

Return Type: N/A Exceptions:  FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used. FacebookInvalidUserException: The user that the call was made on behalf of is not valid. FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time. FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available. FacebookSigningException: Indicates that the secret or API key were not specified or were invalid. FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold

 

  

Facebook Data Objects
Album Class
This class represents a Facebook photo album.

1.1.1.22Property: AlbumId
The Facebook identifier of the album Definition: public string AlbumId

1.1.1.23Property: CoverPhotoId
The Facebook identifier of photo that is used as the cover photo for the album Definition: public string CoverPhotoId

1.1.1.24Property: CreateDate
The date that the album was created Definition: public DateTime CreateDate

1.1.1.25Property: Description
The user entered description of the album Definition: public string Description

1.1.1.26Property: Location
The location that the album pertains to Definition: public string Location

1.1.1.27Property: ModifiedDate
The date that this album was last updated Definition: public DateTime ModifiedDate

1.1.1.28Property: Name
The name of the album Definition: public string Name

1.1.1.29Property: OwnerUserId
The Facebook user id of the person who created the album Definition: public string OwnerUserId

Photo Class
This class contains the information about a Facebook Photo.

1.1.1.30Property: AlbumId A Facebook unique identifier of the album that the photo is part of. Definition: public string AlbumId 1.1.1.31Property: Caption The caption of the photo. Definition: public string Caption 1.1.1.32Property: CreateDate A date when the photo was first uploaded.

Definition: public DateTime CreateDate 1.1.1.33Property: Link The photo link. Definition: public Uri Link 1.1.1.34Property: OwnerUserId A Facebook unique identifier of user who owns the photo. Definition: public string OwnerUserId

1.1.1.35Property: PhotoId
A Facebook unique identifier of the photo. Definition: public string PhotoId

1.1.1.36Property: Picture
The actual image. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit. Definition: public Image Picture

1.1.1.37Property: PictureUrl
The url of this picture Definition: public Uri PictureUrl

FacebookEvent Class
This class represents a Facebook event.

1.1.1.38Property: Creator The Facebook identifier of the user who created the event Definition: public string Creator 1.1.1.39Property: Description Description of the event Definition: public string Description 1.1.1.40Property: EndDate The date that the events ends Definition: public DateTime EndDate 1.1.1.41Property: EventId The Facebook identifier of the event.

Definition: public string EventId 1.1.1.42Property: Host The Facebook user id of the host of the event Definition: public string Host 1.1.1.43Property: Location The name of the place where the event will take place. Definition: public string Location

1.1.1.44Property: Name
The name of the event Definition: public string Name 1.1.1.45Property: NetworkId The Facebook identifier of the network that this event is a part of Definition: public string NetworkId

1.1.1.46Property: Picture
The actual image associated with the event. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit. Definition: public Image Picture

1.1.1.47Property: PictureUrl
The url of this event’s picture Definition: public Uri PictureUrl

1.1.1.48Property: StartDate
The date and time when the event starts Definition: public DateTime StartDate

1.1.1.49Property: SubType
The seconary group of event type. Definition: public string SubType

1.1.1.50Property: TagLine
The tagline of the event if one was specified

Definition: public string TagLine

1.1.1.51Property: Type
The primary grouping of the event Definition: public string Type

1.1.1.52Property: UpdateDate
The Facebook user id of the person who created the album Definition: public DateTime UpdateDate

Group Class
This class contains represents a Facebook group.

1.1.1.53Property: Creator The Facebook identifier of the user who created the group Definition: public string Creator

1.1.1.54Property: Description The description of the group Definition: public string Description 1.1.1.55Property: GroupId The Facebook identifier of the group Definition: public string GroupId 1.1.1.56Property: Name The user entered name of the group Definition: public string Name 1.1.1.57Property: NetworkId The Facebook identifier of the network that the group is part of Definition: public string NetworkId 1.1.1.58Property: Office The address of the group’s office if it has one. Definition: public string Office

1.1.1.59Property: Picture
The actual image associated with the group. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit. Definition: public Image Picture

1.1.1.60Property: PictureUrl
The url of this group’s picture Definition: public Uri PictureUrl 1.1.1.61Property: RecentNews Free form text describing recent news associated with the group Definition: public string Recent News

1.1.1.62Property: SubType
The seconary group of group type. Definition: public string SubType

1.1.1.63Property: Type
The primary grouping of the event Definition: public string Type 1.1.1.64Property: UpdateDate The last date and time that changes were made to the group Definition: public DateTime UpdateDate 1.1.1.65Property: Venue The name of the venue where the group meetings occur Definition: public string Venue

1.1.1.66Property: WebSite
The url of the website for the group. Definition: public string WebSite

GroupUser Class
This class contains represents a Facebook group.

1.1.1.67Property: GroupId The Facebook identifier of the group Definition: public string GroupId 1.1.1.68Property: Positions Collection of positions held by this user

Definition: public Collection<GroupPosition> Positions 1.1.1.69Property: User The user object representing the profile of the user Definition: public User User 1.1.1.70Property: UserId The Facebook identified of the user Definition: public string UserId

User Class
This class contains represents a Facebook user.

1.1.1.71Property: AboutMe A string describing the user. Free form. Definition: public string AboutMe 1.1.1.72Property: Activities Free form text describing the activities this user is interested in. Definition: public string Activities 1.1.1.73Property: Affiliations A collection of Networks this user belongs to Definition: public Collection<Network> Affiliations 1.1.1.74Property: Birthday The day this user was born Definition: public DateTime? Birthday

1.1.1.75Property: Books
Free form text describing this user’s favorite books Definition: public string Books 1.1.1.76Property: CurrentLocation The current location for the user Definition: public Location CurrentLocation 1.1.1.77Property: FirstName The user’s first name Definition: public string FirstName 1.1.1.78Property: HometownLocation The location of the user’s hometown Definition: public Location HometownLocation 1.1.1.79Property: InterestedInGenders A collection containing enum values representing the genders that this person is interested in. Definition: public Collection<Gender> InterestedInGenders

1.1.1.80Property: Interests Free form text describing the user’s interests Definition: public string Interests

1.1.1.81Property: InterestedInRelationshipTypes
A collection containing enum values representing the types of relationships that this person is interested in. Definition:
public InterstedInRelationshipTypes Collection<LookingFor>

1.1.1.82Property: LastName The user’s last name Definition: public string LastName 1.1.1.83Property: Movies Free form text describing the user’s favorite movies Definition: public string Movies 1.1.1.84Property: Music Free form text describing the user’s favorite music Definition: public string Music 1.1.1.85Property: Name The user’s name Definition: public string Name 1.1.1.86Property: NotesCount The number of notes this user has associated with their Facebook account. Definition: public int NotesCount 1.1.1.87Property: Picture The actual image associated with this user’s profile. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit. Definition: public Image Picture

1.1.1.88Property: PictureUrl The url of this user’s Facebook picture Definition: public Uri PictureUrl 1.1.1.89Property: PoliticalView An enum value representing the user’s political view Definition: public PoliticalView PoliticalView 1.1.1.90Property: Quotes Free form text representing the user’s favorite quotes Definition: public string Quotes 1.1.1.91Property: RelationshipStatus An enum value representing the user’s current relationship status. Definition: public RelationshipStatus RelationshipStatus

1.1.1.92Property: Religion
Free form text representing the Religion Definition: public string Religion

1.1.1.93Property: SchoolHistory
A data object representing the user’s education history Definition: public SchoolHistory SchoolHistory 1.1.1.94Property: Sex The user’s gender Definition: public Gender Sex 1.1.1.95Property: SignificantOtherId The Facebook user id of this user’s significant other Definition: public string SignificantOtherId 1.1.1.96Property: TVShows Free form text describing this user’s favorite TVShows Definition: public string TVShows

1.1.1.97Property: UserId The Facebook unique identifier of the user Definition: public string UserId 1.1.1.98Property: WallCount The number of messages that have been written on this user’s wall. Definition: public int WallCount

1.1.1.99Property: RelationshipStatus
The Facebook identified of the user Definition: public RelationshipStatus RelationshipStatus 1.1.1.100Property: WorkHistory Collection of Work object representing this user’s employment history Definition: public Collection<Work> WorkHistory

SchoolHistory Class
This class contains Facebook user’s education history (including high school and college). 1.1.1.101Property: HigherEducaton A collection of HigherEducation object representing the colleges this user attended. Definition: public Collection<HigherEducation> HigherEducation

1.1.1.102Property: HighSchool
A HighSchool data object containing information about the high schools this user attended. Definition: public HighSchool HighSchool

HighSchool Class
This classs contains information about the high schools this user attended.

1.1.1.103Property: GraduationYear
The year this user graduated from college Definition: public int GraduationYear

1.1.1.104Property: HighSchoolOneId
The Facebook unique identifier of the high school

Definition: public string HighSchoolOneId 1.1.1.105Property: HighSchoolOneName The name of the high school Definition: public string HighSchoolOneName

1.1.1.106Property: HighSchoolTwoId
The Facebook unique identifier of the high school Definition: public string HighSchoolTwoId

1.1.1.107Property: HighSchoolTwoName
The name of the high school Definition: public string HighSchoolTwoName

HigherEducation Class
This class contains Facebook user’s college education history. 1.1.1.108Property: AttendedFor An enum value representing if the school was attended for under graduate work or graduate work Definition: public SchoolType AttendedFor

1.1.1.109Property: ClassYear
Graduation year Definition: public int ClassYear

1.1.1.110Property: Concentration
A collection describing user’s majors Definition: public Collection<string> Concentration

1.1.1.111Property: School
The name of the school Definition: public string School

Network Class
This class contains the information about a Facebook Network. 1.1.1.112Property: Name The name of the network.

Definition: public string Name

1.1.1.113Property: NetworkId
The Facebook unique identifier of the network. Definition: public string NetworkId

1.1.1.114Property: Status
The status of the network (Open or Closed). Definition: public string Status 1.1.1.115Property: Type An enum value representing the type of the network (College, High School, Work or Region) Definition: public NetworkType Type 1.1.1.116Property: Year The year associated with the network. Definition: public int Year

Location Class
This class contains information about a geographic location. 1.1.1.117Property: City A city of the location. Definition: public string City

1.1.1.118Property: Country
A country of the location. Definition: public Country Country

1.1.1.119Property: State
A state of the location. Definition: public State State

1.1.1.120Property: StateAbbreviation
A postal abbreviation of the state of the location. Definition: public StateAbbreviation StateAbbreviation

1.1.1.121Property: ZipCode
A zip code of the location. Definition: public string ZipCode

Work Class
This class contains Facebook user’s work history. 1.1.1.122Property: CompanyName The name of the company. Definition: public string CompanyName

1.1.1.123Property: Description
The description of job. Definition: public string Description

1.1.1.124Property: EndDate
The date that the user ended this employment. Definition: public DateTime EndDate

1.1.1.125Property: Location
The location of the job. Definition: public Location Location

1.1.1.126Property: Position
The user’s position/title. Definition: public string Position

1.1.1.127Property: StartDate
The date the user started the job. Definition: public DateTime StartDate

Code Snippets
Windows Form: Application Setup
After registering your desktop application at http://api.Facebook.com, you will receive an API key and a secret. To start utilizing the Facebook API, you must add a reference to the Facebook.dll. Drag an instance of FacebookService from the toolbox. Enter your API Key and Secret.

Windows Form: Retrieving Friends
The FacebookService component contains methods that wrap all of the methods of the Facebook Developer API. The following provides an example for getting all the friends of the logged in user. This method returns a generic collection of User objects. The User object is a strongly typed representation of a Facebook User profile.
Visual C# using System.Collections.Generic; using System.Collections.ObjectModel; … Collection<User> friends = FacebookService1.GetFriends(); Visual Basic Imports System.Collections.Generic Imports System.Collections.ObjectModel

Dim friends As Collection(Of User) = FacebookService1.GetFriends()

Windows Form: Utilizing the FriendList Control
There are several WinForm controls that exercise the FacebookService. This sample shows how to use the FriendList control. Drag a FriendList from the Toolbox to your form. (This assumes you have already added the FacebookService component and set your API key and secret). Simply set the Friends property of the FriendList control.
Visual C# using System.Collections.Generic; using System.Collections.ObjectModel; using Facebook.Controls;

… friendList1.Friends = FacebookService1.GetFriends(); Visual Basic Imports System.Collections.Generic Imports System.Collections.ObjectModel Imports Facebook.Controls

friendList1.Friends = FacebookService1.GetFriends()

Windows Form: Hooking a FriendList Control to a Profile Control
The Profile Control is used to display the detailed profile information about a Facebook User. This sample shows how to hook up the event that a Friend was selected in the FriendList Control and populate a Profile control on the same form.
Visual C# using System.Collections.Generic; using System.Collections.ObjectModel; using Facebook.Controls; … Collection<User> friends = FacebookService1.GetFriends(); friendList1.Friends = friends; profile1.User = friends[0]; friendList1.FriendSelected += new EventHandler<FriendSelectedEventArgs>(friendList1_FriendSelected); void friendList1_FriendSelected(object sender, FriendSelectedEventArgs e) { profile1.User = e.User; } Visual Basic Dim friends As Collection(Of User) = FacebookService1.GetFriends() friendList1.Friends = friends profile1.User = friends(0) AddHandler friendList1.FriendSelected, AddressOf friendList1_FriendSelected … Private Sub friendList1_FriendSelected(ByVal sender As Object, ByVal e As FriendSelectedEventArgs)

End Sub

profile1.User = e.User

Web Application: Authentication Process
Web Application development requires writing code to handle 3 userstates. 1. If we don’t have an auth_token, redirect to the Facebook hosted login page. 2. If we have an auth_token, start a session on behalf of the user. 3. Store the user’s session information for making calls to the Facebook service. The following shows a simple page that handles these 3 states.
Visual C# // ApplicationKey and Secret are acquired when you sign up for _fbService.ApplicationKey = "bfeefa69afdfe81975f0d6136ace3009"; _fbService.Secret = "9b672d682e1d8befd06382953fc2615b"; _fbService.IsDesktopApplication = false; string sessionKey = Session["Facebook_session_key"] as String; string userId = Session["Facebook_userId"] as String; // When the user uses the Facebook login page, the redirect back here // will will have the auth_token in the query params string authToken = Request.QueryString["auth_token"]; // We have already established a session on behalf of this user if (!String.IsNullOrEmpty(sessionKey)) { _fbService.SessionKey = sessionKey; _fbService.UserId = userId; } // This will be executed when Facebook login redirects to our page else if (!String.IsNullOrEmpty(authToken)) { _fbService.CreateSession(authToken); Session["Facebook_session_key"] = _fbService.SessionKey; Session["Facebook_userId"] = _fbService.UserId; Session["Facebook_session_expires"] = fbService.SessionExpires; } // Need to login else { Response.Redirect(@"http://www.Facebook.com/login.php?ap i_key=" + _fbService.ApplicationKey + @"&v=1.0\"); } if (!IsPostBack) {

// Use the FacebookService Component to populate Friends MyFriendList.Friends = _fbService.GetFriends(); } Visual Basic Private _fbService As Facebook.Components.FacebookService = New Facebook.Components.FacebookService() Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs) ' ApplicationKey and Secret are acquired when you sign up for _fbService.ApplicationKey = "7a399eeba47b0f5b2bfd88cc872ada4a" _fbService.Secret = "fad3d3fbeb8571957c39e2792073b978" _fbService.IsDesktopApplication = False Dim sessionKey As String = TryCast(Session("Facebook_session_key"), String) Dim userId As String = TryCast(Session("Facebook_userId"), String) ' When the user uses the Facebook login page, the redirect back here will will have the auth_token in the query params Dim authToken As String = Request.QueryString("auth_token") ' We have already established a session on behalf of this user If (Not String.IsNullOrEmpty(sessionKey)) Then _fbService.SessionKey = sessionKey _fbService.UserId = userId ' This will be executed when Facebook login redirects to our page ElseIf (Not String.IsNullOrEmpty(authToken)) Then _fbService.CreateSession(authToken) Session("Facebook_session_key") = _fbService.SessionKey Session("Facebook_userId") = _fbService.UserId Session("Facebook_session_expires") = _fbService.SessionExpires ' Need to login Else Response.Redirect("http://www.Facebook.com/login.php?api_key=" & _fbService.ApplicationKey & "&v=1.0") End If If (Not IsPostBack) Then ' Use the FacebookService Component to populate Friends MyFriendList.Friends = _fbService.GetFriends() End If