Version 1.1 - Updated on 6/16/2016
public class CloudAPI
Gateway to access Personal Cloud Storage APIs.
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.
appID
— Application ID provisioned by ThingSpace portalappSecret
— Application Secret provisioned by ThingSpace portalcallbackUrl
— Callback Url provisioned to ThingSpace portal to return authorization code.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.
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()).public void refreshToken(Context context)
Refreshes the access token when expired.
context
— Contextobjectpublic void logout(Context context)
Logs out the user by clearing the token and cache.
context
— Context objectpublic 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.
public String getAccessToken(Context context)
Retrieves the access token to call Personal Cloud Storage APIs.
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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectpublic 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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectpublic 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_UNAUTHAURIZED if user is not authorized to perform this operation.
context
— Context objectsrc
— Path where the folder or a file is to be copied fromtarget
— Path where the folder or a file is to be copied tosafe
— 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:NOTE:
You cannot perform the copy
operation on a virutal folder.
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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectpath
— Path where the folder is to be createdfolderName
— Name of the folder to be createdoverride
— Specifies what happens when a folder of the same name already exists at the specified path:NOTE:
You cannot perform the createFolder
operation on a virutal folder.
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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectpath
— 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.Throws Cloud API Exception if the request cannot be processed.
NOTE:
You cannot perform the delete
operation on a virutal folder.
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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectparentPath
— Path of the directory where the file is storedname
— File namedownloadPath
— Intended destination directory pathpublic 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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectpath
— Path of a folder or file stored in user’s Personal Cloud Storage accountpublic 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_UNAUTHAURIZED if the user is not authorized to perform this operation.
Examples: - SortType.NAME
- SortType.NAME.setOrder(SortType.SortOrder.ASC)
. Pass null for default order.
context
— Context objectpath
— 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).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.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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectcontentToken
— Content-Token of file of which the thumbnail has to be downloadedoutputStream
— Output stream where thumbnail is to be storedpublic 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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectcontentToken
— 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.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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectcontentToken
— 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)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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectpublic 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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectsrc
— Path where the folder or file is to be moved fromtarget
— Path where the folder or file is to be moved tosafe
— 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.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.
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_UNAUTHAURIZED if theuser is not authorized to perform this operation.
context
— Context objectsrc
— 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.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.
context
— Context objectqueryType
— CloudAPI.QueryType - type of the search query. It could be either SQL
or LUCENE
.query
— Search query to be executed:queryType
is QueryType.SQL, query must follow SQL query standards.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.NOTE:
You cannot perform the file upload operation on a virutal folder.
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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectuploadPath
— Path of the directory where the file is intended to be stored on the cloudfileName
— File namefilePath
— Path of the directory where the file is stored on the devicepublic 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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectplaylistUid
— Playlist unique identifier - can be obtained with Playlist.getUid().paths
— Array list of file paths to be added to the playlist.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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectname
— 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
.public boolean deletePlaylist(Context context, String playlistUid)
Delete 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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectplaylistUid
— playlist unique identifier - can be obtained with Playlist.getUid().public boolean deletePlaylistItem(Context context, String playlistUid, String itemUid)
Delete an existing playlist item. This method makes an HTTP call and should not be called from the main thread.
Throws Cloud API Exception with the error code USER_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectplaylistUid
— playlist unique identifier - can be obtained with Playlist.getUid().itemUid
— playlist item unique identifier - can be obtained at PlaylistItem.getItemuid().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.
**EXAMPLES: **
SortType.NAME.setOrder(SortType.SortOrder.ASC). Pass null for default order.
Parameters:
context
— Context objectplaylistUid
— 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).SortType.NAME
SortType.NAME.setOrder(SortType.SortOrder.ASC)
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: Returns ItemList populated with the PlaylistItem as a list item. Call ItemList when the list is no longer needed. Throws Cloud API Exception if the request cannot be processed.
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_UNAUTHAURIZED if the user is not authorized to perform this operation.
EXAMPLES:
SortType.NAME
SortType.NAME.setOrder(SortType.SortOrder.ASC)
. Pass null for default order.
Parameters:
context
— Context objectplaylistType
— Set to null to get all the playlists.sortType
— Sort type as defined in SortType
. Can be combined with with SortType.setOrder(SortType.SortOrder).SortType.NAME
SortType.NAME.setOrder(SortType.SortOrder.ASC)
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: 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.
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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectuid
— playlist unique identifier - can be obtained with Playlist.getUid().name
— Intended name of the playlist.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_UNAUTHAURIZED if the user is not authorized to perform this operation.
context
— Context objectplaylistUid
— 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.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_UNAUTHAURIZED
if the user is not authorized to perform this operation.
context
— Context objectsortType
— Sort type as defined in SortType
. Can be combined with with SortType.setOrder(SortType.SortOrder).SortType.NAME
SortType.NAME.setOrder(SortType.SortOrder.ASC)
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
.Throws Cloud API Exception if the request cannot be processed.
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_UNAUTHAURIZED
if the user is not authorized to perform this operation.
context
— Context objectpublic 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_UNAUTHAURIZED
if the user is not authorized to perform this operation.
context
— Context objectpaths
— Array list of file and folder paths to be restored. Path for a file and folder can be obtained as: MetadataItem.getParentPath() + “/” MetadataItem.getName()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.
Query type following SQL query syntax:
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.