BOOL WINAPI WebPutObject(
	HSTORAGE hStorage,
	LPCTSTR lpszObjectLabel,
	LPCVOID lpvBuffer,
	DWORD dwLength
);

The WebPutObject function creates a new storage object or overwrites an existing object with the contents of the buffer provided.

Parameters

hStorage

A handle to the storage container.

lpszObjectLabel

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 function will fail if the label contains any illegal characters.

lpvBuffer

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 function will fail.

Return Value

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

Remarks

The WebPutObject function stores the contents of a buffer to the storage container specified by the hStorage handle. If an object with this name already exists, its data will be replaced with the contents of the file. The object will be created using the default attributes that permit read and write access, and it will automatically determine the content type based on the data being stored.

Although storage object labels are similar to Windows file names, they are case-sensitive. When requesting information about an object, your application must specify the label name exactly as it was created using this function. The object label cannot contain wildcard characters.

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

If you want to specify the object content type, its attributes, or obtain additional information about the storage object that was created, use the WebPutObjectEx function.

If you want to upload the contents of a file, the WebPutFile function 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 WebPutObject.

If you are storing a large amount of data and want your application to receive progress updates during the data transfer, use the WebRegisterEvent function and provide a pointer to a callback function that will receive event notifications.

Example

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

// 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
if (WebPutObject(hStorage, lpszObjectLabel, lpContents, dwLength))
{
    _tprintf(_T("WebPutObject stored %lu bytes\n"), dwLength);
}
else
{
    // The object could not be created
    TCHAR szError[128];

    WebGetErrorString(WebGetLastError(), szError, 128);    
    _tprintf(_T("Unable to create \"%s\" (%s)\n"), lpszObjectLabel, szError);
}

Requirements

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

See Also

WebPutFile, WebPutObjectEx, WebRegisterEvent

Copyright © 2025 Catalyst Development Corporation. All rights reserved.