mergDropbox

mergDropbox is an iOS external for interacting with a user's Dropbox account. The external enables you to upload
and download files, create folders and manage the files on the user's Dropbox account. mergDropbox includes the Dropbox SDK for iOS by Evenflow, Inc.

Copyright (c) 2010 Dropbox (Evenflow, Inc.), https://getdropbox.com/
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

command mergDropboxSetup pAppKey,pAppSecret,pAccessType

Initialises the Dropbox SDK with your Dropbox app details. Create your app at https://www.dropbox.com/developers/apps.

Parameters:

  • pAppKey - the application key for your Dropbox app
  • pAppSecret - the application secred for your Dropbox app
  • pAccessType - the access type of your Dropbox app which will be one of:
    • app - the root of the path is the app folder
    • dropbox - the root of the path is the Dropbox folder

command mergDropboxLink

Link the user's Dropbox account with your Dropbox app

command mergDropboxUnlink

Unlink the user's account with your Dropbox app

command mergDropboxHandleOpenURL pURL

Called after linking to update the SDK. To enable your iOS app to recieve the urlWakeUp message enter "db-"+your Dropbox app key

Parameters:

  • pURL - the url that dropbox lauches your app with after authentication

Code sample

on urlWakeUp pURL
  mergDropboxHandleOpenURL pURL
end urlWakeUp

function mergDropboxIsLinked

Checks to see if the user's account is linked to your Dropbox app.

Returns boolean

command mergDropboxLoadAccountInfo

Loads the user's account info.

Code sample

on preOpenStack
   if the environment is "mobile" then
      mergDropboxSetup "yourappkey","yourappsecret","app"
      if mergDropboxIsLinked()  then
         -- change ui to allow user to unlink account
         mergDropboxLoadAccountInfo
      else
         -- change ui to allow user to link account
      end if
   end if
end preOpenStack
 
on mergDropboxAccountInfoLoaded pDisplayName,pUserId,pCountry,pReferralURL,pQuota
   put "Hi "&pDisplayName&" you have used "&round((item 1 of pQuota + item 2 of pQuota) / item 3 of pQuota * 100)&"% of your dropbox space." into fld "account"
end mergDropboxAccountInfoLoaded
 
on mergDropboxLoadAccountInfoError pError
   answer "There was an error loading account info: "&cr&pError
end mergDropboxAccountInfoError

command mergDropboxUpload pFileName,pDropboxPath,pLocalPath,[pParentRev]

Upload a file to the user's Dropbox account.

Parameters:

  • pFileName - the name you want the file to have
  • pDropboxPath - the folder you want the file to go in
  • pLocalPath - the full local path of the file
  • pParentRev - (optional with "" default) the parent rev if the file has been downloaded and edited. For new uploads leave as the default empty.

command mergDropboxCancelUpload pDropboxPath

Cancel an upload in progress.

Parameters:

  • pDropboxPath - the path the file would be uploaded to

message mergDropboxUploaded pDropboxPath,pLocalPath,pRev

Sent to the control that called mergDropboxUpload when the file upload is complete.

Parameters:

  • pDropboxPath - the Dropbox path the file was be uploaded to
  • pLocalPath - the full local path of the file being uploaded
  • pRev - the revison of the file (required for re-uploading another copy of the local file)

message mergDropboxUploadProgress pDropboxPath,pLocalPath,pProgress

Sent to the control that called mergDropboxUpload while the file is uploading.

Parameters:

  • pDropboxPath - the Dropbox path the file was be uploaded to
  • pLocalPath - the full local path of the file being uploaded
  • pProgress - the ratio of the file uploaded (0=0% , 1=100%)

message mergDropboxUploadError pError

Sent to the control that called mergDropboxUpload when there is an upload error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   set the visible of the templateImage to false
   mobilePickPhoto "library",320,480
   put the seconds&".png" into tFilename
   export image 1 to file (the documents folder&fld "path"&tFilename) as PNG
   delete image 1
   mergDropboxUpload  tFilename,fld "path",the documents folder&fld "path"&tFilename
end mouseUp
 
