windows-server-2003/base/ntos/fsrtl/filtrctx.c

/*++

Copyright (c) 1997  Microsoft Corporation

Module Name:

    FiltrCtx.c

Abstract:

    This module provides three routines that allow filesystem filter drivers
    to associate state with FILE_OBJECTs -- for filesystems which support
    an extended FSRTL_COMMON_HEADER with FsContext.

    These routines depend on fields (FastMutext and FilterContexts)
    added at the end of FSRTL_COMMON_HEADER in NT 5.0.

    Filesystems should set FSRTL_FLAG2_SUPPORTS_FILTER_CONTEXTS if
    these new fields are supported.  They must also initialize the mutex
    and list head.

    Filter drivers must use a common header for the context they wish to
    associate with a file object:

        FSRTL_FILTER_CONTEXT:
                LIST_ENTRY  Links;
                PVOID       OwnerId;
                PVOID       InstanceId;

    The OwnerId is a bit pattern unique to each filter driver
    (e.g. the device object).

    The InstanceId is used to specify a particular instance of the context
    data owned by a filter driver (e.g. the file object).

Author:

    Dave Probert      [DavePr]    30-May-1997

Revision History:

    Neal Christiansen [nealch]    12-Jan-2001   Changed APIs to take 
                                                PFSRTL_ADVANCED_FCB_HEADER
                                                structures instead of
                                                FileObjects.

    Neal Christiansen [nealch]    19-Jan-2001   Added mutex lock to FsRtlTeardownFilterContexts
                                                because you can get filters
                                                trying to delete at the same 
                                                time the file system is trying
                                                to delete.

    Neal Christiansen [nealch]    25-Apr-2001   Added FileObject context routines
    Neal Christiansen [nealch]    25-Apr-2001   Marked all of this code as pageable
--*/

#include "FsRtlP.h"

#define MySearchList(pHdr, Ptr) \
    for ( Ptr = (pHdr)->Flink;  Ptr != (pHdr);  Ptr = Ptr->Flink )


//
//  The rest of the routines are not marked pageable so they can be called
//  during the paging path
//

NTKERNELAPI
VOID
FsRtlTeardownFilterContexts (
  IN PFSRTL_ADVANCED_FCB_HEADER AdvFcbHeader
  );


#ifdef ALLOC_PRAGMA
#pragma alloc_text(PAGE, FsRtlTeardownPerStreamContexts)
#pragma alloc_text(PAGE, FsRtlTeardownFilterContexts)
#pragma alloc_text(PAGE, FsRtlPTeardownPerFileObjectContexts)
#endif


//===========================================================================
//                  Handles Stream Contexts
//===========================================================================

NTKERNELAPI
NTSTATUS
FsRtlInsertPerStreamContext (
  IN PFSRTL_ADVANCED_FCB_HEADER AdvFcbHeader,
  IN PFSRTL_PER_STREAM_CONTEXT Ptr
  )
/*++

Routine Description:

    This routine associates filter driver context with a stream.

Arguments:

    AdvFcbHeader - Advanced FCB Header for stream of interest.

    Ptr - Pointer to the filter-specific context structure.
        The common header fields OwnerId and InstanceId should
        be filled in by the filter driver before calling.

Return Value:

    STATUS_SUCCESS - operation succeeded.

    STATUS_INVALID_DEVICE_REQUEST - underlying filesystem does not support
        filter contexts.

--*/

{
    if (!AdvFcbHeader || 
        !FlagOn(AdvFcbHeader->Flags2,FSRTL_FLAG2_SUPPORTS_FILTER_CONTEXTS))
    {

        return STATUS_INVALID_DEVICE_REQUEST;
    }

    ExAcquireFastMutex(AdvFcbHeader->FastMutex);

    InsertHeadList(&AdvFcbHeader->FilterContexts, &Ptr->Links);

    ExReleaseFastMutex(AdvFcbHeader->FastMutex);
    return STATUS_SUCCESS;
}


NTKERNELAPI
PFSRTL_PER_STREAM_CONTEXT
FsRtlLookupPerStreamContextInternal (
  IN PFSRTL_ADVANCED_FCB_HEADER AdvFcbHeader,
  IN PVOID         OwnerId     OPTIONAL,
  IN PVOID         InstanceId  OPTIONAL
  )
