AzureFile Class

Properties   Methods   Events   Config Settings   Errors  

The AzureFile class provides an easy to use interface to Microsoft's Azure File Storage service.

Syntax

AzureFile

Remarks

The AzureFile class offers an easy-to-use API for the Microsoft Azure File Storage service. Capabilities include uploading and downloading files, strong encryption support, creating folders, file manipulation, and more.

Authentication

Authentication is simple, set the Account property to the name of the Azure Storage account to operate against, and set the AccessKey property to an Azure access key associated with that account.

Addressing Resources

Azure File Storage accounts can contain one or more file shares. Use the ListShares method to list available shares, and select which one the class should operate against using the Share property.

After selecting a share, address the files and folders within it using Linux-style absolute paths. Unless otherwise specified, the class always works in terms of absolute paths, and will always prepend a forward slash (/) to any path passed to it that does not already start with one.

Listing Directory Contents

ListResources lists resources (files and folders) within the specified directory. Calling this method will fire the ResourceList event once for each resource, and will also populate the Resources properties. // ResourceList event handler. azurefile.OnResourceList += (s, e) => { Console.WriteLine(e.Name); }; azurefile.Share = "myshare"; do { azurefile.ListResources("/work_files/serious_business/cats"); for (int i = 0; i < azurefile.Resources.Count; i++) { // Process resources here. } } while (!string.IsNullOrEmpty(azurefile.ResourceMarker));

Downloading Files

The DownloadFile method downloads files.

If a stream has been specified using SetDownloadStream, the file data will be sent through it. If a stream is not specified, and LocalFile is set, the file will be saved to the specified location; otherwise, the file data will be held by ResourceData.

To download and decrypt an encrypted file, set EncryptionAlgorithm and EncryptionPassword before calling this method.

Download Notes

In the simplest use-case, downloading a file looks like this: azurefile.LocalFile = "../MyFile.zip"; azurefile.DownloadFile(azurefile.Resources[0].Path);

Resuming Downloads

The class also supports resuming failed downloads by using the StartByte property. If a download is interrupted, set StartByte to the appropriate offset before calling this method to resume the download. string downloadFile = "../MyFile.zip"; azurefile.LocalFile = downloadFile; azurefile.DownloadFile(azurefile.Resources[0].Path); //The transfer is interrupted and DownloadFile() above fails. Later, resume the download: //Get the size of the partially downloaded file azurefile.StartByte = new FileInfo(downloadFile).Length; azurefile.DownloadFile(azurefile.Resources[0].Path);

Resuming Encrypted File Downloads

Resuming encrypted file downloads is only supported when LocalFile was set in the initial download attempt.

If LocalFile is set when beginning an encrypted download, the class creates a temporary file in TempPath to hold the encrypted data until the download is complete. If the download is interrupted, DownloadTempFile will be populated with the path of the temporary file that holds the partial data.

To resume, 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. azurefile.LocalFile = "../MyFile.zip"; azurefile.EncryptionPassword = "password"; azurefile.DownloadFile(azurefile.Resources[0].Path); //The transfer is interrupted and DownloadFile() above fails. Later, resume the download: //Get the size of the partially download temp file azurefile.StartByte = new FileInfo(azurefile.Config("DownloadTempFile")).Length; azurefile.DownloadFile(azurefile.Resources[0].Path);

Uploading Files

The UploadFile method uploads new files.

If SetUploadStream has been used to set an upload stream, it will take priority as the file data source. If LocalFile is set the file will be uploaded from the specified path. If LocalFile is not set the data in ResourceData will be used.

To encrypt the file before uploading it, set EncryptionAlgorithm and EncryptionPassword.

Upload Notes

The UploadFile method is a convenience method that performs a resumable file upload. When called, the class first uses CreateFile to initialize a new file entry on the server; and then it fragments the file data into smaller pieces and calls PutRange multiple times in succession to upload those fragments. The fragment size is fixed at 4MB (this is a server limitation that cannot be changed).

During the upload, the FragmentComplete event fires after each fragment is uploaded to indicate overall progress. The class also updates StartByte as necessary to indicate the current offset in the file.

If the upload is interrupted for any reason, resuming it is easy. First, verify that StartByte is populated (if the same instance of the class is used, they should already be populated, and no special action should be needed). If uploading from a stream, be sure to reset its position to where it was the first time the upload was started (typically the beginning). Then call UploadFile again to resume the upload at the specified StartByte offset. azurefile.LocalFile = "../MyFile.zip"; azurefile.UploadFile("MyFile.zip"); //The transfer is interrupted and UploadFile() above fails. Later, resume the download. //Using the same instance StartByte is already populated from the previous upload attempt. azurefile.UploadFile("MyFile.zip"); MemoryStream uploadStream = new MemoryStream(File.ReadAllBytes("../MyFile.zip")); azurefile.SetUploadStream(uploadStream); azurefile.UploadFile("MyFile.zip"); //The transfer is interrupted and UploadFile() above fails. Later, resume the download. //Using the same instance StartByte is already populated from the previous upload attempt. //You MUST reset the stream's position to where it was when you first started the upload! uploadStream.Position = 0; azurefile.UploadFile("MyFile.zip");

Additional Functionality

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

• Encrypt and decrypt files using the EncryptionAlgorithm and EncryptionPassword properties.
• Basic file and folder manipulation and organization using methods such as CreateFolder, CopyFile, DeleteFolder, and DeleteFile.
• Advanced file manipulation with CreateFile, ResizeFile, PutRange, GetRanges, and ClearRange.
• Share manipulation with CreateShare, SetShareQuota, and DeleteShare.
• Retrieval of information and metadata for files, folders, and shares using GetFileInfo, GetFolderInfo, and GetShareInfo.
• 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.

AccessKey Property (AzureFile Class)

The Azure access key to use for authentication.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAccessKey();
int SetAccessKey(const char* lpszAccessKey);

Unicode (Windows)
LPWSTR GetAccessKey();
INT SetAccessKey(LPCWSTR lpszAccessKey);

char* cloudstorage_azurefile_getaccesskey(void* lpObj);
int cloudstorage_azurefile_setaccesskey(void* lpObj, const char* lpszAccessKey);

QString GetAccessKey();
int SetAccessKey(QString qsAccessKey);

Default Value

""

Remarks

This property specifies the Azure access key that should be used for authentication. It must be set before attempting any operations which connect to the server.

Both primary and secondary access keys are valid.

This property is not available at design time.

Data Type

String

Account Property (AzureFile Class)

The Azure storage account name.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAccount();
int SetAccount(const char* lpszAccount);

Unicode (Windows)
LPWSTR GetAccount();
INT SetAccount(LPCWSTR lpszAccount);

char* cloudstorage_azurefile_getaccount(void* lpObj);
int cloudstorage_azurefile_setaccount(void* lpObj, const char* lpszAccount);

QString GetAccount();
int SetAccount(QString qsAccount);

Default Value

""

Remarks

This property specifies the name of the Azure storage account to operate against. It must be set before attempting any operations which connect to the server.

This property is not available at design time.

Data Type

String

Authorization Property (AzureFile Class)

OAuth 2.0 Authorization Token.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAuthorization();
int SetAuthorization(const char* lpszAuthorization);

Unicode (Windows)
LPWSTR GetAuthorization();
INT SetAuthorization(LPCWSTR lpszAuthorization);

char* cloudstorage_azurefile_getauthorization(void* lpObj);
int cloudstorage_azurefile_setauthorization(void* lpObj, const char* lpszAuthorization);

QString GetAuthorization();
int SetAuthorization(QString qsAuthorization);

Default Value

""

Remarks

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

Bearer ACCESS_TOKEN

TBD.

Data Type

String

EncryptionAlgorithm Property (AzureFile Class)

The encryption algorithm.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetEncryptionAlgorithm();
int SetEncryptionAlgorithm(int iEncryptionAlgorithm);

Unicode (Windows)
INT GetEncryptionAlgorithm();
INT SetEncryptionAlgorithm(INT iEncryptionAlgorithm);

EA_AES(0), 
EA_BLOWFISH(1), 
EA_CAST(2), 
EA_DES(3), 
EA_IDEA(4), 
EA_RC2(5), 
EA_RC4(6), 
EA_TEA(7), 
EA_TRIPLE_DES(8), 
EA_TWOFISH(9), 
EA_RIJNDAEL(10), 
EA_CHA_CHA(11), 
EA_XSALSA_20(12)

int cloudstorage_azurefile_getencryptionalgorithm(void* lpObj);
int cloudstorage_azurefile_setencryptionalgorithm(void* lpObj, int iEncryptionAlgorithm);

int GetEncryptionAlgorithm();
int SetEncryptionAlgorithm(int iEncryptionAlgorithm);

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:

Data Type

Integer

EncryptionPassword Property (AzureFile Class)

The encryption password.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetEncryptionPassword();
int SetEncryptionPassword(const char* lpszEncryptionPassword);

Unicode (Windows)
LPWSTR GetEncryptionPassword();
INT SetEncryptionPassword(LPCWSTR lpszEncryptionPassword);

char* cloudstorage_azurefile_getencryptionpassword(void* lpObj);
int cloudstorage_azurefile_setencryptionpassword(void* lpObj, const char* lpszEncryptionPassword);

QString GetEncryptionPassword();
int SetEncryptionPassword(QString qsEncryptionPassword);

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.

Data Type

String

Firewall Property (AzureFile Class)

A set of properties related to firewall access.

Syntax

• C++
• C
• Qt

CloudStorageFirewall* GetFirewall();
int SetFirewall(CloudStorageFirewall* val);

int cloudstorage_azurefile_getfirewallautodetect(void* lpObj);
int cloudstorage_azurefile_setfirewallautodetect(void* lpObj, int bFirewallAutoDetect);

int cloudstorage_azurefile_getfirewalltype(void* lpObj);
int cloudstorage_azurefile_setfirewalltype(void* lpObj, int iFirewallType);

char* cloudstorage_azurefile_getfirewallhost(void* lpObj);
int cloudstorage_azurefile_setfirewallhost(void* lpObj, const char* lpszFirewallHost);

char* cloudstorage_azurefile_getfirewallpassword(void* lpObj);
int cloudstorage_azurefile_setfirewallpassword(void* lpObj, const char* lpszFirewallPassword);

int cloudstorage_azurefile_getfirewallport(void* lpObj);
int cloudstorage_azurefile_setfirewallport(void* lpObj, int iFirewallPort);

char* cloudstorage_azurefile_getfirewalluser(void* lpObj);
int cloudstorage_azurefile_setfirewalluser(void* lpObj, const char* lpszFirewallUser);

bool GetFirewallAutoDetect();
int SetFirewallAutoDetect(bool bFirewallAutoDetect);

int GetFirewallType();
int SetFirewallType(int iFirewallType);

QString GetFirewallHost();
int SetFirewallHost(QString qsFirewallHost);

QString GetFirewallPassword();
int SetFirewallPassword(QString qsFirewallPassword);

int GetFirewallPort();
int SetFirewallPort(int iFirewallPort);

QString GetFirewallUser();
int SetFirewallUser(QString qsFirewallUser);

Remarks

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

Data Type

CloudStorageFirewall

Idle Property (AzureFile Class)

The current status of the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIdle();

Unicode (Windows)
BOOL GetIdle();

int cloudstorage_azurefile_getidle(void* lpObj);

bool GetIdle();

Default Value

TRUE

Remarks

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

This property is read-only.

Data Type

Boolean

LocalFile Property (AzureFile Class)

The location of the local file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetLocalFile();
wchar_t* GetLocalFile_W(); // Windows only
int SetLocalFile(const char* lpszLocalFile);
int SetLocalFile(const wchar_t* lpszLocalFile); // Windows only

