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

The UploadFile method uploads the contents of a local file and creates or overwrites a storage object.

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 omitted, 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, the default value of WEB_STORAGE_GLOBAL will be used. One of the following values may 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.
dwAttributes
An unsigned integer that specifies the attributes associated with the storage object. If this parameter is omitted, a default value of WEB_OBJECT_NORMAL will be used. This value can be a combination of one or more of the following bitflags using a bitwise OR operation:
Value Constant Description
0 WEB_OBJECT_DEFAULT Default object attributes. This value is used to indicate the object can be modified, or that the attributes for a previously existing object should not be changed.
1 WEB_OBJECT_NORMAL A normal object that that can be read and modified by the application. This is the default attribute for new objects that are created by the application.
2 WEB_OBJECT_READONLY A read-only object that can only be read by the application. Attempts to modify or replace the contents of the object will fail. Read-only objects can be deleted.
4 WEB_OBJECT_HIDDEN A hidden object. Objects with this attribute are not returned when enumerated using the CWebStorage::EnumObjects method. The object can only be accessed directly when specifying its label.
dwTimeout
An unsigned 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 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 function. If this parameter is NULL, no callback function will be invoked during the data transfer.
dwParam
A user-defined integer value that is passed to the callback function 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 UploadFile method uploads the contents of a local file and either creates a new storage object, or replaces an object if one already exists with the same label. The UploadFile method provides a simpler interface that defaults to uploading an object to the global storage container.

If the label identifies an object that already exists in the container, and that object was created with the WEB_OBJECT_READONLY attribute, this method will fail. To replace a read-only object, the application must explicitly move, rename or delete the existing object.

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 uploading a large file 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 uploaded.

Example

CWebStorage appStorage;
WEB_STORAGE_OBJECT webObject;

// Upload a local file to the global storage container
if (appStorage.UploadFile(lpszLocalFile, lpszObjectLabel, &webObject))
{
    // The object was uploaded, 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 uploaded, display the error
    CString strError;

    appStorage.GetLastError(strError);    
    _tprintf(_T("Unable to upload \"%s\" (%s)\n"), lpszLocalFile, (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

DownloadFile, GetFile, PutFile

 
 

Copyright © 2023 Catalyst Development Corporation. All rights reserved.