windows-xp/Source/XPSP1/NT/base/fs/rdr2/inc/mrxfcb.h

/*++

Copyright (c) 1994  Microsoft Corporation

Module Name:

    mrxfFcb.h

Abstract:

    This module defines the macros/inline functions and function prototypes used by
    the mini redirectors to access the RDBSS wrapper data structures.

    IMPORTANT: All mini redirector writers cannot and should not make any assumptions
    about the layout of the RDBSS wrapper data structures. They are not guaranteed to
    be the same across platforms and even on a single platform are liable to change
    across versions.

    The following six data structure abstractions are available to the mini
    redirector writer.

       1) Server Call Context (SRV_CALL)
            The context associated with each known file system server.

       2) Net Roots (NET_ROOT)
            The root of a file system volume( local/remote) opened by the user.

       3) Virtual Net Roots (V_NET_ROOT)
            The view of a file system volume on a server. The view can be
            constrained along multiple dimensions. As an example the view can be
            associated with a logon id. which will constrain the operations that
            can be performed on the file system volume.

       4) File Control Blocks (FCB)
            The RDBSS data structure associated with each unique file opened.

       5) File Object Extensions (FOXB)

       6) ServerSide Open Context (SRV_OPEN)

    A common convention that is adopted for defining Flags in all of these data structures
    is to define a ULONG ( 32 ) flags and split them into two groups -- those that are visible
    to the mini redirector and those that are invisible. These flags are not meant for use
    by the mini redirector writers and are reserved for the wrapper.

Author:

    Balan Sethu Raman    [SethuR]   23-Oct-1995

Revision History:

--*/

#ifndef __MRXFCB_H__
#define __MRXFCB_H__

// The SRVCALL flags are split into two groups, i.e., visible to mini rdrs and invisible to mini rdrs.
// The visible ones are defined above and the definitions for the invisible ones can be found
// in fcb.h. The convention that has been adopted is that the lower 16 flags will be visible
// to the mini rdr and the upper 16 flags will be reserved for the wrapper. This needs to be
// enforced in defining new flags.

#define SRVCALL_FLAG_MAILSLOT_SERVER              (0x1)
#define SRVCALL_FLAG_FILE_SERVER                  (0x2)
#define SRVCALL_FLAG_CASE_INSENSITIVE_NETROOTS    (0x4)
#define SRVCALL_FLAG_CASE_INSENSITIVE_FILENAMES   (0x8)
#define SRVCALL_FLAG_DFS_AWARE_SERVER             (0x10)
#define SRVCALL_FLAG_FORCE_FINALIZED              (0x20)

typedef struct _MRX_NORMAL_NODE_HEADER {
   NODE_TYPE_CODE           NodeTypeCode;
   NODE_BYTE_SIZE           NodeByteSize;
   ULONG                    NodeReferenceCount;
} MRX_NORMAL_NODE_HEADER;