on mergDropboxUploadProgress pDropboxPath,pLocalPath,pProgress
   set the itemDel to "/"
   put "Upload progress for "&item -1 of pDropboxPath&": "&round(pProgress*100)&"%" into fld "progress"
end mergDropboxUploadProgress
 
on mergDropboxUploaded pDropboxPath,pLocalPath,pRev
   put "" into fld "progress"
end mergDropboxUploaded
 
on mergDropboxUploadError pError
   answer "There was an error uploading: "&cr&pError
end mergDropboxUploadError

command mergDropboxDownload pDropboxPath,pLocalPath,[pRev]

Download a file.

Parameters:

  • pDropboxPath - the Dropbox path of the file
  • pLocalPath - the full local path to download the file to
  • pRev - (optional with "" default) the revision of the file you want to download with empty downloading the most recent

command mergDropboxCancelDownload pDropboxPath

Cancel an download in progress.

Parameters:

  • pDropboxPath - the Dropbox path of the file

message mergDropboxDownloaded pLocalPath,pContentType,pRev

Sent to the control that called mergDropboxDownload when the file download is complete.

Parameters:

  • pLocalPath - the full local path to save the file to
  • pContentType - the content type of the file
  • pRev - the revison of the file (required for re-uploading another copy of the local file)

message mergDropboxDownloadProgress pLocalPath,pProgress

Sent to the control that called mergDropboxDownload while the file is downloading.

Parameters:

  • pLocalPath - the full local path of the file being downloaded
  • pProgress - the ratio of the file downloaded (0=0% , 1=100%)

message mergDropboxDownloadError pError

Sent to the control that called mergDropboxDownload when there is a download error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   set the visible of the templateImage to false
   mobilePickPhoto "library",320,480
   put the seconds&".png" into tFilename
   export image 1 to file (the documents folder&fld "path"&tFilename) as PNG
   delete image 1
   mergDropboxUpload  tFilename,fld "path",the documents folder&fld "path"&tFilename
end mouseUp
 
on mergDropboxDownloadProgress pLocalPath,pProgress
   set the itemDel to "/"
   put "Download progress for "&item -1 of pLocalPath&": "&round(pProgress*100)&"%" into fld "progress"
end mergDropboxDownloadProgress
 
on mergDropboxDownloaded pLocalPath,pContentType,pRev
   put "" into fld "progress"
   mergDocShowPreview pLocalPath
end mergDropboxDownloaded
 
on mergDropboxDownloadError pError
   answer "There was an error uploading: "&cr&pError
end mergDropboxDownloadError

command mergDropboxLoadMetadata pDropboxPath

Load the metadata for a folder or file. Once loaded you can use the mergDropboxGetMetadataProperty function.

Parameters:

  • pDropboxPath - the Dropbox path of the file or folder

message mergDropboxMetadataLoaded pDropboxPath

Sent to the control that called mergDropboxLoadMetadata when the load is complete.

Parameters:

  • pDropboxPath - the Dropbox path of the file or folder

message mergDropboxLoadMetadataError pError

Sent to the control that called mergDropboxLoadMetadata when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

function mergDropboxGetMetadataProperty pDropboxPath,pProperty,[pMetadataDropboxPath]

Query individual metadata properties of a folder or file.

Parameters:

  • pDropboxPath - the Dropbox path of the file or folder
  • pProperty - the metadata property you would like returned which will be one of:
    • thumbnail exists - true if there is a thumbnail available to load for the path
    • total bytes - a number representing the total bytes of the path
    • last modified date - in long seconds form
    • client modified time - in long seconds form
    • path - the path from the root of your app
    • is folder - true if the metadata is for a folder
    • files - a return delimited list of file paths in the folder
    • folders - a return delimited list of folder paths in the folder
    • hash - the hash of the path
    • human readable size - the size of the path in a human readable form
    • root - the root of the path
    • icon - the icon of the path
    • rev - the revision of the path which should be used if modifying and re-uploading a file
    • is deleted - true if the file is deleted
    • filename - the filename of the path
  • pMetadataDropboxPath - (optional with "" default) the Dropbox path of the file or folder you want the metadata of. This must be a loaded path or a file or folder under a loaded path otherwise a "path not found" error will be thrown.

Returns The property queried.

Code sample

