HttpDeclarePush function (http.h)

Article
10/13/2021

Declares a resource-to-subresource relationship to use for an HTTP server push. HTTP.sys then performs an HTTP 2.0 server push for the given resource, if the underlying protocol, connection, client, and policies allow the push operation.

Syntax

HTTPAPI_LINKAGE ULONG HttpDeclarePush(
  [in]           HANDLE                RequestQueueHandle,
  [in]           HTTP_REQUEST_ID       RequestId,
  [in]           HTTP_VERB             Verb,
  [in]           PCWSTR                Path,
  [in, optional] PCSTR                 Query,
  [in, optional] PHTTP_REQUEST_HEADERS Headers
);

Parameters

[in] RequestQueueHandle

The handle to an HTTP.sys request queue that the HttpCreateRequestQueue function returned.

[in] RequestId

The opaque identifier of the request that is declaring the push operation. The request must be from the specified queue handle.

[in] Verb

The HTTP verb to use for the push operation. The HTTP.sys push operation only supports HttpVerbGET and HttpVerbHEAD.

[in] Path

The path portion of the URL for the resource being pushed.

[in, optional] Query

The query portion of the URL for the resource being pushed. This string should not include the leading question mark (?).

[in, optional] Headers

The request headers for the push operation.

You should not provide a Host header, because HTTP.sys automatically generates the correct Host information. HTTP.sys does not support cross-origin push operations, so HTTP.sys enforces and generates Host information that matches the original client-initiated request.

The push request is not allowed to have an entity body, so you cannot include a non-zero Content-Length header or any Transfer-Encoding header.

Return value

If the function succeeds, it returns NO_ERROR.

If the function fails, it returns a system error code defined in WinError.h.

Remarks

You should call HttpDeclarePush before you send any response bytes that would cause the client to discover the subresource itself. Failure to observe this order results in a race between the server that is pushing the resource and the client that is retrieving the resources, which can waste bandwidth. The server application should only use HttpDeclarePush to push resources that the server application is highly confident are needed and not already cached by the client. If the server application pushes other resources, unnecessary use of bandwidth and CPU may occur.

Requirements

Requirement	Value
Minimum supported client	Windows 10 [desktop apps only]
Minimum supported server	Windows Server 2016 [desktop apps only]
Target Platform	Windows
Header	http.h
Library	Httpapi.lib
DLL	Httpapi.dll