CHttpClient::GetData Method  
 
INT GetData(
  LPCTSTR lpszResource,  
  LPBYTE lpBuffer,  
  LPDWORD lpdwLength,  
  DWORD dwOptions  
);
INT GetData(
  LPCTSTR lpszResource,  
  HGLOBAL* lpBuffer,  
  LPDWORD lpdwLength,  
  DWORD dwOptions  
);
INT GetData(
  LPCTSTR lpszResource,  
  LPTSTR lpBuffer,  
  DWORD dwMaxLength  
);
INT GetData(
  LPCTSTR lpszResource,  
  CString& strBuffer,  
  DWORD dwOptions  
);

The GetData method requests a resource from the server and copies the data to the specified buffer.

Parameters

lpszResource
A pointer to a string that specifies the resource that will be transferred to the local system. This may be the name of a file on the server, or it may specify the name of a script that will be executed and the output returned to the caller. This string may specify a valid URL for the current server that the client is connected to.
lpBuffer
A pointer to a byte buffer which will contain the data transferred from the server, or a pointer to a global memory handle which will reference the data when the method returns.
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 lpvBuffer parameter. If the lpvBuffer 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.
dwMaxLength
An unsigned integer value which specifies the maximum number of characters can be copied into the lpBuffer string. This parameter is used with the version of the method that returns the data in a character array and includes the terminating null character. This value must be greater than one and the lpBuffer parameter cannot be NULL, otherwise the method will return an error.
dwOptions
An unsigned integer that specifies one or more options. This parameter is constructed by using a bitwise operator with any of the following values:
Constant Description
HTTP_TRANSFER_DEFAULT The default transfer mode. The resource data is downloaded to the local system exactly as it is stored on the server. If you are requesting a text-based resource, the data may use a different end-of-line character sequence. For example, the end-of-line character may be a single linefeed character instead of a carriage return and linefeed pair.
HTTP_TRANSFER_CONVERT If the resource being downloaded from the server is textual, the data is automatically converted so that the end of line character sequence is compatible with the Windows platform. Individual carriage return or linefeed characters are converted to carriage return/linefeed character sequences.
HTTP_TRANSFER_COMPRESS This option informs the server that the client is willing to accept compressed data. If the server supports compression for the specified resource, then the data will be automatically expanded before being returned to the caller. This option is selected by default if compression has been enabled using the EnableCompression method.
HTTP_TRANSFER_ERRORDATA This option causes the client to accept error data from the server if the request fails. If this option is specified, an error response from the server will not cause the method to fail. Instead, the response is returned to the client and the method will succeed. If this option is used, your application should call HttpGetResultCode to obtain the HTTP status code returned by the server. This will enable you to determine if the operation was successful.

Return Value

If the method succeeds, the return value is the server result code. If the method fails, the return value is HTTP_ERROR. To get extended error information, call GetLastError.

Remarks

The GetData method is used to retrieve a resource from the server and copy it into a local buffer. The method may be used in one of two 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 file. In this case, the lpBuffer parameter will point to the buffer that was allocated, 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 have the lpBuffer parameter point to a 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.

If the third method or fourth method is used, where the data is returned in a string buffer, the data may be modified so that the end-of-line character sequence matches the convention used by the Windows platform (a carriage return character followed by a linefeed). If Unicode is being used, the data will be converted from a byte array to a Unicode string. An application should only use these versions of the GetData method if the resource or remote file contains text.

If compression has been enabled and the server returns compressed data, it will be automatically expanded before being returned to the caller. This will result in a difference between the value returned in the lpdwLength parameter, which contains the actual number of bytes copied into the buffer, and the values reported by GetTransferStatus. For example, if the server returns 5,000 bytes of compressed data that expands into 15,000 bytes, this function will return 15,000 as the number of bytes copied into the buffer. However, the GetTransferStatus method will return the content length as the original 5,000 bytes of compressed data. For this reason, you should always use the value returned in the lpdwLength parameter to determine the amount of data that has been copied into the buffer.

This method will cause the current thread to block until the file transfer completes, a timeout occurs or the transfer is canceled. During the transfer, the HTTP_EVENT_PROGRESS event will be periodically fired, enabling the application to update any user interface controls. Event notification must be enabled, either by calling EnableEvents, or by registering a callback function using the RegisterEvent method.

To determine the current status of a file transfer while it is in progress, use the GetTransferStatus method.

Example

HGLOBAL hgblBuffer = (HGLOBAL)NULL;
LPBYTE lpBuffer = (LPBYTE)NULL;
DWORD cbBuffer = 0;

// Return the file data into block of global memory allocated by
// the GlobalAlloc function; the handle to this memory will be
// returned in the hgblBuffer parameter
nResult = pClient->GetData(lpszResource, &hgblBuffer, &cbBuffer);

if (nResult != HTTP_ERROR)
{
    // Lock the global memory handle, returning a pointer to the
    // resource data
    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);
}

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: cshtpv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

EnableCompression, EnableEvents, GetFile, GetText, GetTransferStatus, PostData, PutData, PutFile, RegisterEvent

  
 

Copyright © 2023 Catalyst Development Corporation. All rights reserved.