on mouseUp
   mergDropboxLoadMetadata fld "path"
end mouseUp
 
on mergDropboxMetadataLoaded pDropboxPath
   put mergDropboxGetMetadataProperty(pDropboxPath,"folders") into fld "folders"
   put mergDropboxGetMetadataProperty(pDropboxPath,"files") into fld "files"
   repeat for each line tLine in fld "files"
     checkIfLocalFileNeedsUpdate tLine,mergDropboxGetMetadataProperty(pDropboxPath,"rev",tLine)
   end repeat
end mergDropboxMetadataLoaded
 
on mergDropboxLoadMetadataError pError
   answer "There was an error loading metadata: "&cr&pError
end mergDropboxLoadMetadataError

command mergDropboxCreateFolder pDropboxPath

Creates a new folder in the user's Dropbox.

Parameters:

  • pDropboxPath - the Dropbox path of the folder you want created

message mergDropboxFolderCreated pDropboxPath

Sent to the control that called mergDropboxCreateFolder when the load is complete.

Parameters:

  • pDropboxPath - the Dropbox path of the file or folder

message mergDropboxCreateFolderError pError

Sent to the control that called mergDropboxCreateFolder when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   mergDropboxCreateFolder fld "path"
end mouseUp
 
on mergDropboxFolderCreated pDropboxPath
   -- upload some files into it
end mergDropboxFolderCreated
 
on mergDropboxCreateFolderError pError
   answer "There was an error creating the folder: "&cr&pError
end mergDropboxCreateFolderError

command mergDropboxDelete pDropboxPath

Delete a folder or file.

Parameters:

  • pDropboxPath - the Dropbox path you want to delete

message mergDropboxDeleted pDropboxPath

Sent to the control that called mergDropboxDelete when the load is complete.

Parameters:

  • pDropboxPath - the Dropbox path of the file or folder

message mergDropboxDeleteError pError

Sent to the control that called mergDropboxDelete when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   mergDropboxDelete fld "path"
end mouseUp
 
on mergDropboxDeleted pDropboxPath
   put "" into fld "path"
end mergDropboxDeleted
 
on mergDropboxDeleteError pError
   answer "There was an error deleteing the file: "&cr&pError
end mergDropboxDeleteError

command mergDropboxCopy pDropboxFromPath,pDropboxToPath

Copy a file or folder.

Parameters:

  • pDropboxFromPath - the Dropbox path you want to copy from
  • pDropboxToPath - the Dropbox path you want to copy to

message mergDropboxCopied pDropboxFromPath,pDropboxToPath

Sent to the control that called mergDropboxCopy when the load is complete.

Parameters:

  • pDropboxFromPath - the Dropbox path copied from
  • pDropboxToPath - the Dropbox path copied to

message mergDropboxCopyError pError

Sent to the control that called mergDropboxCopy when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   set the itemDel to "."
   mergDropboxCopy fld "path",item 1 to -2 of fld "path"&" copy.jpg"
end mouseUp
 
on mergDropboxCopied pDropboxFromPath,pDropboxToPath
   answer "File copied from "&pDropboxFromPath&" to "&pDropboxToPath
end mergDropboxCopied
 
on mergDropboxCopyError pError
   answer "There was an error copying the file: "&cr&pError
end mergDropboxCopyError

command mergDropboxMove pDropboxFromPath,pDropboxToPath

Parameters:

  • pDropboxFromPath - the full Dropbox path you want to move from
  • pDropboxToPath - the full Dropbox path of the path you want to move to

message mergDropboxMoved pDropboxFromPath,pDropboxToPath

Sent to the control that called mergDropboxMove when the load is complete.

Parameters:

  • pDropboxFromPath - the Dropbox path moved from
  • pDropboxToPath - the Dropbox path moved to

message mergDropboxMoveError pError

Sent to the control that called mergDropboxMove when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   set the itemDel to "."
   mergDropboxMove fld "path",item 1 to -2 of fld "path"&" copy.jpg"
end mouseUp
 
on mergDropboxMoved pDropboxFromPath,pDropboxToPath
   answer "File moved from "&pDropboxFromPath&" to "&pDropboxToPath
end mergDropboxMoved
 
