DBClientsManager

Objective-C

@interface DBClientsManager : NSObject

Swift

class DBClientsManager : NSObject

Dropbox Clients Manager.

This is a convenience class for typical integration cases.

To use this class, see details in the tutorial at: https://github.com/dropbox/dropbox-sdk-obj-c/blob/master/README.md.

  • Accessor method for the current Dropbox API consumer app key.

    Declaration

    Objective-C

    + (nullable NSString *)appKey;

    Swift

    class func appKey() -> String?

    Return Value

    The app key of the current Dropbox API app.

  • Accessor method for the authorized DBUserClient shared instance.

    Declaration

    Objective-C

    + (nullable DBUserClient *)authorizedClient;

    Swift

    class func authorizedClient() -> DBUserClient?

    Return Value

    The authorized DBUserClient shared instance.

  • Multi-Dropbox account use case. Returns all current Dropbox user clients.

    Declaration

    Objective-C

    + (nonnull NSDictionary<NSString *, DBUserClient *> *)authorizedClients;

    Swift

    class func authorizedClients() -> [String : DBUserClient]

    Return Value

    Mapping of tokenUid (account ID) to authorized DBUserClient instance.

  • Accessor method for the authorized DBTeamClient shared instance.

    Declaration

    Objective-C

    + (nullable DBTeamClient *)authorizedTeamClient;

    Swift

    class func authorizedTeamClient() -> DBTeamClient?

    Return Value

    The the authorized DBTeamClient shared instance.

  • Multi-Dropbox account use case. Returns all current Dropbox team clients.

    Declaration

    Objective-C

    + (nonnull NSDictionary<NSString *, DBTeamClient *> *)authorizedTeamClients;

    Swift

    class func authorizedTeamClients() -> [String : DBTeamClient]

    Return Value

    Mapping of tokenUid (account ID) to authorized DBTeamClient instance.

  • Multi-Dropbox account use case. Creates and stores a new shared authorized user client instance with the access token retrieved from storage via the supplied tokenUid key.

    @returns Whether a valid token exists in storage for the supplied tokenUid.

    Declaration

    Objective-C

    + (BOOL)authorizeClientFromKeychain:(nullable NSString *)tokenUid;

    Swift

    class func authorizeClient(fromKeychain tokenUid: String?) -> Bool

    Parameters

    tokenUid

    The uid of the stored access token to use to reauthorize. This uid is returned after a successful progression through the OAuth flow (via handleRedirectURL:) in the DBAccessToken field of the DBOAuthResult object.

  • Multi-Dropbox account use case. Creates and stores a new shared authorized team client instance with the access token retrieved from storage via the supplied tokenUid key.

    @returns Whether a valid token exists in storage for the supplied tokenUid.

    Declaration

    Objective-C

    + (BOOL)authorizeTeamClientFromKeychain:(nullable NSString *)tokenUid;

    Swift

    class func authorizeTeamClient(fromKeychain tokenUid: String?) -> Bool

    Parameters

    tokenUid

    The uid of the stored access token to use to reauthorize. This uid is returned after a successful progression through the OAuth flow (via handleRedirectURLTeam:) in the DBAccessToken field of the DBOAuthResult object.

  • Handles launching the SDK with a redirect url from an external source to authorize a user API client.

    Used after OAuth authentication has completed. A DBUserClient instance is initialized and the response access token is saved in the DBKeychain class.

    Declaration

    Objective-C

    + (BOOL)handleRedirectURL:(nonnull NSURL *)url
               completion:(nonnull DBOAuthCompletion)completion;

    Swift

    class func handleRedirectURL(_ url: URL, completion: @escaping DBOAuthCompletion) -> Bool

    Parameters

    url

    The auth redirect url which relaunches the SDK.
    completion

    Completion block to pass back authorization result.

    Return Value

    Whether the URL can be handled.

  • Handles launching the SDK with a redirect url from an external source to authorize a team API client.

    Used after OAuth authentication has completed. A DBTeamClient instance is initialized and the response access token is saved in the DBKeychain class.

    Declaration

    Objective-C

    + (BOOL)handleRedirectURLTeam:(nonnull NSURL *)url
                   completion:(nonnull DBOAuthCompletion)completion;

    Swift

    class func handleRedirectURLTeam(_ url: URL, completion: @escaping DBOAuthCompletion) -> Bool

    Parameters

    url

    The auth redirect url which relaunches the SDK.
    completion

    Completion block to pass back authorization result.

    Return Value

    Whether the URL can be handled.

  • Multi-Dropbox account use case. Sets to nil the active user / team shared authorized client, clears the stored access token associated with the supplied tokenUid, and removes the assocaited client from the shared clients list.

    Declaration

    Objective-C

    + (void)unlinkAndResetClient:(nonnull NSString *)tokenUid;

    Swift

    class func unlinkAndResetClient(_ tokenUid: String)

    Parameters

    tokenUid

    The uid of the token to clear.

  • Sets to nil the active user / team shared authorized client and clears all stored access tokens in DBKeychain.

    Declaration

    Objective-C

    + (void)unlinkAndResetClients;

    Swift

    class func unlinkAndResetClients()

  • Checks if performing an API v1 OAuth 1 token migration is necessary, and if so, performs it.

    This method should successfully migrate all stored access tokens in the official Dropbox Core and Sync SDKs from April 2012 until present, for both iOS and OS X. The method executes its network requests off the main thread.

    Token migration is treated as an atomic operation. Either all tokens that are possible to migrate are migrated at once, or none of them are. If all token conversion requests complete successfully, then the shouldRetry argument in responseBlock will be NO. If some token conversion requests succeed and some fail, and if the failures are for any reason other than network connectivity issues (e.g. token has been invalidated), then the migration will continue normally, and those tokens that were unsuccessfully migrated will be skipped, and shouldRetry will be NO. If any of the failures were because of network connectivity issues, none of the tokens will be migrated, and shouldRetry will be YES.

    Declaration

    Objective-C

    + (BOOL)checkAndPerformV1TokenMigration:
            (nonnull DBTokenMigrationResponseBlock)responseBlock
                                  queue:(nullable NSOperationQueue *)queue
                                 appKey:(nonnull NSString *)appKey
                              appSecret:(nonnull NSString *)appSecret;

    Swift

    class func checkAndPerformV1TokenMigration(_ responseBlock: @escaping DBTokenMigrationResponseBlock, queue: OperationQueue?, appKey: String, appSecret: String) -> Bool

    Parameters

    responseBlock

    The custom handler for determining whether to retry the migration.
    queue

    The operation queue on which to execute the supplied response block (defaults to main queue, if nil).
    appKey

    The consumer app key associated with the app that is integrating with the Dropbox API. Here, app key is used for querying endpoints that have “app auth” authentication type.
    appSecret

    The consumer app secret associated with the app that is integrating with the Dropbox API. Here, app key is used for querying endpoints that have “app auth” authentication type.

    Return Value

    Whether a token migration will be performed.

