Google Workspace® Objects

PxPlus Google Drive Object

The PxPlus Google Drive object provides the ability to work with Google Workspace® Drive, a cloud-based file storage application. This object consists of various properties and methods that are used to interact with Google Drive files. See Properties and Methods below.

The Google Drive object allows more than one file to be opened at one time.

(The PxPlus Google Drive object was added in PxPlus 2021.)

Instantiating the Object

To instantiate the Google Drive object using the handle drive_obj (where drive_obj could be any numeric variable), enter the following command:

drive_obj=NEW("*obj/GoogleDrive",client_ID$,client_secret$[,login_token$])

The constructor requires a Client ID and Client Secret, both of which must be obtained from Google via the Google API Console. See Google API App Setup for detailed steps.

The login token can be optionally used to avoid having to select a Google account and login more than once. See Google Authentication for information on how to get a login_token$.

To access any of the available properties and/or methods, the Google Drive object handle (drive_obj) is used, followed by an ' (apostrophe) and the property or method (with the desired parameters).

Examples:

file=drive_obj'ACTIVE_FILE

retVal=drive_obj'SetFile(3)

Google Authentication

During object instantiation, the user will be asked to select and login to a Google account and allow PxPlus access to it via their default Web browser. When this process is completed, the Login( ) method must be run to complete login to Google Drive.

Successful login can be confirmed via the IsLoggedIn( ) method. If successfully logged in, then files can be read, modified and saved to a local file system.

Once logged in to Google Drive, the LOGIN_TOKEN$ property can be accessed and saved to avoid having to select and login to a Google account, allow access, and run the Login( ) method again. The login token can either be hard-coded into an encrypted program or saved to an encrypted file. The next time the Google Drive object gets instantiated, just include the saved login token and it will be logged into the same Google account automatically.

After one hour of inactivity, Google automatically expires a login. If logged in and Google expires the login, the next time you run a method, the object will automatically re-login. This may be noticeable if a method takes longer than usual to complete.

Cloud-Based Files

Files are stored in your Google Drive cloud storage, not as local files. Google Drive supports directories and sub-directories. All methods of this object that support a file path allow the Google Drive directories and the file name to be specified so that files can be organized more easily. For example, to download the "SalesReport" PDF file in the Google Drives directory "Template", the following method can be used:

DownloadFileByPath("C:\Users\user\Documents\SalesReport.pdf","Templates\SalesReport.pdf")

To work with a local file, upload it to Google Drive by using the UploadFile( ) method. This method uploads the local file into Google Drive and possibly converts the file into a Google file type such as a document or spreadsheet. For a list of supported conversions, visit https://developers.google.com/drive/api/v3/manage-uploads#import_to_google_docs_types.

To download a Google file such as a document or spreadsheet, use the ExportFile( ) method. This method converts the Google Drive file into a local file. The type of file is determined by the file extension specified in the output path. For a list of supported file types that a Google file can be converted to, visit https://developers.google.com/drive/api/v3/ref-export-formats.

Properties and Methods

The properties used by the Google Drive object are listed below.

Property	Description
ACTIVE_FILE	*(Read Only)* Index of the active open file. This property is set by using the SetFile( ) method. If the ACTIVE_FILE is not set with the SetFile( ) method, it is always the last opened file/highest index number. Returns '0' if no files are opened.
FILES_COUNT	*(Read Only)* Number of files opened.
LOGIN_TOKEN$	Login token (also known as an Oauth2 refresh token) that can be used when instantiating the object to avoid having to login again.

The methods used by the Google Drive object are listed below. To make it easier to locate information for a particular method, this list has been broken into smaller groups as follows:

	Authentication Methods	For logging into Google and confirming logged in status
	File Methods	For working with Google Drive files

Common Parameters

The following is a list of some of the common parameters used by multiple methods of the Google Drive object:

Note:
The file, fileID$ and file_path$ parameters can refer to a Google Drive directory, as well as a file. All methods that work with these parameters can accept properties that point to directories, as well as files, with the exception of Copy, Download and Export.

Parameter	Description
file	1-based index number in the list of sequentially opened files. If FileA, FileB and FileC were opened in that order, the corresponding indexes would be 1, 2 and 3. If FileA was closed at index 1, then FileB and FileC would now have indexes 1 and 2 respectively.
fileID$	Every file in a Google Drive cloud has a unique file ID. The file ID is displayed in the address bar when a file from a Google Drive cloud is opened in a Web browser. Since it is possible to have more than one file with the same path, the file ID is used to specify a particular file. This parameter is used by methods that end with ByID.
file_path$	The Google Drive path consists of any directories and a file name. It can be used as a simple and readable method to specify a file. This parameter is used by methods that end with ByPath. Note: This path consists of the directories and file name from the Google Drive cloud, not a path to a file on the local file system.

Authentication Methods

Authentication Methods

Description

IsLoggedIn( )

Returns '1' if logged into Google Drive.

Returns '0' if not yet logged into Google Drive.

Note:
After one hour of inactivity, Google Drive will expire the login; however, this method will still return '1'.

Login( )

