CloudFiles Class

Properties   Methods   Events   Config Settings   Errors  

The CloudFiles class provides an easy way to upload, download, and manage files and folders with multiple service providers.

Syntax

cloudstorage.cloudfiles()

Remarks

The CloudFiles class provides a single interface that can be used to work with a variety of services. By supporting multiple providers with a single API code may be written once and used to support multiple services. The following providers are currently supported by this class:

• Amazon S3
• Azure Blob
• Azure File
• Backblaze B2
• Box.com
• Digital Ocean Spaces
• Dropbox
• Google Cloud Storage
• Google Drive
• Hadoop DFS
• IBM Cloud Object Storage
• Linode Object Storage
• Microsoft OneDrive
• Wasabi

The class supports simple file and folder management as well as encryption. Capabilities include uploading and downloading files, strong encryption support, creating folders, and more.

To begin, first create an account and register your application. Consult the documentation of the individual service provider for instructions on this process.

Authentication

The following providers use OAuth 2.0 for authentication:

• Box.com
• Dropbox
• Google Cloud Storage*
• Google Drive
• Microsoft OneDrive

Use the OAuth class included in the toolkit, or any other OAuth implementation to perform authentication and retrieve an authorization string. Once you've obtained an authorization string like:

Bearer ya29.AHES6ZSZEJzATdZYjeihDn5W-VrXSsxEZu5p0pclxGdKKQ

To authenticate with the remaining providers, set the Account* properties shown in the table below:

*Google Cloud Storage supports two authentication methods. To authenticate with OAuth 2.0 (preferred) set the Authorization property and the AccountProjectId property. To authenticate with an access and secret key, set the AccountAccessKey and AccountSecretKey properties instead.

Selecting a Provider

To specify the provider simply set ServiceProvider. This tells the class to which service requests will be made.

Listing Files and Folders

ListDirectory lists files and folder the path specified by RemotePath.

The directory entries are provided through the DirList event and also via the DirList* properties. cloudfiles.RemoteFile = ""; //Clear filemask cloudfiles.RemotePath = "MyFolder"; cloudfiles.ListDirectory(); for (int i = 0; i < cloudfiles.DirList.Count; i++) { Console.WriteLine(cloudfiles.DirList[i].FileName); Console.WriteLine(cloudfiles.DirList[i].FileSize); Console.WriteLine(cloudfiles.DirList[i].FileTime); Console.WriteLine(cloudfiles.DirList[i].IsDir); }

The RemoteFile property may also be used as a filemask when listing files. For instance: component.RemoteFile = "*.txt" component.ListDirectory()

Note: Since RemoteFile is used as a filemask be sure to clear or reset this value before calling ListDirectory

Downloading Files

The Download method downloads a specific file.

Set RemoteFile to the name the file to download before calling this method. If RemoteFile only specifies a filename it will be downloaded from the path specified by RemotePath. RemoteFile may also be set to an absolute path.

If LocalFile is set the file will be saved to the specified location. If LocalFile is not set the file data will be held by ResourceData.

To decrypt an encrypted file set EncryptionAlgorithm and EncryptionPassword before calling this method. cloudfiles.RemotePath = "My Folder"; cloudfiles.RemoteFile = "MyFile.zip"; cloudfiles.LocalFile = "../MyFile.zip"; cloudfiles.Download();

Resuming Downloads

The class also supports resuming failed downloads by using the StartByte property. If the download was interrupted, set StartByte to the appropriate offset before calling this method to resume the download. cloudfiles.RemotePath = myRemoteFolder; cloudfiles.RemoteFile = myRemoteFile; cloudfiles.LocalFile = downloadFile; cloudfiles.Download(); //The transfer is interrupted and Download() above fails. Later, resume the download: //Get the size of the partially downloaded file cloudfiles.StartByte = new FileInfo(downloadFile).Length; cloudfiles.RemotePath = myRemoteFolder; cloudfiles.RemoteFile = myRemoteFile; cloudfiles.LocalFile = downloadFile; cloudfiles.Download();

Resuming Encrypted File Downloads

