portcls.h

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

#define PCPROPERTY_ITEM_FLAG_UNSERIALIZERAW KSPROPERTY_TYPE_UNSERIALIZERAW  
#define PCPROPERTY_ITEM_FLAG_SERIALIZESIZE  KSPROPERTY_TYPE_SERIALIZESIZE   
#define PCPROPERTY_ITEM_FLAG_SERIALIZE\
	(PCPROPERTY_ITEM_FLAG_SERIALIZERAW\
	|PCPROPERTY_ITEM_FLAG_UNSERIALIZERAW\
	|PCPROPERTY_ITEM_FLAG_SERIALIZESIZE\
	)
#define PCPROPERTY_ITEM_FLAG_DEFAULTVALUES  KSPROPERTY_TYPE_DEFAULTVALUES   
    PCPFNPROPERTY_HANDLER   Handler;
}
PCPROPERTY_ITEM, *PPCPROPERTY_ITEM;

/*****************************************************************************
 * PCMETHOD_ITEM
 *****************************************************************************
 * Method table entry.
 *
 * A method item describes a method supported by a given filter, pin or node.
 * The flags indicate what operations regarding the method are supported and 
 * specify selected options with respect to the port's handling of method
 * requests.
 */
typedef struct
{
    const GUID *            Set;
    ULONG                   Id;
    ULONG                   Flags;
#define PCMETHOD_ITEM_FLAG_NONE         KSMETHOD_TYPE_NONE
#define PCMETHOD_ITEM_FLAG_READ         KSMETHOD_TYPE_READ
#define PCMETHOD_ITEM_FLAG_WRITE        KSMETHOD_TYPE_WRITE
#define PCMETHOD_ITEM_FLAG_MODIFY       KSMETHOD_TYPE_MODIFY
#define PCMETHOD_ITEM_FLAG_SOURCE       KSMETHOD_TYPE_SOURCE
#define PCMETHOD_ITEM_FLAG_BASICSUPPORT KSMETHOD_TYPE_BASICSUPPORT
    PCPFNMETHOD_HANDLER     Handler;
}
PCMETHOD_ITEM, *PPCMETHOD_ITEM;

/*****************************************************************************
 * PCEVENT_ITEM
 *****************************************************************************
 * Event table entry.
 *
 * An event item describes an event supported by a given filter, pin or node.
 * The flags indicate what operations regarding the event are supported and 
 * specify selected options with respect to the port's handling of event
 * requests.
 */
typedef struct
{
    const GUID *            Set;
    ULONG                   Id;
    ULONG                   Flags;
#define PCEVENT_ITEM_FLAG_ENABLE        KSEVENT_TYPE_ENABLE
#define PCEVENT_ITEM_FLAG_ONESHOT       KSEVENT_TYPE_ONESHOT
#define PCEVENT_ITEM_FLAG_BASICSUPPORT  KSEVENT_TYPE_BASICSUPPORT
    PCPFNEVENT_HANDLER      Handler;
}
PCEVENT_ITEM, *PPCEVENT_ITEM;

/*****************************************************************************
 * PCPROPERTY_REQUEST
 *****************************************************************************
 * Property request submitted to a property handler.
 *
 * This is the form that a property request takes.  Although the major target
 * is generic, in the case of miniports, it will be a pointer to the miniport
 * object.  Likewise, the minor target is the stream or voice if the request
 * is specific to a stream or voice.  Otherwise, the minor target is NULL.
 * If the request is targeted at a node, the Node parameter will specify which
 * one, otherwise it will be ULONG(-1).  If the target is a node, the minor
 * target may be specified to indicate the stream or voice with which the 
 * targeted node instance is associated.
 */
typedef struct _PCPROPERTY_REQUEST
{
    PUNKNOWN                MajorTarget;
    PUNKNOWN                MinorTarget;
    ULONG                   Node;
    const PCPROPERTY_ITEM * PropertyItem;
    ULONG                   Verb;
    ULONG                   InstanceSize;
    PVOID                   Instance;
    ULONG                   ValueSize;
    PVOID                   Value;
    PIRP                    Irp;
}
PCPROPERTY_REQUEST, *PPCPROPERTY_REQUEST;

/*****************************************************************************
 * PCMETHOD_REQUEST
 *****************************************************************************
 * Method request submitted to a property handler.
 *
 * Comments in the description of PCPROPERTY_REQUEST regarding the target
 * fields apply to this structure as well.
 */
typedef struct _PCMETHOD_REQUEST
{
    PUNKNOWN                MajorTarget;
    PUNKNOWN                MinorTarget;
    ULONG                   Node;
    const PCMETHOD_ITEM *   MethodItem;
    ULONG                   Verb;
    // TODO
}
PCMETHOD_REQUEST, *PPCMETHOD_REQUEST;

/*****************************************************************************
 * PCEVENT_REQUEST
 *****************************************************************************
 * Event request submitted to a property handler.
 *
 * Comments in the description of PCPROPERTY_REQUEST regarding the target
 * fields apply to this structure as well.
 */
