HttpAddUrlToUrlGroup function (http.h)

Article
12/06/2022

The HttpAddUrlToUrlGroup function adds the specified URL to the URL Group identified by the URL Group ID.

This function replaces the HTTP version 1.0 HttpAddUrl function.

Syntax

HTTPAPI_LINKAGE ULONG HttpAddUrlToUrlGroup(
  [in]           HTTP_URL_GROUP_ID UrlGroupId,
  [in]           PCWSTR            pFullyQualifiedUrl,
  [in, optional] HTTP_URL_CONTEXT  UrlContext,
  [in]           ULONG             Reserved
);

Parameters

[in] UrlGroupId

The group ID for the URL group to which requests for the specified URL are routed. The URL group is created by the HttpCreateUrlGroup function.

[in] pFullyQualifiedUrl

A pointer to a Unicode string that contains a properly formed UrlPrefix String that identifies the URL to be registered. If you are not running as an administrator, specify a port number greater than 1024, otherwise you may get an ERROR_ACCESS_DENIED error.

[in, optional] UrlContext

The context that is associated with the URL registered in this call. The URL context is returned in the HTTP_REQUEST structure with every request received on the URL specified in the pFullyQualifiedUrl parameter.

[in] Reserved

Reserved. Must be zero.

Return value

If the function succeeds, it returns NO_ERROR

If the function fails, it returns one of the following error codes.

Value	Meaning
ERROR_INVALID_PARAMETER	The UrlGroupId does not exist. The Reserved parameter is not zero. The application does not have permission to add URLs to the Group. Only the application that created the URL Group can add URLs.
ERROR_ACCESS_DENIED	The calling process does not have permission to register the URL.
ERROR_ALREADY_EXISTS	The specified URL conflicts with an existing registration.

Value

Meaning

ERROR_INVALID_PARAMETER

The UrlGroupId does not exist.

The Reserved parameter is not zero.

The application does not have permission to add URLs to the Group. Only the application that created the URL Group can add URLs.

ERROR_ACCESS_DENIED

The calling process does not have permission to register the URL.

ERROR_ALREADY_EXISTS

The specified URL conflicts with an existing registration.

Remarks

The HTTP Server API supports existing applications using version 1.0 URL registrations, however, new development with the HTTP Server API should use HttpAddUrlToUrlGroup; HttpAddUrl should not be used.

An application can add multiple URLs to a URL group using repeated calls to HttpAddUrlToUrlGroup. Requests that match the specified URL are routed to the request queue associated with the URL group. For more information about how the HTTP Server API matches request URLs to registered URLs, see UrlPrefix Strings.

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