Resuming encrypted file downloads is only supported when LocalFile was set in the initial download attempt. When beginning an encrypted download if LocalFile is set the class will create a temporary file in TempPath to hold the encrypted data until it is complete.

If the download is interrupted DownloadTempFile will be populated with the temporary file holding the partial data. When resuming, DownloadTempFile must be populated along with StartByte to allow the remainder of the encrypted data to be downloaded. Once the encrypted data is downloaded it will be decrypted and written to LocalFile. cloudfiles.RemotePath = myRemoteFolder; cloudfiles.RemoteFile = myRemoteFile; cloudfiles.LocalFile = downloadFile; cloudfiles.EncryptionPassword = "password"; cloudfiles.Download(); //The transfer is interrupted and Download() above fails. Later, resume the download: //Get the size of the partially download temp file cloudfiles.StartByte = new FileInfo(cloudfiles.Config("DownloadTempFile")).Length; cloudfiles.RemotePath = myRemoteFolder; cloudfiles.RemoteFile = myRemoteFile; cloudfiles.LocalFile = downloadFile; cloudfiles.EncryptionPassword = "password"; cloudfiles.Download();

Uploading Files

The Upload method is used to upload files.

RemoteFile should be set to either a relative or absolute path. If RemoteFile is not an absolute path it will be uploaded relative to RemotePath.

To encrypt a file before uploading set EncryptionAlgorithm and EncryptionPassword.

Note: Resuming uploads is not currently supported.

Code Example: //Upload with a relative path cloudfiles.LocalFile = "C:\localfile.txt" cloudfiles.RemoteFile = "remotefile.txt" cloudfiles.Upload() //Upload with an absolute path cloudfiles.LocalFile = "C:\localfile2.txt" cloudfiles.RemoteFile = "/folder/remotefile2.txt" cloudfiles.Upload()

Additional Functionality

The CloudFiles class offers advanced functionality beyond simple uploads and downloads. For instance:

• Encrypt and decrypt files using EncryptionAlgorithm and EncryptionPassword.
• DeleteFile provides a way to delete files.
• MakeDirectory and RemoveDirectory support creating and deleting folders.
• RenameFile allows renaming of existing files on the server.
• And more!

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

CloudFiles.Account Property

Account credentials.

Syntax

 getAccount(): CloudFilesAccount;

 setAccount(account: CloudFilesAccount): void;

Default Value

Remarks

This property holds account credentials for all storage service providers that do not use OAuth for authentication (or that do use OAuth, but require additional configuration).

CloudFiles.Authorization Property

OAuth 2.0 Authorization Token.

Syntax

 getAuthorization(): string;

 setAuthorization(authorization: string): void;

Default Value

""

Remarks

This class supports authentication via OAuth 2.0. First, perform OAuth authentication using the OAuth* properties, using the OAuth class or a separate process. If using the OAuth* properties, then the Authorization property will not be used.

Bearer ACCESS_TOKEN

CloudFiles.DirList Property

Collection of entries resulting in the last directory listing.

Syntax

 getDirList(): CFDirEntryList;

Default Value

Remarks

This property contains a collection of entries after calling ListDirectory. The collection holds details about each entry at RemotePath.

This property is read-only and not available at design time.

CloudFiles.EncryptionAlgorithm Property

The encryption algorithm.

Syntax

 getEncryptionAlgorithm(): CloudfilesEncryptionAlgorithms;

 setEncryptionAlgorithm(encryptionAlgorithm: CloudfilesEncryptionAlgorithms): void;

enum CloudfilesEncryptionAlgorithms {
  eaAES,
  eaBlowfish,
  eaCAST,
  eaDES,
  eaIDEA,
  eaRC2,
  eaRC4,
  eaTEA,
  eaTripleDES,
  eaTwofish,
  eaRijndael,
  eaChaCha,
  eaXSalsa20
}

Default Value

0

Remarks

This property specifies the encryption algorithm to be used. The maximum allowable key size is automatically used for the selected algorithm. Possible values are:

CloudFiles.EncryptionPassword Property

The encryption password.

Syntax

 getEncryptionPassword(): string;

 setEncryptionPassword(encryptionPassword: string): void;

Default Value

""

Remarks