#ifdef __cplusplus
typedef struct _MRX_SRV_CALL_ : public MRX_NORMAL_NODE_HEADER {
#else // !__cplusplus
typedef struct _MRX_SRV_CALL_ {
    MRX_NORMAL_NODE_HEADER;
#endif // __cplusplus

   // !!!! changes above this require realignment with fcb.h

   // the context fields for extensions required by the mini redirectors

   PVOID                    Context;
   PVOID                    Context2;

   // Associated DeviceObject which also contains the dispatch vector

   PRDBSS_DEVICE_OBJECT     RxDeviceObject;

   // the srv call name, the server principal name and the server domain name.

   PUNICODE_STRING          pSrvCallName;
   PUNICODE_STRING          pPrincipalName;
   PUNICODE_STRING          pDomainName;

   // Flags used to denote the state of the SRV_CALL.

   ULONG                    Flags;

   // Server parameters updated by the mini redirectors.
   LONG                     MaximumNumberOfCloseDelayedFiles;

   // Status return from the transport in case of failure
   NTSTATUS                 Status;

} MRX_SRV_CALL, *PMRX_SRV_CALL;

// The various types of NET_ROOT's currently supported by the wrapper.
#define   NET_ROOT_DISK      ((UCHAR)0)
#define   NET_ROOT_PIPE      ((UCHAR)1)
#define   NET_ROOT_COMM      ((UCHAR)2)
#define   NET_ROOT_PRINT     ((UCHAR)3)
#define   NET_ROOT_WILD      ((UCHAR)4)
#define   NET_ROOT_MAILSLOT  ((UCHAR)5)
typedef UCHAR NET_ROOT_TYPE, *PNET_ROOT_TYPE;

// The pipe buffer size for transferring cannot be larger than 0xffff
#define   MAX_PIPE_BUFFER_SIZE    0xFFFF

// The possible states associated with a NET_ROOT. These have been defined to be
// line with the definitions foe the LanManager service to avoid redundant mappings.
// These MUST agree with sdkinc\lmuse.h use_ok, etc.....

#define   MRX_NET_ROOT_STATE_GOOD         ((UCHAR)0)
#define   MRX_NET_ROOT_STATE_PAUSED       ((UCHAR)1)
#define   MRX_NET_ROOT_STATE_DISCONNECTED ((UCHAR)2)
#define   MRX_NET_ROOT_STATE_ERROR        ((UCHAR)3)
#define   MRX_NET_ROOT_STATE_CONNECTED    ((UCHAR)4)
#define   MRX_NET_ROOT_STATE_RECONN       ((UCHAR)5)
typedef UCHAR MRX_NET_ROOT_STATE, *PMRX_NET_ROOT_STATE;

// The file systems on the remote servers provide varying levels of functionality to
// detect aliasing between file names. As an example consider two shares on the same
// file system volume. In the absence of any support from the file system on the server
// the correct and conservative approach is to flush all the files to the server as
// opposed to all the files on the same NET_ROOT to preserve coherency and handle
// delayed close operations.

#define   MRX_PURGE_SAME_NETROOT         ((UCHAR)0)
#define   MRX_PURGE_SAME_SRVCALL         ((UCHAR)1)
//these are not implemented yet....
//#define   MRX_PURGE_SAME_FCB           ((UCHAR)2)
//#define   MRX_PURGE_SAME_VOLUME        ((UCHAR)3)
//#define   MRX_PURGE_ALL                ((UCHAR)4)
typedef UCHAR MRX_PURGE_RELATIONSHIP, *PMRX_PURGE_RELATIONSHIP;

#define   MRX_PURGE_SYNC_AT_NETROOT         ((UCHAR)0)
#define   MRX_PURGE_SYNC_AT_SRVCALL         ((UCHAR)1)
typedef UCHAR MRX_PURGE_SYNCLOCATION, *PMRX_PURGE_SYNCLOCATION;

// The NET_ROOT flags are split into two groups, i.e., visible to mini rdrs and
// invisible to mini rdrs. The visible ones are defined above and the definitions
// for the invisible ones can be found in fcb.h. The convention that has been
// adopted is that the lower 16 flags will be visible to the mini rdr and the
// upper 16 flags will be reserved for the wrapper. This needs to be enforced
// in defining new flags.

#define NETROOT_FLAG_SUPPORTS_SYMBOLIC_LINKS  ( 0x0001 )
#define NETROOT_FLAG_DFS_AWARE_NETROOT        ( 0x0002 )
#define NETROOT_FLAG_DEFER_READAHEAD          ( 0x0004 )
#define NETROOT_FLAG_VOLUMEID_INITIALIZED     ( 0x0008 )
#define NETROOT_FLAG_FINALIZE_INVOKED         ( 0x0010 )
#define NETROOT_FLAG_UNIQUE_FILE_NAME         ( 0x0020 )

//
// Read ahead amount used for normal data files (32k)

#define DEFAULT_READ_AHEAD_GRANULARITY           (0x08000)

//
// the wrapper implements throttling for certain kinds of operations:
//      PeekNamedPipe/ReadNamedPipe
//      LockFile
//
// a minirdr can set the timing parameters for this in the netroot. leaving them
// as zero will disable throttling.

typedef struct _NETROOT_THROTTLING_PARAMETERS {
    ULONG Increment;     // Supplies the increase in delay in milliseconds, each time a request
                         // to the network fails.
    ULONG MaximumDelay;  // Supplies the longest delay the backoff package can introduce
                         // in milliseconds.
} NETROOT_THROTTLING_PARAMETERS, *PNETROOT_THROTTLING_PARAMETERS;

#define RxInitializeNetRootThrottlingParameters(__tp,__incr,__maxdelay) { \
       PNETROOT_THROTTLING_PARAMETERS tp = (__tp);                         \
       tp->Increment = (__incr);                                   \
       tp->MaximumDelay = (__maxdelay);                            \
}