on mergDropboxMoveError pError
   answer "There was an error moving the file: "&cr&pError
end mergDropboxMoveError

command mergDropboxLoadRevisions pDropboxPath,[pLimit]

Loads a list of revisions for a file.

Parameters:

  • pDropboxPath - the full Dropbox path you want to load revisions for
  • pLimit - (optional with 10 default) a maximum limit to the number of revisions returned

message mergDropboxRevisionsLoaded pDropboxPath,pDropboxPath

Sent to the control that called mergDropboxLoadRevisions when the load is complete.

Parameters:

  • pDropboxPath - the Dropbox path of the file
  • pDropboxPath - a list of revisions (one per line) with three items: revison code, last modified date in long seconds format and total bytes.

message mergDropboxLoadRevisionsError pError

Sent to the control that called mergDropboxLoadRevisions when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   mergDropboxLoadRevisions fld "path"
end mouseUp
 
on mergDropboxRevisionsLoaded pDropboxPath,pRevisions
   set the uRevisions of this stack to pRevisons
   repeat for each line tLine in pRevisions
      put item 2 of pRevisions into tDate
      convert tDate to abbrev date and time
      put tDate&cr after tList
    end repeat
    put tList into btn "pick revision"
end mergDropboxRevisionsLoaded
 
on mergDropboxLoadRevisionsError pError
   answer "There was an error loading the file revisions: "&cr&pError
end mergDropboxLoadRevisionsError

command mergDropboxRestore pDropboxPath,pRev

Restores a file to a specified revision.

Parameters:

  • pDropboxPath - the Dropbox path of the file
  • pRev - the revision you want the file restored to

message mergDropboxRestored pDropboxPath

Sent to the control that called mergDropboxRestore when the load is complete.

Parameters:

  • pDropboxPath - the Dropbox path of the file

message mergDropboxRestoreError pError

Sent to the control that called mergDropboxRestore when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   mergDropboxRestore the uFile of this stack,the uRev of this stack
end mouseUp
 
on mergDropboxRestored pDropboxPath
   answer "Whew... I'm glad Dropbox had a backup."
end mergDropboxRestored
 
on mergDropboxRestoreError pError
   answer "There was an error restoring the file: "&cr&pError
end mergDropboxRestoreError

command mergDropboxLoadSharableURL pDropboxPath

Parameters:

  • pDropboxPath - the full Dropbox path you want the sharable url for

message mergDropboxSharableURLLoaded pDropboxPath,pURL

Sent to the control that called mergDropboxLoadSharableURL when the load is complete.

Parameters:

  • pDropboxPath - the Dropbox path of the file
  • pURL - the sharable url for the file

message mergDropboxLoadSharableURLError pError

Sent to the control that called mergDropboxLoadSharableURL when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   mergDropboxLoadSharableURL fld "path"
end mouseUp
 
on mergDropboxSharableURLLoaded pDropboxPath,pURL
   mergTweet "Check this out!",pURL 
end mergDropboxSharableURLLoaded
 
on mergDropboxLoadSharableURLError pError
   answer "There was an error loading the URL: "&cr&pError
end mergDropboxLoadSharableURLError

command mergDropboxLoadStreamableURL pDropboxPath

Parameters:

  • pDropboxPath - the full Dropbox path you want the streamable url for

message mergDropboxStreamableURLLoaded pDropboxPath,pURL

Sent to the control that called mergDropboxLoadStreamableURL when the load is complete.

Parameters:

  • pDropboxPath - the Dropbox path of the file or folder
  • pURL - the streamable url for the file

message mergDropboxLoadStreamableURLError pError

Sent to the control that called mergDropboxLoadStreamableURL when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   mergDropboxLoadStreamableURL fld "path"
end mouseUp
 
on mergDropboxStreamableURLLoaded pDropboxPath,pURL
   play video pURL
end mergDropboxStreamableURLLoaded
 
on mergDropboxLoadStreamableURLError pError
   answer "There was an error loading the URL: "&cr&pError
end mergDropboxLoadStreamableURLError

command mergDropboxLoadSearch pDropboxPath,pKeyword

Parameters:

  • pDropboxPath - the full Dropbox path you want to search
  • pKeyword - the keyword to search for

