Getting Started with the Transporter API (v2.0)

Once you have registered and received your app token and test account, you are ready to start the integration process. Test accounts are only required for app developers that don’t already have a Transporter.

The current release of the Transporter API uses an Objective-C interface that handles all communication to the Transporter services and devices. Service communications are made through RESTful calls over HTTPS and device communications are made through a custom protocol that utilizes AES 256 encryption to ensure security.

The Transporter API will allow your app to do the following:

• Read and write files to / from Transporter(s)
• Create, rename, copy and delete files to / from Transporter(s)
• Create, rename, copy and delete folders to / from Transporter(s)

API Package Contents

The current release of the Transporter API is focused on Windows, iOS and Mac OS X applications. Future versions of the API will include support for other platform applications.

The current package consists of two static libraries (libPublicAPIForTransporter.a in both simulator and device forms) and a header file (PublicAPIForTransporter.h).

Installation Details

All applications should use the static library and the header file provided. If required, you can linkBinaryWithLibraries (“libstdc++.dylib” and “libz.dylib”).

Implementation Notes

There are two paths to files and folders that developers need to be aware of:

1. PathOnTransporter is always relative to the Transporter directory.

Example:

a) [/] root of the Transporter directory
b) [/Transporter Library/photos] for accessing photos directory under Transporter Library

2. LocalPathToFile is always the absolute path of the folder on the local machine.

Limitations

There are a few limitations with the current version of the API that you should be aware of:

1. The move command is not currently supported as a safeguard to ensure data integrity is preserved. Moves can cause unintended results due to the different nature of shared and unshared folders.

First Run Initialization

The first time you run the API, the following call will need to occur:

registerAndAuthenticateUser – to get app instance token and auth token for the user and password combination; should only be called the first time.

/**
 * registerAndAuthenticateUser - Call with appKey, username and password with Nil appInstanceToken on first 
 *                               run / install. Both appInstanceToken and authToken will be retuned in this
 *                               scenario and they should be stored in the app to be reused again. 
 *                                              OR
 *                               Call with appKey, username, password and appInstanceToken on seubsequent runs.
 *                               This method authenticates the user and associates the user with the appKey.
 *                               The returned authToken value should be stored in the app and reused again.
 *
 *
 * - [IN] appKey: An application Key for the app; unique for every application (supplied by Connected Data)
 * - [IN] displayName: An application name or appName (shown on the Transporter Management web site)
 * - [IN] email: Email address of the user
 * - [IN] password: Password of the user
 * - [IN/OUT] appInstanceToken: A Nil value for registering the app OR a valid value for app InstanceId/Token.
 * - [OUT] authToken : returns an authToken or NIL if the email/password combo was not correct / no network connection
 * - [OUT] error: Returns error code if the input arguments are NIL or if the input parameters are invalid
 *                or any other error generated from the underlying layer.
 *                On success, the error code will be NIL.
 *                Note: This value must be stored and passed to reauthenticateUser
 *
 * Returns YES upon successful connection to the Transporter Service and retrieval of users account data
 * Note: Both appInstanceToken and authToken should be stored in the application to call reauthenticateUser
 *
 */
- (BOOL) registerAndAuthenticateUser:(NSString *)appKey displayName:(NSString *)displayName
                                            userEmail:(NSString *)email userPassword:(NSString *)password
                                            appInstanceToken:(NSString **)appInstanceToken
                                            authToken:(NSString **)authToken
                                            errorCode:(TPErrorCode **)error;
  • After First Run Initialization:

    authenticateWithTokens – to get auth token for the user and password combination. This also starts the Transporter service and devices. AuthToken should be saved and only called again when the user logs out, logs in again, or a new user logs in.

/**
 * authenticateWithTokens - Called on app launch; if the authenticateUser is called, this method should not
 *                          be called.
 *
 * - [IN] appInstanceToken: A valid application token that is obtained from the registerAppKey() method
 * - [IN] authToken: A valid authentication Token that is obtained using authenticateUser() method
 * - [OUT] error: Returns error code if the input arguments are NIL or if the input parameters are invalid
 *                or any other error generated from the underlying layer.
 *                On success, the error code will be NIL.
 *
 * Returns YES upon successful connection to the Transporter Service and retrieval of users account data
 */
- (Bool) authenticateWithTokens:(NSString *)appInstanceToken authenticationToken:(NSString *)authToken 
                               errorCode:(TPErrorCode **)error;

Note: authenticateUser and authenticateWithTokens initialize the Transporter Service. There is a small delay between initializing and connecting with the device.

You have to make sure the device is connected, before you can getDirectoryContents, or make any Transporter calls.

After the first run, you will normally only need to call authenticateWithTokens when starting the API. The only exceptions are if the user invalidates the auth token by logging out or if authenticateWithTokens fails.

If the user removes the connection by logging out to their Transporter from your app, you can keep the app instance token, but should delete the account auth token.

Sample Calls

Below are a few sample calls for copying a file and creating a folder. A full list of all supported calls is available in the header file you will receive after you

/**
 * copyFile - Copies a file from the specified remote path on the Transporter to the other specified remote path
 *
 * - [IN] fromPathOnTransporter: Relative to the transporter directory(source)
 * - [IN] toPathOnTransporter: Relative to the transporter directory(destination)
 * - [OUT] error: Returns error code if the input arguments are NIL or if the input parameters are invalid
 *                or any other error generated from the underlying layer.
 *                On success, the error code will be NIL.
 *
 * Returns YES if copy was successful.
 *
 * Note: User should check for the return BOOL value, before checking the progress
 *
 */
- (BOOL) copyFile: (NSString *)fromPathOnTransporter
                          transporterFilePath:(NSString *)toPathOnTransporter
                                        abort:(BOOL *) abort
                                     progress:(double *) progressInPercentage
                                    errorCode:(TPErrorCode **)error;

Create Folder

/**
 * createFolder - Creates folder at the specified remote path on the Transporter
 *
 * - [IN] pathOnTransporter: Relative to the transporter directory
 * - [IN] folderName: Name of the folder to be created.
 * - [OUT] error: Returns error code if the input arguments are NIL or if the input parameters are invalid
 *                or any other error generated from the underlying layer.
 *                On success, the error code will be NIL.
 *
 * Returns YES if folder was created successful.
 *
 */
- (BOOL) createFolder: (NSString *)pathOnTransporter
           FolderName:(NSString *)folderName
            errorCode:(TPErrorCode **)error;