DesktopAuth

  • Deprecated

    This method was used for long-lived access tokens, which are now deprecated. Please use authorizeFromControllerDesktopV2 instead.

    Commences OAuth desktop flow from supplied view controller.

    This method should no longer be used. Long-lived access tokens are deprecated. See https://dropbox.tech/developers/migrating-app-permissions-and-access-tokens. Please use authorizeFromControllerDesktopV2 instead.

    Declaration

    Objective-C

    + (void)authorizeFromControllerDesktop:(nonnull NSWorkspace *)sharedApplication
                            controller:(nullable NSViewController *)controller
                               openURL:
                                   (void (^_Nonnull)(NSURL *_Nonnull))openURL;

    Swift

    class func authorize(fromControllerDesktop sharedApplication: NSWorkspace, controller: NSViewController?, openURL: @escaping (URL) -> Void)

    Parameters

    sharedApplication

    The NSWorkspace with which to render the OAuth flow.
    controller

    The NSViewController with which to render the OAuth flow. The controller reference is weakly held.
    openURL

    A wrapper around app-extension unsafe openURL call.

  • Commences OAuth mobile flow from supplied view controller.

    This starts the OAuth 2 Authorization Code Flow with PKCE. PKCE allows “authorization code” flow without “client_secret” It enables “native application”, which is ensafe to hardcode client_secret in code, to use “authorization code”. PKCE is more secure than “token” flow. If authorization code is compromised during transmission, it can’t be used to exchange for access token without random generated code_verifier, which is stored inside this SDK.

    Declaration

    Objective-C

    + (void)
    authorizeFromControllerDesktopV2:(nonnull NSWorkspace *)sharedApplication
                          controller:(nullable NSViewController *)controller
               loadingStatusDelegate:
                   (nullable id<DBLoadingStatusDelegate>)loadingStatusDelegate
                             openURL:(void (^_Nonnull)(NSURL *_Nonnull))openURL
                        scopeRequest:(nullable DBScopeRequest *)scopeRequest;

    Swift

    class func authorize(fromControllerDesktopV2 sharedApplication: NSWorkspace, controller: NSViewController?, loadingStatusDelegate: DBLoadingStatusDelegate?, openURL: @escaping (URL) -> Void, scopeRequest: DBScopeRequest?)

    Parameters

    sharedApplication

    The NSWorkspace with which to render the OAuth flow.
    controller

    The NSViewController with which to render the OAuth flow. The controller reference is weakly held.
    loadingStatusDelegate

    An optional delegate to handle loading experience during auth flow. e.g. Show a loading spinner and block user interaction while loading/waiting.
    openURL

    A wrapper around app-extension unsafe openURL call.
    scopeRequest

    Request contains information of scopes to be obtained.

  • Stores the user app key for desktop. If any access token already exists, initializes an authorized shared DBUserClient instance. Convenience method for setupWithTransportConfigDesktop:.

    This method should be used in the single Dropbox user case. If any stored OAuth tokens exist, one will arbitrarily be retrieved and used to authenticate API calls. Use setupWithTransportConfig:, if additional customization of network calling parameters is necessary. This method should be called from the app delegate.

    Declaration

    Objective-C

    + (void)setupWithAppKeyDesktop:(nonnull NSString *)appKey;

    Swift

    class func setup(withAppKeyDesktop appKey: String)

    Parameters

    appKey

    The app key of the third-party Dropbox API user app that will be associated with all API calls. To create an app or to locate your app’s app key, please visit the App Console here: https://www.dropbox.com/developers/apps.

  • Stores the user transport config info for desktop. If any access token already exists, initializes an authorized shared DBUserClient instance.

    This method should be used in the single Dropbox user case. If any stored OAuth tokens exist, one will arbitrarily be retrieved and used to authenticate API calls. You can customize some network calling parameters using the different DBTransportDefaultConfig constructors. This method should be called from the app delegate.

    Declaration

    Objective-C

    + (void)setupWithTransportConfigDesktop:
    (nullable DBTransportDefaultConfig *)transportConfig;

    Swift

    class func setup(withTransportConfigDesktop transportConfig: DBTransportDefaultConfig?)

    Parameters

    transportConfig

    A wrapper around the different parameters that can be set to change network calling behavior.

  • Stores the team app key for desktop. If any access token already exists, initializes an authorized shared DBTeamClient instance. Convenience method for setupWithTeamTransportConfigDesktop:.

    This method should be used in the single Dropbox user case. If any stored OAuth tokens exist, one will arbitrarily be retrieved and used to authenticate API calls. Use setupWithTeamTransportConfig:, if additional customization of network calling parameters is necessary. This method should be called from the app delegate.

    Declaration

    Objective-C

    + (void)setupWithTeamAppKeyDesktop:(nonnull NSString *)appKey;

    Swift

    class func setup(withTeamAppKeyDesktop appKey: String)

    Parameters

    appKey

    The app key of the third-party Dropbox API user app that will be associated with all API calls. To create an app or to locate your app’s app key, please visit the App Console here: https://www.dropbox.com/developers/apps.

  • Stores the team transport config info for desktop. If any access token already exists, initializes an authorized shared DBTeamClient instance.

    This method should be used in the single Dropbox user case. If any stored OAuth tokens exist, one will arbitrarily be retrieved and used to authenticate API calls. You can customize some network calling parameters using the different DBTransportDefaultConfig constructors. This method should be called from the app delegate.

    Declaration

    Objective-C

    + (void)setupWithTeamTransportConfigDesktop:
    (nullable DBTransportDefaultConfig *)transportConfig;

    Swift

    class func setup(withTeamTransportConfigDesktop transportConfig: DBTransportDefaultConfig?)

    Parameters

    transportConfig

    A wrapper around the different parameters that can be set to change network calling behavior.