#ifdef __cplusplus
typedef struct _MRX_NET_ROOT_ : public MRX_NORMAL_NODE_HEADER {
#else // !__cplusplus
typedef struct _MRX_NET_ROOT_ {
    MRX_NORMAL_NODE_HEADER;
#endif // __cplusplus

   // the MRX_SRV_CALL instance with which this MRX_NET_ROOT instance is associated

   PMRX_SRV_CALL      pSrvCall;

   // !!!! changes above this require realignment with fcb.h

   // the context fields used by the mini redirectors for recording
   // additional state.

   PVOID              Context;
   PVOID              Context2;

   // The flags used to denote the state of the NET_ROOT instance.

   ULONG              Flags;

   // We count the number of fcbs, srvopens on the netroot

   ULONG NumberOfFcbs;
   ULONG NumberOfSrvOpens;

   // The current state and the purge relationships based on the support
   // provided by the file system on the server.

   MRX_NET_ROOT_STATE     MRxNetRootState;
   NET_ROOT_TYPE          Type;
   MRX_PURGE_RELATIONSHIP PurgeRelationship;
   MRX_PURGE_SYNCLOCATION PurgeSyncLocation;

   // the type of device, i.e., file system volume, printer, com port etc.

   DEVICE_TYPE            DeviceType;

   // Name of the NET_ROOT instance

   PUNICODE_STRING        pNetRootName;

   // the name to be prepended to all FCBS associated with this NET_ROOT

   UNICODE_STRING     InnerNamePrefix;

   // Parameters based upon the type of the NET_ROOT.

   ULONG  ParameterValidationStamp;
   union {
      struct {
         ULONG  DataCollectionSize;
         NETROOT_THROTTLING_PARAMETERS PipeReadThrottlingParameters;
      } NamedPipeParameters;

      struct {
         ULONG  ClusterSize;
         ULONG  ReadAheadGranularity;
         NETROOT_THROTTLING_PARAMETERS LockThrottlingParameters;
         ULONG  RenameInfoOverallocationSize; //could be a USHORT
         GUID   VolumeId;
      } DiskParameters;
   };
} MRX_NET_ROOT, *PMRX_NET_ROOT;


// The VNET_ROOT flags are split into two groups, i.e., visible to mini rdrs and
// invisible to mini rdrs. The visible ones are defined below and the definitions
// for the invisible ones can be found in fcb.h. The convention that has been
// adopted is that the lower 16 flags will be visible to the mini rdr and the
// upper 16 flags will be reserved for the wrapper. This needs to be enforced
// in defining new flags.

#define VNETROOT_FLAG_CSCAGENT_INSTANCE   0x00000001
#define VNETROOT_FLAG_FINALIZE_INVOKED    0x00000002
#define VNETROOT_FLAG_FORCED_FINALIZE     0x00000004
#define VNETROOT_FLAG_NOT_FINALIZED    0x00000008

#ifdef __cplusplus
typedef struct _MRX_V_NET_ROOT_ : public MRX_NORMAL_NODE_HEADER {
#else // !__cplusplus
typedef struct _MRX_V_NET_ROOT_ {
    MRX_NORMAL_NODE_HEADER;
#endif // __cplusplus

   // the MRX_NET_ROOT instance with which the MRX_V_NET_ROOT instance is associated

   PMRX_NET_ROOT      pNetRoot;

   // !!!! changes above this require realignment with fcb.h

   // the context fields provided for storing additional information as deemed
   // necessary by the mini redirectors

   PVOID              Context;
   PVOID              Context2;

   ULONG              Flags;

   // This field should not be updated by the mini redirectors. Its usage is intended
   // to provide an easy mechanism for accessing certain state information

   ULONG              NumberOfOpens;

   // We count the number of Fobxss on the virtual netroot

   ULONG              NumberOfFobxs;

   // the security parameters associated with the V_NET_ROOT instance.

   LUID               LogonId;

   // These are the parameters supplied by the used in a NtCreateFile call in
   // which the FILE_CREATE_TREE_CONNECTION flag is specified as part of the
   // CreateOptions.

   PUNICODE_STRING    pUserDomainName;
   PUNICODE_STRING    pUserName;
   PUNICODE_STRING    pPassword;
   ULONG              SessionId;
   NTSTATUS           ConstructionStatus;
   BOOLEAN            IsExplicitConnection;
} MRX_V_NET_ROOT, *PMRX_V_NET_ROOT;


//  the following flags describe the fcb state. the fcbstate is readonly
//  for minirdrs. the buffering/cacheing flags are set in the wrapper in
//  response to changebufferingstate calls


#define FCB_STATE_WRITECACHEING_ENABLED          ( 0x08000000 )
#define FCB_STATE_WRITEBUFFERING_ENABLED         ( 0x04000000 )
#define FCB_STATE_READCACHEING_ENABLED           ( 0x02000000 )
#define FCB_STATE_READBUFFERING_ENABLED          ( 0x01000000 )
#define FCB_STATE_OPENSHARING_ENABLED            ( 0x00800000 )
#define FCB_STATE_COLLAPSING_ENABLED             ( 0x00400000 )
#define FCB_STATE_LOCK_BUFFERING_ENABLED         ( 0x00200000 )
#define FCB_STATE_FILESIZECACHEING_ENABLED       ( 0x00100000 )
#define FCB_STATE_FILETIMECACHEING_ENABLED       ( 0x00080000 )

#define FCB_STATE_TIME_AND_SIZE_ALREADY_SET      ( 0x00040000 )

#define FCB_STATE_ORPHANED                       ( 0x00000080 )

#define FCB_STATE_DELETE_ON_CLOSE                ( 0x00000001 )

//
// ALL FIELDS IN AN FCB ARE READONLY EXCEPT Context and Context2....
// Also, Context is read only the the mini has specified RDBSS_MANAGE_FCB_EXTENSION
typedef struct _MRX_FCB_ {
   FSRTL_ADVANCED_FCB_HEADER Header;

   // The MRX_NET_ROOT instance with which this is associated

   PMRX_NET_ROOT    pNetRoot;

   // !!!! changes above this require realignment with fcb.h

   // the context fields to store additional information as deemed necessary by the
   // mini redirectors.

   PVOID            Context;
   PVOID            Context2;

   // The reference count: in a different place because we must prefix with
   // the FSRTL_COMMON_FCB_HEADER structure.

   ULONG            NodeReferenceCount;

    //
    //  The internal state of the Fcb.  THIS FIELD IS READONLY FOR MINIRDRS
    //

    ULONG           FcbState;

    //  A count of the number of file objects that have been opened for
    //  this file/directory, but not yet been cleaned up yet.  This count
    //  is only used for data file objects, not for the Acl or Ea stream
    //  file objects.  This count gets decremented in RxCommonCleanup,
    //  while the OpenCount below gets decremented in RxCommonClose.

    CLONG           UncleanCount;

    //  A count of the number of file objects that have been opened for
    //  this file/directory, but not yet been cleaned up yet and for which
    //  cacheing is not supported. This is used in cleanup.c to tell if extra
    //  purges are required to maintain coherence.

    CLONG           UncachedUncleanCount;

    //  A count of the number of file objects that have opened
    //  this file/directory.  For files & directories the FsContext of the
    //  file object points to this record.

    CLONG           OpenCount;


   // The outstanding locks count: if this count is nonzero, the we silently
   // ignore adding LOCK_BUFFERING in a ChangeBufferingState request. This field
   // is manipulated by interlocked operations so you only have to have the fcb
   // shared to manipulate it but you have to have it exclusive to use it.

   ULONG            OutstandingLockOperationsCount;

   // The actual allocation length as opposed to the valid data length

   ULONGLONG        ActualAllocationLength;

   // Attributes of the MRX_FCB,

   ULONG            Attributes;

   // Intended for future use, currently used to round off allocation to
   // DWORD boundaries.

   BOOLEAN          Spare1;
   BOOLEAN          fShouldBeOrphaned;
   BOOLEAN          fMiniInited;

   // Type of the associated MRX_NET_ROOT, intended to avoid pointer chasing.

   UCHAR            CachedNetRootType;

    //  Header for the list of srv_opens for this FCB....
    //  THIS FIELD IS READONLY FOR MINIS

    LIST_ENTRY              SrvOpenList;

    //  changes whenever the list changes..prevents extra lookups
    //  THIS FIELD IS READONLY FOR MINIS

    ULONG                   SrvOpenListVersion;

} MRX_FCB, *PMRX_FCB;


// The following flags define the various types of buffering that can be selectively
// enabled or disabled for each SRV_OPEN.
//

#define SRVOPEN_FLAG_DONTUSE_READ_CACHEING                  (0x1)
#define SRVOPEN_FLAG_DONTUSE_WRITE_CACHEING                 (0x2)
#define SRVOPEN_FLAG_CLOSED                                 (0x4)
#define SRVOPEN_FLAG_CLOSE_DELAYED                          (0x8)
#define SRVOPEN_FLAG_FILE_RENAMED                           (0x10)
#define SRVOPEN_FLAG_FILE_DELETED                           (0x20)
#define SRVOPEN_FLAG_BUFFERING_STATE_CHANGE_PENDING         (0x40)
#define SRVOPEN_FLAG_COLLAPSING_DISABLED                    (0x80)
#define SRVOPEN_FLAG_BUFFERING_STATE_CHANGE_REQUESTS_PURGED (0x100)
#define SRVOPEN_FLAG_NO_BUFFERING_STATE_CHANGE              (0x200)
#define SRVOPEN_FLAG_ORPHANED                               (0x400)

#ifdef __cplusplus
typedef struct _MRX_SRV_OPEN_ : public MRX_NORMAL_NODE_HEADER {
#else // !__cplusplus
typedef struct _MRX_SRV_OPEN_ {
    MRX_NORMAL_NODE_HEADER;
#endif // __cplusplus

    // the MRX_FCB instance with which the SRV_OPEN is associated.

    PMRX_FCB pFcb;

    // the V_NET_ROOT instance with which the SRV_OPEN is associated

    PMRX_V_NET_ROOT pVNetRoot;

    // !!!! changes above this require realignment with fcb.h

    // the context fields to store additional state information as deemed necessary
    // by the mini redirectors

    PVOID        Context;
    PVOID        Context2;

    // The flags are split into two groups, i.e., visible to mini rdrs and invisible
    // to mini rdrs. The visible ones are defined above and the definitions for the
    // invisible ones can be found in fcb.h. The convention that has been adopted is
    // that the lower 16 flags will be visible to the mini rdr and the upper 16 flags
    // will be reserved for the wrapper. This needs to be enforced in defining new flags.

    ULONG        Flags;

    // the name alongwith the MRX_NET_ROOT prefix, i.e. fully qualified name

    PUNICODE_STRING pAlreadyPrefixedName;


    // the number of Fobx's associated with this open for which a cleanup IRP
    // has not been processed.

    CLONG        UncleanFobxCount;

    // the number of local opens associated with this open on the server

    CLONG        OpenCount;

    // the Key assigned by the mini redirector for this SRV_OPEN. Since the various mini
    // redirectors do not always get to pick the unique id for a open instance, the key
    // used to identify the open to the server is different for different mini redirectors
    // based upon the convention adopted at the server.

    PVOID        Key;

    // the access and sharing rights specified for this SRV_OPEN. This is used in
    // determining is subsequent open requests can be collapsed  with an existing
    // SRV_OPEN instance.

    ACCESS_MASK  DesiredAccess;
    ULONG        ShareAccess;
    ULONG        CreateOptions;

    // The BufferingFlags field is temporal.....it does not really belong to the
    // srvopen; rather the srvopen is used as a representative of the fcb. On
    // each open, the bufferingflags field of the srvopen is taken as the minirdr's
    // contribution to the buffering state. On an oplock break, a srvopen is passed
    // (the one that's being broken) whose bufferflags field is taken as the new
    // proxy. On a close that changes the minirdr's contribution, the minirdr should
    // take steps to cause a ChangeBufferingState to the new state.
    //
    // just to reiterate, the field is just used to carry the information from
    // the minirdr to RxChangeBufferingState and does not hold longterm coherent
    // information.

    ULONG        BufferingFlags;

    // List Entry to wire the SRV_OPEN to the list of SRV_OPENS maintained as
    // part of theFCB
    //  THIS FIELD IS READONLY FOR MINIS

    ULONG       ulFileSizeVersion;

    LIST_ENTRY    SrvOpenQLinks;

} MRX_SRV_OPEN, *PMRX_SRV_OPEN;

#define FOBX_FLAG_DFS_OPEN        (0x0001)
#define FOBX_FLAG_BAD_HANDLE      (0x0002)
#define FOBX_FLAG_BACKUP_INTENT   (0x0004)
#define FOBX_FLAG_NOT_USED        (0x0008)

#define FOBX_FLAG_FLUSH_EVEN_CACHED_READS   (0x0010)
#define FOBX_FLAG_DONT_ALLOW_PAGING_IO      (0x0020)
#define FOBX_FLAG_DONT_ALLOW_FASTIO_READ    (0x0040)

typedef struct _MRX_PIPE_HANDLE_INFORMATION {

    ULONG         TypeOfPipe;
    ULONG         ReadMode;
    ULONG         CompletionMode;

} MRX_PIPE_HANDLE_INFORMATION, *PMRX_PIPE_HANDLE_INFORMATION;

#ifdef __cplusplus
typedef struct _MRX_FOBX_ : public MRX_NORMAL_NODE_HEADER {
#else // !__cplusplus
typedef struct _MRX_FOBX_ {
    MRX_NORMAL_NODE_HEADER;
#endif // __cplusplus

    // the MRX_SRV_OPEN instance with which the FOBX is associated

    PMRX_SRV_OPEN    pSrvOpen;

    // the FILE_OBJECT with which this FOBX is associated
    // In certain instances the I/O subsystem creates a FILE_OBJECT instance
    // on the stack in the interests of efficiency. In such cases this field
    // is NULL.

    PFILE_OBJECT     AssociatedFileObject;

    // !!!! changes above this require realignment with fcb.h

    // The fields provided to accomodate additional state to be associated
    // by the various mini redirectors

    PVOID            Context;
    PVOID            Context2;

    // The FOBX flags are split into two groups, i.e., visible to mini rdrs and invisible to mini rdrs.
    // The visible ones are defined above and the definitions for the invisible ones can be found
    // in fcb.h. The convention that has been adopted is that the lower 16 flags will be visible
    // to the mini rdr and the upper 16 flags will be reserved for the wrapper. This needs to be
    // enforced in defining new flags.

    ULONG            Flags;

    union {
        struct {
            //
            //  The query template is used to filter directory query requests.
            //  It originally is set to null and on the first call the NtQueryDirectory
            //  it is set to the input filename or "*" if the name is not supplied.
            //  All subsquent queries then use this template.

            UNICODE_STRING UnicodeQueryTemplate;
        }; //for directories

        PMRX_PIPE_HANDLE_INFORMATION PipeHandleInformation;   //for pipes
    };

    //
    //  The following field is used as an offset into the Eas for a
    //  particular file.  This will be the offset for the next
    //  Ea to return.  A value of 0xffffffff indicates that the
    //  Ea's are exhausted.
    //

    // This field is manipulated directly by the smbmini....maybe it should move down
    // one thing is that it is a reminder that NT allows a resume on getting EAs

    ULONG OffsetOfNextEaToReturn;
} MRX_FOBX, *PMRX_FOBX;

// Resource accquisition routines.
//
// The synchronization resources of interest to mini redirector writers are
// primarily associated with the FCB. There is a paging I/O resource and a
// regular resource. The paging I/O resource is managed by the wrapper. The only
// resource accesible to mini redirector writers is the regular resource which
// should be accessed using the supplied routines.

extern NTSTATUS
RxAcquireExclusiveFcbResourceInMRx(
    PMRX_FCB pFcb);

extern NTSTATUS
RxAcquireSharedFcbResourceInMRx(
    PMRX_FCB pFcb);

extern VOID
RxReleaseFcbResourceInMRx(
    PMRX_FCB pFcb);


#endif // __MRXFCB_H__