CWebStorage::DownloadFile Method  
 
BOOL DownloadFile(
  LPCTSTR lpszLocalFile,  
  LPCTSTR lpszObjectLabel,  
  LPWEB_STORAGE_OBJECT lpObject  
);
BOOL DownloadFile(
  LPCTSTR lpszLocalFile,  
  LPCTSTR lpszObjectLabel,  
  LPCTSTR lpszAppId,  
  DWORD dwStorageType,  
  DWORD dwTimeout,  
  LPWEB_STORAGE_OBJECT lpObject,  
  WEBEVENTPROC lpEventProc,  
  DWORD_PTR dwParam  
);

The DownloadFile method downloads the contents of a storage object and copies it to a local file.

Parameters

lpszLocalFile
A pointer to a null terminated string that specifies the name of the local file that will be created or overwritten with the contents of the storage object. If a path is not specified, the file will be created in the current working directory.
lpszObjectLabel
A pointer to a null terminated string that specifies the label of the object that should be retrieved from the server.
lpszAppId
A pointer to null terminated string which specifies the application ID for the storage container. The application ID is a string that uniquely identifies the application and can only contain letters, numbers, the period and the underscore character. If this parameter is NULL or an empty string, the default identifier SocketTools.Storage.Default will be used.
dwStorageType
An integer value that identifies the storage container type. If this parameter is omitted, WEB_STORAGE_GLOBAL will be used as the default. One of the following values can be specified:
Constant Description
WEB_STORAGE_GLOBAL
(1)		 Global storage. Objects stored using this storage type are available to all users. Any changes made to objects using this storage type will affect all users of the application. Unless there is a specific need to limit access to the objects stored by the application to specific domains, local machines or users, it is recommended that you use this storage type when creating new objects.
WEB_STORAGE_DOMAIN
(2)		 Local domain storage. Objects stored using this storage type are only available to users in the same local domain, as defined by the domain name or workgroup name assigned to the local system. If the domain or workgroup name changes, objects previously stored using this storage type will not be available to the application.
WEB_STORAGE_MACHINE
(3)		 Local machine storage. Objects stored using this storage type are only available to users on the same local machine. The local machine is identified by unique characteristics of the system, including the boot volume GUID. Objects previously stored using this storage type will not be available on that system if the boot disk is reformatted.
WEB_STORAGE_USER
(4)		 Current user storage. Objects stored using this storage type are only available to the current user logged in on the local machine. The user identifier is based on the Windows user SID that is assigned when the user account is created. If the user account is deleted, the objects previously stored using this storage type will not be available to the application.
dwTimeout
An integer value that specifies a timeout period in seconds. If this value is zero, a default timeout period will be used.
lpObject
A pointer to a WEB_STORAGE_OBJECT structure that will contain additional information about the object that has been downloaded. This parameter may be omitted or NULL if the information is not required.
lpEventProc
Specifies the procedure-instance address of the application defined callback method. For more information about the callback method, see the description of the WebEventProc callback method. If this parameter is omitted or NULL, no callback method will be invoked during the data transfer.
dwParam
A user-defined integer value that is passed to the callback method specified by lpEventProc. If the application targets the x86 (32-bit) platform, this parameter must be a 32-bit unsigned integer. If the application targets the x64 (64-bit) platform, this parameter must be a 64-bit unsigned integer.

Return Value

If the method succeeds, the return value is a non-zero. If the method fails, the return value is zero. To get extended error information, call the GetLastError method.

Remarks

The DownloadFile method downloads the contents of the storage object and stores it in a local file. Unlike the GetFile method, it is not required that you explicitly open a storage container using the OpenStorage method prior to calling this method.

Additional metadata about the object will be returned in the WEB_STORAGE_OBJECT structure provided by the caller, such as the date and time the object was created, the content type and the SHA-256 hash of the object contents.

If you are downloading a large object and want your application to receive progress updates during the data transfer, provide a pointer to a static callback function as the lpEventProc parameter. That function will receive event notifications as the data is being downloaded.

Example

WEB_STORAGE_OBJECT webObject;

// Download the object from global storage to a local file
if (pStorage->DownloadFile(lpszObjectLabel, lpszLocalFile, &webObject))
{
    // The object was downloaded, display the metadata
    _tprintf(_T("Object:  %s\n"), webObject.szObjectId);
    _tprintf(_T("Label:   %s\n"), webObject.szLabel);
    _tprintf(_T("Size:    %lu\n"), webObject.dwObjectSize);
    _tprintf(_T("Digest:  %s\n"), webObject.szDigest);
    _tprintf(_T("Content: %s\n"), webObject.szContent);
}
else
{
    // The object could not be retrieved, display the error
    CString strError;

    pStorage->GetLastError(strError);    
    _tprintf(_T("Unable to retrieve \"%s\" (%s)\n"), lpszObjectLabel, (LPCTSTR)strError);
}

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: cswebv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

GetFile, PutFile, UploadFile,

 
 

Copyright © 2023 Catalyst Development Corporation. All rights reserved.