PCAPISDK

Version 1.7 - Updated on 01/12/2017

Superclass: NSObject
Declared In: PCAPISDK.h

Introduction

This class acts as the interface between iOS SDK for Personal Cloud Storage APIs and a third party applications. Third party applications can invoke all Personal Cloud Storage APIs using public methods exposed in this class.

Authentication and Authorization

authenticateClient

- (void)authenticateClient:(PCClientCredentials *)clientCredentials 
        fromViewController:(UIViewController *)viewController 
        withCompletionHandler:(void (^)(PCAuthenticationResponse *authenticationCredentials, PCOAuthLoginPageResponse *OAuthLoginPageResponse, PCAPIQueryResponse *response))completion;

Parameters
- clientCredentials
  - ClientID
  - clientSecret
  - redirectURL
  - keychainID
- viewController
  - viewController - from OAuth 2.0 screen
- completion
  This completion block is called once OAuth 2.0 process completes. If the user is successfully logged on, the authentication credentials are returned in this block.
Discussion
Call this method to present OAuth 2.0 login screen. Once authentication is complete or has failed, the completion handler is called. If the authentication is successful, the authentication credentials are passed in the completion handler. Access token received as a result of login is saved in keychain. This will remain in keychain until user forcefully logged off.

fetchAccessToken

-(NSString *)fetchAccessToken;

Discussion
Returns the access token if an access token is available in the keychain. Otherwise, returns nil value.

isUserLoggedIn

- (BOOL)isUserLoggedIn;

Discussion
Returns YES if the user has an access token.

logout

- (BOOL)logout;

Discussion
Call this method to log the user out from the current session. This method removes the user’s access token stored in the keychain and returns YES if the token has been successfully removed.

refreshSession

- (PCAPI *)refreshSessionWithCompletionHandler:(void (^)(PCAuthenticationResponse *authenticationCredentials, PCAPIQueryResponse *response))completion;

Parameters
- completion
  This block is called on the completion of the refresh session process. Returns new authentication credentials.
Discussion
Call this methods to refresh current session. Once session is refreshed, authentication credentials are returned with the completion block.

Account Information

fetchAccountInfo

- (PCAPI *)fetchAccountInfoWithCompletionHandler:(void (^)(PCAccountInfo *accountInfo, PCAPIQueryResponse *response))completion;

Parameters
- completion
  This block is called on the completion of fetchAccountInfo process. An object of PCAccountInfo which holds account information is returned in completion block.
Discussion
Call this method to retrieve account details.

Contacts

fetchContacts

