portcls.h

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

    STDMETHOD(NewMasterDmaChannel)
    (   THIS_
        OUT     PDMACHANNEL *       OutDmaChannel,
        IN      PUNKNOWN            OuterUnknown    OPTIONAL,
        IN      POOL_TYPE           PoolType,
        IN      PRESOURCELIST       ResourceList    OPTIONAL,
        IN      BOOLEAN             ScatterGather,
        IN      BOOLEAN             Dma32BitAddresses,
        IN      BOOLEAN             Dma64BitAddresses,
        IN      BOOLEAN             IgnoreCount,
        IN      DMA_WIDTH           DmaWidth,
        IN      DMA_SPEED           DmaSpeed,
        IN      ULONG               MaximumLength,
        IN      ULONG               DmaPort
    )   PURE;
};

typedef IPortWavePci *PPORTWAVEPCI;

#ifdef PC_IMPLEMENTATION
#define IMP_IPortWavePci\
    IMP_IPort;\
    STDMETHODIMP_(void) Notify\
    (   IN      PSERVICEGROUP       ServiceGroup\
    );\
    STDMETHODIMP NewMasterDmaChannel\
    (   OUT     PDMACHANNEL *       OutDmaChannel,\
        IN      PUNKNOWN            OuterUnknown    OPTIONAL,\
        IN      POOL_TYPE           PoolType,\
        IN      PRESOURCELIST       ResourceList    OPTIONAL,\
        IN      BOOLEAN             ScatterGather,\
        IN      BOOLEAN             Dma32BitAddresses,\
        IN      BOOLEAN             Dma64BitAddresses,\
        IN      BOOLEAN             IgnoreCount,\
        IN      DMA_WIDTH           DmaWidth,\
        IN      DMA_SPEED           DmaSpeed,\
        IN      ULONG               MaximumLength,\
        IN      ULONG               DmaPort\
    )
#endif

/*****************************************************************************
 * IPortWavePciStream
 *****************************************************************************
 * Interface for PCI wave port pin lower edge.
 */
DECLARE_INTERFACE_(IPortWavePciStream,IUnknown)
{
    STDMETHOD(GetMapping)
    (   THIS_
        IN      PVOID               Tag,
        OUT     PPHYSICAL_ADDRESS   PhysicalAddress,
        OUT     PVOID *             VirtualAddress,
        OUT     PULONG              ByteCount,
        OUT     PULONG              Flags
    )   PURE;

    STDMETHOD(ReleaseMapping)
    (   THIS_
        IN      PVOID               Tag
    )   PURE;

    STDMETHOD(TerminatePacket)
    (   THIS
    )   PURE;
};

typedef IPortWavePciStream *PPORTWAVEPCISTREAM;

#ifdef PC_IMPLEMENTATION
#define IMP_IPortWavePciStream\
    STDMETHODIMP GetMapping\
    (   IN      PVOID               Tag,\
        OUT     PPHYSICAL_ADDRESS   PhysicalAddress,\
        OUT     PVOID *             VirtualAddress,\
        OUT     PULONG              ByteCount,\
        OUT     PULONG              Flags\
    );\
    STDMETHODIMP ReleaseMapping\
    (   IN      PVOID               Tag\
    );\
    STDMETHODIMP TerminatePacket\
    (   void\
    )
#endif

/*****************************************************************************
 * IMiniportWavePciStream
 *****************************************************************************
 * Interface for PCI wave miniport streams.
 */
DECLARE_INTERFACE_(IMiniportWavePciStream,IUnknown)
{
    STDMETHOD(SetFormat)
    (   THIS_
        IN      PKSDATAFORMAT   DataFormat
    )   PURE;

    STDMETHOD(SetState)
    (   THIS_
        IN      KSSTATE         State
    )   PURE;

    STDMETHOD(GetPosition)
    (   THIS_
        OUT     PULONGLONG      Position
    )   PURE;
    
    STDMETHOD(NormalizePhysicalPosition)
    (
        THIS_
        IN OUT PLONGLONG        PhysicalPosition
    )   PURE;
    
    STDMETHOD(GetAllocatorFraming)
    (
        THIS_
        OUT PKSALLOCATOR_FRAMING AllocatorFraming
    ) PURE;

    STDMETHOD(RevokeMappings)
    (   THIS_
        IN      PVOID           FirstTag,
        IN      PVOID           LastTag,
        OUT     PULONG          MappingsRevoked
    )   PURE;

    STDMETHOD_(void,MappingAvailable)
    (   THIS
    )   PURE;

    STDMETHOD_(void,Service)
    (   THIS
    )   PURE;
};