/*++

Routine Description:

    This routine lookups filter driver context associated with a stream.

    The macro FsRtlLookupFilterContext should be used instead of calling
    this routine directly.  The macro optimizes for the common case
    of an empty list.

Arguments:

    AdvFcbHeader - Advanced FCB Header for stream of interest.

    OwnerId - Used to identify context information belonging to a particular
        filter driver.

    InstanceId - Used to search for a particular instance of a filter driver
        context.  If not provided, any of the contexts owned by the filter
        driver is returned.

    If neither the OwnerId nor the InstanceId is provided, any associated
    filter context will be returned.

Return Value:

    A pointer to the filter context, or NULL if no match found.

--*/

{
    PFSRTL_PER_STREAM_CONTEXT ctx;
    PFSRTL_PER_STREAM_CONTEXT rtnCtx;
    PLIST_ENTRY list;

    ASSERT(AdvFcbHeader);
    ASSERT(FlagOn(AdvFcbHeader->Flags2,FSRTL_FLAG2_SUPPORTS_FILTER_CONTEXTS));

    ExAcquireFastMutex(AdvFcbHeader->FastMutex);
    rtnCtx = NULL;

    //
    // Use different loops depending on whether we are comparing both Ids or not.
    //

    if ( ARGUMENT_PRESENT(InstanceId) ) {

        MySearchList (&AdvFcbHeader->FilterContexts, list) {

            ctx  = CONTAINING_RECORD(list, FSRTL_PER_STREAM_CONTEXT, Links);
            if (ctx->OwnerId == OwnerId && ctx->InstanceId == InstanceId) {

                rtnCtx = ctx;
                break;
            }
        }

    } else if ( ARGUMENT_PRESENT(OwnerId) ) {

        MySearchList (&AdvFcbHeader->FilterContexts, list) {

            ctx  = CONTAINING_RECORD(list, FSRTL_PER_STREAM_CONTEXT, Links);
            if (ctx->OwnerId == OwnerId) {

                rtnCtx = ctx;
                break;
            }
        }

    } else if (!IsListEmpty(&AdvFcbHeader->FilterContexts)) {

        rtnCtx = (PFSRTL_PER_STREAM_CONTEXT)AdvFcbHeader->FilterContexts.Flink;
    }

    ExReleaseFastMutex(AdvFcbHeader->FastMutex);
    return rtnCtx;
}


NTKERNELAPI
PFSRTL_PER_STREAM_CONTEXT
FsRtlRemovePerStreamContext (
  IN PFSRTL_ADVANCED_FCB_HEADER AdvFcbHeader,
  IN PVOID         OwnerId     OPTIONAL,
  IN PVOID         InstanceId  OPTIONAL
  )
/*++

Routine Description:

    This routine deletes filter driver context associated with a stream.

    FsRtlRemoveFilterContext functions identically to FsRtlLookupFilterContext,
    except that the returned context has been removed from the list.

Arguments:

    AdvFcbHeader - Advanced FCB Header for stream of interest.

    OwnerId - Used to identify context information belonging to a particular
        filter driver.

    InstanceId - Used to search for a particular instance of a filter driver
        context.  If not provided, any of the contexts owned by the filter
        driver is removed and returned.

    If neither the OwnerId nor the InstanceId is provided, any associated
    filter context will be removed and returned.

Return Value:

    A pointer to the filter context, or NULL if no match found.

--*/

{
    PFSRTL_PER_STREAM_CONTEXT ctx;
    PFSRTL_PER_STREAM_CONTEXT rtnCtx;
    PLIST_ENTRY list;

    if (!AdvFcbHeader ||
        !FlagOn(AdvFcbHeader->Flags2,FSRTL_FLAG2_SUPPORTS_FILTER_CONTEXTS))
    {

        return NULL;
    }

    ExAcquireFastMutex(AdvFcbHeader->FastMutex);
    rtnCtx = NULL;

  // Use different loops depending on whether we are comparing both Ids or not.
    if ( ARGUMENT_PRESENT(InstanceId) ) {

        MySearchList (&AdvFcbHeader->FilterContexts, list) {

            ctx  = CONTAINING_RECORD(list, FSRTL_PER_STREAM_CONTEXT, Links);
            if (ctx->OwnerId == OwnerId && ctx->InstanceId == InstanceId) {

                rtnCtx = ctx;
                break;
            }
        }

    } else if ( ARGUMENT_PRESENT(OwnerId) ) {

        MySearchList (&AdvFcbHeader->FilterContexts, list) {

            ctx  = CONTAINING_RECORD(list, FSRTL_PER_STREAM_CONTEXT, Links);
            if (ctx->OwnerId == OwnerId) {

                rtnCtx = ctx;
                break;
            }
        }

    } else if (!IsListEmpty(&AdvFcbHeader->FilterContexts)) {

        rtnCtx = (PFSRTL_PER_STREAM_CONTEXT)AdvFcbHeader->FilterContexts.Flink;
    }

    if (rtnCtx) {
        RemoveEntryList(&rtnCtx->Links);   // remove the matched entry
    }

    ExReleaseFastMutex(AdvFcbHeader->FastMutex);
    return rtnCtx;
}