During object instantiation, the user will be asked to select a Google account and allow access to it. When this process is completed, run this method to complete login to Google Drive.

Returns '1' if successful.

Returns '0' if any error is encountered while logging in.

File Methods

File Methods

Description

CloseFile( )

CloseFile(file)

CloseFileByID(fileID$)

CloseFileByPath(file_path$)

Closes the file specified by an open file index number, a Google Drive file ID, or a Google Drive path. If no file is specified, the active file will be closed.

If you close the ACTIVE_FILE, the ACTIVE_FILE is set to the last opened file still open; i.e. the highest file index or 0 if no files are left opened.

Note:
When closing a file, any file opened after the closed file was opened (any file with a higher index) will have its index shifted down 1. For example, if closing the file with index 2, then the file at index 3 becomes index 2.

Returns '1' if successful.

Returns '0' if any error is encountered while closing the file.

CloseFiles( )

Closes all open files.

Returns '1' if successful.

Returns '0' if any error is encountered while closing the files.

CopyFile(copy_path$)

CopyFile(copy_path$,file)

CopyFileByID(copy_path$,fileID$)

CopyFileByPath(copy_path$,file_path$)

Makes a copy with the given path of the file specified by an open file index number, a Google Drive file ID, or a Google Drive path. If no file is specified, the active file will be copied.

Returns '1' if successful.

Returns '0' if any error is encountered while copying the file.

CreateFile(file_path$,mime_type$)

Creates a new blank Google Drive file with the path file_path$. The file type is determined by the mime_type$. For a list of common mime types, visit:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types

The new file is opened and becomes the ACTIVE_FILE.

If the file_path$ parameter is null, the file is named "Untitled".

Important Note:
It is possible to have multiple files with the same path. They have different file IDs.

Returns '1' if successful.

Returns '0' if any error is encountered while creating the file.

CreateFolder(folder_path$)

Creates a new empty Google Drive folder with the path folder_path$. The new folder is opened and becomes the ACTIVE_FILE.

If the folder_path$ parameter is null, the folder is named "Untitled".

Important Note:
It is possible to have multiple folders with the same path. They have different file IDs.

Returns '1' if successful.

Returns '0' if any error is encountered while creating the folder.

DeleteFile( )

DeleteFile(file)

DeleteFileByID(fileID$)

DeleteFileByPath(file_path$)

Deletes the file from Google Drive specified by an open file index number, a Google Drive file ID, or a Google Drive path. If no file is specified, the active file will be deleted.

The file is closed as well.

Returns '1' if successful.

Returns '0' if any error is encountered while deleting the file.

DownloadFile(output_path$)

DownloadFile(output_path$,file)

DownloadFileByID(output_path$,fileID$)

DownloadFileByPath(output_path$,file_path$)

Downloads the Google Drive file specified by the ACTIVE_FILE or the file specified by the open file index number, a Google Drive file ID, or a Google Drive path. The path of the downloaded file is determined by output_path$.

Returns '1' if successful.

Returns '0' if any error is encountered while downloading the file.

ExportFile(output_path$)

ExportFile(output_path$,file)

ExportFileByID(output_path$,fileID$)

ExportFileByPath(output_path$,file_path$)

Converts the ACTIVE_FILE or the file specified by the open file index number, a Google Drive file ID, or a Google Drive path from a Google Workspace® file (document, sheet, etc.) to a local file, and then downloads the file to the local file system. The type of local file and the path of the file is determined by output_path$.

For supported output_path$ file types, see Cloud-Based Files.

Returns '1' if successful.

Returns '0' if any error is encountered while converting and downloading the file.

GetFileID$( )

GetFileID$(file)

GetFileID$(file_path$)

Returns a Google Drive file ID of the file specified by an open file index number or a Google Drive path. If no file is specified, the Google Drive file ID of the active file is returned. Before getting a file ID, the file must be opened first.

Returns "" if unable to locate the file.

GetMimeType$( )

GetMimeType$(file)

Returns the mime type of the file specified by an open file index number. If no file is specified, the mime type of the active file is returned.

Returns "" if unable to locate the file.

GetPath$( )

GetPath$(file)

Returns a Google Drive path of the file specified by an open file index number. If no file is specified, the Google Drive path of the active file is returned.

Returns "" if unable to locate the file.

ListFiles( )

Returns a handle to a memory file loaded with the directory and file information from Google Drive.

The IOL of the memory file is:

   file_name$
   fileID$
   directory_path$
   mime_type$
   file_size$
   created_time$
   modified_time$
   viewed_by_me_time$

Returns "" if any error is encountered while listing files.

OpenFileByID(fileID$)

OpenFileByPath(file_path$)

Opens the Google Drive file specified by either a Google Drive file ID or a Google Drive path.

After opening a file, the ACTIVE_FILE property is set to the file index corresponding to the file just opened.

Note:
When opening a file, the index is set to the number of open files. The first file opened will be index 1, the second file opened will be index 2, etc.

Returns '1' if successful.

Returns '0' if any error is encountered while opening the file.

SetFile(file)

SetFileByID(fileID$)

SetFileByPath(file_path$)

