HttpDeclarePush function (http.h)
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 |