CapeSoft.Com
Clarion Accessories
NetTalk
Doc Index
NetDrive
CapeSoft Logo

CapeSoft NetTalk
NetDrive

Download Latest Version
Installed Version Latest Version

NetTalk NetDrive

Available in NetTalk Desktop, NetTalk Server and NetTalk Apps. Applies to Desktop (ABC or Clarion) apps.

Introduction

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; 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

Requirements

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.

Features

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;

Concepts

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.

Links

The following links are provided so that the API for each service can be studied (if desired.) Understanding the actual API's is not a requirement for using this class.

Dropbox

Google Drive

Microsoft OneDrive

Class Reference

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

Method Description
CreateFolder Create a new folder
DeleteFile Delete an existing file
DeleteFolder Deleted an existing folder
Directory Get a directory listing
Done Called when a command is completed
DownloadFile Download a file from the service
SetProgress Set the value of the Progress Control to a value from 1 to 100
UploadFile Upload a file to the service
UserLogin Log the user into the service.

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)          ! Call the parent first
self.OAuthParms.pClientId = 'xxxxxxxxxxxxxx'   
! set this to your application Client ID
self.OAuthParms.pClientSecret = 'xxxxxxxxxxxxx' ! set this to your application Client Secret.
ReturnValue = OAuthLogin(self.OAuthParms)       ! OAuthLogin is a procedure in your app tree.

Return Value

The method returns a Long, which is the result from calling the OAuthLogin procedure.

See Also

OAuthParametersGroup, OAuthLogin procedure,

[End of this document]
Return to NetTalk Documentation Index