Fungsi PFN_REGISTERMODULE

Artikel
07/19/2023

RegisterModule Menentukan prototipe fungsi untuk modul HTTP kode asli.

Sintaks

typedef HRESULT(WINAPI* PFN_REGISTERMODULE)(  
   DWORD dwServerVersion,  
   IHttpModuleRegistrationInfo* pModuleInfo,  
   IHttpServer* pGlobalInfo  
);

Parameter

dwServerVersion
DWORD yang berisi nomor versi utama IIS.

pModuleInfo
Penunjuk ke antarmuka IHttpModuleRegistrationInfo .

pGlobalInfo
Penunjuk ke antarmuka IHttpServer .

Tampilkan Nilai

Sebuah HRESULT. Nilai yang mungkin termasuk, tetapi tidak terbatas pada, yang ada dalam tabel berikut.

Nilai	Deskripsi
S_OK	Menunjukkan bahwa operasi berhasil.

Catatan

Modul Anda dapat mengembalikan nilai yang valid HRESULT , tetapi harus mengembalikan setidaknya S_OK untuk menunjukkan bahwa fungsi Anda RegisterModule berhasil.

Keterangan

PFN_REGISTERMODULE adalah prototipe fungsi untuk RegisterModule fungsi yang diperlukan semua modul HTTP untuk diimplementasikan untuk titik masuk DLL mereka.

Saat Anda membuat modul HTTP, modul Anda perlu menambahkan metode berikut RegisterModule :

HRESULT RegisterModule(  
   DWORD dwServerVersion,  
   IHttpModuleRegistrationInfo* pModuleInfo,  
   IHttpServer* pGlobalInfo  
)

Semua modul HTTP harus mengekspor fungsinya RegisterModule agar IIS dapat memuat modul. Anda dapat mengekspor RegisterModule fungsi dengan membuat file definisi modul (.def) untuk proyek DLL Anda atau mengkompilasi modul dengan menggunakan sakelar /EXPORT:RegisterModule .

Fungsi Anda RegisterModule harus menggunakan IHttpModuleRegistrationInfo antarmuka untuk mendaftar pemberitahuan dengan menggunakan metode SetRequestNotifications dan SetGlobalNotifications . RegisterModule juga perlu digunakan IHttpModuleRegistrationInfo untuk mendaftarkan prioritas modul dengan menggunakan metode SetPriorityForRequestNotification dan SetPriorityForGlobalNotification .

Parameter dwServerVersion berisi nomor versi utama untuk versi IIS yang memuat modul. Misalnya, untuk IIS 7.0 dwServerVersion parameter akan berisi 7.

Saat IIS memanggil fungsi Anda RegisterModule , IIS menyediakan IHttpServer antarmuka, yang dapat digunakan modul Anda untuk mengambil informasi tingkat server.

Catatan

Peristiwa pelacakan tidak boleh dinaikkan (melalui IHttpTraceContext::Metode QuickTrace atau cara lain melalui Metode IHttpServer::GetTraceContext) di dalam RegisterModule implementasi fungsi. Meningkatkan peristiwa pelacakan di dalam RegisterModule dapat menyebabkan pelanggaran akses karena terlalu dini dalam alur permintaan.

Contoh

Contoh kode berikut menunjukkan cara membuat modul HTTP "Halo Dunia" sederhana. Modul menentukan fungsi yang diekspor yang meneruskan RegisterModule instans antarmuka IHttpModuleFactory ke metode IHttpModuleRegistrationInfo::SetRequestNotifications dan mendaftar untuk pemberitahuan RQ_BEGIN_REQUEST . IIS menggunakan metode IHttpModuleFactory::GetHttpModule untuk membuat contoh kelas CHttpModule dan mengembalikan status keberhasilan. IIS juga menggunakan metode IHttpModuleFactory::Terminate untuk menghapus pabrik dari memori.