Sets the ACTIVE_FILE index to the file specified by an open file index number, a Google Drive file ID, or a Google Drive path. For a file to be set as active, the file must be opened.

Returns '1' if successful.

Returns '0' if unable to locate the file.

UploadFile(input_path$,file_path$)

UploadFile(input_path$,file_path$,mime_type$)

Upload a local file input_path$ to Google Drive. If a mime_type$ is specified, the file is converted to a Google file such as a document or spreadsheet. The new Google Drive file is given the specified Google Drive path.

For supported conversions, see Cloud-Based Files.

Returns '1' if successful.

Returns '0' if any error is encountered while uploading the file.

Example: Testing the Google Drive Object

This example program tests the Google Drive object.

! Test Google Drive object
!
! Instantiate object where you define the clientID$ and clientSecret$ variables to be the values you got from Google
gd=NEW("*obj/GoogleDrive",clientID$,clientSecret$)
!
! Wait for user to complete Google sign-in and allow PxPlus access
INPUT "Press any key to continue after logging into Google account and allowing PxPlus access:",*;print ""
!
! Complete the Google Drive login
gd'Login()
!
! Open file from root Google Drive folder
path$="SalesReport.pdf"
if gd'OpenFileByPath(path$)=0 then MSGBOX "Error opening first file"
!
! Open another file this one from a different Google Drive folder
path2$="Notifications/NewDiscount.txt"
if gd'OpenFileByPath(path2$)=0 then MSGBOX "Error opening second file"
!
! Check number of files open
MSGBOX STR(gd'files_count),"Open File Count"
!
! Create a backup folder
if gd'CreateFolder("backups/")<>1 then MSGBOX "Error creating backup folder"
!
! Set active file as the first open file
if gd'SetFileByPath(path$)=0 then MSGBOX "Error making first file active"
!
! Create a copy in backups
if gd'CopyFile("backups/"+path$)<>1 then MSGBOX "Error copying file"
!
! Set active file
if gd'SetFile(2)=0 then MSGBOX "Error making second file active"
!
! Download active document
gd'DownloadFile("c:\users\user\documents\NewDiscount.txt")
!
! Delete downloaded file
if gd'DeleteFile(2)<>1 then MSGBOX "Error deleting file"
!
!
DROP OBJECT gd
END

Google Workspace® Objects

Instantiating the Object

Cloud-Based Files

Properties and Methods

Note:
The file, fileID$ and file_path$ parameters can refer to a Google Drive directory, as well as a file. All methods that work with these parameters can accept properties that point to directories, as well as files, with the exception of Copy, Download and Export.

Note:
This path consists of the directories and file name from the Google Drive cloud, not a path to a file on the local file system.

Note:
After one hour of inactivity, Google Drive will expire the login; however, this method will still return '1'.

Note:
When closing a file, any file opened after the closed file was opened (any file with a higher index) will have its index shifted down 1. For example, if closing the file with index 2, then the file at index 3 becomes index 2.

Important Note:
It is possible to have multiple files with the same path. They have different file IDs.

Important Note:
It is possible to have multiple folders with the same path. They have different file IDs.

Note:
When opening a file, the index is set to the number of open files. The first file opened will be index 1, the second file opened will be index 2, etc.

Example: Testing the Google Drive Object

See Also

Google Workspace® Objects

Instantiating the Object

Cloud-Based Files

Properties and Methods

Note: The file, fileID$ and file_path$ parameters can refer to a Google Drive directory, as well as a file. All methods that work with these parameters can accept properties that point to directories, as well as files, with the exception of Copy, Download and Export.

Note: This path consists of the directories and file name from the Google Drive cloud, not a path to a file on the local file system.

Note: After one hour of inactivity, Google Drive will expire the login; however, this method will still return '1'.

Note: When closing a file, any file opened after the closed file was opened (any file with a higher index) will have its index shifted down 1. For example, if closing the file with index 2, then the file at index 3 becomes index 2.

Important Note: It is possible to have multiple files with the same path. They have different file IDs.

Important Note: It is possible to have multiple folders with the same path. They have different file IDs.

Note: When opening a file, the index is set to the number of open files. The first file opened will be index 1, the second file opened will be index 2, etc.

Example: Testing the Google Drive Object

See Also

Note:
The file, fileID$ and file_path$ parameters can refer to a Google Drive directory, as well as a file. All methods that work with these parameters can accept properties that point to directories, as well as files, with the exception of Copy, Download and Export.

Note:
This path consists of the directories and file name from the Google Drive cloud, not a path to a file on the local file system.

Note:
After one hour of inactivity, Google Drive will expire the login; however, this method will still return '1'.

Note:
When closing a file, any file opened after the closed file was opened (any file with a higher index) will have its index shifted down 1. For example, if closing the file with index 2, then the file at index 3 becomes index 2.

Important Note:
It is possible to have multiple files with the same path. They have different file IDs.

Important Note:
It is possible to have multiple folders with the same path. They have different file IDs.

Note:
When opening a file, the index is set to the number of open files. The first file opened will be index 1, the second file opened will be index 2, etc.