BOOL PutFile(
	LPCTSTR lpszLocalFile,
	LPCTSTR lpszObjectLabel,
	LPWEB_STORAGE_OBJECT lpObject

BOOL PutFile(
	LPCTSTR lpszLocalFile,
	LPCTSTR lpszObjectLabel,
	LPCTSTR lpszContentType,
	DWORD dwAttributes,
	LPWEB_STORAGE_OBJECT lpObject
);

The PutFile method uploads the contents of a local file to a storage container and returns information about the new object.

Parameters

lpszLocalFile

A pointer to a null terminated string that specifies the name of the local file that will be uploaded. If a path is not specified, the file will be read from the current working directory. The current user must have read access to the file, and an error will be returned if the method cannot obtain an exclusive lock on the file during the upload process.

lpszObjectLabel

A pointer to a null terminated string that specifies the label of the storage object that will be created or replaced. This parameter cannot be NULL or a zero-length string. The method will fail if the label contains any illegal characters.

lpszContentType

A pointer to a null terminated string that identifies the contents of the file being uploaded. If this parameter is omitted, a NULL pointer, or specifies a zero-length string, the method will attempt to automatically determine the content type based on the file name extension and the contents of the file.

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 EnumObjects method. The object can only be accessed directly when specifying its label.

lpObject

A pointer to a WEB_STORAGE_OBJECT structure that will contain additional information about the object. This parameter may be omitted or NULL if the information is not required.

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 PutFile method uploads the contents of a local file to the current storage container. The content type, which identifies the type of data stored in the object, and its attributes may be specified by the caller or default values may be used.

If a content type is provided, it must specify a valid MIME media type and subtype. For example, normal text files have a content type of text/plain while an XML-formatted text file would have a content type of text/xml. Files that contain unstructured binary data are typically identified as application/octet-stream. If the content type is not explicitly specified, an attempt will be made to identify it automatically based on contents of the file and the file extension.

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 first move, rename or delete the existing object.

The ValidateLabel method can be used to ensure a label is valid prior to calling this method. Refer to that method for more information about the difference between Windows file names and object labels

If you are uploading a large file and want your application to receive progress updates during the data transfer, use the RegisterEvent method and provide a pointer to a static callback method that will receive event notifications.

Example

WEB_STORAGE_OBJECT webObject;

// Upload a local file to the storage container, automatically
// determining the content type with normal read/write access
if (pStorage->PutFile(lpszLocalFile, lpszObjectLabel, &webObject))
{
    // The file was uploaded, display the object 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 file could not be uploaded, display the error
    CString strError;

    pStorage->GetLastError(strError);    
    _tprintf(_T("Unable to store \"%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, RegisterEvent, UploadFile, ValidateLabel

Copyright © 2023 Catalyst Development Corporation. All rights reserved.