If this property is populated when UploadFile or DownloadFile is called, the class will attempt to encrypt or decrypt the data before uploading or after downloading it.

The class uses the value specified here to generate the necessary encryption Key and IV values using the PKCS5 password digest algorithm. This provides a simpler alternative to creating and managing Key and IV values directly.

However, it is also possible to explicitly specify the Key and IV values to use by setting the EncryptionKey and EncryptionIV configuration settings. This may be necessary if, e.g., the data needs to be encrypted/decrypted by another utility which generates Key and IV values differently.

This property is not available at design time.

CloudFiles.Firewall Property

A set of properties related to firewall access.

Syntax

 getFirewall(): Firewall;

 setFirewall(firewall: Firewall): void;

Default Value

Remarks

This is a Firewall type property which contains fields describing the firewall through which the class will attempt to connect.

CloudFiles.Idle Property

The current status of the class.

Syntax

 isIdle(): boolean;

Default Value

TRUE

Remarks

Idle will be False if the component is currently busy (communicating and/or waiting for an answer), and True at all other times.

This property is read-only.

CloudFiles.LocalFile Property

The location of the local file.

Syntax

 getLocalFile(): string;

 setLocalFile(localFile: string): void;

Default Value

""

Remarks

This property specifies the location of a file on disk. This is used as the source file when calling Upload, and as the destination file when calling Download.

CloudFiles.LocalHost Property

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

 getLocalHost(): string;

 setLocalHost(localHost: string): void;

Default Value

""

Remarks

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

If the class is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

CloudFiles.Overwrite Property

Whether to overwrite the local or remote file.

Syntax

 isOverwrite(): boolean;

 setOverwrite(overwrite: boolean): void;

Default Value

FALSE

Remarks

When calling DownloadFile, this property determines if LocalFile should be overwritten if it already exists.

When calling UploadFile, this property determines if the remote file should be overwritten if it already exists.

CloudFiles.Proxy Property

This property includes a set of properties related to proxy access.

Syntax

 getProxy(): Proxy;

 setProxy(proxy: Proxy): void;

Default Value

Remarks

This property contains fields describing the proxy through which the class will attempt to connect.

CloudFiles.RemoteFile Property

The name of the remote file.

Syntax

 getRemoteFile(): string;

 setRemoteFile(remoteFile: string): void;

Default Value

""

Remarks

This property contains the name of the remote file to upload or download. This value is either an absolute or relative path based on RemotePath.

Example (Setting RemoteFile) component.LocalFile = "C:\\test.txt"; component.RemoteFile = "test.txt"; component.Upload(); component.LocalFile = "C:\\test.txt"; component.RemoteFile = "/MyFolder/SubFolder/file.txt"; component.Upload(); Note: This property will also act as a file mask when calling ListDirectory.

Example (Using RemoteFile as a file mask): component.RemoteFile = "*.txt" component.ListDirectory()

The following special characters are supported for pattern matching:

If these characters need to be used as a literal in a pattern, then they must be escaped by surrounding them with brackets []. Note: "]" and "-" do not need to be escaped. See below for the escape sequences:

For example, to match the value [Something].txt, specify the pattern [[]Something].txt.

CloudFiles.RemotePath Property

The current path on the server.

Syntax

 getRemotePath(): string;

 setRemotePath(remotePath: string): void;

Default Value

""

Remarks

This property shows the current working directory on the server. It can also be used to change the working directory by setting an absolute or relative path.

If the path begins with a "/" it is considered an absolute path.

If the first two characters of the path are ".." this indicates a change to the parent directory.

Example (Changing Directory) component.RemotePath = "/MyFolder/Child"; //absolute component.RemotePath = "GrandChild"; //relative, change to a sub-folder of the current directory component.RemotePath = "../.."; //relative, use ".." to navigate to parent folders

CloudFiles.ServiceProvider Property

The storage service provider.

Syntax

 getServiceProvider(): CloudfilesServiceProviders;

 setServiceProvider(serviceProvider: CloudfilesServiceProviders): void;

