NT4/private/ntos/npfs/npstruc.h

/*++

Copyright (c) 1989  Microsoft Corporation

Module Name:

    NpStruc.h

Abstract:

    This module defines the data structures that make up the major internal
    part of the Named Pipe file system.

Author:

    Gary Kimura     [GaryKi]    20-Aug-1990

Revision History:

--*/

#ifndef _NPSTRUC_
#define _NPSTRUC_


//
//  The VCB record is the top record in the Named Pipe file system in-memory
//  data structure.  This structure must be allocated from non-paged pool
//  and immediately follows (in memory) the Device object for the named
//  pipe.  Structurally the layout of the data structure is as follows
//
//    +------------+
//    |NPDO        |
//    |            |
//    +------------+
//    |Vcb         |
//    |            |
//    | EventTable |
//    | WaitQueue  |
//    |            |
//    +------------+
//        | ^
//        | |
//        | |
//        v |
//      +-------------+
//      |RootDcb      |
//      |             |<-+
//      +-------------+  |
//       |               |
//       v               |
//      +-------------+  |
//      |NonPaged     |  |
//      |             |  |
//      +-------------+  |
//          :            |
//          :            |
//          :            |
//          v            |
//        +----------------+    +-------------------+        +---------+
//        |Fcb             |    |Ccb                |        |ServerFO |
//        |                |<---|                   |        |         |
//        | MaxInstances   |    | ServerFO          |<-------|-       1|
//        | CurrentInst    |    | ClientFO          |        |         |
//        | DefaultTimeOut |...>|                   |<-+  +--|-        |
//        |                |    |                   |  |  |  |         |
//        +----------------+    +-------------------+  |  |  +---------+
//         |                     |                     |  |
//         v                     v                     |  |
//        +----------------+    +-------------------+  |  |  +---------+
//        |NonPagedFcb     |    |NonPagedCcb        |<-|--+  |ClientFO |
//        |                |<---|                   |  |     |         |
//        | PipeConfig     |    | PipeState         |  +-----|-       0|
//        | PipeType       |    | ReadMode[2]       |        |         |
//        |                |    | CompletionMode[2] |<-------|-        |
//        |                |    | CreatorProcess    |        |         |
//        |                |    | EventTabEnt[2]    |        +---------+
//        |                |    | DataQueue[2]      |
//        |                |    |                   |     (low bit determines
//        +----------------+    +-------------------+      server/client)
//
//
//  Where there is only one Vcb for the entire Named Pipe file system, and
//  it contains a single pointer to the root dcb for the file system.  Off
//  of the Dcb is a queue of Fcb's.  There is one Fcb for every named pipe.
//  There is one Ccb for every instance of a named pipe.  There are also
//  two additional ccb types for the vcb and the root dcb, and notify records
//  for the notify change operations.
//
//  A newly initialized named pipe file system only contains the Vcb and
//  the root dcb.  A new Fcb is created when a new named pipe is created
//  and then a ccb must also be created.  The file object for the creater
//  (i.e., server end) points to the ccb and indicates that it is the server
//  end.  When a user does an open on the named pipe its file object is
//  set to point to the same ccb and is also set to indicate that it is the
//  client end.  This is denoted by using the last bit of the FsContext pointer
//  if the bit is 1 it is a server end file object, if the bit is 0 it is
//  the client end.
//
//  A file object with a null pointer to the FsContext field is a closed or
//  disconnected pipe.
//
//  The Ccb also contains back pointer to the file objects that have it opened
//


//
//  The following types are used to help during development by keeping the
//  data types distinct.  The manifest contants that go in each is declared
//  in the ntioapi.h file
//

typedef ULONG NAMED_PIPE_TYPE;
typedef NAMED_PIPE_TYPE *PNAMED_PIPE_TYPE;

typedef ULONG READ_MODE;
typedef READ_MODE *PREAD_MODE;

typedef ULONG COMPLETION_MODE;
typedef COMPLETION_MODE *PCOMPLETION_MODE;

typedef ULONG NAMED_PIPE_CONFIGURATION;
typedef NAMED_PIPE_CONFIGURATION *PNAMED_PIPE_CONFIGURATION;

typedef ULONG NAMED_PIPE_STATE;
typedef NAMED_PIPE_STATE *PNAMED_PIPE_STATE;

typedef ULONG NAMED_PIPE_END;
typedef NAMED_PIPE_END *PNAMED_PIPE_END;


//
//  The following two types are used by the event table package.  The first
//  is the event table itself which is just a generic table.  It is protected
//  by the vcb resource, and the second structure is an event table entry.
//