Unicode (Windows)
LPWSTR GetLocalFile();
INT SetLocalFile(LPCWSTR lpszLocalFile);

char* cloudstorage_azurefile_getlocalfile(void* lpObj);
wchar_t* cloudstorage_azurefile_getlocalfile_W(void* lpObj); // Windows only
int cloudstorage_azurefile_setlocalfile(void* lpObj, const char* lpszLocalFile);
int cloudstorage_azurefile_setlocalfile(void* lpObj, const wchar_t* lpszLocalFile); // Windows only

QString GetLocalFile();
int SetLocalFile(QString qsLocalFile);

Default Value

""

Remarks

This property specifies the location of a file on disk. This is used as the source file when calling UploadFile or PutRange, and as the destination file when calling DownloadFile.

Note that if SetUploadStream or SetDownloadStream is called, the specified stream will be used instead of the file set here.

Data Type

String

LocalHost Property (AzureFile Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetLocalHost();
int SetLocalHost(const char* lpszLocalHost);

Unicode (Windows)
LPWSTR GetLocalHost();
INT SetLocalHost(LPCWSTR lpszLocalHost);

char* cloudstorage_azurefile_getlocalhost(void* lpObj);
int cloudstorage_azurefile_setlocalhost(void* lpObj, const char* lpszLocalHost);

QString GetLocalHost();
int SetLocalHost(QString qsLocalHost);

Default Value

""

Remarks

This 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 multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

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 multihomed 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.

Data Type

String

Metadata Property (AzureFile Class)

A collection of metadata items.

Syntax

• C++
• C
• Qt

CloudStorageList<CloudStorageAzureMetadata>* GetMetadata();
int SetMetadata(CloudStorageList<CloudStorageAzureMetadata>* val);

int cloudstorage_azurefile_getmetadatacount(void* lpObj);
int cloudstorage_azurefile_setmetadatacount(void* lpObj, int iMetadataCount);

char* cloudstorage_azurefile_getmetadataname(void* lpObj, int metadataindex);
int cloudstorage_azurefile_setmetadataname(void* lpObj, int metadataindex, const char* lpszMetadataName);

char* cloudstorage_azurefile_getmetadatavalue(void* lpObj, int metadataindex);
int cloudstorage_azurefile_setmetadatavalue(void* lpObj, int metadataindex, const char* lpszMetadataValue);

int GetMetadataCount();
int SetMetadataCount(int iMetadataCount);

QString GetMetadataName(int iMetadataIndex);
int SetMetadataName(int iMetadataIndex, QString qsMetadataName);

QString GetMetadataValue(int iMetadataIndex);
int SetMetadataValue(int iMetadataIndex, QString qsMetadataValue);

Remarks

This collection holds a list of metadata items.

This collection is populated anytime one of GetFileInfo, GetFolderInfo, or GetShareInfo is called.

The items in this collection may be used by some of the following methods: UpdateMetadata, UploadFile, CreateFile, CopyFile, and CreateFolder.

This property is not available at design time.

Data Type

CloudStorageAzureMetadata

OAuth Property (AzureFile Class)

This property holds the OAuth Settings.

Syntax

• C++
• C
• Qt

CloudStorageOAuthSettings* GetOAuth();

char* cloudstorage_azurefile_getoauthaccesstoken(void* lpObj);
int cloudstorage_azurefile_setoauthaccesstoken(void* lpObj, const char* lpszOAuthAccessToken);

char* cloudstorage_azurefile_getoauthauthorizationcode(void* lpObj);
int cloudstorage_azurefile_setoauthauthorizationcode(void* lpObj, const char* lpszOAuthAuthorizationCode);

char* cloudstorage_azurefile_getoauthauthorizationscope(void* lpObj);
int cloudstorage_azurefile_setoauthauthorizationscope(void* lpObj, const char* lpszOAuthAuthorizationScope);

char* cloudstorage_azurefile_getoauthclientid(void* lpObj);
int cloudstorage_azurefile_setoauthclientid(void* lpObj, const char* lpszOAuthClientId);

int cloudstorage_azurefile_getoauthclientprofile(void* lpObj);
int cloudstorage_azurefile_setoauthclientprofile(void* lpObj, int iOAuthClientProfile);

char* cloudstorage_azurefile_getoauthclientsecret(void* lpObj);
int cloudstorage_azurefile_setoauthclientsecret(void* lpObj, const char* lpszOAuthClientSecret);

int cloudstorage_azurefile_getoauthgranttype(void* lpObj);
int cloudstorage_azurefile_setoauthgranttype(void* lpObj, int iOAuthGrantType);

char* cloudstorage_azurefile_getoauthrefreshtoken(void* lpObj);
int cloudstorage_azurefile_setoauthrefreshtoken(void* lpObj, const char* lpszOAuthRefreshToken);

int cloudstorage_azurefile_getoauthrequestrefreshtoken(void* lpObj);
int cloudstorage_azurefile_setoauthrequestrefreshtoken(void* lpObj, int bOAuthRequestRefreshToken);

char* cloudstorage_azurefile_getoauthreturnurl(void* lpObj);
int cloudstorage_azurefile_setoauthreturnurl(void* lpObj, const char* lpszOAuthReturnURL);

char* cloudstorage_azurefile_getoauthserverauthurl(void* lpObj);
int cloudstorage_azurefile_setoauthserverauthurl(void* lpObj, const char* lpszOAuthServerAuthURL);

char* cloudstorage_azurefile_getoauthservertokenurl(void* lpObj);
int cloudstorage_azurefile_setoauthservertokenurl(void* lpObj, const char* lpszOAuthServerTokenURL);

char* cloudstorage_azurefile_getoauthwebauthurl(void* lpObj);

QString GetOAuthAccessToken();
int SetOAuthAccessToken(QString qsOAuthAccessToken);

QString GetOAuthAuthorizationCode();
int SetOAuthAuthorizationCode(QString qsOAuthAuthorizationCode);

QString GetOAuthAuthorizationScope();
int SetOAuthAuthorizationScope(QString qsOAuthAuthorizationScope);

QString GetOAuthClientId();
int SetOAuthClientId(QString qsOAuthClientId);

int GetOAuthClientProfile();
int SetOAuthClientProfile(int iOAuthClientProfile);

QString GetOAuthClientSecret();
int SetOAuthClientSecret(QString qsOAuthClientSecret);

int GetOAuthGrantType();
int SetOAuthGrantType(int iOAuthGrantType);

QString GetOAuthRefreshToken();
int SetOAuthRefreshToken(QString qsOAuthRefreshToken);

bool GetOAuthRequestRefreshToken();
int SetOAuthRequestRefreshToken(bool bOAuthRequestRefreshToken);

QString GetOAuthReturnURL();
int SetOAuthReturnURL(QString qsOAuthReturnURL);

QString GetOAuthServerAuthURL();
int SetOAuthServerAuthURL(QString qsOAuthServerAuthURL);

QString GetOAuthServerTokenURL();
int SetOAuthServerTokenURL(QString qsOAuthServerTokenURL);

QString GetOAuthWebAuthURL();

Remarks

This property is used to define the necessary fields to authenticate with the service provider. See the introduction for more information.

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

Data Type

CloudStorageOAuthSettings

OtherHeaders Property (AzureFile Class)

Other headers as determined by the user (optional).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOtherHeaders();
int SetOtherHeaders(const char* lpszOtherHeaders);

Unicode (Windows)
LPWSTR GetOtherHeaders();
INT SetOtherHeaders(LPCWSTR lpszOtherHeaders);

char* cloudstorage_azurefile_getotherheaders(void* lpObj);
int cloudstorage_azurefile_setotherheaders(void* lpObj, const char* lpszOtherHeaders);

QString GetOtherHeaders();
int SetOtherHeaders(QString qsOtherHeaders);

Default Value

""

Remarks

This property can be set to a string of headers to be appended to the HTTP request headers created from other properties like ContentType and From.

The headers must follow the format Header: Value as described in the HTTP specifications. Header lines should be separated by CRLF ("\r\n") .

Use this property with caution. If this property contains invalid headers, HTTP requests may fail.

This property is useful for extending the functionality of the class beyond what is provided.

This property is not available at design time.

Data Type

String

Overwrite Property (AzureFile Class)

Determines if files are overwritten.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOverwrite();
int SetOverwrite(int bOverwrite);

Unicode (Windows)
BOOL GetOverwrite();
INT SetOverwrite(BOOL bOverwrite);

int cloudstorage_azurefile_getoverwrite(void* lpObj);
int cloudstorage_azurefile_setoverwrite(void* lpObj, int bOverwrite);

bool GetOverwrite();
int SetOverwrite(bool bOverwrite);

Default Value

FALSE

Remarks

This property controls whether local files are overwritten when calling DownloadFile or remote files are renamed when calling RenameFile. The default value is false.

Data Type

Boolean

ParsedHeaders Property (AzureFile Class)

This property includes a collection of headers returned from the last request.

Syntax

• C++
• C
• Qt

CloudStorageList<CloudStorageHeader>* GetParsedHeaders();

int cloudstorage_azurefile_getparsedheadercount(void* lpObj);

char* cloudstorage_azurefile_getparsedheaderfield(void* lpObj, int parsedheaderindex);

char* cloudstorage_azurefile_getparsedheadervalue(void* lpObj, int parsedheaderindex);

int GetParsedHeaderCount();

QString GetParsedHeaderField(int iParsedHeaderIndex);

QString GetParsedHeaderValue(int iParsedHeaderIndex);

Remarks

This property contains a collection of headers returned from the last request. Whenever headers are returned from the server, the headers are parsed into a collection of headers. Each Header in this collection contains information describing that header.

MaxHeaders can be used to control the maximum number of headers saved.

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

Data Type

CloudStorageHeader

Prefix Property (AzureFile Class)

A prefix used to restrict the results returned when listing resources or shares.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetPrefix();
int SetPrefix(const char* lpszPrefix);

Unicode (Windows)
LPWSTR GetPrefix();
INT SetPrefix(LPCWSTR lpszPrefix);

char* cloudstorage_azurefile_getprefix(void* lpObj);
int cloudstorage_azurefile_setprefix(void* lpObj, const char* lpszPrefix);

QString GetPrefix();
int SetPrefix(QString qsPrefix);

Default Value

""

Remarks

This property, if non-empty, is used to restrict the results returned by ListResources or ListShares to only the items whose names begin with the given value.

This property is not available at design time.

Data Type

String

Proxy Property (AzureFile Class)

A set of properties related to proxy access.

Syntax

• C++
• C
• Qt

CloudStorageProxy* GetProxy();
int SetProxy(CloudStorageProxy* val);

int cloudstorage_azurefile_getproxyauthscheme(void* lpObj);
int cloudstorage_azurefile_setproxyauthscheme(void* lpObj, int iProxyAuthScheme);

int cloudstorage_azurefile_getproxyautodetect(void* lpObj);
int cloudstorage_azurefile_setproxyautodetect(void* lpObj, int bProxyAutoDetect);

char* cloudstorage_azurefile_getproxypassword(void* lpObj);
int cloudstorage_azurefile_setproxypassword(void* lpObj, const char* lpszProxyPassword);

int cloudstorage_azurefile_getproxyport(void* lpObj);
int cloudstorage_azurefile_setproxyport(void* lpObj, int iProxyPort);

char* cloudstorage_azurefile_getproxyserver(void* lpObj);
int cloudstorage_azurefile_setproxyserver(void* lpObj, const char* lpszProxyServer);

int cloudstorage_azurefile_getproxyssl(void* lpObj);
int cloudstorage_azurefile_setproxyssl(void* lpObj, int iProxySSL);

char* cloudstorage_azurefile_getproxyuser(void* lpObj);
int cloudstorage_azurefile_setproxyuser(void* lpObj, const char* lpszProxyUser);

int GetProxyAuthScheme();
int SetProxyAuthScheme(int iProxyAuthScheme);

bool GetProxyAutoDetect();
int SetProxyAutoDetect(bool bProxyAutoDetect);

QString GetProxyPassword();
int SetProxyPassword(QString qsProxyPassword);

int GetProxyPort();
int SetProxyPort(int iProxyPort);

QString GetProxyServer();
int SetProxyServer(QString qsProxyServer);

int GetProxySSL();
int SetProxySSL(int iProxySSL);

QString GetProxyUser();
int SetProxyUser(QString qsProxyUser);

Remarks

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

Data Type

CloudStorageProxy

QueryParams Property (AzureFile Class)

Additional query parameters to be included in the request.

Syntax

• C++
• C
• Qt

CloudStorageList<CloudStorageQueryParam>* GetQueryParams();
int SetQueryParams(CloudStorageList<CloudStorageQueryParam>* val);

int cloudstorage_azurefile_getqueryparamcount(void* lpObj);
int cloudstorage_azurefile_setqueryparamcount(void* lpObj, int iQueryParamCount);

char* cloudstorage_azurefile_getqueryparamname(void* lpObj, int queryparamindex);
int cloudstorage_azurefile_setqueryparamname(void* lpObj, int queryparamindex, const char* lpszQueryParamName);

char* cloudstorage_azurefile_getqueryparamvalue(void* lpObj, int queryparamindex);
int cloudstorage_azurefile_setqueryparamvalue(void* lpObj, int queryparamindex, const char* lpszQueryParamValue);

int GetQueryParamCount();
int SetQueryParamCount(int iQueryParamCount);

QString GetQueryParamName(int iQueryParamIndex);
int SetQueryParamName(int iQueryParamIndex, QString qsQueryParamName);

QString GetQueryParamValue(int iQueryParamIndex);
int SetQueryParamValue(int iQueryParamIndex, QString qsQueryParamValue);

Remarks

This is a collection of query parameters that will be added to the request. Parameters can be added via the AddQueryParam method.

Data Type

CloudStorageQueryParam

Ranges Property (AzureFile Class)

A collection of byte ranges.

Syntax

• C++
• C
• Qt

CloudStorageList<CloudStorageAzureRange>* GetRanges();

int cloudstorage_azurefile_getrangecount(void* lpObj);

int64 cloudstorage_azurefile_getrangefirst(void* lpObj, int rangeindex);

int64 cloudstorage_azurefile_getrangelast(void* lpObj, int rangeindex);

int GetRangeCount();

qint64 GetRangeFirst(int iRangeIndex);

qint64 GetRangeLast(int iRangeIndex);

Remarks

This collection holds a list of byte ranges.

Calling GetRanges will populate this collection.

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

Data Type

CloudStorageAzureRange

ResourceData Property (AzureFile Class)

The data that was downloaded, or that should be uploaded.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetResourceData(char* &lpResourceData, int &lenResourceData);
int SetResourceData(const char* lpResourceData, int lenResourceData);

Unicode (Windows)
INT GetResourceData(LPSTR &lpResourceData, INT &lenResourceData);
INT SetResourceData(LPCSTR lpResourceData, INT lenResourceData);

int cloudstorage_azurefile_getresourcedata(void* lpObj, char** lpResourceData, int* lenResourceData);
int cloudstorage_azurefile_setresourcedata(void* lpObj, const char* lpResourceData, int lenResourceData);

QByteArray GetResourceData();
int SetResourceData(QByteArray qbaResourceData);

Default Value

""

Remarks

This property is populated with file data after calling DownloadFile if SetDownloadStream and LocalFile are not set.

This property can also be set before calling UploadFile; its data will be uploaded if SetUploadStream and LocalFile are not set.

This property is not available at design time.

Data Type

Binary String

ResourceMarker Property (AzureFile Class)

A marker indicating what page of resources to return next.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetResourceMarker();
int SetResourceMarker(const char* lpszResourceMarker);

Unicode (Windows)
LPWSTR GetResourceMarker();
INT SetResourceMarker(LPCWSTR lpszResourceMarker);

char* cloudstorage_azurefile_getresourcemarker(void* lpObj);
int cloudstorage_azurefile_setresourcemarker(void* lpObj, const char* lpszResourceMarker);

QString GetResourceMarker();
int SetResourceMarker(QString qsResourceMarker);

Default Value

""

Remarks

This property will be populated when ListResources is called if the results are paged and there are more pages. To list all resources, continue to call ListResources until this property returns empty string.

Refer to ListResources for more information.

This property is not available at design time.

Data Type

String

Resources Property (AzureFile Class)

A collection of resources.

Syntax

• C++
• C
• Qt

CloudStorageList<CloudStorageAzureFileResource>* GetResources();

int cloudstorage_azurefile_getresourcecount(void* lpObj);

char* cloudstorage_azurefile_getresourcecontentmd5(void* lpObj, int resourceindex);

char* cloudstorage_azurefile_getresourcecontenttype(void* lpObj, int resourceindex);

char* cloudstorage_azurefile_getresourceetag(void* lpObj, int resourceindex);

char* cloudstorage_azurefile_getresourcemodifiedtime(void* lpObj, int resourceindex);

char* cloudstorage_azurefile_getresourcename(void* lpObj, int resourceindex);

char* cloudstorage_azurefile_getresourcepath(void* lpObj, int resourceindex);

char* cloudstorage_azurefile_getresourceshare(void* lpObj, int resourceindex);

int64 cloudstorage_azurefile_getresourcesize(void* lpObj, int resourceindex);

int cloudstorage_azurefile_getresourcetype(void* lpObj, int resourceindex);

int GetResourceCount();

QString GetResourceContentMD5(int iResourceIndex);

QString GetResourceContentType(int iResourceIndex);

QString GetResourceETag(int iResourceIndex);

QString GetResourceModifiedTime(int iResourceIndex);

QString GetResourceName(int iResourceIndex);

QString GetResourcePath(int iResourceIndex);

QString GetResourceShare(int iResourceIndex);

qint64 GetResourceSize(int iResourceIndex);

int GetResourceType(int iResourceIndex);

Remarks

This collection holds a list of file and folder resources.

Calling ListResources or GetResourceInfo will populate this collection.

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

Data Type

CloudStorageAzureFileResource

Share Property (AzureFile Class)

Selects a share.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetShare();
int SetShare(const char* lpszShare);

Unicode (Windows)
LPWSTR GetShare();
INT SetShare(LPCWSTR lpszShare);

char* cloudstorage_azurefile_getshare(void* lpObj);
int cloudstorage_azurefile_setshare(void* lpObj, const char* lpszShare);

QString GetShare();
int SetShare(QString qsShare);

Default Value

""

Remarks

This property selects a share, by name, for the class to operate against. It must be set before attempting most operations.

Share Name Rules

Share names must adhere to the following rules:

• Must be 3 to 63 characters long.
• Must start with a letter or number; and may only contain letters, numbers, and hyphens.
• All letters much be lowercase. (For convenience, the class will automatically lowercase all letters in any value assigned to Share.)
• All hyphens must be immediately preceded and followed by a letter or number (consecutive hyphens are not allowed).

This property is not available at design time.

Data Type

String

ShareMarker Property (AzureFile Class)

A marker indicating what page of shares to return next.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetShareMarker();
int SetShareMarker(const char* lpszShareMarker);

Unicode (Windows)
LPWSTR GetShareMarker();
INT SetShareMarker(LPCWSTR lpszShareMarker);

char* cloudstorage_azurefile_getsharemarker(void* lpObj);
int cloudstorage_azurefile_setsharemarker(void* lpObj, const char* lpszShareMarker);

QString GetShareMarker();
int SetShareMarker(QString qsShareMarker);

Default Value

""

Remarks

This property will be populated when ListShares is called if the results are paged and there are more pages. To list all shares, continue to call ListShares until this property returns empty string.

Refer to ListShares for more information.

This property is not available at design time.

Data Type

String

Shares Property (AzureFile Class)

A collection of shares.

Syntax

• C++
• C
• Qt

CloudStorageList<CloudStorageAzureFileShare>* GetShares();

int cloudstorage_azurefile_getsharecount(void* lpObj);

char* cloudstorage_azurefile_getshareetag(void* lpObj, int shareindex);

char* cloudstorage_azurefile_getsharemodifiedtime(void* lpObj, int shareindex);

char* cloudstorage_azurefile_getsharename(void* lpObj, int shareindex);

int cloudstorage_azurefile_getsharequota(void* lpObj, int shareindex);

int cloudstorage_azurefile_getsharespaceused(void* lpObj, int shareindex);

int GetShareCount();

QString GetShareETag(int iShareIndex);

QString GetShareModifiedTime(int iShareIndex);

QString GetShareName(int iShareIndex);

int GetShareQuota(int iShareIndex);

int GetShareSpaceUsed(int iShareIndex);

Remarks

This collection holds a list of shares.

Calling ListShares or GetShareInfo will populate this collection.

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

Data Type

CloudStorageAzureFileShare

SSLAcceptServerCert Property (AzureFile Class)

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

Syntax

• C++
• C
• Qt

CloudStorageCertificate* GetSSLAcceptServerCert();
int SetSSLAcceptServerCert(CloudStorageCertificate* val);

char* cloudstorage_azurefile_getsslacceptservercerteffectivedate(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertexpirationdate(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertextendedkeyusage(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertfingerprint(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertfingerprintsha1(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertfingerprintsha256(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertissuer(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertprivatekey(void* lpObj);

int cloudstorage_azurefile_getsslacceptservercertprivatekeyavailable(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertprivatekeycontainer(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertpublickey(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertpublickeyalgorithm(void* lpObj);

int cloudstorage_azurefile_getsslacceptservercertpublickeylength(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertserialnumber(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertsignaturealgorithm(void* lpObj);

int cloudstorage_azurefile_getsslacceptservercertstore(void* lpObj, char** lpSSLAcceptServerCertStore, int* lenSSLAcceptServerCertStore);
int cloudstorage_azurefile_setsslacceptservercertstore(void* lpObj, const char* lpSSLAcceptServerCertStore, int lenSSLAcceptServerCertStore);

char* cloudstorage_azurefile_getsslacceptservercertstorepassword(void* lpObj);
int cloudstorage_azurefile_setsslacceptservercertstorepassword(void* lpObj, const char* lpszSSLAcceptServerCertStorePassword);

int cloudstorage_azurefile_getsslacceptservercertstoretype(void* lpObj);
int cloudstorage_azurefile_setsslacceptservercertstoretype(void* lpObj, int iSSLAcceptServerCertStoreType);

char* cloudstorage_azurefile_getsslacceptservercertsubjectaltnames(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertthumbprintmd5(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertthumbprintsha1(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertthumbprintsha256(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertusage(void* lpObj);

int cloudstorage_azurefile_getsslacceptservercertusageflags(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertversion(void* lpObj);

char* cloudstorage_azurefile_getsslacceptservercertsubject(void* lpObj);
int cloudstorage_azurefile_setsslacceptservercertsubject(void* lpObj, const char* lpszSSLAcceptServerCertSubject);

int cloudstorage_azurefile_getsslacceptservercertencoded(void* lpObj, char** lpSSLAcceptServerCertEncoded, int* lenSSLAcceptServerCertEncoded);
int cloudstorage_azurefile_setsslacceptservercertencoded(void* lpObj, const char* lpSSLAcceptServerCertEncoded, int lenSSLAcceptServerCertEncoded);

QString GetSSLAcceptServerCertEffectiveDate();

QString GetSSLAcceptServerCertExpirationDate();

QString GetSSLAcceptServerCertExtendedKeyUsage();

QString GetSSLAcceptServerCertFingerprint();

QString GetSSLAcceptServerCertFingerprintSHA1();

QString GetSSLAcceptServerCertFingerprintSHA256();

QString GetSSLAcceptServerCertIssuer();

QString GetSSLAcceptServerCertPrivateKey();

bool GetSSLAcceptServerCertPrivateKeyAvailable();

QString GetSSLAcceptServerCertPrivateKeyContainer();

QString GetSSLAcceptServerCertPublicKey();

QString GetSSLAcceptServerCertPublicKeyAlgorithm();

int GetSSLAcceptServerCertPublicKeyLength();

QString GetSSLAcceptServerCertSerialNumber();

QString GetSSLAcceptServerCertSignatureAlgorithm();

QByteArray GetSSLAcceptServerCertStore();
int SetSSLAcceptServerCertStore(QByteArray qbaSSLAcceptServerCertStore);

QString GetSSLAcceptServerCertStorePassword();
int SetSSLAcceptServerCertStorePassword(QString qsSSLAcceptServerCertStorePassword);

int GetSSLAcceptServerCertStoreType();
int SetSSLAcceptServerCertStoreType(int iSSLAcceptServerCertStoreType);

QString GetSSLAcceptServerCertSubjectAltNames();

QString GetSSLAcceptServerCertThumbprintMD5();

QString GetSSLAcceptServerCertThumbprintSHA1();

QString GetSSLAcceptServerCertThumbprintSHA256();

QString GetSSLAcceptServerCertUsage();

int GetSSLAcceptServerCertUsageFlags();

QString GetSSLAcceptServerCertVersion();

QString GetSSLAcceptServerCertSubject();
int SetSSLAcceptServerCertSubject(QString qsSSLAcceptServerCertSubject);

QByteArray GetSSLAcceptServerCertEncoded();
int SetSSLAcceptServerCertEncoded(QByteArray qbaSSLAcceptServerCertEncoded);

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.

Note: This functionality is provided only for cases in which 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.

Data Type

CloudStorageCertificate

SSLCert Property (AzureFile Class)

The certificate to be used during Secure Sockets Layer (SSL) negotiation.

Syntax

• C++
• C
• Qt

CloudStorageCertificate* GetSSLCert();
int SetSSLCert(CloudStorageCertificate* val);

char* cloudstorage_azurefile_getsslcerteffectivedate(void* lpObj);

char* cloudstorage_azurefile_getsslcertexpirationdate(void* lpObj);

char* cloudstorage_azurefile_getsslcertextendedkeyusage(void* lpObj);

char* cloudstorage_azurefile_getsslcertfingerprint(void* lpObj);

char* cloudstorage_azurefile_getsslcertfingerprintsha1(void* lpObj);

char* cloudstorage_azurefile_getsslcertfingerprintsha256(void* lpObj);

char* cloudstorage_azurefile_getsslcertissuer(void* lpObj);

char* cloudstorage_azurefile_getsslcertprivatekey(void* lpObj);

int cloudstorage_azurefile_getsslcertprivatekeyavailable(void* lpObj);

char* cloudstorage_azurefile_getsslcertprivatekeycontainer(void* lpObj);

char* cloudstorage_azurefile_getsslcertpublickey(void* lpObj);

char* cloudstorage_azurefile_getsslcertpublickeyalgorithm(void* lpObj);

int cloudstorage_azurefile_getsslcertpublickeylength(void* lpObj);

char* cloudstorage_azurefile_getsslcertserialnumber(void* lpObj);

char* cloudstorage_azurefile_getsslcertsignaturealgorithm(void* lpObj);

int cloudstorage_azurefile_getsslcertstore(void* lpObj, char** lpSSLCertStore, int* lenSSLCertStore);
int cloudstorage_azurefile_setsslcertstore(void* lpObj, const char* lpSSLCertStore, int lenSSLCertStore);

char* cloudstorage_azurefile_getsslcertstorepassword(void* lpObj);
int cloudstorage_azurefile_setsslcertstorepassword(void* lpObj, const char* lpszSSLCertStorePassword);

int cloudstorage_azurefile_getsslcertstoretype(void* lpObj);
int cloudstorage_azurefile_setsslcertstoretype(void* lpObj, int iSSLCertStoreType);

char* cloudstorage_azurefile_getsslcertsubjectaltnames(void* lpObj);

char* cloudstorage_azurefile_getsslcertthumbprintmd5(void* lpObj);

char* cloudstorage_azurefile_getsslcertthumbprintsha1(void* lpObj);

char* cloudstorage_azurefile_getsslcertthumbprintsha256(void* lpObj);

char* cloudstorage_azurefile_getsslcertusage(void* lpObj);

int cloudstorage_azurefile_getsslcertusageflags(void* lpObj);

char* cloudstorage_azurefile_getsslcertversion(void* lpObj);

char* cloudstorage_azurefile_getsslcertsubject(void* lpObj);
int cloudstorage_azurefile_setsslcertsubject(void* lpObj, const char* lpszSSLCertSubject);

int cloudstorage_azurefile_getsslcertencoded(void* lpObj, char** lpSSLCertEncoded, int* lenSSLCertEncoded);
int cloudstorage_azurefile_setsslcertencoded(void* lpObj, const char* lpSSLCertEncoded, int lenSSLCertEncoded);

QString GetSSLCertEffectiveDate();

QString GetSSLCertExpirationDate();

QString GetSSLCertExtendedKeyUsage();

QString GetSSLCertFingerprint();

QString GetSSLCertFingerprintSHA1();

QString GetSSLCertFingerprintSHA256();

QString GetSSLCertIssuer();

QString GetSSLCertPrivateKey();

bool GetSSLCertPrivateKeyAvailable();

QString GetSSLCertPrivateKeyContainer();

QString GetSSLCertPublicKey();

QString GetSSLCertPublicKeyAlgorithm();

int GetSSLCertPublicKeyLength();

QString GetSSLCertSerialNumber();

QString GetSSLCertSignatureAlgorithm();

QByteArray GetSSLCertStore();
int SetSSLCertStore(QByteArray qbaSSLCertStore);

QString GetSSLCertStorePassword();
int SetSSLCertStorePassword(QString qsSSLCertStorePassword);

int GetSSLCertStoreType();
int SetSSLCertStoreType(int iSSLCertStoreType);

QString GetSSLCertSubjectAltNames();

QString GetSSLCertThumbprintMD5();

QString GetSSLCertThumbprintSHA1();

QString GetSSLCertThumbprintSHA256();

QString GetSSLCertUsage();

int GetSSLCertUsageFlags();

QString GetSSLCertVersion();

QString GetSSLCertSubject();
int SetSSLCertSubject(QString qsSSLCertSubject);

QByteArray GetSSLCertEncoded();
int SetSSLCertEncoded(QByteArray qbaSSLCertEncoded);

Remarks

This property includes 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 Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

Data Type

CloudStorageCertificate

SSLProvider Property (AzureFile Class)

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLProvider();
int SetSSLProvider(int iSSLProvider);

Unicode (Windows)
INT GetSSLProvider();
INT SetSSLProvider(INT iSSLProvider);

SSLP_AUTOMATIC(0), 
SSLP_PLATFORM(1), 
SSLP_INTERNAL(2)

int cloudstorage_azurefile_getsslprovider(void* lpObj);
int cloudstorage_azurefile_setsslprovider(void* lpObj, int iSSLProvider);

int GetSSLProvider();
int SetSSLProvider(int iSSLProvider);

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 as follows:

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, on Windows, the class will use the platform implementation. On Linux/macOS, the class will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols, the internal implementation is used on all platforms.

Data Type

Integer

SSLServerCert Property (AzureFile Class)

The server certificate for the last established connection.

Syntax

• C++
• C
• Qt

CloudStorageCertificate* GetSSLServerCert();

char* cloudstorage_azurefile_getsslservercerteffectivedate(void* lpObj);

char* cloudstorage_azurefile_getsslservercertexpirationdate(void* lpObj);

char* cloudstorage_azurefile_getsslservercertextendedkeyusage(void* lpObj);

char* cloudstorage_azurefile_getsslservercertfingerprint(void* lpObj);

char* cloudstorage_azurefile_getsslservercertfingerprintsha1(void* lpObj);

char* cloudstorage_azurefile_getsslservercertfingerprintsha256(void* lpObj);

char* cloudstorage_azurefile_getsslservercertissuer(void* lpObj);

char* cloudstorage_azurefile_getsslservercertprivatekey(void* lpObj);

int cloudstorage_azurefile_getsslservercertprivatekeyavailable(void* lpObj);

char* cloudstorage_azurefile_getsslservercertprivatekeycontainer(void* lpObj);

char* cloudstorage_azurefile_getsslservercertpublickey(void* lpObj);

char* cloudstorage_azurefile_getsslservercertpublickeyalgorithm(void* lpObj);

int cloudstorage_azurefile_getsslservercertpublickeylength(void* lpObj);

char* cloudstorage_azurefile_getsslservercertserialnumber(void* lpObj);

char* cloudstorage_azurefile_getsslservercertsignaturealgorithm(void* lpObj);

int cloudstorage_azurefile_getsslservercertstore(void* lpObj, char** lpSSLServerCertStore, int* lenSSLServerCertStore);

char* cloudstorage_azurefile_getsslservercertstorepassword(void* lpObj);

int cloudstorage_azurefile_getsslservercertstoretype(void* lpObj);

char* cloudstorage_azurefile_getsslservercertsubjectaltnames(void* lpObj);

char* cloudstorage_azurefile_getsslservercertthumbprintmd5(void* lpObj);

char* cloudstorage_azurefile_getsslservercertthumbprintsha1(void* lpObj);

char* cloudstorage_azurefile_getsslservercertthumbprintsha256(void* lpObj);

char* cloudstorage_azurefile_getsslservercertusage(void* lpObj);

int cloudstorage_azurefile_getsslservercertusageflags(void* lpObj);

char* cloudstorage_azurefile_getsslservercertversion(void* lpObj);

char* cloudstorage_azurefile_getsslservercertsubject(void* lpObj);

int cloudstorage_azurefile_getsslservercertencoded(void* lpObj, char** lpSSLServerCertEncoded, int* lenSSLServerCertEncoded);

QString GetSSLServerCertEffectiveDate();

QString GetSSLServerCertExpirationDate();

QString GetSSLServerCertExtendedKeyUsage();

QString GetSSLServerCertFingerprint();

QString GetSSLServerCertFingerprintSHA1();

QString GetSSLServerCertFingerprintSHA256();

QString GetSSLServerCertIssuer();

QString GetSSLServerCertPrivateKey();

bool GetSSLServerCertPrivateKeyAvailable();

QString GetSSLServerCertPrivateKeyContainer();

QString GetSSLServerCertPublicKey();

QString GetSSLServerCertPublicKeyAlgorithm();

int GetSSLServerCertPublicKeyLength();

QString GetSSLServerCertSerialNumber();

QString GetSSLServerCertSignatureAlgorithm();

QByteArray GetSSLServerCertStore();

QString GetSSLServerCertStorePassword();

int GetSSLServerCertStoreType();

QString GetSSLServerCertSubjectAltNames();

QString GetSSLServerCertThumbprintMD5();

QString GetSSLServerCertThumbprintSHA1();

QString GetSSLServerCertThumbprintSHA256();

QString GetSSLServerCertUsage();

int GetSSLServerCertUsageFlags();

QString GetSSLServerCertVersion();

QString GetSSLServerCertSubject();

QByteArray GetSSLServerCertEncoded();

Remarks

This property contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Data Type

CloudStorageCertificate

StartByte Property (AzureFile Class)

The byte offset from which to start the upload or download.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetStartByte();
int SetStartByte(int64 lStartByte);

Unicode (Windows)
LONG64 GetStartByte();
INT SetStartByte(LONG64 lStartByte);

int64 cloudstorage_azurefile_getstartbyte(void* lpObj);
int cloudstorage_azurefile_setstartbyte(void* lpObj, int64 lStartByte);

qint64 GetStartByte();
int SetStartByte(qint64 lStartByte);

Default Value

0

Remarks

This property may be set to resume an upload or download; it specifies the offset in the file (or stream, when uploading) from which to resume. See UploadFile and DownloadFile for details about resuming uploads and downloads.

When uploading from a stream, the class will always seek forward in the stream if the value of StartByte is greater than 0 when UploadFile is called. Keep this in mind when resuming interrupted uploads.

This property is not available at design time.

Data Type

Long64

Timeout Property (AzureFile Class)

The timeout for the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTimeout();
int SetTimeout(int iTimeout);

Unicode (Windows)
INT GetTimeout();
INT SetTimeout(INT iTimeout);

int cloudstorage_azurefile_gettimeout(void* lpObj);
int cloudstorage_azurefile_settimeout(void* lpObj, int iTimeout);

int GetTimeout();
int SetTimeout(int iTimeout);

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 fails with an error.

Note: By default, all timeouts are inactivity timeouts, that is, 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.

Data Type

Integer

UseSSL Property (AzureFile Class)

Whether to use SSL/TLS when connecting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseSSL();
int SetUseSSL(int bUseSSL);

Unicode (Windows)
BOOL GetUseSSL();
INT SetUseSSL(BOOL bUseSSL);

int cloudstorage_azurefile_getusessl(void* lpObj);
int cloudstorage_azurefile_setusessl(void* lpObj, int bUseSSL);

bool GetUseSSL();
int SetUseSSL(bool bUseSSL);

Default Value

TRUE

Remarks

This property specifies whether the class should use SSL/TLS when connecting.

This property is not available at design time.

Data Type

Boolean

AbortCopy Method (AzureFile Class)

Aborts a copy operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AbortCopy(const char* lpszDestFilePath, const char* lpszCopyId);

Unicode (Windows)
INT AbortCopy(LPCWSTR lpszDestFilePath, LPCWSTR lpszCopyId);

int cloudstorage_azurefile_abortcopy(void* lpObj, const char* lpszDestFilePath, const char* lpszCopyId);

int AbortCopy(const QString& qsDestFilePath, const QString& qsCopyId);

Remarks

This method aborts the copy operation identified by the given CopyId for the destination file at DestFilePath in the share currently selected by Share.

Note that the destination file will still exist after aborting a copy operation, but it will be empty.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

AddMetadata Method (AzureFile Class)

Adds a metadata item to the Metadata properties.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddMetadata(const char* lpszName, const char* lpszValue);

Unicode (Windows)
INT AddMetadata(LPCWSTR lpszName, LPCWSTR lpszValue);

int cloudstorage_azurefile_addmetadata(void* lpObj, const char* lpszName, const char* lpszValue);

int AddMetadata(const QString& qsName, const QString& qsValue);

Remarks

This method adds a metadata item to the Metadata properties. Name specifies the name of the item, and Value specifies the value of the item.

Note that the class will automatically prepend x-ms-meta- to metadata item names (as necessary) when they are submitted to the server. Also note that while metadata item names are case-preserving, they are not case-sensitive.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

AddQueryParam Method (AzureFile Class)

Adds a query parameter to the QueryParams properties.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddQueryParam(const char* lpszName, const char* lpszValue);

Unicode (Windows)
INT AddQueryParam(LPCWSTR lpszName, LPCWSTR lpszValue);

int cloudstorage_azurefile_addqueryparam(void* lpObj, const char* lpszName, const char* lpszValue);

int AddQueryParam(const QString& qsName, const QString& qsValue);

Remarks

This method is used to add a query parameter to the QueryParams properties. Name specifies the name of the parameter, and Value specifies the value of the parameter.

All specified Values will be URL encoded by the class automatically. Consult the service documentation for details on the available parameters.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Authorize Method (AzureFile Class)

Get the authorization string required to access the protected resource.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Authorize();

Unicode (Windows)
INT Authorize();

int cloudstorage_azurefile_authorize(void* lpObj);

int Authorize();

Remarks

This method is used to get an access token that is required to access the protected resource. The method will act differently based on what is set in the ClientProfile field and the GrantType field. This method is not to be used in conjunction with the Authorization property. It should instead be used when setting the OAuth property.

For more information, see the introduction section.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ClearRange Method (AzureFile Class)

Clears a range of bytes from a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ClearRange(const char* lpszFilePath, int64 lFirst, int64 lLast);

Unicode (Windows)
INT ClearRange(LPCWSTR lpszFilePath, LONG64 lFirst, LONG64 lLast);

int cloudstorage_azurefile_clearrange(void* lpObj, const char* lpszFilePath, int64 lFirst, int64 lLast);

int ClearRange(const QString& qsFilePath, qint64 lFirst, qint64 lLast);

Remarks

This method clears the range of bytes from First to Last (inclusive) from the file at FilePath in the share currently selected by Share.

The server tracks ranges of file data in 512-byte chunks, aligned to the absolute beginning of the file. When this method is called, the server frees any such chunks that are completely covered by the specified range of bytes ([First]-[Last]), and writes 0s to the appropriate portions of any chunks which are not completely covered by that range.

Freed chunks are not included in the results returned by GetRanges.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (AzureFile Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* cloudstorage_azurefile_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CopyFile Method (AzureFile Class)

Copies a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* CopyFile(const char* lpszFromFilePath, const char* lpszToFilePath, const char* lpszToShare);

Unicode (Windows)
LPWSTR CopyFile(LPCWSTR lpszFromFilePath, LPCWSTR lpszToFilePath, LPCWSTR lpszToShare);

char* cloudstorage_azurefile_copyfile(void* lpObj, const char* lpszFromFilePath, const char* lpszToFilePath, const char* lpszToShare);

QString CopyFile(const QString& qsFromFilePath, const QString& qsToFilePath, const QString& qsToShare);

Remarks

This method copies the file at FromFilePath (in the share currently selected by Share) to the path ToFilePath in the share ToShare. If this method finishes successfully, it will either return an asynchronous copy operation Id, or an empty string (if the copy has finished already).

If ToShare is empty, the current value of Share will be used instead. If ToShare is non-empty, the value will automatically be lowercased when preparing the request.

Any parent folders included in ToFilePath must already exist.

If the destination file already exists, it will be overwritten.

As long as the server doesn't return an error, this method will always populate the CopyId and CopyStatus configuration settings (and clear CopyProgress and CopyStatusDesc).

Asynchronous Copy Notes

As mentioned, this method will return a copy operation Id if the copy operation was started asynchronously. In this case, use the GetFileInfo method to poll the destination file's information, which will cause the CopyStatus, CopyStatusDesc, and CopyProgress configuration settings to be refreshed.

A copy operation whose CopyStatus is still pending may also be aborted by passing the copy operation Id returned by this method (or later retrieved from CopyId) to the AbortCopy method. // Copy a file to another location within the same share. string copyResult = azurefile.CopyFile("/folder1/important.zip", "/folder2/secrets.zip", ""); // If the returned value *isn't* empty string, then we'll monitor the status of the // asynchronous copy operation by polling once every 2 seconds using GetFileInfo(). if (!string.IsNullOrEmpty(copyResult)) { do { azurefile.GetFileInfo("/folder2/secrets.zip"); Console.WriteLine("Copy progress: " + azurefile.Config("CopyProgress")); } while (azurefile.Config("CopyStatus") == "pending"); }

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateFile Method (AzureFile Class)

Initializes a new file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* CreateFile(const char* lpszNewFilePath, int64 lFileLength);

Unicode (Windows)
LPWSTR CreateFile(LPCWSTR lpszNewFilePath, LONG64 lFileLength);

char* cloudstorage_azurefile_createfile(void* lpObj, const char* lpszNewFilePath, int64 lFileLength);

QString CreateFile(const QString& qsNewFilePath, qint64 lFileLength);

Remarks

This method initializes a new file with a given FileLength (in bytes) at the specified NewFilePath in the share currently selected by Share. The path of the newly-initialized file is returned.

Any parent folders included in NewFilePath must already exist.

If the SendMetadata configuration setting is enabled when this method is called, all items in the Metadata properties will be sent along with the creation request.

Note: This method is typically only useful for advanced use-cases. To upload a file, just call UploadFile.

Usage Notes

This method does not upload or otherwise allocate any data, it just creates the file entry and "reserves" storage space for it. After a file has been created with this method, the following methods can be used to manipulate its data:

• The PutRange method can be used to upload ranges of data (up to 4MB at once) to the file.
• The ClearRange method can be used to clear an arbitrary range of data from the file, allowing the server to release the associated storage resources.
• The GetRanges method can be used to obtain a list of all data ranges present in the file.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateFolder Method (AzureFile Class)

Creates a new folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* CreateFolder(const char* lpszNewFolderPath);

Unicode (Windows)
LPWSTR CreateFolder(LPCWSTR lpszNewFolderPath);

char* cloudstorage_azurefile_createfolder(void* lpObj, const char* lpszNewFolderPath);

QString CreateFolder(const QString& qsNewFolderPath);

Remarks

This method creates a new folder at the specified NewFolderPath in the share currently selected by Share. The path of the newly-created folder is returned.

Any parent folders included in NewFolderPath must already exist.

If the SendMetadata configuration setting is enabled when this method is called, all items in the Metadata properties will be sent along with the creation request.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateShare Method (AzureFile Class)

Creates a new share.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateShare();

Unicode (Windows)
INT CreateShare();

int cloudstorage_azurefile_createshare(void* lpObj);

int CreateShare();

Remarks

This method creates a new share using the name specified by the Share property.

If the CreateShareQuota configuration setting is a positive, non-zero integer when this method is called, the share will be created with a space quota of that many GB. A share's space quota may be changed at any time using the SetShareQuota method.

If the SendMetadata configuration setting is enabled when this method is called, all items in the Metadata properties will be sent along with the creation request.

Share Name Rules

Share names must adhere to the following rules:

• Must be 3 to 63 characters long.
• Must start with a letter or number; and may only contain letters, numbers, and hyphens.
• All letters much be lowercase. (For convenience, the class will automatically lowercase all letters in any value assigned to Share.)
• All hyphens must be immediately preceded and followed by a letter or number (consecutive hyphens are not allowed).

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DeleteFile Method (AzureFile Class)

Deletes a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteFile(const char* lpszFilePath);

Unicode (Windows)
INT DeleteFile(LPCWSTR lpszFilePath);

int cloudstorage_azurefile_deletefile(void* lpObj, const char* lpszFilePath);

int DeleteFile(const QString& qsFilePath);

Remarks

This method deletes the file at the specified FilePath in the share currently selected by Share.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DeleteFolder Method (AzureFile Class)

Deletes a folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteFolder(const char* lpszFolderPath);

Unicode (Windows)
INT DeleteFolder(LPCWSTR lpszFolderPath);

int cloudstorage_azurefile_deletefolder(void* lpObj, const char* lpszFolderPath);

int DeleteFolder(const QString& qsFolderPath);

Remarks

This method deletes the folder at the specified FolderPath in the share currently selected by Share.

Only empty folders may be deleted; non-empty folders must be emptied first.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DeleteShare Method (AzureFile Class)

Deletes a share.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteShare();

Unicode (Windows)
INT DeleteShare();

int cloudstorage_azurefile_deleteshare(void* lpObj);

int DeleteShare();

Remarks

This method deletes the share currently selected by the Share property.

If the currently selected Share has any snapshots associated with it, and the DeleteShareSnapshots configuration setting is disabled (default) when this method is called, the server will return an error. Shares with snapshots can only be deleted after enabling DeleteShareSnapshots.

Note that, according to the Azure File Storage documentation, a share's name cannot be reused until at least 30 seconds after its deletion.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DownloadFile Method (AzureFile Class)

Downloads a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DownloadFile(const char* lpszFilePath);

Unicode (Windows)
INT DownloadFile(LPCWSTR lpszFilePath);

int cloudstorage_azurefile_downloadfile(void* lpObj, const char* lpszFilePath);

int DownloadFile(const QString& qsFilePath);

Remarks

This method downloads the file at the specified FilePath in the share currently selected by Share.

If a stream has been specified using SetDownloadStream, the file data will be sent through it. If a stream is not specified, and LocalFile is set, the file will be saved to the specified location; otherwise, the file data will be held by ResourceData.

To download and decrypt an encrypted file, set EncryptionAlgorithm and EncryptionPassword before calling this method.

Download Notes

In the simplest use-case, downloading a file looks like this: azurefile.LocalFile = "../MyFile.zip"; azurefile.DownloadFile(azurefile.Resources[0].Path);

Resuming Downloads

The class also supports resuming failed downloads by using the StartByte property. If a download is interrupted, set StartByte to the appropriate offset before calling this method to resume the download. string downloadFile = "../MyFile.zip"; azurefile.LocalFile = downloadFile; azurefile.DownloadFile(azurefile.Resources[0].Path); //The transfer is interrupted and DownloadFile() above fails. Later, resume the download: //Get the size of the partially downloaded file azurefile.StartByte = new FileInfo(downloadFile).Length; azurefile.DownloadFile(azurefile.Resources[0].Path);

Resuming Encrypted File Downloads

Resuming encrypted file downloads is only supported when LocalFile was set in the initial download attempt.

If LocalFile is set when beginning an encrypted download, the class creates a temporary file in TempPath to hold the encrypted data until the download is complete. If the download is interrupted, DownloadTempFile will be populated with the path of the temporary file that holds the partial data.

To resume, 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. azurefile.LocalFile = "../MyFile.zip"; azurefile.EncryptionPassword = "password"; azurefile.DownloadFile(azurefile.Resources[0].Path); //The transfer is interrupted and DownloadFile() above fails. Later, resume the download: //Get the size of the partially download temp file azurefile.StartByte = new FileInfo(azurefile.Config("DownloadTempFile")).Length; azurefile.DownloadFile(azurefile.Resources[0].Path);

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetFileInfo Method (AzureFile Class)

Gets a file's information and metadata.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFileInfo(const char* lpszFilePath);

Unicode (Windows)
INT GetFileInfo(LPCWSTR lpszFilePath);

int cloudstorage_azurefile_getfileinfo(void* lpObj, const char* lpszFilePath);

int GetFileInfo(const QString& qsFilePath);

Remarks

This method gets information and metadata for the file at the specified FilePath in the share currently selected by Share.

Calling this method will fire the ResourceList event, will re-populate the Resources properties with a single item, and will re-populate the Metadata properties with any metadata currently associated with the file.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetFolderInfo Method (AzureFile Class)

Gets a folder's information and metadata.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFolderInfo(const char* lpszFolderPath);

Unicode (Windows)
INT GetFolderInfo(LPCWSTR lpszFolderPath);

int cloudstorage_azurefile_getfolderinfo(void* lpObj, const char* lpszFolderPath);

int GetFolderInfo(const QString& qsFolderPath);

Remarks

This method gets information and metadata for the folder at the specified FolderPath in the share currently selected by Share.

FolderPath can be empty string to get information about the root folder of the share.

Calling this method will fire the ResourceList event, will re-populate the Resources properties with a single item, and will re-populate the Metadata properties with any metadata currently associated with the folder.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetLink Method (AzureFile Class)

Creates a link that provides access to a share or file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetLink(const char* lpszFilePath, const char* lpszPermissions, const char* lpszStartTime, const char* lpszExpiryTime);

Unicode (Windows)
LPWSTR GetLink(LPCWSTR lpszFilePath, LPCWSTR lpszPermissions, LPCWSTR lpszStartTime, LPCWSTR lpszExpiryTime);

char* cloudstorage_azurefile_getlink(void* lpObj, const char* lpszFilePath, const char* lpszPermissions, const char* lpszStartTime, const char* lpszExpiryTime);

QString GetLink(const QString& qsFilePath, const QString& qsPermissions, const QString& qsStartTime, const QString& qsExpiryTime);

Remarks

This method creates and returns a shared access signature (SAS), which is a link that provides access to a specific share or file. The following table indicates which inputs must be provided to produce a link of the desired type:

Permissions specifies what permissions the SAS grants, in the form of an abbreviated permissions list. Refer to this section of Azure's "Create a Service SAS" article for more information about how to format this value.

StartTime and ExpiryTime specify the UTC start and end times of the SAS's validity interval. Refer to this section of Azure's "Create a Service SAS" article for more information about how to format these values.

StartTime may be empty, in which case the server will assume that the link is valid immediately. Permissions and ExpiryTime must both be non-empty, unless an si query parameter that references a stored access policy (which has corresponding non-empty values) is present in the QueryParams properties.

If any of the query parameters listed below are present in the QueryParams properties when this method is called, they will be included when creating the SAS. All other application-specified query parameters are ignored.

• Response headers: rscc, rscd, rsce, rscl, rsct
• IP address (single or range): sip
• Allowed HTTP protocol(s): spr
• Stored access policy ("signed identifier"): si

For more information about SAS links, refer to Azure's Create a Service SAS article.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetRanges Method (AzureFile Class)

Gets the list of allocated data ranges in a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRanges(const char* lpszFilePath);

Unicode (Windows)
INT GetRanges(LPCWSTR lpszFilePath);

int cloudstorage_azurefile_getranges(void* lpObj, const char* lpszFilePath);

int GetRanges(const QString& qsFilePath);

Remarks

This method gets the list of allocated data ranges in the file at the specified FilePath in the share currently selected by Share and populates the Ranges properties with the results.

The server tracks ranges of file data in 512-byte chunks, aligned to the absolute beginning of the file; thus, the size of every range returned by this method will always be a multiple of 512. Chunks that are not currently allocated (either because no data has been written to them, or because they've been freed with ClearRange) will not be returned by this method.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetShareInfo Method (AzureFile Class)

Gets a share's information and metadata.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetShareInfo();

Unicode (Windows)
INT GetShareInfo();

int cloudstorage_azurefile_getshareinfo(void* lpObj);

int GetShareInfo();

Remarks

This method gets information and metadata for the share currently selected by the Share property.

Calling this method will fire the ShareList event, will re-populate the Shares properties with a single item, and will re-populate the Metadata properties with any metadata currently associated with the share.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Interrupt Method (AzureFile Class)

This method interrupts the current method.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Interrupt();

Unicode (Windows)
INT Interrupt();

int cloudstorage_azurefile_interrupt(void* lpObj);

int Interrupt();

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ListResources Method (AzureFile Class)

Lists resources in a given folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ListResources(const char* lpszFolderPath);

Unicode (Windows)
INT ListResources(LPCWSTR lpszFolderPath);

int cloudstorage_azurefile_listresources(void* lpObj, const char* lpszFolderPath);

int ListResources(const QString& qsFolderPath);

Remarks

This method lists the resources in the folder at the specified FolderPath in the share currently selected by Share.

Before calling this method, the Prefix property may be set in order to restrict the results to only the items whose names begin with a given string. The MaxResults configuration setting may also be used to limit the number of results returned.

Calling this method will fire the ResourceList event once for each resource, and will also populate the Resources properties.

If there are still more resources available to list when this method returns, the ResourceMarker property will be populated. Continue to call this method until ResourceMarker is empty to accumulate all pages of results in the Resources properties. Alternatively, the AccumulatePages configuration setting can be disabled to clear the Resources properties every time a page of results is returned.

Note that the server only returns the following resource fields when listing resources (use GetFileInfo or GetFolderInfo to retrieve all fields for a specific resource):

• Name
• Path (populated by the class automatically)
• Share (populated by the class automatically)
• Size
• Type

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ListShares Method (AzureFile Class)

Lists shares in the file storage account.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ListShares();

Unicode (Windows)
INT ListShares();

int cloudstorage_azurefile_listshares(void* lpObj);

int ListShares();

Remarks

This method lists the shares in the file storage account specified by the Account property.

Before calling this method, the Prefix property may be set in order to restrict the results to only the items whose names begin with a given string. The MaxResults configuration setting may also be used to limit the number of results returned.

Calling this method will fire the ShareList event once for each share, and will also populate the Shares properties.

If there are still more shares available to list when this method returns, the ShareMarker property will be populated. Continue to call this method until ShareMarker is empty to accumulate all pages of results in the Shares properties. Alternatively, the AccumulatePages configuration setting can be disabled to clear the Shares properties every time a page of results is returned.

Note that the server does not return the shares' SpaceUsed field when listing shares; use GetShareInfo to retrieve all fields for a specific share. // ShareList event handler. azurefile.OnShareList += (s, e) => { Console.WriteLine(e.Name); }; do { azurefile.ListShares(); for (int i = 0; i < azurefile.Shares.Count; i++) { // Process shares here. } } while (!string.IsNullOrEmpty(azurefile.ShareMarker));

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

PutRange Method (AzureFile Class)

Uploads a range of data to a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int PutRange(const char* lpszFilePath, int64 lWriteOffset);

Unicode (Windows)
INT PutRange(LPCWSTR lpszFilePath, LONG64 lWriteOffset);

int cloudstorage_azurefile_putrange(void* lpObj, const char* lpszFilePath, int64 lWriteOffset);

int PutRange(const QString& qsFilePath, qint64 lWriteOffset);

Remarks

This method uploads a range of data to the file at the specified FilePath in the share currently selected by Share. The data to upload cannot be larger than 4MB (4194304 bytes), and is written to the file at the given WriteOffset (specified in bytes).

The server tracks ranges of file data in 512-byte chunks, aligned to the absolute beginning of the file. However, neither the WriteOffset nor the length of the data to upload need be a multiple of 512. Any portions of a chunk not written to will be populated with 0s.

Note that, according to the Azure File Storage documentation, this operation requires a write lock on the entire file in order to complete successfully.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

RenameFile Method (AzureFile Class)

Renames a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RenameFile(const char* lpszOldFilePath, const char* lpszNewFilePath);

Unicode (Windows)
INT RenameFile(LPCWSTR lpszOldFilePath, LPCWSTR lpszNewFilePath);

int cloudstorage_azurefile_renamefile(void* lpObj, const char* lpszOldFilePath, const char* lpszNewFilePath);

int RenameFile(const QString& qsOldFilePath, const QString& qsNewFilePath);

Remarks

This method moves and/or renames an existing file on the server at the specified OldFilePath in the share currently selected by Share. The NewFilePath parameter indicates the new location and name of the file.

Any parent folders included in NewFilePath must already exist.

The Overwrite property can optionally be enabled to overwrite the file if it already exists at the location specified by NewFilePath.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

RenameFolder Method (AzureFile Class)

Renames a directory.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RenameFolder(const char* lpszOldDirPath, const char* lpszNewDirPath);

Unicode (Windows)
INT RenameFolder(LPCWSTR lpszOldDirPath, LPCWSTR lpszNewDirPath);

int cloudstorage_azurefile_renamefolder(void* lpObj, const char* lpszOldDirPath, const char* lpszNewDirPath);

int RenameFolder(const QString& qsOldDirPath, const QString& qsNewDirPath);

Remarks

This method moves and/or renames an existing folder on the server at the specified OldDirPath in the share currently selected by Share. The NewDirPath parameter indicates the new location and name of the folder.

Any parent folders included in NewDirPath must already exist.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Reset Method (AzureFile Class)

Resets the class to its initial state.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int cloudstorage_azurefile_reset(void* lpObj);

int Reset();

Remarks

This method resets the class to its initial state.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ResizeFile Method (AzureFile Class)

Resizes a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ResizeFile(const char* lpszFilePath, int64 lNewSize);

Unicode (Windows)
INT ResizeFile(LPCWSTR lpszFilePath, LONG64 lNewSize);

int cloudstorage_azurefile_resizefile(void* lpObj, const char* lpszFilePath, int64 lNewSize);

int ResizeFile(const QString& qsFilePath, qint64 lNewSize);

Remarks

This method resizes the file at the specified FilePath in the share currently selected by Share. NewSize, which is specified in bytes, cannot be negative.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetDownloadStream Method (AzureFile Class)

Sets the stream to which downloaded data will be written.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetDownloadStream(CloudStorageStream* sDownloadStream);

Unicode (Windows)
INT SetDownloadStream(CloudStorageStream* sDownloadStream);

int cloudstorage_azurefile_setdownloadstream(void* lpObj, CloudStorageStream* sDownloadStream);

int SetDownloadStream(CloudStorageStream* sDownloadStream);

Remarks

If a download stream is set before data is downloaded, the downloaded data will be written to the stream. The stream should be open and normally set to position 0.

Note: Passing a non-null value for DownloadStream will cause LocalFile to be cleared. Similarly, setting LocalFile to a non-empty value will discard any stream set using this method.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetShareQuota Method (AzureFile Class)

Sets a share's space quota.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetShareQuota(int iQuota);

Unicode (Windows)
INT SetShareQuota(INT iQuota);

int cloudstorage_azurefile_setsharequota(void* lpObj, int iQuota);

int SetShareQuota(int iQuota);

Remarks

This method sets the size, in GB, of the space quota imposed on the share currently selected by the Share property. Quota must be greater than 0.

It is legal to lower a share's quota to a value less than its current space usage. However, doing so will prevent new space from being allocated until either the space usage falls below quota or the quota is raised above the space usage.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetUploadStream Method (AzureFile Class)

Sets the stream from which data is read when uploading.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetUploadStream(CloudStorageStream* sUploadStream);

Unicode (Windows)
INT SetUploadStream(CloudStorageStream* sUploadStream);

int cloudstorage_azurefile_setuploadstream(void* lpObj, CloudStorageStream* sUploadStream);

int SetUploadStream(CloudStorageStream* sUploadStream);

Remarks

If an upload stream is set before data is uploaded, the content of the stream will be read by the class and uploaded to the server. The stream should be open and normally set to position 0.

Note: Passing a non-null value for UploadStream will cause LocalFile to be cleared. Similarly, setting LocalFile to a non-empty value will discard any stream set using this method.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

UpdateMetadata Method (AzureFile Class)

Sets the metadata for a file, folder, or share.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int UpdateMetadata(const char* lpszPath, int iResourceType);

Unicode (Windows)
INT UpdateMetadata(LPCWSTR lpszPath, INT iResourceType);

int cloudstorage_azurefile_updatemetadata(void* lpObj, const char* lpszPath, int iResourceType);

int UpdateMetadata(const QString& qsPath, int iResourceType);

Remarks

This method sets the metadata for a file, folder, or share to the items currently held by the Metadata properties. The ResourceType parameter indicates the kind of resource the class should prepare the request for; possible values are:

• 0: Set the metadata for the file at the specified Path in the share currently selected by Share.
• 1: Set the metadata for the folder at the specified Path in the share currently selected by Share.
• 2: Set the metadata for the share currently selected by Share (Path is ignored).

Note that it is not possible to do a partial metadata update. That is, all metadata currently associated with the remote entity will be replaced with the metadata sent in the request.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

UploadFile Method (AzureFile Class)

Uploads a new file resource.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* UploadFile(const char* lpszNewFilePath);

Unicode (Windows)
LPWSTR UploadFile(LPCWSTR lpszNewFilePath);

char* cloudstorage_azurefile_uploadfile(void* lpObj, const char* lpszNewFilePath);

QString UploadFile(const QString& qsNewFilePath);

Remarks

This method uploads a new file resource at the specified NewFilePath in the share currently selected by Share. The path of the newly-created file is returned.

Any parent folders included in NewFilePath must already exist.

If the SendMetadata configuration setting is enabled when this method is called, all items in the Metadata properties will be sent along with the creation request.

If SetUploadStream has been used to set an upload stream, it will take priority as the file data source. If LocalFile is set the file will be uploaded from the specified path. If LocalFile is not set the data in ResourceData will be used.

To encrypt the file before uploading it, set EncryptionAlgorithm and EncryptionPassword.

Upload Notes

The UploadFile method is a convenience method that performs a resumable file upload. When called, the class first uses CreateFile to initialize a new file entry on the server; and then it fragments the file data into smaller pieces and calls PutRange multiple times in succession to upload those fragments. The fragment size is fixed at 4MB (this is a server limitation that cannot be changed).

During the upload, the FragmentComplete event fires after each fragment is uploaded to indicate overall progress. The class also updates StartByte as necessary to indicate the current offset in the file.

If the upload is interrupted for any reason, resuming it is easy. First, verify that StartByte is populated (if the same instance of the class is used, they should already be populated, and no special action should be needed). If uploading from a stream, be sure to reset its position to where it was the first time the upload was started (typically the beginning). Then call UploadFile again to resume the upload at the specified StartByte offset. azurefile.LocalFile = "../MyFile.zip"; azurefile.UploadFile("MyFile.zip"); //The transfer is interrupted and UploadFile() above fails. Later, resume the download. //Using the same instance StartByte is already populated from the previous upload attempt. azurefile.UploadFile("MyFile.zip"); MemoryStream uploadStream = new MemoryStream(File.ReadAllBytes("../MyFile.zip")); azurefile.SetUploadStream(uploadStream); azurefile.UploadFile("MyFile.zip"); //The transfer is interrupted and UploadFile() above fails. Later, resume the download. //Using the same instance StartByte is already populated from the previous upload attempt. //You MUST reset the stream's position to where it was when you first started the upload! uploadStream.Position = 0; azurefile.UploadFile("MyFile.zip");

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

EndTransfer Event (AzureFile Class)

This event fires when a document finishes transferring.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireEndTransfer(AzureFileEndTransferEventParams *e);

typedef struct {
  int Direction;
  int reserved;
} AzureFileEndTransferEventParams;


Unicode (Windows)
virtual INT FireEndTransfer(AzureFileEndTransferEventParams *e);

typedef struct {
  INT Direction;
  INT reserved;
} AzureFileEndTransferEventParams;

#define EID_AZUREFILE_ENDTRANSFER 1

virtual INT CLOUDSTORAGE_CALL FireEndTransfer(INT &iDirection);

class AzureFileEndTransferEventParams {
public:
  int Direction();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void EndTransfer(AzureFileEndTransferEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireEndTransfer(AzureFileEndTransferEventParams *e) {...}

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.

Error Event (AzureFile Class)

Fired when information is available about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(AzureFileErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} AzureFileErrorEventParams;


Unicode (Windows)
virtual INT FireError(AzureFileErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} AzureFileErrorEventParams;

#define EID_AZUREFILE_ERROR 2

virtual INT CLOUDSTORAGE_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class AzureFileErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(AzureFileErrorEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireError(AzureFileErrorEventParams *e) {...}

Remarks

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

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

FragmentComplete Event (AzureFile Class)

Fires after each fragment of a resumable upload is completed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireFragmentComplete(AzureFileFragmentCompleteEventParams *e);

typedef struct {
  int FragmentNumber;
  int FragmentCount;
  int Interrupt;
  int reserved;
} AzureFileFragmentCompleteEventParams;


Unicode (Windows)
virtual INT FireFragmentComplete(AzureFileFragmentCompleteEventParams *e);

typedef struct {
  INT FragmentNumber;
  INT FragmentCount;
  BOOL Interrupt;
  INT reserved;
} AzureFileFragmentCompleteEventParams;

#define EID_AZUREFILE_FRAGMENTCOMPLETE 3

virtual INT CLOUDSTORAGE_CALL FireFragmentComplete(INT &iFragmentNumber, INT &iFragmentCount, BOOL &bInterrupt);

class AzureFileFragmentCompleteEventParams {
public:
  int FragmentNumber();

  int FragmentCount();

  bool Interrupt();
  void SetInterrupt(bool bInterrupt);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void FragmentComplete(AzureFileFragmentCompleteEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireFragmentComplete(AzureFileFragmentCompleteEventParams *e) {...}

Remarks

When UploadFile is called, this event will fire after each fragment is uploaded, providing an indication of overall upload progress.

FragmentNumber is the number of the current fragment that has completed. This value begins at 1.

FragmentCount is the total number of fragments that will be uploaded.

Interrupt can be set to true to interrupt the upload. The upload may be resumed later.

Header Event (AzureFile Class)

Fired every time a header line comes in.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireHeader(AzureFileHeaderEventParams *e);

typedef struct {
  const char *Field;
  const char *Value;
  int reserved;
} AzureFileHeaderEventParams;


Unicode (Windows)
virtual INT FireHeader(AzureFileHeaderEventParams *e);

typedef struct {
  LPCWSTR Field;
  LPCWSTR Value;
  INT reserved;
} AzureFileHeaderEventParams;

#define EID_AZUREFILE_HEADER 4

virtual INT CLOUDSTORAGE_CALL FireHeader(LPSTR &lpszField, LPSTR &lpszValue);

class AzureFileHeaderEventParams {
public:
  const QString &Field();

  const QString &Value();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Header(AzureFileHeaderEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireHeader(AzureFileHeaderEventParams *e) {...}

Remarks

The Field parameter contains the name of the HTTP header (which is the same as it is delivered). The Value parameter contains the header contents.

If the header line being retrieved is a continuation header line, then the Field parameter contains "" (empty string).

Log Event (AzureFile Class)

Fired once for each log message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireLog(AzureFileLogEventParams *e);

typedef struct {
  int LogLevel;
  const char *Message;
  const char *LogType;
  int reserved;
} AzureFileLogEventParams;


Unicode (Windows)
virtual INT FireLog(AzureFileLogEventParams *e);

typedef struct {
  INT LogLevel;
  LPCWSTR Message;
  LPCWSTR LogType;
  INT reserved;
} AzureFileLogEventParams;

#define EID_AZUREFILE_LOG 5

virtual INT CLOUDSTORAGE_CALL FireLog(INT &iLogLevel, LPSTR &lpszMessage, LPSTR &lpszLogType);

class AzureFileLogEventParams {
public:
  int LogLevel();

  const QString &Message();

  const QString &LogType();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Log(AzureFileLogEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireLog(AzureFileLogEventParams *e) {...}

Remarks

This event is fired 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"

Progress Event (AzureFile Class)

Fires during an upload or download to indicate transfer progress.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireProgress(AzureFileProgressEventParams *e);

typedef struct {
  int Direction;
  int64 BytesTransferred;
  int64 TotalBytes;
  int PercentDone;
  int reserved;
} AzureFileProgressEventParams;


Unicode (Windows)
virtual INT FireProgress(AzureFileProgressEventParams *e);

typedef struct {
  INT Direction;
  LONG64 BytesTransferred;
  LONG64 TotalBytes;
  INT PercentDone;
  INT reserved;
} AzureFileProgressEventParams;

#define EID_AZUREFILE_PROGRESS 6

virtual INT CLOUDSTORAGE_CALL FireProgress(INT &iDirection, LONG64 &lBytesTransferred, LONG64 &lTotalBytes, INT &iPercentDone);

class AzureFileProgressEventParams {
public:
  int Direction();

  qint64 BytesTransferred();

  qint64 TotalBytes();

  int PercentDone();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Progress(AzureFileProgressEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireProgress(AzureFileProgressEventParams *e) {...}

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.

ResourceList Event (AzureFile Class)

Fires once for each resource returned when listing resources.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireResourceList(AzureFileResourceListEventParams *e);

typedef struct {
  const char *Name;
  const char *Path;
  const char *Share;
  int ResourceType;
  const char *ModifiedTime;
  int64 Size;
  const char *ETag;
  int reserved;
} AzureFileResourceListEventParams;


Unicode (Windows)
virtual INT FireResourceList(AzureFileResourceListEventParams *e);

typedef struct {
  LPCWSTR Name;
  LPCWSTR Path;
  LPCWSTR Share;
  INT ResourceType;
  LPCWSTR ModifiedTime;
  LONG64 Size;
  LPCWSTR ETag;
  INT reserved;
} AzureFileResourceListEventParams;

#define EID_AZUREFILE_RESOURCELIST 7

virtual INT CLOUDSTORAGE_CALL FireResourceList(LPSTR &lpszName, LPSTR &lpszPath, LPSTR &lpszShare, INT &iResourceType, LPSTR &lpszModifiedTime, LONG64 &lSize, LPSTR &lpszETag);

class AzureFileResourceListEventParams {
public:
  const QString &Name();

  const QString &Path();

  const QString &Share();

  int ResourceType();

  const QString &ModifiedTime();

  qint64 Size();

  const QString &ETag();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void ResourceList(AzureFileResourceListEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireResourceList(AzureFileResourceListEventParams *e) {...}

Remarks

This event fires once for each resource returned when ListResources, GetFileInfo, or GetFolderInfo is called.

Name is the name of the resource.

Path is the full path of the resource (not including the share).

Share is the name of the share the resource resides in.

ResourceType reflects the resource's type. Possible values are:

ModifiedTime is the last modified time of the resource, formatted according to RFC 1123. (Note: this parameter is not populated by calls to ListResources.)

Size is the size of the file. Always 0 for folders.

ETag is the ETag of the resource. (Note: this parameter is not populated by calls to ListResources.)

ShareList Event (AzureFile Class)

Fires once for each share returned when listing shares.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireShareList(AzureFileShareListEventParams *e);

typedef struct {
  const char *Name;
  const char *ModifiedTime;
  const char *ETag;
  int Quota;
  int reserved;
} AzureFileShareListEventParams;


Unicode (Windows)
virtual INT FireShareList(AzureFileShareListEventParams *e);

typedef struct {
  LPCWSTR Name;
  LPCWSTR ModifiedTime;
  LPCWSTR ETag;
  INT Quota;
  INT reserved;
} AzureFileShareListEventParams;

#define EID_AZUREFILE_SHARELIST 8

virtual INT CLOUDSTORAGE_CALL FireShareList(LPSTR &lpszName, LPSTR &lpszModifiedTime, LPSTR &lpszETag, INT &iQuota);

class AzureFileShareListEventParams {
public:
  const QString &Name();

  const QString &ModifiedTime();

  const QString &ETag();

  int Quota();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void ShareList(AzureFileShareListEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireShareList(AzureFileShareListEventParams *e) {...}

Remarks

This event fires once for each share returned when ListShares or GetShareInfo is called.

Name is the name of the share.

ModifiedTime is the last modified time of the share, formatted according to RFC 1123.

ETag is the ETag of the share.

Quota is the share's space quota, in GB.

SSLServerAuthentication Event (AzureFile Class)

Fired after the server presents its certificate to the client.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSSLServerAuthentication(AzureFileSSLServerAuthenticationEventParams *e);

typedef struct {
  const char *CertEncoded;
  int lenCertEncoded;
  const char *CertSubject;
  const char *CertIssuer;
  const char *Status;
  int Accept;
  int reserved;
} AzureFileSSLServerAuthenticationEventParams;


Unicode (Windows)
virtual INT FireSSLServerAuthentication(AzureFileSSLServerAuthenticationEventParams *e);

typedef struct {
  LPCSTR CertEncoded;
  INT lenCertEncoded;
  LPCWSTR CertSubject;
  LPCWSTR CertIssuer;
  LPCWSTR Status;
  BOOL Accept;
  INT reserved;
} AzureFileSSLServerAuthenticationEventParams;

#define EID_AZUREFILE_SSLSERVERAUTHENTICATION 9

virtual INT CLOUDSTORAGE_CALL FireSSLServerAuthentication(LPSTR &lpCertEncoded, INT &lenCertEncoded, LPSTR &lpszCertSubject, LPSTR &lpszCertIssuer, LPSTR &lpszStatus, BOOL &bAccept);

class AzureFileSSLServerAuthenticationEventParams {
public:
  const QByteArray &CertEncoded();

  const QString &CertSubject();

  const QString &CertIssuer();

  const QString &Status();

  bool Accept();
  void SetAccept(bool bAccept);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SSLServerAuthentication(AzureFileSSLServerAuthenticationEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireSSLServerAuthentication(AzureFileSSLServerAuthenticationEventParams *e) {...}

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (AzureFile Class)

Fired when secure connection progress messages are available.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSSLStatus(AzureFileSSLStatusEventParams *e);

typedef struct {
  const char *Message;
  int reserved;
} AzureFileSSLStatusEventParams;


Unicode (Windows)
virtual INT FireSSLStatus(AzureFileSSLStatusEventParams *e);

typedef struct {
  LPCWSTR Message;
  INT reserved;
} AzureFileSSLStatusEventParams;

#define EID_AZUREFILE_SSLSTATUS 10

virtual INT CLOUDSTORAGE_CALL FireSSLStatus(LPSTR &lpszMessage);

class AzureFileSSLStatusEventParams {
public:
  const QString &Message();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SSLStatus(AzureFileSSLStatusEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireSSLStatus(AzureFileSSLStatusEventParams *e) {...}

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

StartTransfer Event (AzureFile Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireStartTransfer(AzureFileStartTransferEventParams *e);

typedef struct {
  int Direction;
  int reserved;
} AzureFileStartTransferEventParams;


Unicode (Windows)
virtual INT FireStartTransfer(AzureFileStartTransferEventParams *e);

typedef struct {
  INT Direction;
  INT reserved;
} AzureFileStartTransferEventParams;

#define EID_AZUREFILE_STARTTRANSFER 11

virtual INT CLOUDSTORAGE_CALL FireStartTransfer(INT &iDirection);

class AzureFileStartTransferEventParams {
public:
  int Direction();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void StartTransfer(AzureFileStartTransferEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireStartTransfer(AzureFileStartTransferEventParams *e) {...}

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.

Transfer Event (AzureFile Class)

Fired while a document transfers (delivers document).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTransfer(AzureFileTransferEventParams *e);

typedef struct {
  int Direction;
  int64 BytesTransferred;
  int PercentDone;
  const char *Text;
  int lenText;
  int reserved;
} AzureFileTransferEventParams;


Unicode (Windows)
virtual INT FireTransfer(AzureFileTransferEventParams *e);

typedef struct {
  INT Direction;
  LONG64 BytesTransferred;
  INT PercentDone;
  LPCSTR Text;
  INT lenText;
  INT reserved;
} AzureFileTransferEventParams;

#define EID_AZUREFILE_TRANSFER 12

virtual INT CLOUDSTORAGE_CALL FireTransfer(INT &iDirection, LONG64 &lBytesTransferred, INT &iPercentDone, LPSTR &lpText, INT &lenText);

class AzureFileTransferEventParams {
public:
  int Direction();

  qint64 BytesTransferred();

  int PercentDone();

  const QByteArray &Text();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Transfer(AzureFileTransferEventParams *e);

// Or, subclass AzureFile and override this emitter function.
virtual int FireTransfer(AzureFileTransferEventParams *e) {...}

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.

AzureFileResource Type

An Azure File service file or folder.

Syntax

CloudStorageAzureFileResource (declared in cloudstorage.h)

Remarks

This type represents an Azure File service file or folder.

Fields

Constructors

AzureFileResource()

AzureFileShare Type

An Azure File service share.

Syntax

CloudStorageAzureFileShare (declared in cloudstorage.h)

Remarks

This type represents an Azure File service share.

Fields

Constructors

AzureFileShare()

AzureMetadata Type

An Azure metadata item.

Syntax

CloudStorageAzureMetadata (declared in cloudstorage.h)

Remarks

This type represents an Azure metadata item.

Fields

Constructors

AzureMetadata()

AzureMetadata(const char* lpszName, const char* lpszValue)

AzureRange Type

An Azure byte range.

Syntax

CloudStorageAzureRange (declared in cloudstorage.h)

Remarks

This type represents an Azure byte range.

Fields

Certificate Type

This is the digital certificate being used.

Syntax

CloudStorageCertificate (declared in cloudstorage.h)

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

Certificate()

Certificate(const char* lpEncoded, int lenEncoded)

Certificate(int iStoreType, const char* lpStore, int lenStore, const char* lpszStorePassword, const char* lpszSubject)

Firewall Type

The firewall the component will connect through.

Syntax

CloudStorageFirewall (declared in cloudstorage.h)

Remarks

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

Fields

Constructors

Firewall()

Header Type

This is an HTTP header as it is received from the server.

Syntax

CloudStorageHeader (declared in cloudstorage.h)

Remarks

When a header is received through a Header event, it is parsed into a Header type. This type contains a Field, and its corresponding Value.

Fields

Constructors

Header()

Header(const char* lpszField, const char* lpszValue)

OAuthSettings Type

The settings to use to authenticate with the service provider.

Syntax

CloudStorageOAuthSettings (declared in cloudstorage.h)

Remarks

Used to set give the class the necessary information needed to complete OAuth authentication.

Fields

Constructors

OAuthSettings()

Proxy Type

The proxy the component will connect to.

Syntax

CloudStorageProxy (declared in cloudstorage.h)

Remarks

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

Fields

Constructors

Proxy()

Proxy(const char* lpszServer, int iPort)

Proxy(const char* lpszServer, int iPort, const char* lpszUser, const char* lpszPassword)

QueryParam Type

A query parameter to send in the request.

Syntax

CloudStorageQueryParam (declared in cloudstorage.h)

Remarks

This type represents a query parameter to send in the request.

Fields

Constructors

QueryParam()

QueryParam(const char* lpszName, const char* lpszValue)

CloudStorageList Type

Syntax

CloudStorageList<T> (declared in cloudstorage.h)

Remarks

CloudStorageList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the AzureFile class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

T* Set(int index, T* value) {}

CloudStorageStream Type

Syntax

CloudStorageStream (declared in cloudstorage.h)

Remarks

The AzureFile class includes one or more API members that take a stream object as a parameter. To use such API members, create a concrete class that implements the CloudStorageStream interface and pass the AzureFile class an instance of that concrete class.

When implementing the CloudStorageStream interface's properties and methods, they must behave as described below. If the concrete class's implementation does not behave as expected, undefined behavior may occur.

bool CanRead() { return true; }

bool CanSeek() { return true; }

bool CanWrite() { return true; }

int64 GetLength() = 0;

void Close() {}

int Flush() { return 0; }

int Read(void* buffer, int count) = 0;