Linking to the Account

The FooDrop class uses the DBLoginControllerDelegate protocol to handle a login session (Listing Two). This protocol supplies the callback delegates for that session.

Listing Three shows how FooDrop would implement the login session. First, it declares the prototypes for two action handlers. Action doLink: starts a login session, while doUnlink: ends it.

Listing Three

/*
--
-- FooDrop.h
--
*/
#import "DropboxSDK.h"

@class DBRestClient;
@interface FooDrop : NSObject <DBLoginControllerDelegate, 
			DBRestClientDelegate>

// -- see Listing Two

// action prototypes
- (IBAction) doLink:(id)aSrc;
- (IBAction) doUnlink:(id)aSrc;
@end

/*
--
-- FooDrop.m
--
*/
@implementation FooDrop

// -- see Listing Two

// -- ACTION HANDLERS
// Start a Dropbox session
- (IBAction) doLink:(id)aSrc
{
	DBSession *tDbx;
	
	tDbx = [DBSession sharedSession];
	if (tDbx != nil)
	{
		if (![tDbx isLinked])
		{
			DBLoginController* tDbx 
				= [[DBLoginController new] autorelease];
			tDbx.delegate = self;
			[tDbx presentFromController:self];
		}
	}
}


// End a Dropbox session
- (IBAction) doUnlink:(id)aSrc
{
	DBSession *tDbx;
	
	tDbx = [DBSession sharedSession];
	if (tDbx != nil)
	{
		if ([tDbx isLinked])
			[tDbx unlink];
	}
}

// -- DELEGATE METHODS
// Login was successful
- (void)loginControllerDidLogin:(DBLoginController*)aSrc 
{
	// create the REST client
	pOut_ = [[DBRestClient alloc] 
		initWithSession:[DBSession sharedSession]];
	self.dboxClient.delegate = self;
}

// Login was cancelled
- (void)loginControllerDidCancel:(DBLoginController*)aSrc 
{
	// handle the cancellation here
}

     @end

Action doLink: checks DBSession for a valid shared session. Then it checks if the session is not linked to a user account. If both checks are true, doLink: creates an instance of DBLoginController. It sets FooDrop as the delegate, and it invokes presentFromController: to display the standard login screen.

Action doUnlink: also checks DBSession for a shared session. But this time, it checks if the session has an active link. If the link exists, the action breaks it using the unlink method.

Figure 3: Typical login screen.

Figure 3 shows a typical Dropbox login screen. Users enter their account details on the fields provided. When they click the Link button, FooDrop invokes the delegate method loginControllerDidLogin: (Listing Three, lines 63-69). This method creates an instance of DBRestClient and stores it into the pOut_ property. Then it sets FooDrop as the delegate for DBRestClient. When users click the Cancel button, FooDrop invokes the delegate method loginControllerDidCancel:. This one provides the clean-up code for the login attempt.

Both delegate methods have the DBLoginController instance as their sole inputs.

Client Folder

The first task for a custom client is to create its own folder on the user's Dropbox account. Moreover, the folder must use the same name as the client. So, if the client's name is FooDrop, its folder must also be named FooDrop.

Creating the folder is done with the DBRestClient object. First, define the folder name as an NSString. Then pass the NSString object to the instance method createFolder:.

tDir = [NSString stringWithString:@"FooDrop"];
[self.dboxClient createFolder:tDir];

Make sure the name does not contain any invalid characters like a forward slash (/) or colon (:). Otherwise, the method will fail.

The client will try to place the new folder at the root level of the user's account. It then invokes one of many delegate methods from the protocol DBRestClientDelegate (Figure 4).

Figure 4.

The method restClient:createdFolder: runs when the client succeeds in creating the desired folder. It gets two input arguments: the DBRestClient instance and a DBMetadata object. The latter object describes the newly made folder.

- (void)restClient:(DBRestClient*)aSrc 
	createdFolder:(DBMetadata*)aDir 
{ 
	// handle the new Dropbox folder…
}

If the client could not create the folder, it runs the method restClient:createFolderFailedWithError:. This, too, gets two input arguments: the same DBRestClient instance and an NSError object. The latter object describes the reason why the task failed.

- (void)restClient:(DBRestClient*)client 
	createFolderFailedWithError:(NSError*)aErr 
{
	// handle the Dropbox error…
}