Several online file services exist for storing, and sharing, files on the
internet. Each one provides an API which allows programs to communicate with
the service. Unfortunately each API is different making it difficult for
desktop programs to easily support them.
The NetDrive class (and
related derived classes) implements each API and therefore exposes the
various services using a common class interface. This makes using any of the
services from Clarion program easy.
Because of the common interface
it's also easier to switch from one service to another service as the needs
of the client require.
Currently the services supported are;
- Dropbox
- Microsoft OneDrive
- Google Drive
All these drive services make use of OAuth User logins, so this class is
related to the
NetOAuth class. This document
starts by assuming that the program has an appropriate OAuthLogin procedure
All the cloud drive services require OAuth 2 authentication. This means that
the
OAUTH Requirements for OAuth
2 apply to NetDrive as well. Cryptonite is only needed for OAuth1, so is not
required for NetDrive.
All the cloud services make use of JSON to
communicate between your program and the server. So
jFiles is required for most NetDrive functionality.
The NetDrive classes create a common set of functions across all the drive services, so implementing cloud file storage is easy regardless of
which service you prefer.
The following features are supported by the
class;
Cloud file services are very similar to local hard drives in the way they
work, and in how they name things. However there are a few differences which
matter, so the things you need to know are listed here;
Slashes
In web services folders are separated by a forward slash character (/)
rather than the window backslash (\) character. Methods will correct \
to / when it is used, but it should be noted that file names containing
either slash are not allowed.
File and Folder IDs
In addition to the Name each Folder or File has an ID. In some systems
the ID is the unique identifier NOT the name. Some systems allow for
multiple files, in the same folder, with the same name (with a different
ID).
Most methods accept both a Name and an ID. When using these
methods it is recommended that both fields are provided - this will
ensure maximum compatibility, and performance, with all services.
There is no concept of a Current Folder. All folder and field
names are expected to be fully qualified (ie containing the full path
name and file name.)
Commands
All commands (
Directory,
UploadFile etc) are asynchronous. This means they happen in the
background. When a command completed then the
Done
method is called.
If a command is called and the object is
already busy then the command is added to a queue, and it waits there
until the object is available. This allows the programmer to generated
multiple commands without having to wait for a command to be finished.
Each command is assigned a unique command ID. When the command is
complete then the Done method is called and the same command number is
loaded into the CommandID field. This allows the calling procedure to
track which command is being Done. It should be noted that commands may
be generated internally by the class so either the command ID or the
Command property should be checked before executing code in the Done
method.
NetDriveDropbox / NetDriveGoogle / NetDriveMicrosoft
Included in NetTalk Desktop
All the NetDrive classes derive from the _NetDrive class. They contain
no additional properties, and merely flesh out the methods as described
by the _NetDrive class depending on the specific code required by the
service they are for. For more information on the properties and methods
available to these classes see the documentation for
_NetDrive below.
_NetDrive
Included in NetTalk Desktop
Derivation
- NetDriveDropBox / NetDriveGoogle / NetDriveMicrosoft
( NetDrive.Inc / NetDrive.Clw )
- _NetDrive
( NetDrive.Inc / NetDrive.Clw )
Properties
| Property | Description |
|---|
Command
(string 20) | The current command being
processed. |
CommandBusy
(Long) | If set to true then the class
is busy processing a command. |
CommandID
(Long) | The ID of the command that just
completed. The ID is returned by all the methods that initiate a
command. |
CommandQueue
(NetDriveCommandQueueType) | A list of
command waiting to be processed by the class. |
DirectoryQueue
(NetDriveDirectoryQueueType) | Holds
the results of a call to the Directory method. |
| OAuthParms | An
AuthParametersGroup provided by a call to
OAuthLogin. |
| ProgressControl | The Field Equate (FEQ) of a Progress
Control on the window. This allows the class to provide visual
feedback to the user as commands execute. Can be left unset. |
Methods
CreateFolder
CreateFolder (String pFolderName,
String pParentId)
Description
Creates a folder in the cloud drive.
Parameters
| Parameter | Description |
|---|
| pFolderName | The name of the new folder
to create. This should be relative to root. For
example if you wanted to make a red folder in the
themes folder then this should be \themes\red. |
| pParentId | The ID of the existing folder
into which the new folder must go. If left blank
then the folder is added to the root folder. To get
the ID of a folder
(not used by OneDrive or
Dropbox) |
NotesIf the
folder already exists then no action will occur. The Done method
will be called as normal, and the CommandResult value will be
set to
net:FolderAlreadyExists.
DropBox does not use the ParentId parameter, however it is a
good idea to supply it anyway to ensure code consistency across
all the services.
Return Value
The method returns the command ID number. This will match
the number in the CommandID property when the
Done method is called.
See Also
DeleteFolder,
Done
DeleteFile
DeleteFile (String pRemoteFile, String
pFileId)
Description
This allows you to delete a file in the service. Pass in the
full pathname of the remote file, as well as the file ID.
Parameters
| Parameter | Description |
|---|
| pRemoteFile | The full pathname to the
remote file to delete. |
| pFileId | The ID of the file to delete.
(not used by OneDrive or Dropbox) |
Notes
Some systems use the ID, others use the filename. For
consistency pass both in.
Return Value
The method returns the command ID number. This will match
the number in the CommandID property when the
Done method is called.
See Also
DeleteFolder,
CreateFolder,
UploadFile,
Done
DeleteFolder
DeleteFolder (String pFolderName,
String pFolderId)
Description
This
method is called after a request to the service completes. The
Command property contains the
name of the command which has just completed.
Parameters
| Parameter | Description |
|---|
| pFolderFile | The full pathname to the
remote folder to delete. |
| pFolderId | The ID of the folder to delete.
(not used by OneDrive or Dropbox) |
Return Value
The method returns the command ID number. This will match
the number in the CommandID property when the
Done method is called.
See Also
DeleteFile,
CreateFolder,
Done
Directory
Directory (String pFolderName, String
pFolderId)
Description
This method is called to get a directory listing.
Parameters
| Parameter | Description |
|---|
| pFolderName | The full pathname of the
remote folder. If the root folder is to be listed
then this parameter should be left blank. |
| pFolderId | The ID of the folder. If the
root folder is to be listed then this parameter
should be left blank.
(not used by OneDrive or
Dropbox) |
Return Value
The method returns the command ID number. This will match
the number in the CommandID property when the
Done method is called.
See Also
Done
Done
Done ()
Description
This
method is called after a request to the service completes. The
Command property contains the
name of the command which has just completed. The
CommandID property contains the ID of
the command that just completed.
Notes
You may need to embed code here if you wish to do something
with the results of the command. For example the following code
looks for a completed directory command, and copies specific
details from the
DirectoryQueue property to a local queue (for displaying on
the screen.) Also in this example, for all other commands a call to Directory is made
to refresh the listing.
case drive.Command
of 'directory'
free(FilesQ)
loop x = 1 to records(drive.DirectoryQueue)
get(drive.DirectoryQueue,x)
FilesQ :=:
drive.DirectoryQueue
if FQ:Attrib = ff_:DIRECTORY
then FQ:Icon = 2 else FQ:Icon = 1.
Add(FilesQ)
end
display()
else
post(EVENT:Accepted,?DirectoryButton)
end
Return Value
The method returns nothing.
See Also
DownloadFile
DownloadFile(String pRemoteFile,
String pRemoteID, String pLocalFile)
Description
This method allows you to download a file from the cloud to the
local machine
Parameters
| Parameter | Description |
|---|
| pRemoteFile | The full path and filename
of the remote file. |
| pRemoteID | The ID of the file.
(not
used by OneDrive or Dropbox) |
| pLocalFile | The fully qualified path name
and file name for the local copy of the file. If the
path is not included then the current folder will be
used. |
Return Value
The method returns the command ID number. This will match
the number in the CommandID property when the
Done method is called.
See Also
UploadFile,
Done
SetProgress
SetProgress (Long pProgress)
Description
Sets the Progress Control Value (if the control exists) to the
passed parameter. This method is usually called directly by the
class, and does not need to be called by the program.
Parameters
| Parameter | Description |
|---|
| pProgress | A value from 1 to 100 that
sets the current position of the progress bar. |
Notes
Progress is set to 5 when a command commences. It is
set to 95 when the response is received from the server. It is
set to 100 in the
Done method. Most commands are very fast
between 5 and and 95, however uploads and downloads can take
some time to cover this range.
Return Value
The method returns nothing.
See Also
UploadFile
UploadFile (String pLocalFileName,
String pRemoteFileName, String pRemoteFolderId, Byte pOverwrite)
Description
This method uploads a local file to the remote service.
Parameters
| Parameter | Description |
|---|
| pLocalFileName | the fully qualified path
name of the local file. |
| pRemoteFileName | The fully qualified path
name of the file as it will appear on the remote
service. |
| pRemoteFolderId | The ID of the remote
folder that this file will go into.
(not used by
OneDrive or Dropbox) |
| pOverwrite | If
net:Overwrite then the file will
overwrite the existing file, if it already exists.
If net:PreserveOriginal
then the upload will fail if the file already
exists. |
Return Value
The method returns the command ID number. This will match
the number in the
CommandID property when the
Done method is called.
See Also
DownloadFile,
Done
UserLogin
UserLogin (Long pForce=false)
Description
This method is called when the login to the service has expired.
Parameters
| Parameter | Description |
|---|
| pForce | If true then a new access
token is requested, even if a token already exists. |
Notes
You will need to embed code here to set some of the
OAuthParms fields, and also to call the OAuthLogin procedure.
For example;
ReturnValue =
PARENT.UserLogin(pForce)
self.OAuthParms.pClientId = 'xxxxxxxxxxxxxx'
self.OAuthParms.pClientSecret = 'xxxxxxxxxxxxx'
ReturnValue = OAuthLogin(self.OAuthParms)
Return Value
The method returns a Long, which is the result from
calling the
OAuthLogin procedure.
See Also
OAuthParametersGroup,
OAuthLogin
procedure,