Saat pemberitahuan RQ_BEGIN_REQUEST terjadi, IIS memanggil metode CHttpModule::OnBeginRequest modul untuk memproses permintaan saat ini. OnBeginRequest menghapus buffer respons dan memodifikasi jenis MIME untuk respons. Metode ini kemudian membuat gugus data yang berisi string "Halo Dunia" dan mengembalikan string ke klien Web. Terakhir, modul mengembalikan indikator status yang memberi tahu IIS bahwa semua pemberitahuan selesai lalu keluar.

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

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

        // Create an HRESULT to receive return values from methods.
        HRESULT hr;
        
        // Retrieve a pointer to the response.
        IHttpResponse * pHttpResponse = pHttpContext->GetResponse();

        // Test for an error.
        if (pHttpResponse != NULL)
        {
            // Clear the existing response.
            pHttpResponse->Clear();
            // Set the MIME type to plain text.
            pHttpResponse->SetHeader(
                HttpHeaderContentType,"text/plain",
                (USHORT)strlen("text/plain"),TRUE);

            // Create a string with the response.
            PCSTR pszBuffer = "Hello World!";
            // Create a data chunk.
            HTTP_DATA_CHUNK dataChunk;
            // Set the chunk to a chunk in memory.
            dataChunk.DataChunkType = HttpDataChunkFromMemory;
            // Buffer for bytes written of data chunk.
            DWORD cbSent;
            
            // Set the chunk to the buffer.
            dataChunk.FromMemory.pBuffer =
                (PVOID) pszBuffer;
            // Set the chunk size to the buffer size.
            dataChunk.FromMemory.BufferLength =
                (USHORT) strlen(pszBuffer);
            // Insert the data chunk into the response.
            hr = pHttpResponse->WriteEntityChunks(
                &dataChunk,1,FALSE,TRUE,&cbSent);

            // Test for an error.
            if (FAILED(hr))
            {
                // Set the HTTP status.
                pHttpResponse->SetStatus(500,"Server Error",0,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 CHelloWorldFactory : public IHttpModuleFactory
{
public:
    HRESULT
    GetHttpModule(
        OUT CHttpModule ** ppModule, 
        IN IModuleAllocator * pAllocator
    )
    {
        UNREFERENCED_PARAMETER( pAllocator );

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

        // 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 CHelloWorldFactory,
        RQ_BEGIN_REQUEST,
        0
    );
}

Modul Anda harus mengekspor RegisterModule fungsi. Anda dapat mengekspor fungsi ini dengan membuat file definisi modul (.def) untuk proyek Anda, atau Anda dapat mengkompilasi modul dengan menggunakan sakelar /EXPORT:RegisterModule . Untuk informasi selengkapnya, lihat Panduan: Membuat Modul HTTP Request-Level Dengan Menggunakan Kode Asli.

Anda dapat secara opsional mengkompilasi kode dengan menggunakan __stdcall (/Gz) konvensi panggilan alih-alih secara eksplisit mendeklarasikan konvensi panggilan untuk setiap fungsi.

Persyaratan

Jenis	Deskripsi
Klien	- IIS 7.0 di Windows Vista - IIS 7.5 di Windows 7 - IIS 8.0 di Windows 8 - IIS 10.0 pada Windows 10
Server	- IIS 7.0 di Windows Server 2008 - IIS 7.5 di Windows Server 2008 R2 - IIS 8.0 di Windows Server 2012 - IIS 8.5 di Windows Server 2012 R2 - IIS 10.0 di Windows Server 2016
Produk	- 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

Lihat juga

Antarmuka IHttpModuleRegistrationInfo
Metode IHttpModuleRegistrationInfo::SetGlobalNotifications
Metode IHttpModuleRegistrationInfo::SetPriorityForGlobalNotification
Metode IHttpModuleRegistrationInfo::SetPriorityForRequestNotification
Metode IHttpModuleRegistrationInfo::SetRequestNotifications
Antarmuka IHttpServer

Bagikan melalui