IHttpContext::ExecuteRequest Method

Article
05/24/2022

Executes a child request.

Syntax

virtual HRESULT ExecuteRequest(  
   IN BOOL fAsync,  
   IN IHttpContext* pHttpContext,  
   IN DWORD dwExecuteFlags,  
   IN IHttpUser* pHttpUser,  
   OUT BOOL* pfCompletionExpected = NULL  
) = 0;

Parameters

fAsync
[IN] Always true (specifies asynchronous execution).

pHttpContext
[IN] A pointer to the child IHttpContext to execute.

dwExecuteFlags
[IN] A DWORD that contains the request execution flags.

pHttpUser
[IN] A pointer to an IHttpUser for the request. (Optional)

pfCompletionExpected
[OUT] true if asynchronous completion is still pending; otherwise, false. (Optional)

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_NOT_SUPPORTED	Indicates that the request is not supported (for example, `fAsync` is set to `false` or the child request was not cloned from the parent request).
ERROR_STACK_OVERFLOW	Indicates that request exceeds the limit for recursive child requests.

Remarks

The ExecuteRequest method executes the child request that is specified by the IHttpContext interface in the pHttpContext parameter. You must create this request context by using the IHttpContext::CloneContext method.

Important

Attempting to execute a child request that was not cloned by the parent request will return ERROR_NOT_SUPPORTED.

Each child context can be executed only once, although child requests can be nested recursively.

Note

The limit for recursive child requests is 10.

The ExecuteRequest method supports only asynchronous operation, which prevents exhausting the thread pool.

Important

Attempting to execute a synchronous child request will return ERROR_NOT_SUPPORTED.

You can control the execution behavior for the child request by specifying execution flags in dwExecuteFlags. The following table lists the possible values for these flags.

Value	Description
EXECUTE_FLAG_NO_HEADERS	Suppress the HTTP headers for the child request.
EXECUTE_FLAG_IGNORE_CURRENT_INTERCEPTOR	Ignore the current script map handler for this request chain.
EXECUTE_FLAG_IGNORE_APPPOOL	Execute the request even if the child request is not in the same application pool.
EXECUTE_FLAG_DISABLE_CUSTOM_ERROR	Disable custom errors for the child request.
EXECUTE_FLAG_SAME_URL	The URL for the child request is the same as the parent request. Note: Script map handlers use this flag to forward execution.
EXECUTE_FLAG_BUFFER_RESPONSE	Do not flush the child response; return the response to the parent request.
EXECUTE_FLAG_HTTP_CACHE_ELIGIBLE	The child response is still eligible for caching by Http.sys. Note: Caching is disabled by default when a child request is executed.

If you specify an IHttpUser interface for pHttpUser, authentication will be skipped for the child request.

Example

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

The module registers for the RQ_MAP_PATH notification.
The module creates a CHttpModule class that contains OnMapPath and OnAsyncCompletion methods.
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 matches two specific URLs at the root of the Web site. If the URL matches either of the specified URLs, the module uses the IHttpContext::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 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.
If asynchronous completion is required, IIS calls the module's OnAsyncCompletion method. This method releases the cloned context.
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.

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