typedef struct _PCEVENT_REQUEST
{
    PUNKNOWN                MajorTarget;
    PUNKNOWN                MinorTarget;
    ULONG                   Node;
    const PCEVENT_ITEM *    EventItem;
    PKSEVENT_ENTRY          EventEntry;
    ULONG                   Verb;
    PIRP                    Irp;
}
PCEVENT_REQUEST, *PPCEVENT_REQUEST;

#define PCEVENT_VERB_NONE          0
#define PCEVENT_VERB_ADD           1
#define PCEVENT_VERB_REMOVE        2
#define PCEVENT_VERB_SUPPORT       4

/*****************************************************************************
 * PCAUTOMATION_TABLE
 *****************************************************************************
 * Master table of properties, methods and events.
 *
 * Any of the item pointers may be NULL, in which case, corresponding counts
 * must be zero.  For item tables that are not zero length, the item size must
 * not be smaller than the size of the item structure defined by port class.
 * The item size may be larger, in which case the port class item structure is
 * assumed to be followed by private data.  Item sizes must be a multiple of
 * 8.
 */
typedef struct
{
    ULONG			        PropertyItemSize;
    ULONG			        PropertyCount;
    const PCPROPERTY_ITEM * Properties;
	ULONG			        MethodItemSize;
	ULONG			        MethodCount;
	const PCMETHOD_ITEM *	Methods;
	ULONG			        EventItemSize;
	ULONG			        EventCount;
	const PCEVENT_ITEM *    Events;
    ULONG                   Reserved;
}
PCAUTOMATION_TABLE, *PPCAUTOMATION_TABLE;

#define DEFINE_PCAUTOMATION_TABLE_PROP(AutomationTable,PropertyTable)\
const PCAUTOMATION_TABLE AutomationTable =\
{\
    sizeof(PropertyTable[0]),\
    SIZEOF_ARRAY(PropertyTable),\
    (const PCPROPERTY_ITEM *) PropertyTable,\
    0,0,NULL,\
    0,0,NULL,\
    0\
}

#define DEFINE_PCAUTOMATION_TABLE_PROP_EVENT(AutomationTable,PropertyTable,EventTable)\
const PCAUTOMATION_TABLE AutomationTable =\
{\
    sizeof(PropertyTable[0]),\
    SIZEOF_ARRAY(PropertyTable),\
    (const PCPROPERTY_ITEM *) PropertyTable,\
    0,0,NULL,\
    sizeof(EventTable[0]),\
    SIZEOF_ARRAY(EventTable),\
    (const PCEVENT_ITEM *) EventTable,\
    0\
}

/*****************************************************************************
 * PCPIN_DESCRIPTOR for IMiniport::GetDescription()
 *****************************************************************************
 * Description of a pin on the filter implemented by the miniport.
 *
 * MaxGlobalInstanceCount and MaxFilterInstanceCount may be zero to indicate
 * that the pin may not be instantiated, ULONG(-1) to indicate the pin may be
 * allocated any number of times, or any other value to indicate a specific 
 * number of times the pin may be allocated.  MinFilterInstanceCount may not
 * be ULONG(-1) because it specifies a definite lower bound on the number of
 * instances of a pin that must exist in order for a filter to function.
 *
 * The KS pin descriptor may have zero interfaces and zero mediums.  The list
 * of interfaces is ignored in all cases.  The medium list will default to
 * a list containing only the standard medium (device I/O).
 *
 * The automation table pointer may be NULL indicating that no automation is
 * supported.
 */
typedef struct
{
    ULONG                       MaxGlobalInstanceCount;
    ULONG                       MaxFilterInstanceCount;
    ULONG                       MinFilterInstanceCount;
    const PCAUTOMATION_TABLE *  AutomationTable;
    KSPIN_DESCRIPTOR            KsPinDescriptor;
} 
PCPIN_DESCRIPTOR, *PPCPIN_DESCRIPTOR;

/*****************************************************************************
 * PCNODE_DESCRIPTOR for IMiniport::GetDescription()
 *****************************************************************************
 * Description of a node in the filter implemented by the miniport.
 *
 * The automation table pointer may be NULL indicating that no automation is
 * supported.  The name GUID pointer may be NULL indicating that the type GUID
 * should be used to determine the node name.
 */
typedef struct
{
    ULONG                       Flags;
	const PCAUTOMATION_TABLE *  AutomationTable;
	const GUID *                Type;
	const GUID *                Name;
} 
PCNODE_DESCRIPTOR, *PPCNODE_DESCRIPTOR;

/*****************************************************************************
 * PCCONNECTION_DESCRIPTOR for IMiniport::GetDescription()
 *****************************************************************************
 * Description of a node connection in the topology of the filter implemented
 * by the miniport.
 */
typedef KSTOPOLOGY_CONNECTION 
PCCONNECTION_DESCRIPTOR, *PPCCONNECTION_DESCRIPTOR;

/*****************************************************************************
 * PCFILTER_DESCRIPTOR for IMiniport::GetDescription()
 *****************************************************************************
 * Description of the of the filter implemented by a miniport, including 
 * pins, nodes, connections and properties.
 *
 * The version number should be zero.
 */
