HttpReadFragmentFromCache function (http.h)

The HttpReadFragmentFromCache function retrieves a response fragment having a specified name from the HTTP Server API cache.

Syntax

HTTPAPI_LINKAGE ULONG HttpReadFragmentFromCache(
  [in]  HANDLE           RequestQueueHandle,
  [in]  PCWSTR           UrlPrefix,
  [in]  PHTTP_BYTE_RANGE ByteRange,
  [out] PVOID            Buffer,
  [in]  ULONG            BufferLength,
  [out] PULONG           BytesRead,
  [in]  LPOVERLAPPED     Overlapped
);

Parameters

[in] RequestQueueHandle

Handle to the request queue with which the specified response fragment is associated. A request queue is created and its handle returned by a call to the HttpCreateRequestQueue function.

Windows Server 2003 with SP1 and Windows XP with SP2:  The handle to the request queue is created by the HttpCreateHttpHandle function.

[in] UrlPrefix

Pointer to a UrlPrefix string that contains the name of the fragment to be retrieved. This must match a UrlPrefix string used in a previous successful call to HttpAddFragmentToCache.

[in] ByteRange

Optional pointer to an HTTP_BYTE_RANGE structure that indicates a starting offset in the specified fragment and byte-count to be returned. NULL if not used, in which case the entire fragment is returned.

[out] Buffer

Pointer to a buffer into which the function copies the requested fragment.

[in] BufferLength

Size, in bytes, of the pBuffer buffer.

[out] BytesRead

Optional pointer to a variable that receives the number of bytes to be written into the output buffer. If BufferLength is less than this number, the call fails with a return of ERROR_INSUFFICIENT_BUFFER, and the value pointed to by pBytesRead can be used to determine the minimum length of buffer required for the call to succeed.

When making an asynchronous call using pOverlapped, set pBytesRead to NULL. Otherwise, when pOverlapped is set to NULL, pBytesRead must contain a valid memory address, and not be set to NULL.

[in] Overlapped

For asynchronous calls, set pOverlapped to point to an OVERLAPPED structure, or for synchronous calls, set it to NULL.

A synchronous call blocks until the cache operation is complete, whereas an asynchronous call immediately returns ERROR_IO_PENDING and the calling application then uses GetOverlappedResult or I/O completion ports to determine when the operation is completed. For more information about using OVERLAPPED structures for synchronization, see Synchronization and Overlapped Input and Output.

Return value

If the function succeeds, the return value is NO_ERROR.

If the function is used asynchronously, a return value of ERROR_IO_PENDING indicates that the cache request is queued and completes later through normal overlapped I/O completion mechanisms.

If the function fails, the return value is one of the following error codes.

Value	Meaning
ERROR_INVALID_PARAMETER	One or more of the supplied parameters is in an unusable form.
ERROR_MORE_DATA	The buffer pointed to by pBuffer is too small to receive all the requested data; the size of buffer required is pointed to by pBytesRead unless it was NULL or the call was asynchronous. In the case of an asynchronous call, the value pointed to by the lpNumberOfBytesTransferred parameter of the GetOverLappedResult function is set to the buffer size required.
Other	A system error code defined in WinError.h.

Requirements

Requirement	Value
Minimum supported client	Windows Vista, Windows XP with SP2 [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	http.h
Library	Httpapi.lib
DLL	Httpapi.dll

See also

HTTP Server API Version 1.0 Functions

HttpAddFragmentToCache

HttpFlushResponseCache