CloudAPI

CloudAPI

Version 1.10 - Updated on 05/04/2017

Contents

Introduction

public class CloudAPI

Gateway to access Personal Cloud Storage APIs.

CloudAPI

public CloudAPI(String appID, String appSecret, String callbackUrl)

Initializes a Personal Cloud Storage api object to authenticate the user and authorize the application to access user account with Personal Cloud Storage APIs.

  • Parameters:
    • appID — Application ID provisioned by ThingSpace portal
    • appSecret — Application Secret provisioned by ThingSpace portal
    • callbackUrl — Callback Url provisioned to ThingSpace portal to return authorization code.

Authentication and Authorization

authorize

public void authorize(Context context)

Authenticates the user and authorizes the application to access user’s content through Personal Cloud Storage APIs.

ThingSpace authorization activity. This will typically be an Activity and the user will be taken back to that activity after authentication is complete.

  • Parameters:
    • context — the Context - to launch the ThingSpace authorization activity. This will typically be an Activity and the user will be taken back to that activity after authentication is complete (for example, your activity will receive an onResume()).

getAccessToken

public String getAccessToken(Context context)

Retrieve the access token to use Cloud APIs.

  • Returns:
    • Access token to be used to call Cloud APIs

getRefreshToken

public String getRefreshToken(Context context)

Retrieves the refresh token. Note that renewing access token outside the SDK does not renew the access token stored within the SDK.

  • Returns: Refresh token to renew the access token

hasAuthorization

public boolean hasAuthorization(Context context)

Verifies if the user is authorized and access token is present. User must be authenticated prior to calling this method in order to have access token.

  • Returns:
    • true - if the user is authenticated and application is authorized.
    • false - if the user is not authenticated and application is not authorized.
    • Call CloudAPI#authorize(Context) to begin authorization.

logout

public void logout(Context context)

Logs out the user by clearing the token and cache.

  • Parameters:
    • context — Context object

Account Information

getAccountInformation

public AccountInformation getAccountInformation(Context context)

Retrieves account information. This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
  • Returns:
    • AccountInformation - data containing available and used storage
    • Throws Cloud API Exception if the request cannot be processed.

Contacts

createContact

public Contact createContact(Context context, Contact.Builder contactBuilder)

Creates a contact. This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • contactBuilder — Contact.Builder with contact values to be created
  • Returns:
    • Contact object with the new contact values if the contact has been successfully created.
    • Throws Cloud API Exception if the request cannot be processed.

deleteContact

public boolean deleteContact(Context context, String contactID)

Deletes a contact. This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • contactID — Unique identifier of the contact. Unique identifier can be obtained from Contact#getId(). Call getContacts() to obtain a list of Contact.
  • Returns:
    • true if the contact has been deleted successfully.
    • Throws Cloud API Exception if the request cannot be processed.

getContacts

public ItemList<Contact> getContacts(Context context)

Retrieves the contacts stored in user’s Personal Cloud Storage account. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
  • Returns:
    • ItemList populated with the Contact as a list item.
    • Call ItemList.close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

getContacts

public ItemList<Contact> getContacts(Context context, int page, int count, SortType sortType)

