strmini.h

书中的主要程序文件。在打开例题的.dsw文件后,请读者在 tools菜单下的 Options 的 Directories 标签中选择 Executable files

/*++

Copyright (c) 1996  Microsoft Corporation

Module Name:

    STRMINI.H

Abstract:

    This file defines streaming minidriver structures and class/minidriver
    interfaces.

Author:

    billpa

Environment:

   Kernel mode only

Revision History:

--*/

#ifndef _STREAM_H
#define _STREAM_H

#include <wdm.h>
#include <windef.h>
#include <stdio.h>
#include "ks.h"

#define STREAMAPI __stdcall

typedef unsigned __int64 STREAM_SYSTEM_TIME,
               *PSTREAM_SYSTEM_TIME;
typedef unsigned __int64 STREAM_TIMESTAMP,
               *PSTREAM_TIMESTAMP;
#define STREAM_SYSTEM_TIME_MASK   ((STREAM_SYSTEM_TIME)0x00000001FFFFFFFF)
//
// debug print level values
//

typedef enum {                  // Use the given level to indicate:
    DebugLevelFatal = 0,        // * imminent nonrecoverable system failure
    DebugLevelError,            // * serious error, though recoverable
    DebugLevelWarning,          // * warnings of unusual occurances
    DebugLevelInfo,             // * status and other information - normal
    // though
    // perhaps unusual events. System MUST remain
    // responsive.
    DebugLevelTrace,            // * trace information - normal events
    // system need not ramain responsive
    DebugLevelVerbose,          // * verbose trace information
    // system need not remain responsive
    DebugLevelMaximum
}               STREAM_DEBUG_LEVEL;

#define DebugLevelAlways    DebugLevelFatal

#if DBG

//
// macro for printing debug information
//
#define DebugPrint(x) StreamClassDebugPrint x

//
// macro for doing INT 3 (or non-x86 equivalent)
//

#if WIN95_BUILD

#define DEBUG_BREAKPOINT() _asm int 3;

#else

#define DEBUG_BREAKPOINT() DbgBreakPoint()

#endif

//
// macro for asserting (stops if not = TRUE)
//

