IHttpRequest::SetUrl Method

Article
03/14/2023

Modifies the request URL.

Syntax

virtual HRESULT SetUrl(  
   IN PCWSTR pszUrl,  
   IN DWORD cchUrl,  
   IN BOOL fResetQueryString  
) = 0;  
  
virtual HRESULT SetUrl(  
   IN PCSTR pszUrl,  
   IN DWORD cchUrl,  
   IN BOOL fResetQueryString  
) = 0;

Parameters

pszUrl
[IN] A pointer to a string that contains the URL to set.

cchUrl
[IN] The length, in characters, of the URL specified by pszUrl.

fResetQueryString
[IN] true to reset the existing query string; otherwise, false.

Return Value

An HRESULT. Possible values include, but are not limited to, those in the following table.

Value	Description
S_OK	Indicates that the operation was successful.
ERROR_INVALID_PARAMETER	Indicates that the specified parameter is not valid (for example, the specified URL is too long).
ERROR_NOT_ENOUGH_MEMORY	Indicates that there is insufficient memory to perform the operation.

Remarks

The SetUrl method modifies the URL for the current request. There are two overloaded versions of the SetUrl method. One enables you to specify the header by using a pointer to a string. The other overload uses a pointer to a wide string.

Subsequent request processing functions and logging operations will process the new URL as if the client had requested the URL. Therefore, any error conditions caused by modifying the URL will be returned to the client. For example, if the new URL does not exist, the Web server will return an HTTP 404 error.

Warning

The SetUrl method is called after the initial parameters for the request have been gathered, so subsequent request processing may be unaware of the changed URL. For example, retrieving the URL server variable will reflect the original request, not the changed URL. Implementers should call IHttpContext::ExecuteRequest Method instead of SetUrl in order to run the request through the complete pipeline. The SetUrl method should not be used for URL rewriting.

Note

Unlike the IHttpResponse::Redirect method, the SetUrl method does not redirect a client to a new URL.

Note

You must call the SetUrl method before the first event in the HTTP integrated request-processing pipeline. Calling the SetUrl method from an OnPostBeginRequest handler results in indeterminate behavior.

Example

The following code example demonstrates how to use the SetUrl method to change a requested URL to another URL.

#define _WINSOCKAPI_
#include <windows.h>
#include <sal.h>
#include <httpserv.h>

// Create the module class.
class MyHttpModule : public CHttpModule
{
public:
    REQUEST_NOTIFICATION_STATUS
    OnBeginRequest(
        IN IHttpContext * pHttpContext,
        IN IHttpEventProvider * pProvider
    )
    {
        HRESULT hr;

        // Retrieve a pointer to the request.
        IHttpRequest * pHttpRequest = pHttpContext->GetRequest();

        // Test for an error.
        if (pHttpRequest != NULL)
        {
            // Create a buffer with an example URL.
            PCSTR pszBuffer = "/example/default.aspx";
            // Set the URL for the request.
            hr = pHttpRequest->SetUrl(
                pszBuffer,(DWORD)strlen(pszBuffer),true);
            // Test for an error.
            if (FAILED(hr))
            {
                // Set the error status.
                pProvider->SetErrorStatus( hr );
                // End additional processing.
                return RQ_NOTIFICATION_FINISH_REQUEST;
            }
        }
 
        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }
};

// Create the module's class factory.
class MyHttpModuleFactory : public IHttpModuleFactory
{
public:
    HRESULT
    GetHttpModule(
        OUT CHttpModule ** ppModule, 
        IN IModuleAllocator * pAllocator
    )
    {
        UNREFERENCED_PARAMETER( pAllocator );

        // Create a new instance.
        MyHttpModule * pModule = new MyHttpModule;

        // Test for an error.
        if (!pModule)
        {
            // Return an error if the factory cannot create the instance.
            return HRESULT_FROM_WIN32( ERROR_NOT_ENOUGH_MEMORY );
        }
        else
        {
            // Return a pointer to the module.
            *ppModule = pModule;
            pModule = NULL;
            // Return a success status.
            return S_OK;
        }            
    }

    void Terminate()
    {
        // Remove the class from memory.
        delete this;
    }
};

// Create the module's exported registration function.
HRESULT
__stdcall
RegisterModule(
    DWORD dwServerVersion,
    IHttpModuleRegistrationInfo * pModuleInfo,
    IHttpServer * pGlobalInfo
)
{
    UNREFERENCED_PARAMETER( dwServerVersion );
    UNREFERENCED_PARAMETER( pGlobalInfo );

    // Set the request notifications and exit.
    return pModuleInfo->SetRequestNotifications(
        new MyHttpModuleFactory,
        RQ_BEGIN_REQUEST,
        0
    );
}

Requirements

Type	Description
Client	- IIS 7.0 on Windows Vista - IIS 7.5 on Windows 7 - IIS 8.0 on Windows 8 - IIS 10.0 on Windows 10
Server	- IIS 7.0 on Windows Server 2008 - IIS 7.5 on Windows Server 2008 R2 - IIS 8.0 on Windows Server 2012 - IIS 8.5 on Windows Server 2012 R2 - IIS 10.0 on Windows Server 2016
Product	- IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0 - IIS Express 7.5, IIS Express 8.0, IIS Express 10.0
Header	Httpserv.h