typedef struct _EVENT_TABLE {

    RTL_GENERIC_TABLE Table;

} EVENT_TABLE;
typedef EVENT_TABLE *PEVENT_TABLE;

//
//  The event table is a generic table of event table entries.  Each Ccb
//  optionally contains a pointer to an event table entry for each direction.
//  The entries are part of the global event table defined off of the Vcb
//

typedef struct _EVENT_TABLE_ENTRY {

    //
    //  The first two fields are used as keys in the generic table's
    //  comparison routines.  The pipe end will either be FILE_PIPE_CLIENT_END
    //  or FILE_PIPE_SERVER_END.
    //

    struct _CCB *Ccb;
    NAMED_PIPE_END NamedPipeEnd;

    //
    //  The following three fields are used to identify the event entry
    //  to the named pipe user
    //

    HANDLE EventHandle;
    PVOID Event;
    ULONG KeyValue;
    PEPROCESS Process;

} EVENT_TABLE_ENTRY;
typedef EVENT_TABLE_ENTRY *PEVENT_TABLE_ENTRY;


//
//  Each Ccb has two data queues for holding the outstanding in-bound and
//  out-bound read/write requests.  The following type is used to determine
//  if the data queue contains read requests, write requests, or is empty.
//

typedef enum _QUEUE_STATE {

    ReadEntries,
    WriteEntries,
    Empty

} QUEUE_STATE;

//
//  The data queue is a structure that contains the queue state, quota
//  information, and the list head.  The quota information is used to
//  maintain pipe quota.
//

typedef struct _DATA_QUEUE {

    //
    //  The current state of what is contained in this data queue,
    //  how many bytes of read/write data there are, and how many individual
    //  requests there are in the queue that contain data (includes
    //  close or flush requests).
    //

    QUEUE_STATE QueueState;
    ULONG BytesInQueue;
    ULONG EntriesInQueue;

    //
    //  The following two fields denote who much quota was reserved for
    //  this pipe direction and how much we've used up.  This is only
    //  the creator quota and not the user quota.
    //

    ULONG Quota;
    ULONG QuotaUsed;

    //
    //  This is the head of a queue of data entries (singly linked)
    //

    struct _DATA_ENTRY *FrontOfQueue;
    struct _DATA_ENTRY *EndOfQueue;

    //
    //  The following field indicates how far we've already processed
    //  into the first entry in the data queue
    //

    ULONG NextByteOffset;

} DATA_QUEUE;
typedef DATA_QUEUE *PDATA_QUEUE;

//
//  Each data entry has a type field that tells us if the operation
//  for the entry is buffered, unbuffered, flush, or a close entry.
//

typedef enum _DATA_ENTRY_TYPE {

    Buffered,
    Unbuffered,
    Flush,
    Close

} DATA_ENTRY_TYPE;

//
//  The following type is used to denote where we got the memory for the
//  data entry and possibly the data buffer.  We either got the memory
//  from the pipe quota, the user quota, or it is part of the next IRP stack
//  location.
//

typedef enum _FROM {

    PipeQuota,
    UserQuota,
    InIrp

} FROM;

//
//  Each entry in the data queue is a data entry.  Processing an IRP
//  has the potential of creating and inserting a new data entry.  If the
//  memory for the entry is taken from the IRP we use the next stack
//  location.
//

typedef struct _DATA_ENTRY {

    //
    //  The following field is how we connect into the queue of data entries
    //

    struct _DATA_ENTRY *Next;

    //
    //  The following two fields describe the type of data entry and where
    //  we got its memory from.  If the type is buffered then the From field
    //  also denotes where we got the memory for the data buffer, otherwise
    //  the data buffer has been supplied by the IRP
    //

    DATA_ENTRY_TYPE DataEntryType : 8;
    FROM From : 8;

    //
    //  The following field indicates if we still have an IRP associated
    //  with this data entry that need to be completed when the remove
    //  the data entry.  Note that if From is InIrp that this IRP field
    //  must not be null.
    //

    PIRP Irp;

    //
    //  The following two fields describe the size and location of the data
    //  buffer described by this entry.  These fields are only used if the
    //  type is buffer, or unbuffered, and are ignored otherwise.
    //

    ULONG DataSize;
    PVOID DataPointer;

    //
    //  The following field is used to point to the client context if dynamic
    //  impersonation is being used
    //

    PSECURITY_CLIENT_CONTEXT SecurityClientContext;

} DATA_ENTRY;
typedef DATA_ENTRY *PDATA_ENTRY;