typedef IMiniportWavePciStream *PMINIPORTWAVEPCISTREAM;

#define IMP_IMiniportWavePciStream\
    STDMETHODIMP SetFormat\
    (   IN      PKSDATAFORMAT   DataFormat\
    );\
    STDMETHODIMP SetState\
    (   IN      KSSTATE         State\
    );\
    STDMETHODIMP GetPosition\
    (   OUT     PULONGLONG      Position\
    );\
    STDMETHODIMP NormalizePhysicalPosition\
    (   IN OUT PLONGLONG        PhysicalPosition\
    );\
    STDMETHODIMP GetAllocatorFraming\
    (   OUT PKSALLOCATOR_FRAMING AllocatorFraming\
    );\
    STDMETHODIMP RevokeMappings\
    (   IN      PVOID           FirstTag,\
        IN      PVOID           LastTag,\
        OUT     PULONG          MappingsRevoked\
    );\
    STDMETHODIMP_(void) MappingAvailable\
    (   void\
    );\
    STDMETHODIMP_(void) Service\
    (   void\
    )

/*****************************************************************************
 * IMiniportWavePci
 *****************************************************************************
 * Interface for PCI wave miniports.
 */
DECLARE_INTERFACE_(IMiniportWavePci,IMiniport)
{
    STDMETHOD(Init)
    (   THIS_
        IN      PUNKNOWN            UnknownAdapter,
        IN      PRESOURCELIST       ResourceList,
        IN      PPORTWAVEPCI        Port,
        OUT     PSERVICEGROUP *     ServiceGroup
    )   PURE;

    STDMETHOD(NewStream)
    (   THIS_
        OUT     PMINIPORTWAVEPCISTREAM *    Stream,
        IN      PUNKNOWN                    OuterUnknown    OPTIONAL,
        IN      POOL_TYPE                   PoolType,
        IN      PPORTWAVEPCISTREAM          PortStream,
        IN      ULONG                       Pin,
        IN      BOOLEAN                     Capture,
        IN      PKSDATAFORMAT               DataFormat,
        OUT     PDMACHANNEL *               DmaChannel,
        OUT     PSERVICEGROUP *             ServiceGroup
    )   PURE;

    STDMETHOD_(void,Service)
    (   THIS
    )   PURE;
};

typedef IMiniportWavePci *PMINIPORTWAVEPCI;

#define IMP_IMiniportWavePci\
    IMP_IMiniport;\
    STDMETHODIMP Init\
    (   IN      PUNKNOWN            UnknownAdapter,\
        IN      PRESOURCELIST       ResourceList,\
        IN      PPORTWAVEPCI        Port,\
        OUT     PSERVICEGROUP *     ServiceGroup\
    );\
    STDMETHODIMP NewStream\
    (   OUT     PMINIPORTWAVEPCISTREAM *    Stream,\
        IN      PUNKNOWN                    OuterUnknown    OPTIONAL,\
        IN      POOL_TYPE                   PoolType,\
        IN      PPORTWAVEPCISTREAM          PortStream,\
        IN      ULONG                       Pin,\
        IN      BOOLEAN                     Capture,\
        IN      PKSDATAFORMAT               DataFormat,\
        OUT     PDMACHANNEL *               DmaChannel,\
        OUT     PSERVICEGROUP *             ServiceGroup\
    );\
    STDMETHODIMP_(void) Service\
    (   void\
    )

/*****************************************************************************
 * IAdapterPowerManagment
 *****************************************************************************
 * Interface that adapters should implment and register
 * if they want power managment messages.
 * Register this interface w/ portcls via the
 * PcRegisterAdapterPowerManagement() call.
 * NOTE: If you want to fill in the caps struct
 * for you device, register the interface
 * w/ portclas in or before your AddDevice()
 * function. The OS queries devices before
 * StartDevice() gets called.
 */