enum CloudfilesServiceProviders {
  cspAmazonS3,
  cspBox,
  cspDropbox,
  cspGoogleDrive,
  cspOneDrive,
  cspAzureBlob,
  cspWasabi,
  cspDigitalOcean,
  cspGoogleStorage,
  cspHadoopDFS,
  cspAzureFile,
  cspBackblazeB2,
  cspIBMStorage,
  cspLinode
}

Default Value

0

Remarks

This property specifies the storage service provider which will be used. Possible values are:

• cspAmazonS3 (0) (default): Amazon S3
• cspBox (1): Box.com
• cspDropbox (2): Dropbox
• cspGoogleDrive (3): Google Drive
• cspOneDrive (4): Microsoft OneDrive
• cspAzureBlob (6): Azure Blob
• cspWasabi (7): Wasabi
• cspDigitalOcean (8): Digital Ocean Spaces
• cspGoogleStorage (9): Google Cloud Storage
• cspHadoopDFS (10): Hadoop DFS
• cspAzureFile (11): Azure File
• cspBackblazeB2 (12): Backblaze B2
• cspIBMStorage (13): IBM Cloud Object Storage
• cspLinode (14): Linode Object Storage

This property is not available at design time.

CloudFiles.SSLAcceptServerCert Property

Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

 getSSLAcceptServerCert(): Certificate;

 setSSLAcceptServerCert(SSLAcceptServerCert: Certificate): void;

Default Value

Remarks

If it finds any issues with the certificate presented by the server, the class will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

CloudFiles.SSLCert Property

The certificate to be used during SSL negotiation.

Syntax

 getSSLCert(): Certificate;

 setSSLCert(SSLCert: Certificate): void;

Default Value

Remarks

The digital certificate that the class will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the field to the encoded certificate. To select a certificate, use the store and subject fields.

CloudFiles.SSLProvider Property

This specifies the SSL/TLS implementation to use.

Syntax

 getSSLProvider(): CloudfilesSSLProviders;

 setSSLProvider(SSLProvider: CloudfilesSSLProviders): void;

enum CloudfilesSSLProviders {
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
}

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic) the class will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are:

Additional Notes

In most cases using the default value (Automatic) is recommended. The class will select a provider depending on the current platform.

When Automatic is selected the platform implementation will be used by default in all cases in the JavaScript edition.

Note: The Internal provider is not support at this time.

CloudFiles.SSLServerCert Property

The server certificate for the last established connection.

Syntax

 getSSLServerCert(): Certificate;

Default Value

Remarks

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

CloudFiles.StartByte Property

The byte offset from which to start download.

Syntax

 getStartByte(): number;

 setStartByte(startByte: number): void;

Default Value

0

Remarks

This property may be set to resume a download. This specifies the offset in the file from which to resume. See Download for details about resuming downloads.

Note: Resuming uploads is not currently supported.

This property is not available at design time.

CloudFiles.Timeout Property

A timeout for the class.

Syntax

 getTimeout(): number;

 setTimeout(timeout: number): void;

Default Value

60

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If Timeout is set to a positive value, the class will wait for the operation to complete before returning control.

The class will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the class .

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

The default value for the Timeout property is 60 seconds.

CloudFiles.config Method

Sets or retrieves a configuration setting.

Syntax

async cloudfiles.config(configurationString : string): Promise<string>

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CloudFiles.deleteFile Method

Remove a file specified by FileName from the server.

Syntax

async cloudfiles.deleteFile(fileName : string): Promise<void>

Remarks

This method deletes the files specified by the FileName parameter from the server. FileName may be either an absolute path, or a path relative to RemotePath.

CloudFiles.download Method

Download the specified file.

Syntax

async cloudfiles.download(): Promise<void>

Remarks

This method downloads the specified file. Set RemoteFile to the name the file to download before calling this method. If RemoteFile only specifies a filename it will be downloaded from the path specified by RemotePath. RemoteFile may also be set to an absolute path.

If LocalFile is set the file will be saved to the specified location. If LocalFile is not set the file data will be held by ResourceData.

To decrypt an encrypted file set EncryptionAlgorithm and EncryptionPassword before calling this method. cloudfiles.RemotePath = "My Folder"; cloudfiles.RemoteFile = "MyFile.zip"; cloudfiles.LocalFile = "../MyFile.zip"; cloudfiles.Download();