MobileAuth

  • Deprecated

    This method was used for long-lived access tokens, which are now deprecated. Please use authorizeFromControllerV2 instead.

    Commences OAuth mobile flow from supplied view controller.

    This starts a “token” flow.

    This method should no longer be used. Long-lived access tokens are deprecated. See https://dropbox.tech/developers/migrating-app-permissions-and-access-tokens. Please use authorizeFromControllerV2 instead.

    Declaration

    Objective-C

    + (void)authorizeFromController:(nonnull UIApplication *)sharedApplication
                     controller:(nullable UIViewController *)controller
                        openURL:(void (^_Nonnull)(NSURL *_Nonnull))openURL;

    Swift

    class func authorize(fromController sharedApplication: UIApplication, controller: UIViewController?, openURL: @escaping (URL) -> Void)

    Parameters

    sharedApplication

    The UIApplication with which to render the OAuth flow.
    controller

    The UIViewController with which to render the OAuth flow. Please ensure that this is the top-most view controller, so that the authorization view displays correctly. The controller reference is weakly held.
    openURL

    A wrapper around app-extension unsafe openURL call.

  • Commences OAuth mobile flow from supplied view controller.

    This starts the OAuth 2 Authorization Code Flow with PKCE. PKCE allows “authorization code” flow without “client_secret” It enables “native application”, which is ensafe to hardcode client_secret in code, to use “authorization code”. PKCE is more secure than “token” flow. If authorization code is compromised during transmission, it can’t be used to exchange for access token without random generated code_verifier, which is stored inside this SDK.

    Declaration

    Objective-C

    + (void)authorizeFromControllerV2:(nonnull UIApplication *)sharedApplication
                       controller:(nullable UIViewController *)controller
            loadingStatusDelegate:
                (nullable id<DBLoadingStatusDelegate>)loadingStatusDelegate
                          openURL:(void (^_Nonnull)(NSURL *_Nonnull))openURL
                     scopeRequest:(nullable DBScopeRequest *)scopeRequest;

    Parameters

    sharedApplication

    The UIApplication with which to render the OAuth flow.
    controller

    The UIViewController with which to render the OAuth flow. Please ensure that this is the top-most view controller, so that the authorization view displays correctly. The controller reference is weakly held.
    loadingStatusDelegate

    An optional delegate to handle loading experience during auth flow. e.g. Show a loading spinner and block user interaction while loading/waiting. If a delegate is not provided, the SDK will show a default loading spinner when necessary.
    openURL

    A wrapper around app-extension unsafe openURL call.
    scopeRequest

    Request contains information of scopes to be obtained.

  • Stores the user app key. If any access token already exists, initializes an authorized shared DBUserClient instance. Convenience method for setupWithTransportConfig:.

    This method should be used in the single Dropbox user case. If any stored OAuth tokens exist, one will arbitrarily be retrieved and used to authenticate API calls. Use setupWithTransportConfig:, if additional customization of network calling parameters is necessary. This method should be called from the app delegate.

    Declaration

    Objective-C

    + (void)setupWithAppKey:(nonnull NSString *)appKey;

    Swift

    class func setup(withAppKey appKey: String)

    Parameters

    appKey

    The app key of the third-party Dropbox API user app that will be associated with all API calls. To create an app or to locate your app’s app key, please visit the App Console here: https://www.dropbox.com/developers/apps.

  • Stores the user transport config info. If any access token already exists, initializes an authorized shared DBUserClient instance.

    This method should be used in the single Dropbox user case. If any stored OAuth tokens exist, one will arbitrarily be retrieved and used to authenticate API calls. You can customize some network calling parameters using the different DBTransportDefaultConfig constructors. This method should be called from the app delegate.

    Declaration

    Objective-C

    + (void)setupWithTransportConfig:
    (nullable DBTransportDefaultConfig *)transportConfig;

    Swift

    class func setup(withTransport transportConfig: DBTransportDefaultConfig?)

    Parameters

    transportConfig

    A wrapper around the different parameters that can be set to change network calling behavior.

  • Stores the team app key. If any access token already exists, initializes an authorized shared DBTeamClient instance. Convenience method for setupWithTeamTransportConfig:.

    This method should be used in the single Dropbox user case. If any stored OAuth tokens exist, one will arbitrarily be retrieved and used to authenticate API calls. Use setupWithTeamTransportConfig:, if additional customization of network calling parameters is necessary. This method should be called from the app delegate.

    Declaration

    Objective-C

    + (void)setupWithTeamAppKey:(nonnull NSString *)appKey;

    Swift

    class func setup(withTeamAppKey appKey: String)

    Parameters

    appKey

    The app key of the third-party Dropbox API user app that will be associated with all API calls. To create an app or to locate your app’s app key, please visit the App Console here: https://www.dropbox.com/developers/apps.

  • Stores the team transport config info. If any access token already exists, initializes an authorized shared DBTeamClient instance.

    This method should be used in the single Dropbox user case. If any stored OAuth tokens exist, one will arbitrarily be retrieved and used to authenticate API calls. You can customize some network calling parameters using the different DBTransportDefaultConfig constructors. This method should be called from the app delegate.

    Declaration

    Objective-C

    + (void)setupWithTeamTransportConfig:
    (nullable DBTransportDefaultConfig *)transportConfig;

    Swift

    class func setup(withTeamTransport transportConfig: DBTransportDefaultConfig?)

    Parameters

    transportConfig

    A wrapper around the different parameters that can be set to change network calling behavior.