message mergDropboxSearchLoaded pDropboxPath,pDropboxPathsFound

Sent to the control that called mergDropboxLoadSearch when the load is complete.

Parameters:

  • pDropboxPath - the Dropbox path searched
  • pDropboxPathsFound - the Dropbox paths of files foind for the keyword

message mergDropboxLoadSearchError pError

Sent to the control that called mergDropboxLoadSearch when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   mergDropboxLoadSearch fld "path",fld "search"
end mouseUp
 
on mergDropboxSearchLoaded pDropboxPath,pDropboxPathsFound
   put pDropboxPathsFound fld "files"
end mergDropboxSearchLoaded
 
on mergDropboxLoadSearchError pError
   answer "There was an error loading search: "&cr&pError
end mergDropboxLoadSearchError

command mergDropboxLoadThumbnail pDropboxPath,pLocalPath,[pSize]

Downloads a thumbnail image of the specified size

Parameters:

  • pDropboxPath - the full Dropbox path of the file
  • pLocalPath - the full local path to Dropbox the thumbnail to
  • pSize - (optional with "xs" default) the thumbnail size which will be one of:
    • xs - 32x32
    • s - 64x64
    • m - 128x128
    • l - 640x480
    • xl - 1024x768

command mergDropboxCancelThumbnailLoad pDropboxPath,pSize

Parameters:

  • pDropboxPath - the full Dropbox path of the file
  • pSize - the thumbnail size which will be one of:
    • xs - 32x32
    • s - 64x64
    • m - 128x128
    • l - 640x480
    • xl - 1024x768

message mergDropboxThumbnailLoaded pDropboxPath,pLocalPath

Sent to the control that called mergDropboxLoadThumbnail when the load is complete.

Parameters:

  • pDropboxPath - the Dropbox path of the file
  • pLocalPath - the local path where the file has been saved

message mergDropboxThumbnailLoadError pError

Sent to the control that called mergDropboxLoadThumbnail when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   mergDropboxLoadThumbnail fld "path","m"
end mouseUp
 
on mergDropboxThumbnailLoaded pDropboxPath,pLocalPath
   put url ("binfile:"&pLocalPath) into image "thumb"
end mergDropboxThumbnailaLoaded
 
on mergDropboxLoadThumbnailError pError
   answer "There was an error loading the thumbnail image : "&cr&pError
end mergDropboxLoadThumbnailError

command mergDropboxLoadDelta pCursor

Loads a list of changed files since the cursor was generated.

Parameters:

  • pCursor - the cursor returned by the last load of a delta. Empty the first time.

message mergDropboxDeltaLoaded pFiles,pCursor,pShouldRest,pHasMore

Sent to the control that called mergDropboxLoadDelta when the load is complete.

Parameters:

  • pFiles - a list of modified or new files
  • pCursor - the cursor required for next time the delta requested
  • pShouldRest - true if the local cache or files should be reset which is rare and mainly cause by a user deleting the folder
  • pHasMore - true if the number of changes were to high to return all of them in one request so you need to repeat the call to get the rest using the original cursor within 5 minutes to get the next batch

message mergDropboxLoadDeltaError pError

Sent to the control that called mergDropboxLoadDelta when there is an error.

Parameters:

  • pError - the error the from the Dropbox SDK

Code sample

on mouseUp
   put "" into fld "files"
   if there is a file (the documents folder&"/deltaCursor.dat") then
      put url ("binfile:"&the documents folder&"/deltaCursor.dat") into tCursor
   else
      put "" into tCursor
   end if
   mergDropboxLoadDelta tCursor
end mouseUp
 
on mergDropboxDeltaLoaded pResults,pCursor,pShouldReset,pHasMore
   if fld "files" <> "" then put cr after fld "files"
   put pResults after fld "files"
   if pHasMore then    
      mergDropboxLoadDelta pCursor
   end if
   put pCursor into url ("binfile:"&the documents folder&"/deltaCursor.dat")
end mergDropboxDeltaLoaded
 
on mergDropboxLoadDeltaError pError
   answer "There was an error loading changes: "&cr&pError
end mergDropboxLoadDeltaError