Retrieves the contacts stored in user’s Personal Cloud Storage account. This method returns a paginated response based on the page and count input. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • page — Page number to return, for paginated responses.
    • count — Maximum items to include in a paginated response. Default is 200.
    • sortType — Sort type as defined in SortType, can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples
        • SortType.FIRST_NAME.setOrder(SortType.SortOrder.ASC)
        • SortType.CREATED.setOrder(SortType.SortOrder.DESC.
      • Supported sort types are:
        • SortType.CREATED
        • SortType.FAVORITE
        • SortType.FIRST_NAME
        • SortType.ID
        • SortType.LAST_NAME
        • SortType.MODIFIED
        • SortType.VERSION
      • Set to null for default order.
  • Returns:
    • ItemList populated with the Contact as a list item.
    • Call ItemList.close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

getContacts

public ItemList<Contact> getContacts(Context context, String query, SortType sortType)

Retrieves all contacts or a subset of contacts stored in user’s Personal Cloud Storage account. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:

    • context — Context object
    • query — Contains the value of a field that is stored in contacts which can be used to search for a specific contact or set of contacts.
      • Supported fields are:
        • ID
        • name
        • email
        • IM
        • address
        • tel
        • field-tag.type, such as address.home
        • address.type.subfield, such as address.home.street
      • Query Examples:
        • name:John
        • tel:201*
        • address.home.street:8 Spruce Street
    • sortType — Sort type as defined in SortType, can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples
        • SortType.FIRST_NAME.setOrder(SortType.SortOrder.ASC)
        • SortType.CREATED.setOrder(SortType.SortOrder.DESC)
      • Supported sort types are:
        • SortType.CREATED
        • SortType.FAVORITE
        • SortType.FIRST_NAME
        • SortType.ID
        • SortType.LAST_NAME
        • SortType.MODIFIED
        • SortType.VERSION
      • Set to null for default order.

  • Returns:

    • ItemList populated with the Contact as a list item.
    • Call ItemList.close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

getContacts

public ItemList<Contact> getContacts(Context context, String query, int page, int count, SortType sortType)

Retrieves all contacts or a subset of contacts stored in user’s Personal Cloud Storage account. This method returns a paginated response based on the page and count input. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • query — Contains the value of a field that is stored in contacts which can be used to search for a specific contact or set of contacts.
      • Supported fields are:
        • ID
        • name
        • email
        • IM
        • address
        • tel
        • field-tag.type, such as address.home
        • address.type.subfield, such as address.home.street
    • page — Page number to return, for paginated responses.
    • count — Maximum items to include in a paginated response. Default is 200.
    • sortType — Sort type as defined in SortType, can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples
        • SortType.FIRST_NAME.setOrder(SortType.SortOrder.ASC)
        • SortType.CREATED.setOrder(SortType.SortOrder.DESC)
      • Supported sort types are:
        • SortType.CREATED
        • SortType.FAVORITE
        • SortType.FIRST_NAME
        • SortType.ID
        • SortType.LAST_NAME
        • SortType.MODIFIED
        • SortType.VERSION
      • Set to null for default order.
  • Returns:
    • ItemList populated with the Contact as a list item.
    • Call ItemList.close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

updateContact

public Contact updateContact(Context context, String contactID, Contact.Builder contactBuilder)

Updates the specified contact. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • contactID — Unique identifier of the contact. Unique identifier can be obtained from Contact#getId(). Call getContacts() to obtain a list of Contact.
    • contactBuilder — Contact.Builder with contact values to be updated.
  • Returns:
    • Contact object with the updated contact values if the contact has been updated successfully.
    • Throws Cloud API Exception if the request cannot be processed.

Favorites

deleteFavorite

public boolean deleteFavorite (Context context, String uri)

Removes a file or folder from favorites. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • uri — URI of the file or folder to be deleted from favorites. You can retrieve the URI as:
      • Photo#getUri()
      • Video#getUri()
      • Audio#getUri()
      • File#getUri() *Folder#getUri()
  • Returns:
    • true - if the file or folder has been removed from favorites
    • false - if the request cannot be processed.
    • Throws Cloud API Exception if the request cannot be processed.

getFavorites

public ItemList<ResourceItem> getFavorites(Context context, ResourceType resourceType)

Retrieves a list of all favorite files and folders stored in a user’s Personal Cloud Storage account. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • resourceType — Resource type as defined in ResourceType.

  • Returns:

    • ItemList populated with ResourceItem as list a item. The list item can be type casted to:

      • Photo - when requesting photos
      • Video - when requesting videos
      • Audio - when requesting audios
      • File - when requesting documents

    • Call ItemList.close() when the list is no longer needed.

    • Throws Cloud API Exception if the request cannot be processed.

setFavorites

public boolean setFavorites (Context context, ArrayList<String> uris)

Marks files or folders as favorite. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • uris — An ArrayList of URIs of the files and folders to be set as favorites. You can retrieve the URIs as:
      • Photo#getUri()
      • Video#getUri()
      • Audio#getUri()
      • File#getUri()
      • Folder#getUri()
  • Returns:
    • true - if the files or folders were set as favorites.
    • false - if the request cannot be processed.
    • Throws Cloud API Exception if the request cannot be processed.

File and Folder Operations

copy

public ItemList<MetadataItem> copy(Context context, String src, String target, Boolean safe, String conflictsolve, String override)

Copies a folder or a file in path specified in cloud. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • src — Path where the folder or a file is to be copied from
    • target — Path where the folder or a file is to be copied to
    • safe — If set to true, ensures that name conflicts are resolved according to the value of the conflictsolve parameter. Defaults to false, in which case the operation overwrites an existing file or folder of the same name. Set to null for default.
    • conflictsolve — Defines how name conflicts are resolved if the safe parameter is set to true. If set to copy, a new file is written to the destination folder with a non-conflicting name. If not set, the operation is rolled back and returns 409 Conflict error message.
    • override — Specifies what happens when a folder of the same name already exists at the specified path:
      • overwrite - overwrites the existing folder.
      • modify - treats the new folder as a modification of the existing folder.
      If the override parameter is not set, the following algorithm is applied:
      • If the existing folder’s deleted attribute is set to true, the folder is overwritten.
      • If the existing folder’s deleted attribute is set to false or not set, the existing folder is modified.
    • Returns:
      • ItemList - list of files & folders from the target path, populated with the MetadataItem as a list item.
      • Call ItemList.close() when the list is no longer needed.
      • Throws Cloud API Exception if the request cannot be processed.

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

createFolder

public MetadataItem createFolder(Context context, String path, String folderName, String override)

Creates a folder in the path specified in cloud. Makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • path — Path where the folder is to be created
    • folderName — Name of the folder to be created
    • override — Specifies what happens when a folder of the same name already exists at the specified path:
      • overwrite - overwrites the existing folder.
      • modify - treats the new folder as a modification of the existing folder.
      If the override parameter is not set, the following algorithm is applied:
      • If the existing folder’s deleted attribute is set to true, the folder is overwritten.
      • If the existing folder’s deleted attribute is set to false or not set, the existing folder is modified.
  • Returns:

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

delete

public boolean delete(Context context, String path, Boolean purge)

Deletes a folder or a file in the path specified. Method makes an HTTP call and should not be called from the main thread.

ThrowsCloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • path — Path of the folderor or file to be deleted.
    • purge — If set to true, deletes the file or folder. If not set, the default is false.
  • Returns:
    • true if delete was successful.
    • false if delete was not successful.
    • Throws Cloud API Exception if the request cannot be processed.

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

downloadFile

public boolean downloadFile(Context context, String parentPath, String name, String downloadPath) throws CloudAPIException

Downloads a file from user’s Personal Cloud Storage account. File is downloaded at the downloadPath location. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • parentPath — Path of the directory where the file is stored
    • name — File name
    • downloadPath — Intended destination directory path
  • Returns: true - if download was successful. false - f download was not successful. Throws Cloud API Exception if the request cannot be processed.

downloadFile

public InputStream downloadFile(Context context, String parentPath, String name)

Downloads a file from user’s Personal Cloud Storage account. An input stream with file data is returned if the response is successful.

This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • parentPath — Path of the directory where the file is stored.
    • name — File name.
  • Returns:
    • Input stream if the response is successful, null otherwise.
    • Throws Cloud API Exception if the request cannot be processed.

fullview

public ItemList<FullviewItem> fullview(Context context)

Retrieves information about all files stored under user’s Personal Cloud Storage account. Makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
  • Returns:

getMetadata

public ItemList<MetadataItem> getMetadata(Context context, String path)

Retrieves metadata information for the specified path. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • path — Path of a folder or file stored in user’s Personal Cloud Storage account
  • Returns:

getMetadata

public ItemList<MetadataItem> getMetadata(Context context, String path, SortType sortType, int start, int count, String filter, Boolean includeDeleted)

Retrieves metadata information for the specified path. This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • path — Path of a folder or file stored in user’s Personal Cloud Storage account.
    • sortType — Sort type as defined in SortType, can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples
        • SortType.NAME
        • SortType.NAME.setOrder(SortType.SortOrder.ASC).
        • Set to null for default order.
    • start — For folders, the starting page to return in a paginated response. Defaults to 1.
    • count — Page number for the paginated response. If start is set to 2 and count is 50, items number 51 to 100 will be returned.Set to -1 to retrieve all files andfolders.
    • filter — Set to file or folder to include only those types of items in the response.
    • includeDeleted — If true, response includes the metadata for deleted files and folders. Default is false.
  • Returns:

getThumbnailToStream

public boolean getThumbnailToStream(Context context, String contentToken, OutputStream outputStream)

Downloads a thumbnail to the output stream provided by the user. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • contentToken — Content-Token of file of which the thumbnail has to be downloaded
    • outputStream — Output stream where thumbnail is to be stored
  • Returns:
    • true - if thumbnail download to the stream was successful.
    • false - if thumbnail download to the stream was not successful.
    • Throws Cloud API Exception if the request cannot be processed.

getThumbnailToStream

public boolean getThumbnailToStream(Context context, String contentToken, OutputStream outputStream, int height, int width)

Downloads a resized thumbnail to the output stream. Thumbnail is resized to the height and width provided in the argument. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • contentToken — File Content Token as retrieved from ResourceItem.getContentToken().
    • outputStream — output stream where thumbnail bytes are intended to be written.
    • height — Intended height of resized thumbnail.
    • width — Intended width of resized thumbnail.
  • Returns:
  • true - if thumbnail download to the stream was successful.
  • false - if thumbnail download to the stream was not successful.
  • Throws Cloud API Exception if the request cannot be processed.

getThumbnailToStream

public boolean getThumbnailToStream(Context context, String contentToken, OutputStream outputStream, ThumbnailSize size)

Downloads a thumbnail to the output stream. This method resizes the thumbnail to the ThumbnailSize provided in the argument. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • contentToken — Content token of the file for which the thumbnail is to be downloaded.
    • outputStream — output stream where thumbnail bytes are intended to be written.
    • size — Size of the thumbnail to be downloaded as defined in ThumbnailSize:
      • XS - Extra Small size - (24x24)
      • S - Small size - (64x64)
      • M - Medium size - (128x128)
  • Returns:
    • true - if thumbnail download to the stream was successful.
    • false - if thumbnail download to the stream was not successful.
    • Throws Cloud API Exception if the request cannot be processed.

move

public ItemList<MetadataItem> move(Context context, String src, String target, Boolean safe, String conflictsolve)

Moves a folder or a file in path specified. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • src — Path where the folder or file is to be moved from
    • target — Path where the folder or file is to be moved to
    • safe — If set to *true, ensures that name conflicts are resolved according to the value of the conflictsolve parameter. Defaults to false, in which case the operation overwrites an existing file or folder of the same name. Set to null for default.
    • conflictsolve — Defines how name conflicts are resolved if the safe parameter is set to true. If set to copy, a new file is written to the destination folder with a non-conflicting name. If not set, the operation is rolled back and returns 409 Conflict error message.
  • Returns:
    • ItemList - list of files and folders from the target path, populated with the MetadataItem as a list item.
    • Call ItemList.close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

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

rename

public ItemList<MetadataItem> rename(Context context, String src, String target, Boolean safe, String conflictsolve)

Renames a file or a folder stored under user’s Personal Cloud Storage account. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if theuser is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • src — Full path of the file or folder for copy, move, or rename operations.
    • target — Full path of the target file or folder for copy, move, or rename operations. In case of files, the full or changed name should be included in the target.
    • safe — If set to true, ensures that name conflicts are resolved according to the value of the conflictsolve parameter. Defaults to false, in which case the operation overwrites an existing file or folder of the same name. Set to null for default.
    • conflictsolve — Defines how name conflicts are resolved if the safe parameter is set to true. If set to copy, a new file is written to the destination folder with a non-conflicting name. If not set, the operation is rolled back and returns 409 Conflict error message.
  • Returns:
    • IItemList - list of files and folders from the target path, populated with the MetadataItem as a list item.
    • Call ItemList.close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

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

public void search(Context context, QueryType queryType, String query, String groupBy, String sortBy, int limit, SearchCallback searchCallback)

Searches for files and folders stored in user’s Personal Cloud Storage account.

  • Parameters:
    • context — Context object
    • queryType — CloudAPI.QueryType - type of the search query. It could be either SQL or LUCENE.
    • query — Search query to be executed:
      • If queryType is QueryType.SQL, query must follow SQL query standards.
      • If queryType is QueryType.Lucene, query must be a valid Lucene search query.
    • groupBy — Specifies the filter to group the result list items. Null value causes the list items to not be grouped. Use CloudAPI.Search parameters.
    • sortBy — Specifies the sort criteria for the result list.
    • limit — Limits the number of item in the result list.
    • searchCallback — SearchCallback to receive the search result or an error.

uploadFile

public boolean uploadFile(Context context, String uploadPath, String fileName, String filePath)

Uploads a file to user’s cloud storage account. File is uploaded at the uploadPath location. This method makes an http call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • uploadPath — Path of the directory where the file is intended to be stored on the cloud
    • fileName — File name
    • filePath — Path of the directory where the file is stored on the device
  • Returns:
    • true - if upload was successful.
    • false if upload was not successful.
    • Throws Cloud API Exception if the request cannot be processed.

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

Log

setLogLevel

public void setLogLevel (LogLevel logLevel)

Sets the log level for the SDK. Log level can be one of the following:

  • LogLevel.DEBUG - prints more logs for debugging.

  • LogLevel.ERROR (default) - prints only errors.

    • Parameters:
    • [logLevel]() to set the log level.

Media

getArtists

public ItemList<Artist> getArtists (Context context)

Retrieves a list of music artists stored under user’s Personal Cloud Storage account.

This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters: context — Context object
  • Returns:
    • ItemList populated with Artist as list item.
    • Call ItemList#close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

getAudioPlaylists

public ItemList<Playlist> getAudioPlaylists(Context context, SortType sortType)

Retrieves audio playlists stored under user’s Personal Cloud Storage account.

This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • sortType — Sort type as defined in SortType. Can be combined with with SortType.setOrder(SortType.SortOrder).
      • Supported sort specifications for playlist are:
        • SortType#NAME
        • SortType#CREATION_DATE
        • SortType#VERSION_CREATED
        • SortType#MODIFICATION_DATE
      • Examples:
        • SortType.NAME.setOrder(SortType.SortOrder.ASC)
        • SortType.VERSION_CREATED.setOrder(SortType.SortOrder.DESC)
        • Set to null for default order
  • Returns:

getAudios

public ItemList<Audio> getAudios(Context context, SortType sortType)

Retrieves a list of all audio files stored under user’s Personal Cloud Storage account. This method performs a search with mime-type as %audio%.

This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • sortType — Sort type as defined in SortType. Can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples:
        • SortType.NAME
        • SortType.NAME.setOrder(SortType.SortOrder.ASC)
        • Set to null for default order
  • Returns:
    • ItemList populated with Audio as list item. This list contains the files that has audio mime-type stored under user’s Personal Cloud Storage account.
    • Call ItemList#close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

getDocuments

public ItemList<File> getDocuments (Context context, SortType sortType)

Retrieves a list of all documents stored under user’s Personal Cloud Storage account.

This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • sortType — Sort type as defined in SortType. Can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples:
        • SortType.NAME
        • SortType.NAME.setOrder(SortType.SortOrder.ASC)
        • Set to null for default order.
  • Returns:
    • ItemList populated with File as a list item. This list contains all the documents stored under user’s Personal Cloud Storage account.
    • Call *ItemList#close()}*when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

getGenres

public ItemList<Genre> getGenres (Context context)

Retrieves a list of music genres stored under user’s Personal Cloud Storage account.

This method makes an HTTP call and should not be called from the main thread.Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters: context — Context object
  • Returns:
    • ItemList populated with Genre as a list item.
    • Call ItemList#close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

getMusicAlbums

public ItemList<Album> getMusicAlbums (Context context, SortType sortType)

Retrieves a list of all music albums stored under user’s Personal Cloud storage account.

This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • sortType — Sort type as defined in SortType. Can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples:
        • SortType.NAME
        • SortType.NAME.setOrder(SortType.SortOrder.ASC)
        • Set to null for default order.
  • Returns:
    • ItemList populated with Album as a list item.
    • Call ItemList#close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

getPhotoAlbums

public ItemList<Album> getPhotoAlbums(Context context, SortType sortType)

Retrieves Photo albums stored under user’s Personal Cloud Storage account.

This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • sortType — Sort type as defined in SortType. Can be combined with with SortType.setOrder(SortType.SortOrder).
      • Supported sort specifications for Photo Albums are:
        • SortType#NAME
        • SortType#CREATION_DATE
        • SortType#VERSION_CREATED
        • SortType#MODIFICATION_DATE
      • Examples:
        • SortType.NAME.setOrder(SortType.SortOrder.ASC)
        • SortType.VERSION_CREATED.setOrder(SortType.SortOrder.DESC)
        • Set to null for default order
  • Returns:
    • ItemList populated with the Album as a list item.
    • Call ItemList#close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

getPhotos

public ItemList<Photo> getPhotos(Context context, SortType sortType)

Retrieves a list of all image files stored under user’s Personal Cloud Storage account. This method performs a search with mime-type as %image%.

This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • sortType — Sort type as defined in SortType. Can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples:
        • SortType.NAME
        • SortType.NAME.setOrder(SortType.SortOrder.ASC)
        • Set to null for default order
  • Returns:
    • ItemList populated with Photo as list item. This list contains the files that have image mime-type stored under user’s Personal Cloud Storage account.
    • Call ItemList#close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

getVideos

public ItemList<Video> getVideos(Context context, SortType sortType)

Retrieves a list of all video files stored under user’s Personal Cloud Storage account. This method performs a search with mime-type as %video%.

This method makes an HTTP call and should not be called from the main thread. Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • sortType — Sort type as defined in SortType. Can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples:
        • SortType.NAME
        • SortType.NAME.setOrder(SortType.SortOrder.ASC)
        • Set to null for default order
  • Returns:
    • ItemList populated with Video as list item. This list contains the files that has video mime-type stored under user’s cloud storage account.
    • Call ItemList#close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

Playlists

addToPlaylist

public ArrayList<String> addToPlaylist(Context context, String playlistUid, ArrayList<String> paths)

Add items to an existing playlist. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • playlistUid — Playlist unique identifier - can be obtained with Playlist.getUid().
    • paths — Array list of file paths to be added to the playlist.
  • Returns:
    • Returns list of paths of all files in the playlist.

createPlaylist

public Playlist createPlaylist(Context context, String name, ArrayList<String> paths, PlaylistType playlistType)

Creates a playlist, with or without items. A playlist can contain music, photos and video files. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • name — name of the playlist.
    • paths — array of items to be included in this playlist. Set to null to create an empty playlist.
    • playlistType — type of playlist as defined in PlaylistType.
  • Returns:

deletePlaylist

public boolean deletePlaylist(Context context, String playlistUid)

Deletes an existing playlist. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • playlistUid — playlist unique identifier - can be obtained with Playlist.getUid().
  • Returns:
  • true - if delete was successful.
  • false if delete was not successful.

deletePlaylistItem

public boolean deletePlaylistItem(Context context, String playlistUid, String itemUid)

Deletes an item from a playlist. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • playlistUid — playlist unique identifier - can be obtained with Playlist.getUid().
    • itemUid — playlist item unique identifier - can be obtained at PlaylistItem.getItemuid().
  • Returns:
    • true - if delete was successful.
    • false if delete was not successful.

getPlaylistItems

public ItemList<PlaylistItem> getPlaylistItems(Context context, String playlistUid, SortType sortType, int start, int count)

Retrieves the details of all items contained in a playlist. A playlist can contain music files, photos and video albums.

  • Parameters:
    • context — Context object
    • playlistUid — Unique ID assigned to the playlist. Accessible by Playlist.getUid().
    • sortType — Sort type as defined in SortType. Can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples:
        • SortType.NAME
        • SortType.NAME.setOrder(SortType.SortOrder.ASC)
        • Set to null for default order
    • start — Page number for the paginated response. If start is set to 2 and count is 50, items number 51 to 100 are returned. Set to -1 to get all playlist items.
    • count — Maximum items to include in a paginated response. Default is 20. Set to -1 to get all the playlist items.
  • Returns:

getPlaylists

public ItemList<Playlist> getPlaylists(Context context, PlaylistType playlistType, SortType sortType, int start, int count)

Retrieves all playlists stored under user’s Personal Cloud Storage account. Makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:

    • context — Context object
    • playlistType — Set to null to get all the playlists.

    • sortType — Sort type as defined in SortType. Can be combined with with SortType.setOrder(SortType.SortOrder).

      • Supported sort specifications for playlist are:

        • SortType#NAME
        • SortType#CREATION_DATE
        • SortType#VERSION_CREATED
        • SortType#MODIFICATION_DATE

      • Examples:

        • SortType.NAME
        • SortType.NAME.setOrder(SortType.SortOrder.ASC)
        • Set to null for default order

    • start — Page number for the paginated response. If start is set to 2 and count is 50, playlist number 51 to 100 is returned.Set to -1 to get all playlists.

    • count — Maximum items to include in a paginated response. Default is 20. Set to -1 to get all the playlists.

  • Returns:

    • ItemList populated with the Playlist as a list item.
    • Call ItemList.close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

updatePlaylist

public Playlist updatePlaylist(Context context, String uid, String name)

Updates a playlist’s name. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • uid — playlist unique identifier - can be obtained with Playlist.getUid().
    • name — Intended name of the playlist.
  • Returns:
    • Returns playlist object populated with the new playlist information.
    • Throws Cloud API Exception if the request cannot be processed.

updatePlaylistDefinition

public Playlist updatePlaylistDefinition(Context context, String playlistUid, String name, PlaylistType playlistType, ArrayList<String> paths)

Updates current playlist definition with a new playlist definition. This method erases existing files from the playlist replacing them with new files that are provided in the argument. A playlist can contain music, photos and video files.

This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • playlistUid — playlist unique identifier - can be obtained at Playlist.getUid().
    • name — Intended name of the playlist.
    • playlistType — Type of the playlist as defined in PlaylistType.
    • paths — Array list of file paths to be included in the new definition for this playlist. Setting to null results in an empty playlist.
  • Returns:
    • Returns playlist object populated with new playlist information.
    • Throws Cloud API Exception if the request cannot be processed.

Shares

createShare

public Share createShare (Context context, String name, int expiresIn, ArrayList<ShareResource> shareResources)

Creates a share with files, folders and playlists. To retrieve resources to add to the share, you can use the following methods:

  • CloudAPI#fullview(Context)
  • CloudAPI#getPhotos(Context, SortType)
  • CloudAPI#getAudios(Context, SortType)
  • CloudAPI#getVideos(Context, SortType)
  • CloudAPI#getDocuments(Context, SortType)
  • CloudAPI#getMetadata(Context, String)
  • CloudAPI#getMetadata(Context, String, SortType, int, int, String, Boolean)
  • CloudAPI#getPlaylists(Context, PlaylistType, SortType, int, int)
  • CloudAPI#getPhotoAlbums(Context, SortType)
  • CloudAPI#getAudioPlaylists(Context, SortType)}

This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • name — The intended name of the share to be created.
    • expiresIn — The intended life-time of the share in seconds. The value 0 signifies the share that never expires. Minimum value is 300.
    • shareResources — The array list of ShareResource - the resources to be added to the share.
  • Returns:
    • Share - populated with newly created share information if the share has been created successfully.
    • Throws Cloud API Exception if the request cannot be processed.

deleteShare

public boolean deleteShare(Context context, String shareUid)

Deletes a share stored in a user’s Personal Cloud Storage account. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • shareUid — Unique ID that identifies a share. Can be obtained via a call to Share#getUid().
  • Returns:
    • true if the share is deleted.
    • false if the share is not deleted.
    • Throws Cloud API Exception if the request cannot be processed.

getShares

public ItemList<Share> getShares(Context context, String since, String until)

Retrieves a list of shares stored in the user’s Personal Cloud Storage account. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • since — The date and time, expressed in the W3C date and time format, after which the messages are to be returned. Pass null to retrieve all.
    • until — The date and time, expressed in the W3C date and time format, until which messages are to be returned. Pass null to retrieve all.
  • Returns:
    • ItemList populated with Share as list item. Call ItemList#close() when the list is no longer needed.
    • Throws Cloud API Exception if the request cannot be processed.

Tags

deleteTags

public boolean deleteTags (Context context, String uri)

Removes tags for the file or folder at the specified path. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • uri — The URI to the file or folder for which tags are to be removed. URI can be retrieved using Photo#getUri(), Video#getUri(), Audio#getUri(), File#getUri(), FullviewItem#getUri(),
    • MetadataItem#getUri()*.
  • Returns:
    • true if tags were removed for this file or folder.
    • false if tags were not removed for this file or folder.
    • Throws Cloud API Exception if the request cannot be processed.

getTags

public String getTags (Context context, String path)

Retrieves tags for the file or folder under the specified path. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • path — The path to the file or folder for which tags are to be retrieved. Path can be created by combining parentPath and “/” and fileName. Parent path and file names can be found in classes Photo, Video, Audio, File, FullviewItem, MetadataItem.
  • Returns:
    • Tags stored in cloud for this file or folder.
    • Throws Cloud API Exception if the request cannot be processed.

setTags

public String setTags (Context context, String uri, String tags)

Updates tags for the file or folder at the specified path. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • uri — The URI to the file or folder for which tags are to be updated. URI can be retrieved using Photo, Video, Audio, File, FullviewItem, MetadataItem.
    • tags — Tags to be updated for the specified file or folder.
  • Returns:
    • Tags for the specified file or folder.
    • Throws Cloud API Exception if the request cannot be processed.

Trash

getTrash

public ItemList<MetadataItem> getTrash(Context context, SortType sortType, int start, int count, String filter, Boolean deep)

Retrieves a list of files and folders that have been deleted from a user’s Personal Cloud Storage account. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • sortType — Sort type as defined in SortType. Can be combined with with SortType.setOrder(SortType.SortOrder).
      • Examples:
        • SortType.NAME
        • SortType.NAME.setOrder(SortType.SortOrder.ASC)
        • Set to null for default order.
    • start — Page number for the paginated response. If start is set to 2 and count is 50, items number 51 to 100 are returned. Set to -1 to get all the files and folders.
    • count — Maximum items to include in a paginated response. Default is 20. Set to -1 to retrieve all files and folders.
    • filter — Set to file to retrieve only files. Set to folder to retrieve only folders. Set to null to retrieve both.
    • deep — If set to true, response includes the trash data of sub-folders. Default is false.
  • Returns:
    • Returns Item List populated with the MetadataItem as a list item.
    • Call ItemList.close() when the list is no longer needed.

Throws Cloud API Exception if the request cannot be processed.

purgeTrash

public boolean purgeTrash(Context context)

Purges all the files and folder that are in a deleted state in user’s Personal Cloud Storage account. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters: context — Context object
  • Returns:
    • true - if purge was successful.
    • false - if purge was not successful.
    • Throws Cloud API Exception if the request cannot be processed.

restoreTrash

public boolean restoreTrash(Context context, ArrayList<String> paths)

Restores files and folders from trash to their original location. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • paths — Array list of file and folder paths to be restored. Path for a file and folder can be obtained as: MetadataItem.getParentPath() + “/” MetadataItem.getName()
  • Returns:
    • true - if restore is successful.
    • false - if restore is not successful.
    • Throws Cloud API Exception if the request cannot be processed.

Virtual Folder

createVirtualFolder

public VirtualFolder createVirtualFolder (Context context, String name)

Creates a virtual folder in user’s cloud storage account. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • name — Name of the virtual folder to be created
  • Returns:
    • [VirtualFolder]() object with the newly created virtual folder information.
    • Throws Cloud API Exception if the request cannot be processed.

deleteVirtualFolder

public boolean deleteVirtualFolder (Context context, String name, Boolean force)

Deletes a virtual folder. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • name — Name of the virtual folder to be deleted
    • force — If set to:
      • false(default) - the virtual folder is not deleted if it contains any files or folders or references to deleted files or folders.
      • true - the virtual folder is deleted only if it contains references to deleted files or folders.
  • Returns:
  • true - if the virtual folder is deleted.
  • false- if the virtual folder cannot be deleted.
  • Throws Cloud API Exception if the request cannot be processed.

renameVirtualFolder

public VirtualFolder renameVirtualFolder (Context context, String src, String target)

Renames a virtual folder. This method makes an HTTP call and should not be called from the main thread.

Throws Cloud API Exception with the error code USER_UNAUTHORIZED if the user is not authorized to perform this operation.

  • Parameters:
    • context — Context object
    • src — Name of the virtual folder to be renamed
    • target — New name for the virtual folder
  • Returns:
    • [VirtualFolder]() object with the newly created virtual folder information.
    • Throws Cloud API Exception if the request cannot be processed.

Search

class Search

public static final class Search

Search parameter names.

  • NAME

    The name of the file

  • PARENT_PATH

    The path of the parent folder in the user’s Personal Cloud Storage account

  • SIZE

    The size of the file, in bytes

  • MIME_TYPE

    Mime type

  • CREATED_DATE

    Creation Date in yyyy-MM-dd

  • CAPTURED_DATE

    Captured Date in yyyy-MM-dd

  • WIDTH

    Width

  • HEIGHT

    Height

  • ALBUM

    Maps to the ID3 album field for MP3 files.

  • ARTIST

    Maps to the ID3 artist field for MP3 files.

  • GENRE

    Maps to the ID3 genre field for MP3 files.

  • ALBUM_ARTIST

    Maps to the Band/Orchestra/Accompaniment (TPE2) ID3 field.

  • COMPILATION

    Compilation (TCP) ID3 tag

  • CREATION_DATE

    The date, in UTC format, that the file has been created on the client system.

  • DURATION

    The duration of an audio file

  • FAVORITE

    Favorite

  • GEO_LATITUDE

    EXIF GPS Latitude tag for image files

  • GEO_LONGITUDE

    EXIF GPS Longitude tag for image files

  • LOCATION_STREET

    Street address

  • LOCATION_LOCALITY

    City, town, village or general locality

  • LOCATION_COUNTY

    County

  • LOCATION_COUNTRY

    Country

  • LOCATION_REGION

    State, province or general region

  • LOCATION_POSTAL_CODE

    Postcode or zip code

  • LOCATION_COUNTRY_CODE

    Country code

  • MODIFICATION_DATE

    The date, in UTC format, that the file has been last modified on the client device.

  • ORIENTATION

    Populated for new content uploaded to ensure content is displayed with correct orientation. Supports images with Exif-Orientation flag present numeric values set to 2, 3, 4, 5, 6, 7, 8. Also supports videos in MP4 (ISO/Quicktime) format with Matrix rotating video stream by 90, 180 or 270 degrees, which would produce 8, 3 and 6 as numeric Orientation system attribute values.

  • PRIORITY

    A client-provided value, used to sort files or folders in order of importance, or as criteria to return only high-priority items

  • SOURCE

    The origin of the file such as MMS or web client

  • TAGS

    Any tag metadata that a client includes when uploading a file

  • TIMELINE_DATE

    Specifies where the media file is to appear in a timeline view on a client application.

  • TRACK

    Maps to the ID3 track number field for MP3 files.

  • YEAR

    Maps to the ID3 year field for MP3 files.

  • QueryType

    Search query type.

SQL

Query type following SQL query syntax:

  • CloudAPI.Search.NAME like ‘%jpg%’
  • CloudAPI.Search.MIME_TYPE like ‘%image%’ AND (CloudAPI.Search.CAPTURED_DATE >= ‘2015-05-01’ AND CloudAPI.Search#CAPTURED_DATE <= ‘2016-02-01’)

LUCENE

Query type following Lucene query syntax:

  • CloudAPI.Search.NAME:"*jpg*"
  • CloudAPI.Search.MIME_TYPE like "*image*" AND CloudAPI.Search.CAPTURED_DATE:[2015-05-01 to 2016-02-01]

Copyright © 2015-2017, Verizon and/or its Licensors. All rights reserved.