3. Programmatic API Usage

(Please notice that programmatic API usage is a feature available starting in v5.)

Programmatic API usage can be done using FPSimpleAPI:

FPSource *source = [FPSource sourceWithIdentifier:FPSourceDropbox];

if (source)
{
    FPSimpleAPI *simpleAPI = [FPSimpleAPI simpleAPIWithSource:source];

    // Set delegate to our class instance (typically a view controller)
    simpleAPI.delegate = self;
}

Supported API calls:

- (void)getMediaListAtPath:(NSString *)path completion:(nullable FPSimpleAPIMediaListCompletionBlock)completion;

Requests a media list at a given path asynchronously.

NOTE: Results are NOT paginated. If you would prefer the results to be paginated, please use -getMediaListAtPath:startPage:success:failure: instead.

--

- (void)getMediaListAtPath:(NSString *)path startPage:(NSUInteger)startPage completion:(nullable FPSimpleAPIMediaListCompletionBlock)completion;

Requests a media list at a given path asynchronously where the results are paginated.

NOTE: When there's more than one page of results, the success block will include a nextPage value greater than 0 that can be used as the startPage value for a subsequent call to this method.

--

- (void)getMediaInfoAtPath:(NSString *)path completion:(nullable FPSimpleAPIMediaCompletionBlock)completion progress:(nullable FPSimpleAPIProgressBlock)progress;

Requests a media at a given path asynchronously.

--

- (void)saveMediaAtLocalURL:(NSURL *)localURL named:(NSString *)name withMimeType:(NSString *)mimetype atPath:(NSString *)path completion:(nullable FPSimpleAPIMediaCompletionBlock)completion progress:(nullable FPSimpleAPIProgressBlock)progress;

Saves some media from a local NSURL to a given path in the source asynchronously.

--

- (void)saveMediaRepresentedByData:(NSData *)data named:(NSString *)name withMimeType:(NSString *)mimetype atPath:(NSString *)path completion:(nullable FPSimpleAPIMediaCompletionBlock)completion progress:(nullable FPSimpleAPIProgressBlock)progress;

Saves some media represented by NSData to a given path in the source asynchronously.

--

- (void)saveMediaInfo:(FPMediaInfo *)mediaInfo named:(NSString *)name atPath:(NSString *)path completion:(nullable FPSimpleAPIMediaCompletionBlock)completion progress:(nullable FPSimpleAPIProgressBlock)progress;

Saves some media represented by a FPMediaInfo to a given path in the source asynchronously.

Example of listing files in Dropbox at path /

FPSource *source = [FPSource sourceWithIdentifier:FPSourceDropbox];

FPSimpleAPI *simpleAPI = [FPSimpleAPI simpleAPIWithSource:source];
// Set delegate to our class instance (typically a view controller)
simpleAPI.delegate = self;

FPSimpleAPIMediaListCompletionBlock completionBlock = ^(NSArray *mediaList, NSUInteger nextPage, NSError *error) {
    if (error)
    {
        // An error has occurred
        NSLog(@"Error getting media list: %@", error);
    }
    else
    {
        // We got our list
        NSLog(@"Got media list: %@", mediaList);
    }

    // Please notice that `nextPage` will always return 0 when using `-getMediaInfoAtPath:completion:`.
    // To receive paginated results, please use `-getMediaListAtPath:startPage:completion:` passing 0
    // as the `startPage`.
};

// Get media list from Dropbox at /
[simpleAPI getMediaListAtPath:@"/"
                   completion:completionBlock];

Suspending, Resuming and Cancelling Requests

- (void)suspendAllRequests;

Suspends all the requests enqueued for execution.

--

- (void)resumeAllRequests;

Resumes all the requests enqueued for execution.

--

- (void)cancelAllRequests;

Cancels all the requests enqueued for execution and those currently running.

FPSimpleAPIDelegate Methods

- (void)simpleAPI:(FPSimpleAPI *)simpleAPI requiresAuthenticationForSource:(FPSource *)source

(Required) Implement this method to delegate source authentication to the content owner. In most circumstances, you'll be relying on FPAuthController to present the authentication UI to the user.

Handling Authentication in iOS

- (void)simpleAPI:(FPSimpleAPI *)simpleAPI requiresAuthenticationForSource:(FPSource *)source
{
    FPAuthController *authController = [[FPAuthController alloc] initWithSource:source];

    if (authController)
    {
        [self.navigationController pushViewController:authController animated:YES];
    }
    else
    {
        NSLog(@"FPAuthController could not be instantiated.");
    }
}

For a full working example, please check FPPicker iOS API Demo.

Handling Authentication in OS X

- (void)simpleAPI:(FPSimpleAPI *)simpleAPI requiresAuthenticationForSource:(FPSource *)source
{
    self.authController = [[FPAuthController alloc] initWithSource:source];

    if (self.authController)
    {
        [self.authController displayAuthSheetInModalWindow:self.view.window
                                                   success: ^{
            // NO-OP
        }
                                                   failure: ^(NSError *__nonnull error) {
            NSAlert *alert = [NSAlert alertWithError:error];
            [alert runModal];
        }];
    }
    else
    {
        NSLog(@"FPAuthController could not be instantiated.");
    }
}

For a full working example, please check FPPicker Mac API Demo.