#define DEBUG_ASSERT(exp) \
            if ( !(exp) ) { \
                StreamClassDebugAssert( __FILE__, __LINE__, #exp, exp); \
            }

#else

#define DebugPrint(x)
#define DEBUG_BREAKPOINT()
#define DEBUG_ASSERT(exp)

#endif

//
// Uninitialized flag value.
//

#define MP_UNINITIALIZED_VALUE ((ULONG) ~0)

//
// define physical address formats
//

typedef PHYSICAL_ADDRESS STREAM_PHYSICAL_ADDRESS,
               *PSTREAM_PHYSICAL_ADDRESS;


//
// functions for the time context structure below
//

typedef enum {

    TIME_GET_STREAM_TIME,
    TIME_READ_ONBOARD_CLOCK,
    TIME_SET_ONBOARD_CLOCK
}               TIME_FUNCTION;

//
// define the time context structure
//

typedef struct _HW_TIME_CONTEXT {

    struct _HW_DEVICE_EXTENSION *HwDeviceExtension;
    struct _HW_STREAM_OBJECT *HwStreamObject;
    TIME_FUNCTION   Function;
    ULONGLONG       Time;
    ULONGLONG       SystemTime;
}               HW_TIME_CONTEXT, *PHW_TIME_CONTEXT;

//
// define the event descriptor for enabling/disabling events.
//

typedef struct _HW_EVENT_DESCRIPTOR {
    BOOLEAN       Enable;  // TRUE means this is an enable, FALSE means disable
    PKSEVENT_ENTRY EventEntry;  // event structure
    PKSEVENTDATA EventData;  // data representing this event
    union {
    struct _HW_STREAM_OBJECT * StreamObject; // stream object for the event
    struct _HW_DEVICE_EXTENSION *DeviceExtension;
    };
    ULONG EnableEventSetIndex; // gives the index of the event set for ENABLE
                               // field has no meaning for DISABLE
    ULONG Reserved[2];    // Reserved for future use

} HW_EVENT_DESCRIPTOR, *PHW_EVENT_DESCRIPTOR;

//
// function prototypes for stream object functions
//

typedef         VOID
                (STREAMAPI * PHW_RECEIVE_STREAM_DATA_SRB) ( // HwReceiveDataPacket
                                             IN struct _HW_STREAM_REQUEST_BLOCK * SRB
);

typedef         VOID
                (STREAMAPI * PHW_RECEIVE_STREAM_CONTROL_SRB) (  // HwReceiveControlPacket
                                             IN struct _HW_STREAM_REQUEST_BLOCK  * SRB
);

typedef         NTSTATUS
                (STREAMAPI * PHW_EVENT_ROUTINE) ( // HwEventRoutine
                                             IN PHW_EVENT_DESCRIPTOR EventDescriptor
);

typedef         VOID
                (STREAMAPI * PHW_CLOCK_FUNCTION) ( // HwClockFunction
                                             IN PHW_TIME_CONTEXT HwTimeContext
);

//
// define the clock object
//

typedef struct _HW_CLOCK_OBJECT {

    //
    // pointer to the minidriver's clock function
    //

    PHW_CLOCK_FUNCTION HwClockFunction;

    //
    // support flags as defined below
    //

    ULONG    ClockSupportFlags;

    ULONG Reserved[2];    // Reserved for future use
} HW_CLOCK_OBJECT, *PHW_CLOCK_OBJECT;

//
// clock object support flags defined as follows
//

//
// indicates that the minidriver's clock for this stream is tunable
// via TIME_SET_ONBOARD_CLOCK
//

#define CLOCK_SUPPORT_CAN_SET_ONBOARD_CLOCK 0x00000001

//
// indicates that the minidriver's clock for this stream is raw readable
// via TIME_READ_ONBOARD_CLOCK
//

#define CLOCK_SUPPORT_CAN_READ_ONBOARD_CLOCK 0x00000002

//
// indicates that the minidriver can return the current stream time for this
// stream via TIME_GET_STREAM_TIME
//

#define CLOCK_SUPPORT_CAN_RETURN_STREAM_TIME 0x00000004

//
// stream object definition
//

typedef struct _HW_STREAM_OBJECT {
    ULONG           SizeOfThisPacket; // size of this structure
    ULONG           StreamNumber;   // number of this stream
    PVOID           HwStreamExtension;  // minidriver's stream extension
    PHW_RECEIVE_STREAM_DATA_SRB ReceiveDataPacket;  // receive data packet routine
    PHW_RECEIVE_STREAM_CONTROL_SRB ReceiveControlPacket;   // receive control packet routine
    HW_CLOCK_OBJECT HwClockObject;    // clock object to be filled in by
                                      // minidriver
    BOOLEAN         Dma;        // device uses busmaster DMA
    // for this stream
    BOOLEAN         Pio;        // device uses PIO for this
    PVOID           HwDeviceExtension;  // minidriver's device ext.

    ULONG    StreamHeaderMediaSpecific;  // Size of media specific per
                                         // stream header expansion. 
    ULONG    StreamHeaderWorkspace; // Size of per-stream header workspace.
    BOOLEAN Allocator;  // Set to TRUE if allocator is needed for this stream.    

    //
    // the following routine receives ENABLE and DISABLE notification of
    // KS synchronization events for this stream.
    //

    PHW_EVENT_ROUTINE HwEventRoutine;

    ULONG Reserved[2];    // Reserved for future use

} HW_STREAM_OBJECT, *PHW_STREAM_OBJECT;

//
// the following structures are used to report which stream types and properties
// are supported by the minidriver.  the HW_STREAM_HEADER structure is followed
// in memory by one or more HW_STREAM_INFORMATION structures.  See the
// HW_STREAM_DESCRIPTOR structure below.
//

typedef struct _HW_STREAM_HEADER {

    //
    // indicates the number of HW_STREAM_INFORMATION structures follow this
    // structure.
    //

    ULONG           NumberOfStreams;

    //
    // size of the HW_STREAM_INFORMATION structure below (filled in by the
    // minidriver)
    //

    ULONG SizeOfHwStreamInformation;

    //
    // indicates the number of property sets supported by the device itself.
    //

    ULONG           NumDevPropArrayEntries;

    //
    // pointer to the array of device property sets.
    //

    PKSPROPERTY_SET DevicePropertiesArray;
    
    //
    // indicates the number of event sets supported by the device itself.
    //

    ULONG           NumDevEventArrayEntries;

    //
    // pointer to the array of device property sets.
    //

    PKSEVENT_SET DeviceEventsArray;

    //
    // pointer to the topology structure
    //

    PKSTOPOLOGY Topology;

    //
    // event routine for processing device events, if any.
    //

    PHW_EVENT_ROUTINE DeviceEventRoutine;

    ULONG Reserved[2];    // Reserved for future use

}               HW_STREAM_HEADER, *PHW_STREAM_HEADER;

//
// the HW_STREAM_INFORMATION structure(s) indicate what streams are supported
//

typedef struct _HW_STREAM_INFORMATION {

    //
    // number of possible instances of this stream that can be opened at once
    //

    ULONG           NumberOfPossibleInstances;

    //
    // Indicates the direction of data flow of this stream
    //

    KSPIN_DATAFLOW  DataFlow;

    //
    // Indicates whether the data is "seen" by the host processor.  If the
    // data is not visible to the processor (such as an NTSC output port)
    // this boolean is set to false.
    //

    BOOLEAN         DataAccessible;

    //
    // Number of formats supported by this stream.  Indicates the number of
    // elements pointed to by StreamFormatsArray below.
    //

    ULONG           NumberOfFormatArrayEntries;

    //
    // pointer to an array of elements indicating what types of data are
    // supported with this stream.
    //

    PKSDATAFORMAT*  StreamFormatsArray;

    //
    // reserved for future use.
    //

    PVOID           ClassReserved[4];

    //
    // number of property sets supported by this stream
    //

    ULONG           NumStreamPropArrayEntries;

    //
    // pointer to an array of property set descriptors for this stream
    //

    PKSPROPERTY_SET StreamPropertiesArray;

    //
    // number of event sets supported by this stream
    //

    ULONG           NumStreamEventArrayEntries;

    //
    // pointer to an array of event set descriptors for this stream
    //

    PKSEVENT_SET StreamEventsArray;

    //
    // pointer to guid representing catagory of stream.  (optional)
    //

    GUID*                   Category;
    
    //
    // pointer to guid representing name of stream.  (optional)
    //

    GUID*                   Name;

    //
    // count of media supported (optional)
    //

    ULONG                   MediumsCount;

    //