NTKERNELAPI
VOID
FsRtlTeardownPerStreamContexts (
  IN PFSRTL_ADVANCED_FCB_HEADER AdvFcbHeader
  )
/*++

Routine Description:

    This routine is called by filesystems to free the filter contexts
    associated with an FSRTL_COMMON_FCB_HEADER by calling the FreeCallback
    routine for each FilterContext.

Arguments:

    FilterContexts - the address of the FilterContexts field within
        the FSRTL_COMMON_FCB_HEADER of the structure being torn down
        by the filesystem.

Return Value:

    None.

--*/

{
    PFSRTL_PER_STREAM_CONTEXT ctx;
    PLIST_ENTRY ptr;
    BOOLEAN lockHeld;

    //
    //  Acquire the lock because someone could be trying to free this
    //  entry while we are trying to free it.
    //

    ExAcquireFastMutex( AdvFcbHeader->FastMutex );
    lockHeld = TRUE;

    try {

        while (!IsListEmpty( &AdvFcbHeader->FilterContexts )) {

            //
            //  Unlink the top entry then release the lock.  We must
            //  release the lock before calling the use or their could
            //  be potential locking order deadlocks.
            //

            ptr = RemoveHeadList( &AdvFcbHeader->FilterContexts );

            ExReleaseFastMutex(AdvFcbHeader->FastMutex);
            lockHeld = FALSE;

            //
            //  Call filter to free this entry
            //

            ctx = CONTAINING_RECORD( ptr, FSRTL_PER_STREAM_CONTEXT, Links );
            ASSERT(ctx->FreeCallback);

            (*ctx->FreeCallback)( ctx );

            //
            //  re-get the lock
            //

            ExAcquireFastMutex( AdvFcbHeader->FastMutex );
            lockHeld = TRUE;
        }

    } finally {

        if (lockHeld) {

            ExReleaseFastMutex( AdvFcbHeader->FastMutex );
        }
    }
}


//===========================================================================
//                  Handles FileObject Contexts
//===========================================================================

//
//  Internal structure used to manage the Per FileObject Contexts.
//

typedef struct _PER_FILEOBJECT_CTXCTRL {

    //
    //  This is a pointer to a Fast Mutex which may be used to
    //  properly synchronize access to the FsRtl header.  The
    //  Fast Mutex must be nonpaged.
    //

    FAST_MUTEX FastMutex;

    //
    // This is a pointer to a list of context structures belonging to
    // filesystem filter drivers that are linked above the filesystem.
    // Each structure is headed by FSRTL_FILTER_CONTEXT.
    //

    LIST_ENTRY FilterContexts;

} PER_FILEOBJECT_CTXCTRL, *PPER_FILEOBJECT_CTXCTRL;


NTKERNELAPI
NTSTATUS
FsRtlInsertPerFileObjectContext (
  IN PFILE_OBJECT FileObject,
  IN PFSRTL_PER_FILEOBJECT_CONTEXT Ptr
  )
/*++

Routine Description:

    This routine associates a context with a file object.

Arguments:

    FileObject - Specifies the file object of interest.

    Ptr - Pointer to the filter-specific context structure.
        The common header fields OwnerId and InstanceId should
        be filled in by the filter driver before calling.

Return Value:

    STATUS_SUCCESS - operation succeeded.

    STATUS_INVALID_DEVICE_REQUEST - underlying filesystem does not support
        filter contexts.

--*/

