HttpAddUrl function

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


ULONG HttpAddUrl(
  _In_  HANDLE ReqQueueHandle,
  _In_  PCWSTR pFullyQualifiedUrl,
  PVOID pReserved
);

Parameters

ReqQueueHandle [in]

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.

pFullyQualifiedUrl [in]

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

pReserved

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.

ValueMeaning
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

Minimum supported client

Windows Vista, Windows XP with SP2 [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Http.h

Library

Httpapi.lib

DLL

Httpapi.dll

See also

HTTP Server API Version 1.0 Functions
HttpRemoveUrl
HttpAddUrlToUrlGroup

 

 

Community Additions

ADD
Show:
© 2015 Microsoft