HttpAddUrl function (http.h)

The HttpAddUrl function registers a given URL so that requests that match it are routed to a specified HTTP Server API request queue. An application can register multiple URLs to a single request queue using repeated calls to HttpAddUrl. For more information about how HTTP Server API matches request URLs to registered URLs, see UrlPrefix Strings.

Starting with HTTP Server API Version 2.0, applications should call HttpAddUrlToUrlGroup to register a URL; HttpAddUrl should not be used.

Syntax

HTTPAPI_LINKAGE ULONG HttpAddUrl(
  [in] HANDLE RequestQueueHandle,
  [in] PCWSTR FullyQualifiedUrl,
       PVOID  Reserved
);

Parameters

[in] RequestQueueHandle

The handle to the request queue to which requests for the specified URL are to be routed. 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] FullyQualifiedUrl

A pointer to a Unicode string that contains a properly formed UrlPrefix string that identifies the URL to be registered.

Reserved

Reserved; must be NULL.

Return value

If the function succeeds, the return value is NO_ERROR.

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

Value Meaning
ERROR_ACCESS_DENIED
The calling application does not have permission to register the URL.
ERROR_DLL_INIT_FAILED
The calling application did not call HttpInitialize before calling this function.
ERROR_INVALID_PARAMETER
One of the parameters are invalid.
ERROR_ALREADY_EXISTS
The specified UrlPrefix conflicts with an existing registration.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
A system error code defined in WinError.h.

Remarks

As stated in the UrlPrefix Strings topic, the scheme specification of the UrlPrefix to be registered must be either lower-case "http" or lower-case "https". No other substring is valid.

Also, it is not possible to register URLs having different schemes on the same port. That is, "http" and "https" schemes cannot coexist on a port.

Also be aware that HttpAddUrl registers any UrlPrefix passed to it as long as the string is well-formed. Any validation of existence, accessibility, ownership, or other characteristic of the specified URL namespace must be handled by the application.

To release the resources allocated as a result of the registration performed by HttpAddUrl, make a matching call to the HttpRemoveUrl function when your application has finished with the namespace involved.

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

HttpAddUrlToUrlGroup

HttpRemoveUrl