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 |
|---|---|
|
The calling application does not have permission to register the URL. |
|
The calling application did not call HttpInitialize before calling this function. |
|
One of the parameters are invalid. |
|
The specified UrlPrefix conflicts with an existing registration. |
|
Insufficient resources to complete the operation. |
|
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 |