NOTE The 1.0 API is deprecated and scheduled to be terminated as of 6/30/17. Support for this library should be assumed to be terminated as of that date. It is included with LC9-dp7. If you are using LC8, I have the library in a repo here.
phxDropboxLib v1.13
Converted to a script-only-stack and dumped the binary pieces.
Removed the version history goodness from the script
NOTE: The rest of this file is just a pandoc-converted version of the phxDropboxLib.rtf file. Sorry if the formatting is crude. The original is much better-looking.
phxDropboxLib v1.12
Introduction:
The phxDropboxLib is a Livecode library to access Dropbox using the REST API. Is totally written in Livecode using only the HTTP GET, the HTTP PUT and
the HTTP POST and should run on ANY Livecode platform.
Currently, all the functions are blocking. The current release of Livecode doesn't have non-blocking functions for the HTTP PUT and HTTP POST functions, which are the tasks that require more time (all other HTTP GET function return very quickly).
I have NOT implemented all the Dropbox REST API's (and not all possible parameters for the ones I have implemented), but, I hope, the most useful ones are included.
Future releases will implement more functions.
Copyright:
(c) 2001-2016 Phoenix Sistemi & Automazione s.a.g.l. - Muralto (TI)- Switzerland - All Rights Reserved Worldwide.
You can use this library under the terms of the MIT License.
Support eMail : guglielmo.braguglia@phoenixsea.ch
If you like this library and you want to support the development, you can make a free little donation by PayPal
to this e-Mail : guglielmo.braguglia@citynet.ch
Thank you in advance.
Revision History:
1.02 : first public release
1.03 : added pLimit and pList to function phx_DropboxGetFileInfo
: added pLimit to function phx_DropboxGetFileList
: added new function phx_DropboxMoveFile pRoot, pFromPath, pToPath
: corrected some Err: messages
: some corrections made by Mike Kerner marked as : #mikey
1.04 : fixed WriteFile code on mobile devices (PUSH) - corrections made by Mike Kerner marked as : #mikey
documentation typo corrections - thanks to Mike Kerner
1.05 : fixed a really obscure issue that could cause a failure on mobile after writing a file
: added some documentation to the code here and there
: corrections made by Mike Kerner marked as : #mikey
1.06 : for mobile, EVERY URL has to be sent through rfcURLEncode, or it will not be handled.
: corrections made by Mike Kerner marked as : #mikey
1.07 : fixed an unecessary URLEncode in phx_DropboxWriteFile
: fixed an unecessary URLEncode in phx_DropboxGetFileList
: added new function phx_DropboxCreateLinkToFile pRoot, pPath, pShortURL
: correction and new function made by Trevor DeVore marked as : #TKD
1.08 : added code to encode spaces in paths where necessary b/c LC handles URL's differently on mobile and desktop
: corrections made by Mike Kerner marked as : #mikey
1.09 : added rfcURLDecode, which converts escaped character sequences (% followed by a hex pair), useful for making a filename human-readable
: added isHex, for checking if a character is hex or not
: changed rfcUrlEncode to not private b/c if we need to be able to encode filenames that include slashes, such as “2/20/15 photos”. If we don’t then
: if we pass a path and a filename with slashes, dropbox will naturally assume that we’re adding extra directories.
: added misc stack handlers (openStack, openCard, preOpenStack, closeCard, closeStack) so developers working in the library won’t get messages from
: their parent stack.
: Changes made by Mike Kerner marked as : #mikey
1.10 : fixed the phx_DropboxAvailable to recognize a differente error message from DropBox and
: to verify the DropBox availabiliy.
1.11 : fixed typo introduced by Mikey when I was fixing the version-out-of-sequence issue that came in with 1.09/1.10 (fix by mikey)
1.12 : dropbox changed the way it handles error responses since 1.09/1.10. Updated phx_dropboxAvailable. #mikey
Function syntax:
function phx_DropboxLibVersion
Call this function to retrieve the library version
Return: the lib version in the format n.nn
function phx_DropboxAvailable
Call this function to verify if the connection with the Dropbox server is available.
Return: a boolean true if the connection is available, false if can't reach the Dropbox server
function phx_DropboxInitLib pAppKey, pAppSec, pTokKey, pTokSec
You must call this function before any other function to initialize the library.
pAppKey : is your Application key assigned by Dropbox
pAppSec : is your Application Secret still assigned by Dropbox
pTokKey : (if the user has already authorized the application) is the Token key returned by the phx_DropboxAuthorized() otherwise leave empty
pTokSec : (if the user has already authorized the application) is the Token secret returned by the phx_DropboxAuthorized() otherwise leave empty
Return: empty if all is ok or an error message beginning with "Err:" if there is an error.
function phx_DropboxReqToken pCallback
If the user has not already authorized the application, you have to call this function to get the https page address where the user can enter his
credentials and authorize the application. If possible you can open a browser window on the returned https address, if not possible, give the
link to the user and ask him to open a browser, enter the link and authorize the application.
Unfortunately, for security reasons, is not possible to enter the user credentials from the application.
pCallback : if not empty, after the user authorize an application, the user is redirected to the application served URL provided by this parameter
Return : the https link if all is ok or an error message beginning with "Err:" if there is an error.
function phx_DropboxAuthorized
Only after the user has authorized the application, you can get the application tokens with this call. You have to save the returned tokens so, on the
following runs, you don't have to authorize the application again (the tokens never expire).
Return: a three row string containing "the token key, a carriage return, the token secret, a carriage return, the user Id" if all is ok or an error
message beginning with "Err:" if there is an error.
function phx_DropboxGetInfo
Call this function if you want to get information about the user account.
Return: a JSON structure with the User account information if all is ok or an error message beginning with "Err:" if there is an error.
For more info on the JSON-returned structure, please see : https://www.dropbox.com/developers/reference/api\#account-info
function phx_DropboxGetFileList pRoot, pPath, pStr, pIncDel, pLimit
Call this function if you want to retrieve the metadata for all files and folders whose filename contains the given search string as a substring.
pRoot : can be only "dropbox" or "sandbox"
pPath : the path to the folder you want to search from (you can leave empty for the root)
pStr : the search string. Must be at least three characters long
pIncDel : boolean, pass true if you want to include the "deleted" otherwise pass false
pLimit : the maximum and default value is 1,000. No more than pLimit search results will be returned.,
Return : a JSON structure with the list of metadata entries for any matching files and folders if all is ok or an error message beginning with "Err:"
if there is an error.
For more info on the JSON returned structure, please see : https://www.dropbox.com/developers/reference/api\#search
function phx_DropboxReadFile pRoot, pPath, pRevision
Call this function to read the content of a file.
pRoot : can be only "dropbox" or "sandbox"
pPath : the path to the file you want to retrieve
pRevision : the revision of the file to retrieve. This defaults to the most recent revision
Return : the specified file's contents at the requested revision if all is ok or an error message beginning with "Err:" if there is an error.
function phx_DropboxGetFileInfo pRoot, pPath, pLimit, pList
Call this function to retrieve file and folder metadata.
pRoot : can be only "dropbox" or "sandbox"
pPath : the path to the file or folder
pLimit : the default is 10,000 (max is 25,000). When listing a folder, the service will not report listings containing more than the specified
amount of files and will instead respond with a 406.
pList : if true or omitted, the folder's metadata will include a contents field with a list of metadata entries for the contents of the folder.
If false, the contents field will be omitted.
Return: a JSON structure with the metadata for the file or folder if all is ok or an error message beginning with "Err:" if there is an error.
For more info on the JSON returned structure, please see : https://www.dropbox.com/developers/reference/api\#metadata
function phx_DropboxGetFileThumb pRoot, pPath, pFormat, pSize
Call this function to get a thumbnail for an image.
pRoot : can be only "dropbox" or "sandbox"
pPath : the path to the image file you want to thumbnail
pFormat: can be only "jpeg" or "png"
pSize : can be only "small", "medium", "large" "s", "m", "l" and "xl"
Return : a thumbnail of the specified image's contents if all is ok or an error message beginning with "Err:" if there is an error. The image returned
may be larger or smaller than the size requested, depending on the size and aspect ratio of the original image.
function phx_DropboxShareFile pRoot, pPath, pShort
Call this function to read the content of a file.
pRoot : can be only "dropbox" or "sandbox"
pPath : the path to the file you want to retrieve
pShort : When true, the url returned will be shortened using the Dropbox url shortener. If false, the url will link directly to the file's preview page
Return : a JSON structure with a Dropbox link to the given path if all is ok, or an error message beginning with "Err:" if there is an error.
For more info on the JSON returned structure, please see : https://www.dropbox.com/developers/reference/api\#shares
function phx_DropboxWriteFile pRoot, pPath, pContentType, pOverWrite, pData
Call this function to write a file.
pRoot : can be only "dropbox" or "sandbox"
pPath : the path to the file you want to write to
pContentType : MIME standard content type (you can use "application/octet-stream" for any type of file)
pOverWrite : boolen value, either true (default) or false, determines what happens when there's already a file at the specified path. If true, the existing file
will be overwritten by the new one. If false, the new file will be automatically renamed (for example, test.txt might be automatically renamed to
test (1).txt). The new name can be obtained from the returned metadata
Return : a JSON structure with the metadata for the uploaded file if all is ok or an error message beginning with "Err:" if there is an error.
For more info on the JSON returned structure, please see : https://www.dropbox.com/developers/reference/api\#files\_put
function phx_DropboxDeleteFile pRoot, pPath
Call this function to delete a file or folder.
pRoot : can be only "dropbox" or "sandbox"
pPath : the path to the file or folder to delete
Return: a JSON structure with the metadata for the deleted file or folder if all is ok or an error message beginning with "Err:" if there is an error.
For more info on the JSON returned structure, please see : https://www.dropbox.com/developers/reference/api\#fileops-delete
function phx_DropboxMoveFile pRoot, pFromPath, pToPath
Call this function to move a file or folder.
pRoot : can be only "dropbox" or "sandbox"
pFromPath : specifies the file or folder to be moved from relative to root
pToPath : specifies the destination path, including the new name for the file or folder, relative to root
Return : a JSON structure with the metadata for the moved file or folder if all is ok or an error message beginning with "Err:" if there is an error.
For more info on the JSON returned structure, please see : https://www.dropbox.com/developers/reference/api\#fileops-move
function phx_DropboxCreateFolder pRoot, pPath
Call this function to create a folder.
pRoot : can be only "dropbox" or "sandbox"
pPath : the path to the folder to create relative to "pRoot"
Return: a JSON structure with metadata the for the created folder if all is ok or an error message beginning with "Err:" if there is an error.
For more info on the JSON returned structure, please see : https://www.dropbox.com/developers/reference/api\#fileops-create-folder
function phx_DropboxCreateLinkToFile pRoot, pPath, pShortURL
Call this function to create a Dropbox link to files or folders users can use to view a preview of the file in a web browser.
pRoot : can be only "dropbox" or "sandbox"
pPath : path to the file or folder you want to link to
pShortURL : when true (default), the url returned will be shortened using the Dropbox url shortener. If false, the url will link
directly to the file's preview page.
Return : a JSON structure with a Dropbox link to the given path. The link can be used publicly and directs to a preview page of the
file. For compatibility reasons, it returns the link's expiration date in Dropbox's usual date format. All links are currently set
to expire far enough in the future so that expiration is effectively not an issue.
For more info on the JSON returned structure, please see : https://www.dropbox.com/developers/core/docs\#shares