HttpCreateRequestQueue function (http.h)
The HttpCreateRequestQueue function creates a new request queue or opens an existing request queue.
This function replaces the HTTP version 1.0 HttpCreateHttpHandle function.
Syntax
HTTPAPI_LINKAGE ULONG HttpCreateRequestQueue(
[in] HTTPAPI_VERSION Version,
[in, optional] PCWSTR Name,
[in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
[in, optional] ULONG Flags,
[out] PHANDLE RequestQueueHandle
);
Parameters
[in] Version
An HTTPAPI_VERSION structure indicating the request queue version. For version 2.0, declare an instance of the structure and set it to the predefined value HTTPAPI_VERSION_2 before passing it to HttpCreateRequestQueue.
The version must be 2.0; HttpCreateRequestQueue does not support version 1.0 request queues.
[in, optional] Name
The name of the request queue. The length, in bytes, cannot exceed MAX_PATH.
The optional name parameter allows other processes to access the request queue by name.
[in, optional] SecurityAttributes
A pointer to the SECURITY_ATTRIBUTES structure that contains the access permissions for the request queue.
This parameter must be NULL when opening an existing request queue.
[in, optional] Flags
The flags parameter defines the scope of the request queue. This parameter can be one or more of the following:
[out] RequestQueueHandle
A pointer to a variable that receives a handle to the request queue. This parameter must contain a valid pointer; it cannot be NULL.
Return value
If the function succeeds, it returns NO_ERROR
If the function fails, it returns one of the following error codes.
| Value | Meaning |
|---|---|
|
The Version parameter contains an invalid version. |
|
The length, in bytes, of the request queue name cannot exceed MAX_PATH.
The pSecurityAttributes parameter must be NULL when opening an existing request queue. The HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER can only be set when the request queue is created. The HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING can only be set when the application has permission to open an existing request queue. In this case, the pReqQueueHandle parameter must be a valid pointer, and the pName parameter must contain a valid request queue name; it cannot be NULL. The pReqQueueHandle parameter returned by HttpCreateRequestQueue is NULL. |
|
The pName parameter conflicts with an existing request queue that contains an identical name. |
|
The calling process does not have a permission to open the request queue. |
|
The application has not called HttpInitialize prior to calling HttpCreateRequestQueue. |
Remarks
The HTTP Server API supports existing applications using the version 1.0 request queues, however, new development with the HTTP Server API should use HttpCreateRequestQueue to create request queues; HttpCreateHttpHandle should not be used. The version 2.0 API are only compatible with the version 2.0 request queues created by HttpCreateRequestQueue.
The HTTP version 2 request queues require manual configuration; the application must create the URL Groups and associate one or more URL Group with the request queue by calling HttpSetUrlGroupProperty with the HttpServerBindingProperty. The application configures the request queue by calling HttpSetRequestQueueProperty with the desired configuration in the Property parameter. For more information about creating and configuring URL groups, see HttpCreateUrlGroup and HttpSetUrlGroupProperty.
Security attributes may be supplied in pSecurityAttributes parameter only when the request queue is created. Only the application that creates the request queue can set Access Control Lists (ACLs) on the request queue handle to allow processes (other than the creator application) permission to open, receive requests, and send responses on the request queue handle. By default, applications are not allowed to open a request queue unless they have been granted permission in the ACL.
The creator process can optionally use the HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER flag to indicate that it does not want to receive http requests.
HttpCreateRequestQueue allows applications to open an existing request queue with the HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING flag and retrieve the handle to the request queue. Non-controller applications can use this handle to perform HTTP I/O operations. Only the application that creates the request queue can set properties on it by calling the HttpSetRequestQueueProperty.
The handle to the request queue created by HttpCreateRequestQueue must be closed by calling HttpCloseRequestQueue before the application terminates or when the session is no longer required.
Applications must call HttpInitialize prior to calling HttpCreateRequestQueue.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | http.h |
| Library | Httpapi.lib |
| DLL | Httpapi.dll |