Resuming Downloads

The class also supports resuming failed downloads by using the StartByte property. If the download was interrupted, set StartByte to the appropriate offset before calling this method to resume the download. cloudfiles.RemotePath = myRemoteFolder; cloudfiles.RemoteFile = myRemoteFile; cloudfiles.LocalFile = downloadFile; cloudfiles.Download(); //The transfer is interrupted and Download() above fails. Later, resume the download: //Get the size of the partially downloaded file cloudfiles.StartByte = new FileInfo(downloadFile).Length; cloudfiles.RemotePath = myRemoteFolder; cloudfiles.RemoteFile = myRemoteFile; cloudfiles.LocalFile = downloadFile; cloudfiles.Download();

Resuming Encrypted File Downloads

Resuming encrypted file downloads is only supported when LocalFile was set in the initial download attempt. When beginning an encrypted download if LocalFile is set the class will create a temporary file in TempPath to hold the encrypted data until it is complete.

If the download is interrupted DownloadTempFile will be populated with the temporary file holding the partial data. When resuming, DownloadTempFile must be populated along with StartByte to allow the remainder of the encrypted data to be downloaded. Once the encrypted data is downloaded it will be decrypted and written to LocalFile. cloudfiles.RemotePath = myRemoteFolder; cloudfiles.RemoteFile = myRemoteFile; cloudfiles.LocalFile = downloadFile; cloudfiles.EncryptionPassword = "password"; cloudfiles.Download(); //The transfer is interrupted and Download() above fails. Later, resume the download: //Get the size of the partially download temp file cloudfiles.StartByte = new FileInfo(cloudfiles.Config("DownloadTempFile")).Length; cloudfiles.RemotePath = myRemoteFolder; cloudfiles.RemoteFile = myRemoteFile; cloudfiles.LocalFile = downloadFile; cloudfiles.EncryptionPassword = "password"; cloudfiles.Download();

CloudFiles.interrupt Method

Interrupt the current method.

Syntax

async cloudfiles.interrupt(): Promise<void>

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

CloudFiles.listDirectory Method

Lists the current directory specified by RemotePath on the server.

Syntax

async cloudfiles.listDirectory(): Promise<void>

Remarks

This method is used to list the directory specified by RemotePath.

The directory entries are provided through the DirList event and also via the DirList* properties. cloudfiles.RemoteFile = ""; //Clear filemask cloudfiles.RemotePath = "MyFolder"; cloudfiles.ListDirectory(); for (int i = 0; i < cloudfiles.DirList.Count; i++) { Console.WriteLine(cloudfiles.DirList[i].FileName); Console.WriteLine(cloudfiles.DirList[i].FileSize); Console.WriteLine(cloudfiles.DirList[i].FileTime); Console.WriteLine(cloudfiles.DirList[i].IsDir); }

The RemoteFile property may also be used as a filemask when listing files. For instance: component.RemoteFile = "*.txt" component.ListDirectory()

Note: Since RemoteFile is used as a filemask be sure to clear or reset this value before calling ListDirectory

CloudFiles.makeDirectory Method

Creates a directory on the server.

Syntax

async cloudfiles.makeDirectory(newDir : string): Promise<void>

Remarks

This method is used to create a directory. The parameter NewDir specifies the name of the directory. NewDir may be either an absolute path, or a path relative to RemotePath.

Note: After creating a directory RemoteFile will be updated with the newly created directory name.

CloudFiles.removeDirectory Method

Remove the specified directory.

Syntax

async cloudfiles.removeDirectory(dirName : string): Promise<void>

Remarks

This method removes the directory specified by the DirName parameter. DirName may be either an absolute path, or a path relative to RemotePath.

Note: The directory and all of its contents will be deleted when calling this method. (With the exception of non-root-level directories for the cspAzureFile (11) ServiceProvider; such directories can only be deleted if they are empty.)

CloudFiles.renameFile Method

Renames the file.

Syntax

async cloudfiles.renameFile(newName : string): Promise<void>

Remarks