DECLARE_INTERFACE_(IAdapterPowerManagement,IUnknown)
{
    // Called by portcls requested
    // that the device change to
    // the new power state
    STDMETHOD_(void,PowerChangeState)
    (   THIS_
        IN      POWER_STATE     NewState
    )   PURE;
    
    // Caled by portcls to see
    // if the device can change to
    // the requested device state.
    STDMETHOD(QueryPowerChangeState)
    (   THIS_
        IN      POWER_STATE     NewStateQuery
    )   PURE;


    // Called by portcls to get the
    // power managment capabilities
    // for the device. See ACPI
    // documentation for data about
    // DEVICE_CAPABILITIES struct.
    STDMETHOD(QueryDeviceCapabilities)
    (   THIS_
        IN      PDEVICE_CAPABILITIES    PowerDeviceCaps
    )   PURE;
};

typedef IAdapterPowerManagement *PADAPTERPOWERMANAGMENT;

#define IMP_IAdapterPowerManagement\
    STDMETHODIMP_(void) PowerChangeState\
    (   IN      POWER_STATE     NewState\
    );\
    STDMETHODIMP QueryPowerChangeState\
    (   IN      POWER_STATE     NewStateQuery\
    );\
    STDMETHODIMP QueryDeviceCapabilities\
    (   IN      PDEVICE_CAPABILITIES    PowerDeviceCaps\
    )
    
/*****************************************************************************
 * IPowerNotify
 *****************************************************************************
 * An OPTIONAL interface for miniports and pinsto implement to enable them to get
 * device power state change notifications.
 */
DECLARE_INTERFACE_(IPowerNotify,IUnknown)
{
    // Called by the port to notify interested miniports and pins
    // of device power state changes so that appropriate context
    // save/restore can take place.
    STDMETHOD_(void,PowerChangeNotify)
    (   THIS_
        IN      POWER_STATE     PowerState
    )   PURE;
};

typedef IPowerNotify *PPOWERNOTIFY;

#define IMP_IPowerNotify\
    STDMETHODIMP_(void) PowerChangeNotify\
    (   IN  POWER_STATE     PowerState\
    )
    
/*****************************************************************************
 * IPortEvents
 *****************************************************************************
 * An interface implemented by ports to provide notification event helpers
 * to miniports.
 */
DECLARE_INTERFACE_(IPortEvents,IUnknown)
{
    STDMETHOD_(void,AddEventToEventList)
    (   THIS_
        IN  PKSEVENT_ENTRY      EventEntry
    )   PURE;
    STDMETHOD_(void,GenerateEventList)
    (   THIS_
        IN  GUID*   Set     OPTIONAL,
        IN  ULONG   EventId,
        IN  BOOL    PinEvent,
        IN  ULONG   PinId,
        IN  BOOL    NodeEvent,
        IN  ULONG   NodeId
    )   PURE;
};

typedef IPortEvents *PPORTEVENTS;

#define IMP_IPortEvents\
    STDMETHODIMP_(void) AddEventToEventList\
    (   IN  PKSEVENT_ENTRY  EventEntry\
    );\
    STDMETHODIMP_(void) GenerateEventList\
    (   IN  GUID*   Set     OPTIONAL,\
        IN  ULONG   EventId,\
        IN  BOOL    PinEvent,\
        IN  ULONG   PinId,\
        IN  BOOL    NodeEvent,\
        IN  ULONG   NodeId\
    )

/*****************************************************************************
 * Functions.
 */

/*****************************************************************************
 * PCPFNSTARTDEVICE
 *****************************************************************************
 * Type for start device callback.
 */
typedef
NTSTATUS
(*PCPFNSTARTDEVICE)
(
#ifdef PC_OLD_NAMES
    IN      PVOID           DeviceObject,
    IN      PVOID           Irp,
#else
    IN      PDEVICE_OBJECT  DeviceObject,
    IN      PIRP            Irp,
#endif
    IN      PRESOURCELIST   ResourceList
);

/*****************************************************************************
 * PCPFNIRPHANDLER
 *****************************************************************************
 * Type for IRP handlers.
 */
typedef
NTSTATUS
(*PCPFNIRPHANDLER)
(
    IN      PDEVICE_OBJECT  DeviceObject,
    IN      PIRP            Irp,
    OUT     PULONG          Action
#define IRP_HANDLER_ACTION_DEFAULT 0
#define IRP_HANDLER_ACTION_FINISH  1
#define IRP_HANDLE