IHttpRequest：：SetUrl 方法

修改要求 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]字串的指標，其中包含要設定的 URL。

cchUrl
[IN]所 pszUrl 指定 URL 的長度，以字元為單位。

fResetQueryString
[IN] true 若要重設現有的查詢字串;否則為 false 。

傳回值

HRESULT。 可能的值包括 (但不限於) 下表中的這些值。

值	描述
S_OK	表示作業成功。
ERROR_INVALID_PARAMETER	表示指定的參數無效 (例如，指定的 URL 太長) 。
ERROR_NOT_ENOUGH_MEMORY	表示記憶體不足，無法執行作業。

備註

方法 SetUrl 會修改目前要求的 URL。 方法有兩個 SetUrl 多載版本。 其中一個可讓您使用字串指標來指定標頭。 另一個多載會使用寬字元串的指標。

後續的要求處理函式和記錄作業將會處理新的 URL，就像用戶端已要求 URL 一樣。 因此，修改 URL 所造成的任何錯誤狀況都會傳回給用戶端。 例如，如果新的 URL 不存在，Web 服務器會傳回 HTTP 404 錯誤。

警告

方法 SetUrl 會在收集要求的初始參數之後呼叫，因此後續的要求處理可能不知道變更的 URL。 例如，擷取 URL 伺服器變數會反映原始要求，而不是變更的 URL。 實作者應該呼叫 IHttpCoNtext：：ExecuteRequest 方法 ，而不是 SetUrl ，以便透過完整的管線執行要求。 SetUrl方法不應該用於 URL 重寫。

注意

不同于 IHttpResponse：：Redirect 方法， SetUrl 此方法不會將用戶端重新導向至新的 URL。

注意

您必須在 HTTP 整合式要求處理管線中的第一個事件之前呼叫 SetUrl 方法。 SetUrl從 OnPostBeginRequest 處理常式呼叫 方法會導致不確定的行為。

範例

下列程式碼範例示範如何使用 SetUrl 方法來將要求的 URL 變更為另一個 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
    );
}

規格需求

類型	Description
Client	- Windows Vista 上的 IIS 7.0 - Windows 7 上的 IIS 7.5 - Windows 8上的 IIS 8.0 - Windows 10上的 IIS 10.0
伺服器	- Windows Server 2008 上的 IIS 7.0 - Windows Server 2008 R2 上的 IIS 7.5 - Windows Server 2012上的 IIS 8.0 - Windows Server 2012 R2 上的 IIS 8.5 - Windows Server 2016上的 IIS 10.0
產品	- 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
標頭	Httpserv.h

另請參閱

IHttpRequest 介面
IHttpRequest：：GetUrlChanged 方法