This method renames an existing file on the server. The NewName parameter specifies the new name of the file. cloudfiles.RemotePath = "/MyFolder"; cloudfiles.RemoteFile = "file.txt"; cloudfiles.RenameFile("newfile.txt");

Note: RenameFile is not supported when ServiceProvider is set to one of the following:

• cspAmazonS3 (0)
• cspAzureBlob (6)
• cspDigitalOcean (8)
• cspGoogleStorage (9)
• cspAzureFile (11)
• cspBackblazeB2 (12)
• cspIBMStorage (13)
• cspLinode (14)

CloudFiles.reset Method

Resets the class to its initial state.

Syntax

async cloudfiles.reset(): Promise<void>

Remarks

This method resets the class to its initial state.

CloudFiles.upload Method

Uploads the file specified by LocalFile to the server.

Syntax

async cloudfiles.upload(): Promise<void>

Remarks

This method uploads the local file specified by LocalFile to the remote file specified by RemoteFile.

RemoteFile should be set to either a relative or absolute path. If RemoteFile is not an absolute path it will be uploaded relative to RemotePath.

To encrypt a file before uploading set EncryptionAlgorithm and EncryptionPassword.

Note: Resuming uploads is not currently supported.

Code Example: //Upload with a relative path cloudfiles.LocalFile = "C:\localfile.txt" cloudfiles.RemoteFile = "remotefile.txt" cloudfiles.Upload() //Upload with an absolute path cloudfiles.LocalFile = "C:\localfile2.txt" cloudfiles.RemoteFile = "/folder/remotefile2.txt" cloudfiles.Upload()

CloudFiles.DirList Event

Fired when a directory entry is received.

Syntax

cloudfiles.on('DirList', listener: (e: {readonly fileName: string, readonly isDir: boolean, readonly fileSize: number, readonly fileTime: string}) => void )

Remarks

This event fires once for each entry returned when ListDirectory is called.

FileName holds the name of the file or folder.

IsDir is true for directories and false for files.

FileSize is the size of the file in bytes. For some providers this also applies directories and will return the size of all files and folders within the directory.

The table below summarizes the applicability of this value on a per-provider basis:

FileTime is the modified date of the file. By default the datetime format used is "yyyy-MM-dd'T'HH:mm:ss". To modify this format set DateFormat.

Note: Modified times are not applicable to directories for the following providers:

• cspAmazonS3 (0)
• cspDropbox (2)
• cspWasabi (7)
• cspDigitalOcean (8)
• cspGoogleStorage (9)
• cspBackblazeB2 (12)
• cspIBMStorage (13)
• cspLinode (14)

Additionally, the following providers do not return modified times at all:

• cspAzureFile (11)

CloudFiles.EndTransfer Event

This event fires when a document finishes transferring.

Syntax

cloudfiles.on('EndTransfer', listener: (e: {readonly direction: number}) => void )

Remarks

The EndTransfer event is fired when the document text finishes transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

CloudFiles.Error Event

Information about errors during data delivery.

Syntax

cloudfiles.on('Error', listener: (e: {readonly errorCode: number, readonly description: string}) => void )

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class .

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

CloudFiles.Log Event

This event fires once for each log message.

Syntax

cloudfiles.on('Log', listener: (e: {readonly logLevel: number, readonly message: string, readonly logType: string}) => void )

Remarks

This event fires once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of message. Possible values are as follows:

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

Message is the log entry.

LogType identifies the type of log entry. Possible values are as follows:

• "Info"
• "RequestHeaders"
• "ResponseHeaders"
• "RequestBody"
• "ResponseBody"
• "ProxyRequest"
• "ProxyResponse"
• "FirewallRequest"
• "FirewallResponse"

CloudFiles.Progress Event

Fires during an upload or download to indicate transfer progress.

Syntax

cloudfiles.on('Progress', listener: (e: {readonly direction: number, readonly bytesTransferred: number, readonly totalBytes: number, readonly percentDone: number}) => void )

Remarks

This event fires during an upload or download to indicate the progress of the transfer of the entire request. By default, this event will fire each time PercentDone increases by one percent; the ProgressStep configuration setting can be used to alter this behavior.

Direction indicates whether the transfer is an upload (0) or a download (1).