//
//  The following type is used by the wait queue package
//

typedef struct _WAIT_QUEUE {

    LIST_ENTRY Queue;

    KSPIN_LOCK SpinLock;

} WAIT_QUEUE;
typedef WAIT_QUEUE *PWAIT_QUEUE;


typedef struct _VCB {

    //
    //  The type and size of this record (must be NPFS_NTC_VCB)
    //

    NODE_TYPE_CODE NodeTypeCode;
    NODE_BYTE_SIZE NodeByteSize;

    //
    //  A pointer to the root DCB for this volume
    //

    struct _FCB *RootDcb;

    //
    //  A count of the number of file objects that have opened the \NamedPipe
    //  object directly, and also a count of the number of file objects
    //  that have opened a name pipe or the root directory.
    //

    CLONG OpenCount;
    CLONG OpenUnderlingCount;

    //
    //  A prefix table that is used for quick, prefix directed, lookup of
    //  FCBs/DCBs that are part of this volume
    //

    UNICODE_PREFIX_TABLE PrefixTable;

    //
    //  A resource variable to control access to the volume specific data
    //  structures
    //

    ERESOURCE Resource;

    //
    //  The following table is used to hold the named pipe events
    //

    EVENT_TABLE EventTable;

    //
    //  The following field is a queue of waiting IRPS of type WaitForNamedPipe
    //

    WAIT_QUEUE WaitQueue;

    //
    //  The following field is used to check share access people who want
    //  to open the named pipe driver
    //

    SHARE_ACCESS ShareAccess;

} VCB;
typedef VCB *PVCB;


//
//  The Named Pipe Device Object is an I/O system device object with
//  additional workqueue parameters appended to the end.  There is only
//  one of these records created for the entire system during system
//  initialization.
//

typedef struct _NPFS_DEVICE_OBJECT {

    DEVICE_OBJECT DeviceObject;

    //
    //  This is the file system specific volume control block.
    //

    VCB Vcb;

} NPFS_DEVICE_OBJECT;
typedef NPFS_DEVICE_OBJECT *PNPFS_DEVICE_OBJECT;


//
//  The Fcb/Dcb record corresponds to every opened named pipe and directory,
//  and to every directory on an opened path.
//
//  The structure is really divided into two parts.  FCB can be allocated
//  from paged pool which the NONPAGED_FCB must be allocated from non-paged
//  pool.
//