- (PCAPI *)fetchContacts:(PCContactAPIParams *)params 
        WithCompletionHandler:(void (^)(NSArray *contacts, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to retrieve contacts.
- completion
  This block is called on the completion of the fetchContacts process. An array of PCContact objects is returned in completion.
Discussion
Call this method to retrieve all contacts in a user’s Personal Cloud Storage account.

Favorites

deleteFavorites

-(PCAPI *)deleteFavorites:(PCDeleteFavoritesAPIParams*)params 
        withCompletionHandler:(void(^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to unmark favorites.
- completion
  This block is called on the completion of a unmark favorites operation.
Discussion
Call this method to unmark file or folder as favorites.

getFavorites

- (void)getFavorites:(PCGetFavoritesAPIParams *)params 
        withCompletionHandler:(void (^)(NSArray *favoritesItems, PCAPIQueryResponse *response))completion;

Parameters
- params Parameters required to retrieve the list of favorite files and folders from the user account.
- completion
  This block is called on the completion of retrieve favorites process. An array of PCMetadata objects is returned in the completion block.
Discussion
Call this method to retrieve the list of favorite files and folders from the user account.

setFavorites

-(PCAPI *)setFavorites:(PCSetFavoritesAPIParams *)params 
        withCompletionHandler:(void(^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to mark favorites.
- completion
  This block is called on the completion of a add to favorites operation.
Discussion
Call this method to mark the list of files or folders as favorites.

File and Folder Operations

copy

- (PCAPI *)copy:(PCFOPSAPIParams *)params 
        withCompletionHandler:(void (^)(PCResource *metadata, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to perform copy operation.
- completion
  This block is called on the completion of a copy operation. Metadata of the target folder is returned in completion block.
Discussion
Call this method to copy a file or a folder.

NOTE:
You cannot perform the copy operation on a virutal folder.

createFolder

- (PCAPI *)createFolder:(PCCreateFolderAPIParams *)params 
        withCompletionHandler:(void (^)(PCResource *metadata, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to create a folder.
- completion
  This block is called on the completion of a folder creation process. Created folder metadata is returned in completion block.
Discussion
Call this method to create a folder at a given path.

NOTE:
You cannot perform the createFolder operation on a virutal folder.

deletePath

- (PCAPI *)deletePath:(PCDeleteParams *)params 
        withCompletionHandler:(void (^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to perform delete operation.
- completion
  This block is called on the completion of a delete operation.
Discussion
Call this method to delete a file or a folder.

NOTE:
You cannot perform the deletePath operation on a virutal folder.

doFullSync

- (PCAPI *)doFullSyncWithCompletionHandler:(void (^)(PCAPIQueryResponse *response))completion;

Parameters
- completion
  This block is called on the completion of full sync operation.
Discussion
Call this method to refresh the local cache of files. This method first calls GET /fullview API to get changes from the server, then merges the changes with the local database.

downloadFile

- (PCAPI *)downloadFile:(PCFilesAPIParams *)params progress:(void(^)(long long totalBytesDownloaded, long long totalBytesToBeDownloaded))progress 
        withCompletionHandler:(void(^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to download a file.
- progress
  Indicates the upload progress of the file.
- completion
  This block is called on the completion of a file download. PCAPIQueryResponse stores the location of the downloaded file.
Return Value
A PCAPI object which is downloading the file.
Discussion
Call this method to download a file. The file is downloaded to a temporary location and will be removed once the API which downloaded the file is released. Move the file to a different location in completion callback.

downloadThumbnail

- (PCAPI *)downloadThumbnail:(PCThumbnailAPIParams *)params 
        withCompletionHandler:(void (^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to fetch a thumbnail image
- completion
  This block is called on the completion of thumbnail fetch process. PCAPIQueryResponse stores the location of downloadThumbnail.
Return Value
A PCAPI object which is downloading the thumbnail image.
Discussion
Call this method to download a thumbnail image of any file.

fetchMetadata

- (PCAPI *)fetchMetadata:(PCMetaDataAPIParams *)params 
        withCompletionHandler:(void (^)(PCMetadata *metadata, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to retrieve metadata of a folder.
- completion
  This block gets called on the completion of metadata fetch process. A PCMetadata object with metadata details are returned in completion block.
Discussion
Call this method to retrieve metadata of a folder.

move

- (PCAPI *)move:(PCFOPSAPIParams *)params 
        withCompletionHandler:(void (^)(PCResource *metadata, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to perform a move operation.
- completion
  This block is called on the completion of a move operation. Returns the metadata of target folder.
Discussion
Call this method to move a file or a folder.

NOTE:
You cannot perform the move operation on a virutal folder.

rename

- (PCAPI *)rename:(PCFOPSAPIParams *)params 
        withCompletionHandler:(void (^)(PCResource *metadata, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to perform rename operation.
- completion
  This block is called on the completion of a rename operation. Returns the metadata of the renamed file or folder.
Discussion
Call this method to rename a file or a folder.

NOTE:
You cannot perform the rename operation on a virutal folder.

search

- (void)search:(PCSearchAPIParams *)params 
        withCompletionHandler:(void (^)(NSArray *results, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to perform a search operation.
- completion
  This block is called on the completion of the search process. An array of NSManagedObjectID is returned in the completion block.
Discussion
Call this method to search for any resource in a user’s Personal Cloud Storage account.

uploadFile

- (void)uploadFile:(PCUploadAPIParams *)params readFromPath:(NSString *)filePath 
        progress:(void(^)(PCUploadAPIState uploadState, long long totalBytesUploaded, long long totalBytesToBeUploaded))progress 
        withCompletionHandler:(void(^)(PCResource *metadata, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to upload a file.
- filePath
  Local path of the file from where file is to be read.
- progress
  Indicates the file upload progress.
- completion
  This block is called on the completion of the upload process. Returns the metadata of the uploaded file.
Discussion
Call this method to upload a file to a folder.

NOTE:
You cannot perform the uploadFile operation on a virutal folder.

Playlists

addPlaylistItems

- (PCAPI *)addPlaylistItems:(PCAddPlaylistItemsAPIParams *)params 
        withCompletionHandler:(void (^)(NSArray *playlistItems, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to add items in a playlist.
- completion
  This block is called on the completion addPlaylistItems operation. A NSArray of PCResource objects are returned in this block.
Discussion
Call this method to add items to a playlist.

createPlaylist

- (PCAPI *)createPlaylist:(PCCreateplaylistAPIParams *)params 
        withCompletionHandler:(void (^)(PCPlaylist *playlist, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to create a playlist.
- completion
  This block is called on the completion of create playlist operation. A PCPlaylist object is returned in this block.
Discussion
Call this method to create a playlist.

deletePlaylist

- (PCAPI *)deletePlaylist:(PCDeletePlaylistAPIParams *)params 
        withCompletionHandler:(void(^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to delete a playlist.
- completion
  This block is called on the completion of a deletePlaylist operation.
Discussion
Call this method to delete a playlist.

editPlaylist

- (PCAPI *)editPlaylist:(PCEditPlaylistAPIParams *)params 
        withCompletionHandler:(void (^)(PCPlaylist *playlist, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to edit a playlist.
- completion
  This block is called on the completion of a rename playlist operation. Renamed PCPlaylist object is returned in this block.
Discussion
Call this method to edit a playlist.

deletePlaylistItem

- (PCAPI *)deletePlaylistItem:(PCDeletePlaylistItemAPIParams *)params 
        withCompletionHandler:(void (^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to delete an item from a playlist.
- completion
  This block is called on the completion of deletePlaylistItem operation.
Discussion
Call this method to delete an item from a playlist.

editPlaylistDefinition

- (PCAPI *)editPlaylistDefinition:(PCEditPlaylistDefinitionAPIParams *)params 
        withCompletionHandler:(void (^)(PCPlaylist *playlist, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to update a playlist by sending a new ‘playlistDefinition’ model.
- completion
  This block is called on the completion of a update playlist definition operation. Updated PCPlaylist object is returned in this block.
Discussion
Call this method to edit playlist definition.

getPlaylist

- (PCAPI *)getPlaylist:(PCGetPlaylistAPIParams *)params 
        withCompletionHandler:(void (^)(NSArray *playlist, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to retrieve a playlist.
- completion
  This block is called on the completion of a getPlaylist operation. An array of PCPlaylist objects is returned in this block.
Discussion
Call this method to retrieve a list of playlists.

getPlaylistContent

- (PCAPI *)getPlaylistContent:(PCGetPlaylistContentAPIParams *)params 
        withCompletionHandler:(void (^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to retrieve the content of a playlist.
- completion
  This block is called on the completion of a file retrieve. PCAPIQueryResponse stores the location of the retrieved file.
Discussion
Call this method to retrieve content of a playlist.

getPlaylistDefinition

- (PCAPI *)getPlaylistDefinition:(PCGetPlaylistDefinitionAPIParams *)params 
        withCompletionHandler:(void (^)(PCPlaylist *playlist, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to retrieve a playlist’s definition.
- completion
  This block is called on the completion of a playlist fetch operation. A PCPlaylist object is returned in this block.
Discussion
Call this method to retrieve the definition of a playlist.

getPlaylistItems

- (PCAPI *)getPlaylistItems:(PCGetPlaylistItemsAPIParams *)params 
        withCompletionHandler:(void (^)(NSArray *playlistItems, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to retrieve items from a playlist.
- completion
  This block is called on the completion of a playlist item fetch operation. An array of PCResource objects is returned in this block.
Discussion
Call this method to retrieve information on the items in a playlist.

createShare

- (PCAPI *)createShare:(PCCreateShareAPIParams *)params 
        withCompletionHandler:(void(^)(PCShareItem *shareItem, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to create a share.
- completion
  This block is called on the completion of a create share operation. PCShareItem objects are returned in completion.
Discussion
Call this method to create a share.

deleteShare

- (PCAPI *)deleteShare:(PCDeleteShareAPIParams *)params 
        withCompletionHandler:(void(^)(PCAPIQueryResponse *response))completion;

Parameters
- params Parameters required to delete a specified share.
- completion
  This block is called on the completion of a share delete operation.
Discussion
Call this method to delete a specified share

fetchShare

- (PCAPI *)fetchShare:(PCGetShareAPIParams *)params 
        withCompletionHandler:(void (^)(PCShare *share, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to retrieve a share.
- completion
  This block is called on the completion of the retrieve shares process. PCShare objects are returned in the completion.
Discussion
Call this method retrieve shares.

sharedInstance

+ (PCAPISDK *)sharedInstance;

Discussion
Returns a shared instance of PCAPISDK class.

Trash Can

deleteTrash

- (PCAPI *)deleteTrash:(PCDeleteTrashAPIParams *)params 
        withCompletionHandler:(void (^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to delete trash.
- completion
  This block is called on the completion of a deleteTrash operation.
Discussion
Call this method to delete all files and folders that are in a deleted state in the user’s Personal Cloud Storage account.

fetchTrash

- (PCAPI *)fetchTrash:(PCGetTrashAPIParams *)params 
        withCompletionHandler:(void (^)(PCMetadata *metadata, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to retrieve a list of files and folders that have been deleted from user’s Personal Cloud Storage account.
- completion
  This block is called on the completion of fetchTrash process. A PCMetadata object with metadata details is returned in completion block.
Discussion
Call this method to retrieve a list of files and folders that have been deleted from user’s Personal Cloud Storage account.

###restore

- (PCAPI *)restore:(PCRestoreAPIParams *)params 
        withCompletionHandler:(void (^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to perform restore operation.
- completion
  This block is called on the completion of a restore operation.
Discussion
Call this method to restore files or folders that are marked as deleted. When called on a folder, the API creates a new version of the folder and any child folder, and restores all files in these folders.

Virtual Folder

createVirtualFolder

- (PCAPI *)createVirtualFolder:(PCCreateVFolderAPIParams *)params 
        withCompletionHandler:(void (^)(PCResource *metadata, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to create a virtual folder.
- completion
  This block is called on the completion of a virtual folder creation process. The metadata of a new virtual folder is returned in completion block
Discussion
Call this method to create a virtual folder.

deleteVirtualFolder

- (PCAPI *)deleteVirtualFolder:(PCDeleteVFolderAPIParams *)params 
        withCompletionHandler:(void (^)(PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to delete a virtual folder.
- completion
  This block is called on the completion of a delete virtual folder operation.
Discussion
Call this method to delete a virtual folder.

renameVirtualFolder

- (PCAPI *)renameVirtualFolder:(PCRenameVFolderAPIParams *)params 
        withCompletionHandler:(void (^)(PCResource *metadata, PCAPIQueryResponse *response))completion;

Parameters
- params
  Parameters required to rename a virtual folder.
- completion
  This block is called on the completion of a rename virtual folder operation. The metadata of the renamed virtual folder is returned in completion block.
Discussion
Call this method to rename a virtual folder.

handleCompletionHandler:forSession:

- (void)handleCompletionHandler:(void (^)())completionHandler 
        forSession:(NSString *)sessionIdentifier;

Parameters
- sessionIdentifier
  The identifier of the URL session, received in application:handleEventsForBackgroundURLSession:completionHandler method.
- completionHandler
  completionHanlder received in application:handleEventsForBackgroundURLSession:completionHandler method.
Discussion
This method is used when your application is enabled to do a background fetch. Implement application:handleEventsForBackgroundURLSession:completionHandler delegate method in your application delegate class and pass completion handler received on to the handleSessionCompletionHandler: method.