IIS7 modules vs. IIS6 ISAPI #9: Intuitive object model

This is the second post in the series on why IIS7 module development beats the pants off the ISAPI development for the previous version of IIS.

Last time, we talked about the class-based encapsulation model for building IIS modules, and how it’s based on C++ classes with type-safe methods as opposed to ISAPI’s static C-style function entrypoints with VOID arguments.

With ISAPI, the majority of server interactions were exposed through a generic SupportFunction callback available off the EXTENSION_CONTROL_BLOCK or HTTP_FILTER_CONTEXT  structures provided to the ISAPI Extension or ISAPI filter entrypoint functions:

BOOL ServerSupportFunction(

      HCONN ConnID,

      DWORD dwServerSupportFunction,

      LPVOID lpvBuffer,

      LPDWORD NULL,

      LPDWORD NULL

);

The ISAPI would perform the required operation by invoking this callback with the specific Function ID, and pass required arguments via the generic arguments.  For example, to check whether the client is still connected, the ISAPI would do:

BOOL fConnected = FALSE;

if ( !pECB->ServerSupportFunction( pECB->connID,

                                   HSE_REQ_IS_CONNECTED,

                                   &fConnected,

                                   NULL,

                                   NULL ) )

{

    hr = HRESULT_FROM_WIN32 ( GetLastError() );

    goto Finished;

}

The developer would first have to read documentation to figure out what support functions were available, and really carefully reading about what each function expected in its arguments.  Errors where the wrong values were being passed into the function that caused AVs or strange behavior because the function was expecting something else were extremely common.

In contrast, IIS7 provides a rich class-based API that exposes server functionality via intuitive server objects.  When the server calls one of the callback methods on your CHttpModule-derived instance, it always provides an instance of the request’s IHttpContext interface, from which you module can access all other objects associated with the request:

REQUEST_NOTIFICATION_STATUS

CMyHttpModule::OnAcquireRequestState(

    IN IHttpContext *             pHttpContext,

    IN OUT IHttpEventProvider *   pProvider

)

{

    IHttpRequest*  pRequest 
                      = pHttpContext->GetRequest();

    IHttpResponse* pResponse
                      = pHttpContext->GetResponse();

    //

    //  Do stuff with request and response

    //

}

With this model, the code needed to determine whether the client is still connected becomes:

BOOL   fConnected = pHttpContext->GetConnection()->IsConnected();

Each of the classes in the API provide strongly typed methods for interacting with the server and providing request processing, such as:

class IHttpRequest

{

    virtual

    PCSTR

    GetHeader(

        IN PCSTR       pszHeaderName,

        OUT USHORT *   pcchHeaderValue = NULL

    ) const = 0;

    virtual

    PCSTR

    GetHttpMethod(

        VOID

    ) const = 0;

    virtual

    PSOCKADDR

    GetRemoteAddress(

        VOID

    ) const = 0;

    virtual

    HRESULT

    GetClientCertificate(

        OUT HTTP_SSL_CLIENT_CERT_INFO ** ppClientCertInfo,

        OUT BOOL *                   &nbsp
;   pfClientCertNegotiated

    ) = 0;

    // and many others

};

class IHttpResponse

{

    virtual

    HRESULT

    SetStatus(

        IN USHORT                   statusCode,

        IN PCSTR                    pszReason,

        IN USHORT                   uSubStatus = 0,

        IN HRESULT                  hrErrorToReport = S_OK,

        IN IAppHostConfigException *pException = NULL,

        IN BOOL                     fTrySkipCustomErrors = FALSE

    ) = 0;

    virtual

    HRESULT

    SetHeader(

        IN PCSTR      pszHeaderName,

        IN PCSTR      pszHeaderValue,

        IN USHORT     cchHeaderValue,

        IN BOOL       fReplace

    ) = 0;

    virtual

    VOID

    ResetConnection(

        VOID

    ) = 0;

    // and many others …

};

Besides being much more intuitive, the IIS7 object model is significantly more powerful / expressive then ISAPI.  The biggest reason for this is the fact that all server features that IIS ships with are written on top of these APIs – as opposed to being built into the server using private APIs like it was the case with previous versions.  While it was acceptable before to expose limited extensibility and have the built in features use private interfaces, now IIS has the requirement of exposing all necessary interfaces needed to build every single feature it ships with.  

All in all, the new IIS7 object model provides 50+ classes and 300+ methods for providing request processing and otherwise interacting with the server.  The object model is fairly similar to the ASP.NET object model, so if you have played with ASP.NET development, you will find most concepts familiar (of course, C++ development experience required).

To learn more:
– To learn more about building IIS7 modules, be sure to check out Developing a Native (C/C++) Module and the associated IIS7 Module Starter Kit for C++.
– To learn more about the other improvements in the IIS7 core server and extensibility, check out the IIS7 Core Web Server.
– As always, feel free to leave comments or post questions here or on IIS.NET Forums.

Next up – still 8 more ways we have improved IIS development in IIS7 – and these are about to get even better / more specific.