Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

IHttpRequest::SetUrl Method

IIS 7.0

Modifies the request URL.

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;

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.

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.

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.

Caution noteCaution:

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.

NoteNote:

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

NoteNote:

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.

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
    );
}


Type

Description

Client

  • IIS 7.0 on Windows Vista

  • IIS 7.5 on Windows 7

  • IIS Express 7.5 on Windows XP, Windows Vista, Windows 7

  • IIS 8.0 on Windows 8 Client

Server

  • IIS 7.0 on Windows Server 2008

  • IIS 7.5 on Windows Server 2008 R2

  • IIS Express 7.5 on Windows Server 2003, Windows Server 2008, Windows Server 2008 R2

  • IIS 8.0 on Windows Server 2012

Product

IIS 7.0, IIS 7.5, IIS Express 7.5, IIS 8.0

Header

Httpserv.h

Community Additions

ADD
Show:
© 2015 Microsoft