BytesTransferred reflects the number of bytes that have been transferred so far, or 0 if the transfer is starting (however, see note below).

TotalBytes reflects the total number of bytes that are to be transferred, or -1 if the total is unknown. This amount includes the size of everything in the request like HTTP headers.

PercentDone reflects the overall progress of the transfer, or -1 if the progress cannot be calculated.

Note: By default, the class tracks transfer progress absolutely. If a transfer is interrupted and later resumed, the values reported by this event upon and after resumption will account for the data that was transferred before the interruption.

For example, if 10MB of data was successfully transferred before the interruption, then this event will fire with a BytesTransferred value of 10485760 (10MB) when the transfer is first resumed, and then continue to fire with successively greater values as usual.

This behavior can be changed by disabling the ProgressAbsolute configuration setting, in which case the class will treat resumed transfers as "new" transfers. In this case, the BytesTransferred parameter will always be 0 the first time this event fires, regardless of whether the transfer is new or being resumed.

CloudFiles.SSLServerAuthentication Event

Fired after the server presents its certificate to the client.

Syntax

cloudfiles.on('SSLServerAuthentication', listener: (e: {readonly certEncoded: string, readonly certEncodedB: Uint8Array, readonly certSubject: string, readonly certIssuer: string, readonly status: string, accept: boolean}) => void )

Remarks

This event fires with information about the server certificate. The Status property shows why verification failed (otherwise, Status contains the string "OK"). To manually accept an untrusted certificate, the SSLAcceptAnyServerCert setting must be set to True before intiating the connection.

CloudFiles.SSLStatus Event

Shows the progress of the secure connection.

Syntax

cloudfiles.on('SSLStatus', listener: (e: {readonly message: string}) => void )

Remarks

The event is fired for informational and logging purposes only. Used to track the progress of the connection.

CloudFiles.StartTransfer Event

This event fires when a document starts transferring (after the headers).

Syntax

cloudfiles.on('StartTransfer', listener: (e: {readonly direction: number}) => void )

Remarks

The StartTransfer event is fired when the document text starts transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

CloudFiles.Transfer Event

This event is fired while a document transfers (delivers document).

Syntax

cloudfiles.on('Transfer', listener: (e: {readonly direction: number, readonly bytesTransferred: number, readonly percentDone: number, readonly text: string, readonly textB: Uint8Array}) => void )

Remarks

The Text parameter contains the portion of the document text being received. It is empty if data are being posted to the server.

The BytesTransferred parameter contains the number of bytes transferred in this Direction since the beginning of the document text (excluding HTTP response headers).

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

Note: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Constructors

public Certificate();

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

public Certificate(String certificateFile);

Opens CertificateFile and reads out the contents as an X509 public key.

public Certificate(byte[] certificateData);

Parses CertificateData as an X509 public key.

public Certificate(int certStoreType, String store, String storePassword, String subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, String store, String storePassword, String subject, String configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CyrptoAPI option. The default value is True (the key is persisted). "Thumbprint" - a MD5, SHA1, or SHA256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, String store, String storePassword, byte[] encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, String subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, String subject, String configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, byte[] encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

CFDirEntry Type

A listing in a directory returned from the server.

Remarks

The DirEntry type contains details about each entry returned after calling ListDirectory.

Fields

Constructors

public CFDirEntry();

CloudFilesAccount Type

This type holds non-OAuth storage account credentials.

Remarks

This type is used to hold account credentials for storages services which do not use OAuth for authentication.

Fields

Constructors

public CloudFilesAccount();

Firewall Type

This is the firewall the class will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall, such as the firewall and the .

Fields

Constructors

public Firewall();

Proxy Type

This is the proxy the class will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the and the .

Fields

Constructors

public Proxy();

public Proxy(String server, int port);

public Proxy(String server, int port, String user, String password);

Config Settings (class cloudstorage.cloudfiles)

<firstlevel>
  <one>value</one>
  <two>
    <item>first</item>
    <item>second</item>
  </two>
  <three>value three</three>
</firstlevel>

{
  "firstlevel": {
    "one": "value",
    "two": ["first", "second"],
    "three": "value three"
  }
}