{
    PPER_FILEOBJECT_CTXCTRL ctxCtrl;
    NTSTATUS status;

    //
    //  Return if no file object
    //

    if (NULL == FileObject) {

        return STATUS_INVALID_PARAMETER;
    }

    if (!FsRtlSupportsPerFileObjectContexts(FileObject)) {

        return STATUS_INVALID_DEVICE_REQUEST;
    }

    //
    //  Get the context control structure out of the file object extension
    //

    ctxCtrl = IoGetFileObjectFilterContext( FileObject );

    if (NULL == ctxCtrl) {

        //
        //  There is not a control structure, allocate and initialize one
        //

        ctxCtrl = ExAllocatePoolWithTag( NonPagedPool,
                                         sizeof(PER_FILEOBJECT_CTXCTRL),
                                         'XCOF' );
        if (NULL == ctxCtrl) {

            return STATUS_INSUFFICIENT_RESOURCES;
        }

        ExInitializeFastMutex( &ctxCtrl->FastMutex );
        InitializeListHead( &ctxCtrl->FilterContexts );

        //
        //  Insert into the file object extension
        //

        status = IoChangeFileObjectFilterContext( FileObject,
                                                  ctxCtrl,
                                                  TRUE );

        if (!NT_SUCCESS(status)) {

            //
            //  If this operation fails it is because someone else inserted the
            //  entry at the same time.  In this case free the memory we
            //  allocated and re-get the current value.
            //

            ExFreePool( ctxCtrl );

            ctxCtrl = IoGetFileObjectFilterContext( FileObject );

            if (NULL == ctxCtrl) {

                //
                //  This should never actually happen.  If it does it means
                //  someone allocated and then freed a context very quickly.
                //

                ASSERT(!"This operation should not have failed");
                return STATUS_UNSUCCESSFUL;
            }
        }
    }

    ExAcquireFastMutex( &ctxCtrl->FastMutex );

    InsertHeadList( &ctxCtrl->FilterContexts, &Ptr->Links );

    ExReleaseFastMutex( &ctxCtrl->FastMutex );

    return STATUS_SUCCESS;
}


NTKERNELAPI
PFSRTL_PER_FILEOBJECT_CONTEXT
FsRtlLookupPerFileObjectContext (
  IN PFILE_OBJECT FileObject,
  IN PVOID OwnerId OPTIONAL,
  IN PVOID InstanceId OPTIONAL
  )
/*++

Routine Description:

    This routine lookups contexts associated with a file object.

Arguments:

    FileObject - Specifies the file object of interest.

    OwnerId - Used to identify context information belonging to a particular
        filter driver.

    InstanceId - Used to search for a particular instance of a filter driver
        context.  If not provided, any of the contexts owned by the filter
        driver is returned.

    If neither the OwnerId nor the InstanceId is provided, any associated
        filter context will be returned.

Return Value:

    A pointer to the filter context, or NULL if no match found.

--*/

{
    PPER_FILEOBJECT_CTXCTRL ctxCtrl;
    PFSRTL_PER_FILEOBJECT_CONTEXT ctx;
    PFSRTL_PER_FILEOBJECT_CONTEXT rtnCtx;
    PLIST_ENTRY list;

    //
    //  Return if no FileObjecty
    //

    if (NULL == FileObject) {

        return NULL;
    }

    //
    //  Get the context control structure out of the file object extension
    //

    ctxCtrl = IoGetFileObjectFilterContext( FileObject );

    if (NULL == ctxCtrl) {

        return NULL;
    }

    rtnCtx = NULL;
    ExAcquireFastMutex( &ctxCtrl->FastMutex );

    //
    //  Use different loops depending on whether we are comparing both Ids or not.
    //

    if ( ARGUMENT_PRESENT(InstanceId) ) {

        MySearchList (&ctxCtrl->FilterContexts, list) {

            ctx  = CONTAINING_RECORD(list, FSRTL_PER_FILEOBJECT_CONTEXT, Links);

            if ((ctx->OwnerId == OwnerId) && (ctx->InstanceId == InstanceId)) {

                rtnCtx = ctx;
                break;
            }
        }

    } else if ( ARGUMENT_PRESENT(OwnerId) ) {

        MySearchList (&ctxCtrl->FilterContexts, list) {

            ctx  = CONTAINING_RECORD(list, FSRTL_PER_FILEOBJECT_CONTEXT, Links);

            if (ctx->OwnerId == OwnerId) {

                rtnCtx = ctx;
                break;
            }
        }

    } else if (!IsListEmpty(&ctxCtrl->FilterContexts)) {

        rtnCtx = (PFSRTL_PER_FILEOBJECT_CONTEXT) ctxCtrl->FilterContexts.Flink;
    }

    ExReleaseFastMutex(&ctxCtrl->FastMutex);

    return rtnCtx;
}