typedef struct _FCB {

    //
    //  Type and size of this record (must be NPFS_NTC_FCB, or
    //  NPFS_NTC_ROOT_DCB)
    //

    NODE_TYPE_CODE NodeTypeCode;
    NODE_BYTE_SIZE NodeByteSize;

    //
    //  The links for the queue of all fcbs for a specific dcb off of
    //  Dcb.ParentDcbQueue.  For the root directory this queue is empty
    //

    LIST_ENTRY ParentDcbLinks;

    //
    //  A pointer to the Dcb that is the parent directory containing
    //  this fcb.  If this record itself is the root dcb then this field
    //  is null.
    //

    struct _FCB *ParentDcb;

    //
    //  A pointer to the Vcb containing this fcb
    //

    PVCB Vcb;

    //
    //  A count of the number of file objects that have opened
    //  this file/directory.  For a pipe this is also the number of instances
    //  created for the pipe.
    //

    CLONG OpenCount;

    //
    //  A count of the number of server end file objects that have opened
    //  this pipe.  ServerOpenCount is incremented when OpenCount is
    //  incremented (when the server end creates an instance), but is
    //  decremented when the server end handle is closed, where OpenCount
    //  isn't decremented until both side's handles are closed.  When
    //  ServerOpenCount is 0, a client's attempt to open a named pipe is
    //  met with STATUS_OBJECT_NAME_NOT_FOUND, not STATUS_PIPE_NOT_AVAILABLE,
    //  based on an assumption that since the server doesn't think it has
    //  any instances open, the pipe really doesn't exist anymore.  An
    //  example of when this distinction is useful is when the server
    //  process exits, but the client processes haven't closed their
    //  handles yet.
    //

    CLONG ServerOpenCount;

    //
    //  The following field points to the security descriptor for this named pipe
    //

    PSECURITY_DESCRIPTOR SecurityDescriptor;

    //
    //  The following union is cased off of the node type code for the fcb.
    //  There is a seperate case for the directory versus file fcbs.
    //

    union {

        //
        //  A Directory Control Block (Dcb)
        //

        struct {

            //
            //  A queue of the notify IRPs that will be completed when any
            //  change is made to a file in the directory.  Enqueued using
            //  the Tail.Overlay.ListEntry of the Irp.
            //

            LIST_ENTRY NotifyFullQueue;

            //
            //  A queue of the notify IRPs that will be completed only if a
            //  file is added, deleted, or renamed in the directory.  Enqueued
            //  using the Tail.Overlay.ListEntry of the Irp.
            //

            LIST_ENTRY NotifyPartialQueue;

            //
            //  A queue of all the fcbs/dcbs that are opened under this
            //  Dcb.
            //

            LIST_ENTRY ParentDcbQueue;

            //
            //  The following field is used to check share access people
            //  who want to open the directory.
            //

            SHARE_ACCESS ShareAccess;

        } Dcb;

        //
        //  An File Control Block (Fcb)
        //

        struct {

            //
            //  This is the maximum number of instances we can have for the
            //  named pipe and the current number of instances is the open
            //  count for the fcb (note that the current number also
            //  correspondsto the number of Ccbs)
            //

            ULONG MaximumInstances;

            //
            //  The assigned pipe configuration (FILE_PIPE_INBOUND,
            //  FILE_PIPE_OUTBOUND, or FILE_PIPE_FULL_DUPLEX) and pipe
            //  type (FILE_PIPE_MESSAGE_TYPE or
            //  FILE_PIPE_BYTE_STREAM_TYPE).
            //

            NAMED_PIPE_CONFIGURATION NamedPipeConfiguration : 16;
            NAMED_PIPE_TYPE NamedPipeType : 16;

            //
            //  The following field is the default timeout assigned to the
            //  named pipe
            //

            LARGE_INTEGER DefaultTimeOut;

            //
            //  The Following field is a queue head for a list of ccbs
            //  that are opened under us
            //

            LIST_ENTRY CcbQueue;

        } Fcb;

    } Specific;

    //
    //  The following field is the fully qualified file name for this FCB/DCB
    //  starting from the root of the volume, and last file name in the
    //  fully qualified name.
    //

    UNICODE_STRING FullFileName;
    UNICODE_STRING LastFileName;

    //
    //  The following field contains a prefix table entry that is used when
    //  searching a volume for a name (or longest matching prefix)
    //

    UNICODE_PREFIX_TABLE_ENTRY PrefixTableEntry;

    //
    //  A pointer to the specific non-paged data for the Fcb.
    //

    struct _NONPAGED_FCB *NonpagedFcb;

} FCB, DCB, ROOT_DCB;

typedef FCB *PFCB;
typedef DCB *PDCB;
typedef ROOT_DCB *PROOT_DCB;

typedef struct _NONPAGED_FCB {

    //
    //  Type and size of this record (must be NPFS_NTC_NONPAGED_FCB, or
    //  NPFS_NTC_NONPAGED_ROOT_DCB)
    //

    NODE_TYPE_CODE NodeTypeCode;
    NODE_BYTE_SIZE NodeByteSize;

} NONPAGED_FCB, NONPAGED_DCB, NONPAGED_ROOT_DCB;

typedef NONPAGED_FCB *PNONPAGED_FCB;
typedef NONPAGED_DCB *PNONPAGED_DCB;
typedef NONPAGED_ROOT_DCB *PNONPAGED_ROOT_DCB;


//
//  The Ccb record is allocated for every opened instance of a named pipe.
//  There are two parts to a ccb a paged part and a Nonpaged part.  Both
//  parts are pointed at by the FsContext and FsContext2 field of a file
//  object.
//

