IHttpContext::CloneContext Method

IHttpContext::CloneContext Method

IIS 7.0

Creates a clone of the current request context.

virtual HRESULT CloneContext(
   IN DWORD dwCloneFlags,
   OUT IHttpContext** ppHttpContext
) = 0;

dwCloneFlags

[IN] A DWORD that contains the clone flags.

ppHttpContext

[OUT] A dereferenced pointer to an IHttpContext.

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 a specified parameter was not valid.

ERROR_NOT_ENOUGH_MEMORY

Indicates that there is insufficient memory to perform the operation.

The CloneContext method creates a clone of the current request context. You can control the cloning behavior by specifying the appropriate flags in the dwCloneFlags parameter. The following table lists the possible values for these flags.

Value

Description

CLONE_FLAG_BASICS

Clone the URL, query string, and HTTP method.

CLONE_FLAG_HEADERS

Clone the request headers.

CLONE_FLAG_ENTITY

Clone the entity body.

CLONE_FLAG_NO_PRECONDITION

Do not include any "range" and "if-" headers for the request.

CLONE_FLAG_NO_DAV

Do not include any WebDAV headers for the request.

Once you have created a cloned context, you can use the clone as you would use the parent context. For example, to execute a child request for a different URL than the parent URL, you would use the IHttpRequest::SetUrl method for the cloned context to change the URL of the cloned context before calling the parent context's IHttpContext::ExecuteRequest method.

The following code example demonstrates how to create an HTTP module that performs the following tasks:

  1. The module registers for the RQ_MAP_PATH notification.

  2. The module creates a CHttpModule class that contains OnMapPath and OnAsyncCompletion methods.

  3. When a Web client requests a URL, IIS calls the module's OnMapPath method. This method performs the following tasks:

    1. Tests to see whether the URL for the current request has a trailing slash or ends with /default.aspx. If the URL ends with either element, the module uses the CloneContext method to create a clone of the current request.

    2. Calls the clone's IHttpRequest::SetUrl method to set the URL for the clone to /example/default.aspx.

    3. Calls the IHttpContext::ExecuteRequest method to execute the child request.

    4. Tests for asynchronous completion. If asynchronous completion is pending, the module returns processing to the integrated request-processing pipeline. If not, the module releases the cloned context.

  4. If asynchronous completion is required, IIS calls the module's OnAsyncCompletion method. This method releases the cloned context.

  5. The module removes the CHttpModule class from memory and then exits.

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

// Create the module class.
class MyHttpModule : public CHttpModule
{

private:

    // Create a pointer for a child request.
    IHttpContext * m_pChildRequestContext;

public:

    MyHttpModule(void)
    {
        m_pChildRequestContext = NULL;
    }

    REQUEST_NOTIFICATION_STATUS
    OnMapPath(
        IN IHttpContext * pHttpContext,
        IN IMapPathProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );

        HRESULT hr;
        BOOL fCompletionExpected;

        // Retrieve a pointer to the URL.
        PCWSTR pwszUrl = pProvider->GetUrl();

        // Only process requests for the root.
        if (0 == wcscmp(pwszUrl,L"/") || 0 == wcscmp(pwszUrl,L"/default.aspx"))
        {            
            // Clone the current context.
            hr = pHttpContext->CloneContext(
                CLONE_FLAG_BASICS, &m_pChildRequestContext );

            // Test for a failure.
            if (FAILED(hr))
            {
                goto Failure;
            }

            // Test for an error.
            if ( NULL != m_pChildRequestContext )
            {
                // Set the URL for the child request.
                hr = m_pChildRequestContext->GetRequest()->SetUrl(
                    "/example/default.aspx",
                    (DWORD)strlen("/example/default.aspx"),false);

                // Test for a failure.
                if (FAILED(hr))
                {
                    goto Failure;
                }

                // Execute the child request.
                hr = pHttpContext->ExecuteRequest(
                    TRUE, m_pChildRequestContext,
                    0, NULL, &fCompletionExpected );

                // Test for a failure.
                if (FAILED(hr))
                {
                    goto Failure;
                }

                // Test for pending asynchronous operations.
                if (fCompletionExpected)
                {
                    return RQ_NOTIFICATION_PENDING;
                }

            }

 Failure:
            // Test for a child request.
            if (NULL != m_pChildRequestContext)
            {
                // Release the child request.
                m_pChildRequestContext->ReleaseClonedContext();
                m_pChildRequestContext = NULL;
            }
        }

        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }

    REQUEST_NOTIFICATION_STATUS
        OnAsyncCompletion(
        IN IHttpContext * pHttpContext,
        IN DWORD dwNotification,
        IN BOOL fPostNotification,
        IN IHttpEventProvider * pProvider,
        IN IHttpCompletionInfo * pCompletionInfo
        )
    {
        // Test for a child request.
        if (NULL != m_pChildRequestContext)
        {
            // Release the child request.
            m_pChildRequestContext->ReleaseClonedContext();
            m_pChildRequestContext = NULL;
        }
        // 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 we 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 );

    return pModuleInfo->SetRequestNotifications(
        new MyHttpModuleFactory,
        RQ_MAP_PATH,
        0
    );
}


Your module must export the RegisterModule function. You can export this function by creating a module definition (.def) file for your project, or you can compile the module by using the /EXPORT:RegisterModule switch. For more information, see Walkthrough: Creating a Request-Level HTTP Module By Using Native Code.

You can optionally compile the code by using the __stdcall (/Gz) calling convention instead of explicitly declaring the calling convention for each function.

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 8 Server

Product

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

Header

Httpserv.h

Community Additions

ADD
Show:
© 2016 Microsoft