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.
DropBox and OneDrive allow for in-program HTML controls to do the login,
and so for these services
ChromeExplorer is recommended (but not required.)
Google requires that the Google login occur via an external browser which
is called from the program.
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) |
Notes
If 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,