typedef struct _CCB {

    //
    //  Type and size of this record (must be NPFS_NTC_CCB).
    //

    NODE_TYPE_CODE NodeTypeCode;
    NODE_BYTE_SIZE NodeByteSize;

    //
    //  The following field is a list entry for the list of ccb that we
    //  are a member of
    //

    LIST_ENTRY CcbLinks;

    //
    //  A pointer to the paged Fcb, or Vcb that we are tied to
    //

    PFCB Fcb;

    //
    //  Back pointers to the server and client file objects that have us
    //  opened.  This is indexed by either FILE_PIPE_CLIENT_END or
    //  FILE_PIPE_SERVER_END.
    //

    PFILE_OBJECT FileObject[2];

    //
    //  The internal state of the Ccb.  This is the shared access for each
    //  time this pipe/directory is opened.
    //

    SHARE_ACCESS ShareAccess;

    //
    //  The following fields contain the session and process IDs of the
    //  client side of the named pipe instance.  They are originally set
    //  to NULL (indicating local session) and the real client process
    //  ID but can be changed via FsCtl calls.
    //

    PVOID ClientSession;
    PVOID ClientProcess;

    //
    //  A pointer to the Nonpaged part of the ccb
    //

    struct _NONPAGED_CCB *NonpagedCcb;

    //
    //  A pointer to the paged Fcb, or Vcb that we are tied to
    //

    PNONPAGED_FCB NonpagedFcb;

    //
    //  Pipe state indicates the current state of the pipe
    //  (FILE_PIPE_DISCONNECTED_STATE, FILE_PIPE_LISTENING_STATE,
    //  FILE_PIPE_CONNECTED_STATE, or FILE_PIPE_CLOSING_STATE).
    //

    NAMED_PIPE_STATE NamedPipeState;

    //
    //  read mode (FILE_PIPE_MESSAGE_MODE or FILE_PIPE_BYTE_STREAM_MODE),
    //  and completion mode (FILE_PIPE_QUEUE_OPERATION or
    //  FILE_PIPE_COMPLETE_OPERATION) describe how to handle requests to the
    //  pipe.  Both of these fields are indexed by either FILE_PIPE_SERVER_END
    //  or FILE_PIPE_CLIENT_END.
    //

    READ_MODE ReadMode[2];
    COMPLETION_MODE CompletionMode[2];

    //
    //  The following field is used to remember the process that created this
    //  instance of the named pipe.  It is needed to allocate quota and
    //  return quota
    //

    PEPROCESS CreatorProcess;

    //
    //  The following data queues are used to contain the buffered information
    //  for each direction in the pipe.  They array is indexed by
    //  PIPE_DIRECTION.
    //

    DATA_QUEUE DataQueue[2];

    //
    //  The following fields are used for security impersonation
    //  Only the server end can impersonate and only for the inbound path
    //  (i.e., client writes then server reads and impersonates).
    //
    //  If it is static tracking (SecurityQos contains the type of tracking)
    //  then we set the quality of service and the client context in the
    //  nonpaged ccb on open and we never change anything.
    //
    //  If it is dynamic tracking then we set the quality of service in the
    //  nonpaged ccb and on every write by the client we set the client
    //  context in the data entry and when read by the server we update the
    //  client context field of the nonpaged ccb to value stored in the data
    //  entry.
    //
    //  On impersonation we use the client context stored in the nonpaged ccb
    //

    SECURITY_QUALITY_OF_SERVICE SecurityQos;
    PSECURITY_CLIENT_CONTEXT SecurityClientContext;

} CCB;
typedef CCB *PCCB;

typedef struct _NONPAGED_CCB {

    //
    //  Type and size of this record (must be NPFS_NTC_NONPAGED_CCB)
    //

    NODE_TYPE_CODE NodeTypeCode;
    NODE_BYTE_SIZE NodeByteSize;

    //
    //  The following pointers denote the events we are to signal for the
    //  server and client ends of the named pipe.  The actual entry
    //  is stored in the event table, and referenced here for easy access.
    //  The client end is signaled if ever a read/write occurs to the client
    //  of the pipe, and likewise for the server end.  The array is
    //  indexed by either FILE_PIPE_SERVER_END or FILE_PIPE_CLIENT_END.
    //

    PEVENT_TABLE_ENTRY EventTableEntry[2];

    //
    //  A queue of waiting listening IRPs.  They are linked into the
    //  Tail.Overlay.ListEntry field in the Irp.
    //

    LIST_ENTRY ListeningQueue;

    //
    // Resource for synchronizing access
    //
    ERESOURCE Resource;

} NONPAGED_CCB;
typedef NONPAGED_CCB *PNONPAGED_CCB;


//
//  The Root Dcb Ccb record is allocated for every opened instance of the
//  root dcb.  This record is pointed at by FsContext2.
//

typedef struct _ROOT_DCB_CCB {

    //
    //  Type and size of this record (must be NPFS_NTC_ROOT_DCB_CCB).
    //

    NODE_TYPE_CODE NodeTypeCode;
    NODE_BYTE_SIZE NodeByteSize;

    //
    //  The following field is a count of the last index returned
    //  by query directory.
    //

    ULONG IndexOfLastCcbReturned;

    //
    //  The following string is used as a query template for directory
    //  query operations
    //

    PUNICODE_STRING QueryTemplate;

} ROOT_DCB_CCB;
typedef ROOT_DCB_CCB *PROOT_DCB_CCB;

#endif // _NPSTRUC_