NTKERNELAPI
PFSRTL_PER_FILEOBJECT_CONTEXT
FsRtlRemovePerFileObjectContext (
  IN PFILE_OBJECT FileObject,
  IN PVOID OwnerId OPTIONAL,
  IN PVOID InstanceId OPTIONAL
  )
/*++

Routine Description:

    This routine deletes contexts associated with a file object

    Filter drivers must explicitly remove all context they associate with
    a file object (otherwise the underlying filesystem will BugCheck at close).
    This should be done at IRP_CLOSE time.

    FsRtlRemoveFilterContext functions identically to FsRtlLookupFilterContext,
    except that the returned context has been removed from the list.

Arguments:

    FileObject - Specifies the file object of interest.

    OwnerId - Used to identify context information belonging to a particular
        filter driver.

    InstanceId - Used to search for a particular instance of a filter driver
        context.  If not provided, any of the contexts owned by the filter
        driver is removed and returned.

    If neither the OwnerId nor the InstanceId is provided, any associated
        filter context will be removed and returned.

Return Value:

    A pointer to the filter context, or NULL if no match found.

--*/

{
    PPER_FILEOBJECT_CTXCTRL ctxCtrl;
    PFSRTL_PER_FILEOBJECT_CONTEXT ctx;
    PFSRTL_PER_FILEOBJECT_CONTEXT rtnCtx;
    PLIST_ENTRY list;

    //
    //  Return if no file object
    //

    if (NULL == FileObject) {

        return NULL;
    }

    //
    //  Get the context control structure out of the file object extension
    //

    ctxCtrl = IoGetFileObjectFilterContext( FileObject );

    if (NULL == ctxCtrl) {

        return NULL;
    }

    rtnCtx = NULL;

    ExAcquireFastMutex( &ctxCtrl->FastMutex );

  // Use different loops depending on whether we are comparing both Ids or not.
    if ( ARGUMENT_PRESENT(InstanceId) ) {

        MySearchList (&ctxCtrl->FilterContexts, list) {

            ctx  = CONTAINING_RECORD(list, FSRTL_PER_FILEOBJECT_CONTEXT, Links);

            if ((ctx->OwnerId == OwnerId) && (ctx->InstanceId == InstanceId)) {

                rtnCtx = ctx;
                break;
            }
        }

    } else if ( ARGUMENT_PRESENT(OwnerId) ) {

        MySearchList (&ctxCtrl->FilterContexts, list) {

            ctx  = CONTAINING_RECORD(list, FSRTL_PER_FILEOBJECT_CONTEXT, Links);

            if (ctx->OwnerId == OwnerId) {

                rtnCtx = ctx;
                break;
            }
        }

    } else if (!IsListEmpty(&ctxCtrl->FilterContexts)) {

        rtnCtx = (PFSRTL_PER_FILEOBJECT_CONTEXT)ctxCtrl->FilterContexts.Flink;
    }

    if (rtnCtx) {

        RemoveEntryList(&rtnCtx->Links);   // remove the matched entry
    }

    ExReleaseFastMutex( &ctxCtrl->FastMutex );
    return rtnCtx;
}


VOID
FsRtlPTeardownPerFileObjectContexts (
  IN PFILE_OBJECT FileObject
  )
/*++

Routine Description:

    This routine is called by the IOManager when a fileObject is being 
    deleted.  This gives us a chance to delete our file object control
    structure.

Arguments:

    FileObject - The fileObject being deleted

Return Value:

    None.

--*/

{
    PPER_FILEOBJECT_CTXCTRL ctxCtrl;
    NTSTATUS status;

    ASSERT(FileObject != NULL);

    ctxCtrl = IoGetFileObjectFilterContext( FileObject );

    if (NULL != ctxCtrl) {

        status = IoChangeFileObjectFilterContext( FileObject,
                                                  ctxCtrl,
                                                  FALSE );

        ASSERT(STATUS_SUCCESS == status);
        ASSERT(IsListEmpty( &ctxCtrl->FilterContexts));

        ExFreePool( ctxCtrl );
    }
}


LOGICAL
FsRtlIsPagingFile (
    IN PFILE_OBJECT FileObject
    )
/*++

Routine Description:

    This routine will return TRUE if the give file object is for a
    paging file.  It returns FALSE otherwise

Arguments:

    FileObject - The file object to test

Return Value:

    TRUE - if paging file
    FALSE - if not

--*/

{
    return MmIsFileObjectAPagingFile( FileObject );
}