typedef struct
{
    ULONG                           Version;
	const PCAUTOMATION_TABLE *      AutomationTable;
    ULONG                           PinSize;
    ULONG                           PinCount;
    const PCPIN_DESCRIPTOR *        Pins;
    ULONG                           NodeSize;
    ULONG                           NodeCount;
    const PCNODE_DESCRIPTOR *       Nodes;
    ULONG                           ConnectionCount;
    const PCCONNECTION_DESCRIPTOR * Connections;
    ULONG                           CategoryCount;
    const GUID *                    Categories;
}
PCFILTER_DESCRIPTOR, *PPCFILTER_DESCRIPTOR;

/*****************************************************************************
 * PCFILTER_NODE for IMiniport::GetTopology()
 *****************************************************************************
 * The placeholder for the FromNode or ToNode fields in connections which
 * describe connections to the filter's pins.
 */
#define PCFILTER_NODE KSFILTER_NODE

/*****************************************************************************
 * IMiniport
 *****************************************************************************
 * Interface common to all miniports.
 */
DECLARE_INTERFACE_(IMiniport,IUnknown)
{
    STDMETHOD(GetDescription)
    (   THIS_
        OUT     PPCFILTER_DESCRIPTOR *  Description
    )   PURE;

    STDMETHOD(DataRangeIntersection)
    (   THIS_
        IN      ULONG           PinId,
        IN      PKSDATARANGE    DataRange,
        IN      PKSDATARANGE    MatchingDataRange,
        IN      ULONG           OutputBufferLength,
        OUT     PVOID           ResultantFormat     OPTIONAL,
        OUT     PULONG          ResultantFormatLength
    )   PURE;
};

typedef IMiniport *PMINIPORT;

#define IMP_IMiniport\
    STDMETHODIMP GetDescription\
    (   OUT     PPCFILTER_DESCRIPTOR *  Description\
    );\
    STDMETHODIMP DataRangeIntersection\
    (   IN      ULONG           PinId,\
        IN      PKSDATARANGE    DataRange,\
        IN      PKSDATARANGE    MatchingDataRange,\
        IN      ULONG           OutputBufferLength,\
        OUT     PVOID           ResultantFormat     OPTIONAL,\
        OUT     PULONG          ResultantFormatLength\
    )

/*****************************************************************************
 * IPort
 *****************************************************************************
 * Interface common to all port lower edges.
 */
DECLARE_INTERFACE_(IPort,IUnknown)
{
    STDMETHOD(Init)
    (   THIS_
#ifdef PC_OLD_NAMES
        IN      PVOID           DeviceObject,
        IN      PVOID           Irp,
#else
        IN      PDEVICE_OBJECT  DeviceObject,
        IN      PIRP            Irp,
#endif
        IN      PUNKNOWN        UnknownMiniport,
        IN      PUNKNOWN        UnknownAdapter      OPTIONAL,
        IN      PRESOURCELIST   ResourceList
    )   PURE;

    STDMETHOD(GetDeviceProperty)
    (   THIS_
        IN      DEVICE_REGISTRY_PROPERTY    DeviceProperty,
        IN      ULONG                       BufferLength,
        OUT     PVOID                       PropertyBuffer,
        OUT     PULONG                      ResultLength
    )   PURE;

    STDMETHOD(NewRegistryKey)
    (   THIS_
        OUT     PREGISTRYKEY *      OutRegistryKey,
        IN      PUNKNOWN            OuterUnknown        OPTIONAL,
        IN      ULONG               RegistryKeyType,
        IN      ACCESS_MASK         DesiredAccess,
        IN      POBJECT_ATTRIBUTES  ObjectAttributes    OPTIONAL,
        IN      ULONG               CreateOptions       OPTIONAL,
        OUT     PULONG              Disposition         OPTIONAL
    )   PURE;
};

typedef IPort *PPORT;

#ifdef PC_IMPLEMENTATION
#define IMP_IPort\
    STDMETHODIMP Init\
    (   IN      PDEVICE_OBJECT  DeviceObject,\
        IN      PIRP            Irp,\
        IN      PUNKNOWN        UnknownMiniport,\
        IN      PUNKNOWN        UnknownAdapter      OPTIONAL,\
        IN      PRESOURCELIST   ResourceList\
    );\
    STDMETHODIMP GetDeviceProperty\
    (   IN      DEVICE_REGISTRY_PROPERTY    DeviceProperty,\
        IN      ULONG                       BufferLength,\
        OUT     PVOID                       PropertyBuffer,\
        OUT     PULONG                      ResultLength\
    );\
    STDMETHODIMP NewRegistryKey\
    (   OUT     PREGISTRYKEY *      OutRegistryKey,\
        IN      PUNKNOWN            OuterUnknown        OPTIONAL,\
        IN      ULONG               RegistryKeyType,\
        IN      ACCESS_MASK         DesiredAccess,\
        IN      POBJECT_ATTRIBUTES  ObjectAttributes    OPTIONAL,\
        IN      ULONG               CreateOptions       OPTIONAL,\
        OUT     PULONG              Disposition         OPTIONAL\
    )
#endif

/*****************************************************************************
 * IPortMidi
 *****************************************************************************
 * Interface for MIDI port lower edge.
 */