CWebStorage::GetData Method  
 
BOOL GetData(
  LPCTSTR lpszObjectLabel,  
  LPBYTE lpBuffer,  
  LPDWORD lpdwLength,  
  LPWEB_STORAGE_OBJECT lpObject,  
);
BOOL GetData(
  LPCTSTR lpszObjectLabel,  
  HGLOBAL * lphgblBuffer,  
  LPDWORD lpdwLength,  
  LPWEB_STORAGE_OBJECT lpObject,  
);
BOOL GetData(
  LPCTSTR lpszObjectLabel,  
  LPTSTR lpszBuffer,  
  INT nMaxLength,  
  LPWEB_STORAGE_OBJECT lpObject,  
);
BOOL GetData(
  LPCTSTR lpszObjectLabel,  
  CString& strBuffer,  
  LPWEB_STORAGE_OBJECT lpObject,  
);

The GetData method retrieves the contents of a storage object and copies it to the memory buffer that is provided. Additional information about the object is optionally returned to the caller.

Parameters

lpszObjectLabel
A pointer to a null terminated string that specifies the label of the object that should be retrieved from the server.
lpBuffer
A pointer to a byte array which will contain the object's data. When this version of the method is called, the buffer must be pre-allocated by the application and large enough to store all of the data or the method will fail. The lpdwLength parameter must be initialized with the maximum size of the byte array, and will be updated with the actual number of bytes copied into the buffer when the method returns.
lphgblBuffer
A pointer to a HGLOBAL memory handle. When this version of the method returns, the handle will reference a block of memory allocated by the GlobalAlloc function and the lpdwLength parameter will contain the number of bytes copied. To obtain a pointer to the data, the application must call the GlobalLock function. It is the responsibility of the application to free the global memory handle when it is no longer needed.
lpszBuffer
A pointer to a string buffer which will contain the object's text when the method returns. When this version of the method is called, the string will be populated with the object contents and terminated with a null character. The nMaxLength parameter must specify the maximum number of characters that can be copied into the string, including the terminating null. This version of the function should only be used with text and must never be used with binary data.
strBuffer
A CString which will contain the object's text when the method returns. This version of the method requires the application be compiled with MFC or ATL support. This version of the function should only be used with text and must never be used with binary data.
lpdwLength
A pointer to an unsigned integer which should be initialized to the maximum number of bytes that can be copied to the buffer specified by the lpBuffer parameter. If the lpBuffer parameter points to a global memory handle, the length value should be initialized to zero. When the method returns, this value will be updated with the actual length of the file that was downloaded.
nMaxLength
An integer value that specifies the maximum number of characters that can be copied into the lpszBuffer string buffer provided by the caller. This value must be large enough to contain the entire contents of the object, including the terminating null character.
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 GetData method is used to retrieve a stored object from the server and copy it into a local buffer. The method may be used in one of several ways, depending on the needs of the application. The first method is to pre-allocate a buffer large enough to store the contents of the object. In this case, the lpBuffer parameter will point to the buffer that was allocated and the value that the lpdwLength parameter points to should be initialized to the size of that buffer.

The second method that can be used is to provide a pointer to an HGLOBAL global memory handle which will contain the file data when the method returns. In this case, the value that the lpdwLength parameter points to must be initialized to zero. It is important to note that the memory handle returned by the method must be freed by the application, otherwise a memory leak will occur. See the example code below.

The third method is to provide a string buffer which will contain the contents of a text object. The nMaxLength parameter must specify a size large enough to contain the entire object text, including a terminating null character. If the PutData method was previously used to store UTF-16 encoded text, you must use a byte array to retrieve that data. This method only recognizes UTF-8 encoded text and considers UTF-16 encoded text to be binary data. This version of the method should never be used to retrieve data from an object that does not contain text.

If you wish to retrieve the contents of an object and store it in a file, use the GetFile method.

Additional metadata about the object can be returned in a 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.

Example

HGLOBAL hgblBuffer = (HGLOBAL)NULL;
DWORD dwLength = 0;
LPCTSTR lpszObjectLabel = _T("MyAppData");

// Open the default global storage container
if (!pStorage->OpenStorage(WEB_STORAGE_GLOBAL))
{
    _tprintf(_T("Unable to open global storage\n"));
    return;
}

// Return the file data into block of global memory allocated by
// the GlobalAlloc method; the handle to this memory will be
// returned in the hgblBuffer parameter
if (pStorage->GetData(lpszObjectLabel, &hgblBuffer, &dwLength))
{
    // Lock the global memory handle, returning a pointer to the
    // resource data
    LPBYTE lpBuffer = (LPBYTE)GlobalLock(hgblBuffer);
    
    // After the data has been used, the handle must be unlocked
    // and freed, otherwise a memory leak will occur
    GlobalUnlock(hgblBuffer);
    GlobalFree(hgblBuffer);
}
else
{
    // The GetData method failed
    _tprintf(_T("Unable to retrieve object \"%s\"\n"), lpszObjectLabel);
}

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, GetObjectSize, GetObjectTime, PutFile, PutData

 
 

Copyright © 2023 Catalyst Development Corporation. All rights reserved.