CWebStorage::PutData

CWebStorage::PutData Method

BOOL PutData(

LPCTSTR lpszObjectLabel,

LPCVOID lpvBuffer,

DWORD dwLength,

LPWEB_STORAGE_OBJECT lpObject

);

BOOL PutData(

LPCTSTR lpszObjectLabel,

LPCTSTR lpszObjectText,

INT cchObjectText,

LPWEB_STORAGE_OBJECT lpObject

);

BOOL PutData(

LPCTSTR lpszObjectLabel,

LPCVOID lpvBuffer,

DWORD dwLength,

LPCTSTR lpszContentType,

DWORD dwAttributes,

LPWEB_STORAGE_OBJECT lpObject

);

The PutData method stores the contents of buffer to a container and returns information about the new object.

Parameters

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.

lpvBuffer

A pointer to a buffer that contains the data to be stored. If this parameter is NULL, the dwLength parameter must have a value of zero and a storage object will be created which has no data associated with it.

dwLength

An unsigned integer value that specifies the number of bytes that will be copied from the lpvBuffer parameter and stored in the object. If the lpvBuffer parameter is NULL, this value must be zero or the method will fail.

lpszObjectText

A pointer to a null terminated string which is used with an alternate version of this method. The string will be stored as a text object and the cchObjectText parameter will specify the number of characters to be stored.

cchObjectText

An integer value that specifies the number of characters that will be copied from the lpszObjectText string and stored in the object. If the lpszObjectText parameter is NULL, this value must be zero or the method will fail. If this parameter is omitted, the length of the string will be calculated by counting the number of characters up to the terminating null.

lpszContentType

A pointer to a null terminated string that identifies the contents of the buffer being stored. 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 object label and the contents of the buffer.

dwAttributes

An unsigned integer that specifies the attributes associated with the storage object. If this parameter is omitted, the default value 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 that was created or replaced. 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 PutData method uploads the contents of a buffer 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 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.

If PutData method is used to store the contents of a string as a text object, the string should be terminated with a null character and cannot contain embedded nulls. If the Unicode version of this function is called, the contents of the string will be normalized prior to being converted to UTF-8 using canonical composition, where decomposed characters are combined to create their canonical precomposed equivalent.

The size of the text object that is created can be different from the length of the string buffer passed to this method, depending on how the text has been encoded and stored. This will almost always be the case when the Unicode version of this function is called because the UTF-16 string will be converted and stored as UTF-8 encoded text. This encoding will typically increase the size of the stored object unless the string only contains ASCII characters.

The version of the PutData method which accepts a string should only be used to store textual data in a null terminated string, and should never be used to store binary data. If you wish to create or update an object which contains binary data, you should always use use a byte array.

If you want to upload the contents of a file, the PutFile method simplifies this process. The example code below demonstrates how the Windows API can be used to read from a local file and store the contents using PutData.

If you are storing a large amount of data 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

HANDLE hFile = INVALID_HANDLE_VALUE;
LPBYTE lpContents = NULL;
DWORD dwLength = 0;
BOOL bFileRead = FALSE;
WEB_STORAGE_OBJECT webObject;

// Open a file on the local system and read the contents
// into a buffer that will be stored on the server
hFile = CreateFile(lpszLocalFile,
                   GENERIC_READ,
                   0,
                   NULL,
                   OPEN_EXISTING,
                   FILE_ATTRIBUTE_NORMAL,
                   NULL);

if (hFile == INVALID_HANDLE_VALUE)
{
    // Unable to open the file
    return;
}

// Get the size of the file and allocate a buffer large
// enough to store the contents of the file 
dwLength = GetFileSize(hFile, NULL);
lpContents = (LPBYTE)LocalAlloc(LPTR, dwLength + 1);

if (lpContents == NULL)
{
    // Memory allocation failed
    return;
}

bFileRead = ReadFile(hFile, lpContents, dwLength, &dwLength, NULL);
CloseHandle(hFile);

if (!bFileRead)
{
    // Unable to read the contents of the file
    return;
}

// Store the contents of the buffer, identifying it as an unstructured
// stream of bytes, and the object is created with read/write access
if (pStorage->PutData(lpszObjectLabel, lpContents, dwLength, &webObject))
{
    // The object was created or replaced, 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 created
    CString strError;

    pStorage->GetLastError(strError);    
    _tprintf(_T("Unable to create \"%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.

Parameters

Return Value

Remarks

Example

Requirements

See Also