|
|
|
The KSPROPERTY structure describes the property and request type of a property request.
typedef struct {
GUID Set;
ULONG Id;
ULONG Flags;
} KSIDENTIFIER;
typedef KSIDENTIFIER KSPROPERTY;
| Value | Type of Property Request |
|---|---|
| KSPROPERTY_TYPE_GET | Get the current property data setting. Flags returned indicate read, write, or read/write access to the property. The queried identifier is appended to the structure as property-specific data. For multiple instance property sets, this identifies all sets as a whole, rather than any particular instance. |
| KSPROPERTY_TYPE_SET | Set the current property data setting. |
| KSPROPERTY_TYPE_SETSUPPORT | Does the driver support this property set? |
| KSPROPERTY_TYPE_BASICSUPPORT | What request types does the driver handle for this property? What is the valid data type, and what are the valid ranges for the property data? All property sets must support this flag. |
| KSPROPERTY_TYPE_DEFAULTVALUES | What are the driver's default values for the property data for this property? If default values exist, they are returned in the Basic Support information, rather than the normal range values. Default values are tagged as such by the filter when defining property range values. |
| KSPROPERTY_TYPE_RELATIONS | Specify all properties whose property data depends on the current setting of this property. Specifies that the property relations list is to be returned, or the amount of buffer room required by such a list if the return buffer is the size of a ULONG. Each element is on FILE_QUAD_ALIGNMENT, preceded by a KSMULTIPLE_ITEM structure. This is not valid when querying support of the property set in general. All property sets must support this flag. |
| KSPROPERTY_TYPE_SERIALIZESET | Serialize the property set, using the standard KSPROPERTY_SERIALHDR and KSPROPERTY_SERIAL structures. |
| KSPROPERTY_TYPE_UNSERIALIZESET | Unserialize the property set, using the standard KSPROPERTY_SERIALHDR and KSPROPERTY_SERIAL structures. |
| KSPROPERTY_TYPE_SERIALIZESIZE | Returns a ULONG specifying size of the property data when serialized as part of a KSPROPERTY_TYPE_SERIALIZESET request. A size of zero indicates that a property does not need to be serialized. |
| KSPROPERTY_TYPE_SERIALIZERAW | Specifies that the properties in this set should be serialized by the property set support handler, if one exists. If not, the call fails. The serialization format is private. This operation must be the inverse of KSPROPERTY_TYPE_UNSERIALIZERAW. |
| KSPROPERTY_TYPE_TOPOLOGY | Property passed is of type KSP_NODE, where NodeId indicates the numeric id of the topology node. Do not set this flag on its own; instead, OR it with the above. |
| KSPROPERTY_TYPE_UNSERIALIZERAW | Specifies that the buffer provided contains a group of properties belonging to this set that should be unserialized by the property set support handler, if one exists. If not, the call fails. The serialization format is private. This operation must be the inverse of KSPROPERTY_TYPE_SERIALIZERAW. |
Declared in ks.h. Include ks.h.
The size of the output buffer passed determines what data is returned from a KSPROPERTY_TYPE_BASICSUPPORT request. If the output buffer is the size of a ULONG, only the access flags are returned. If the output buffer is the size of the KSPROPERTY_DESCRIPTION structure, the structure is filled with the access flags, the inclusive size of the entire values information, the property value type information, and the number of members lists that correspond to the structure.
For a KSPROPERTY_TYPE_RELATIONS request, data returned also depends on the size of the output buffer. If the output buffer size is zero, the size required to return the related properties is returned in BytesReturned with a warning status of STATUS_BUFFER_OVERFLOW. If the buffer is the size of a KSMULTIPLE_ITEM structure, both the byte size and count of relations is returned. Otherwise, the buffer is expected to be long enough to return the KSMULTIPLE_ITEM structure and all related property identifiers, which is returned as a list of KSIDENTIFIER structures.
KSPROPERTY_TYPE_SERIALIZESET and KSPROPERTY_TYPE_UNSERIALIZESET requests allow interaction with multiple properties with a single call from the client. If the KS handler is being used to process property requests, these are broken up into multiple calls by the KsPropertyHandler function. When using this handler, the property set definition controls which properties are to be serialized.
For serialization requests, the SerializedSize member of the relevant KSPROPERTY_ITEM structure is checked for a non-zero value indicating the size in bytes of the property, where –1 is unknown and must be queried (all unknown properties begin with a KSMULTIPLE_ITEM structure that can be queried separately). To query for the total size a serialization would take, the clients passes a zero length buffer in the call to DeviceIoControl. BytesReturned then returns the size in bytes the buffer must be to serialize the set and a warning status of STATUS_BUFFER_OVERFLOW is returned. A buffer allocated that size can then be filled with the serialized data.
The format of the serialization buffer is a KSPROPERTY_SERIALHDR, followed by serialized properties. Each property that follows contains a header (KSPROPERTY_SERIAL), followed by the property data, with the start of each property on FILE_LONG_ALIGNMENT. Note that the serial header structure is defined to be on FILE_LONG_ALIGNMENT.
KSPROPERTY_TYPE_SERIALIZERAW and KSPROPERTY_TYPE_UNSERIALIZERAW are supported if a property item handler exists. The KsPropertyHandler function invokes the minidriver-provided handler. The buffer size required for serialization can also be queried by passing a zero length buffer to a serialize raw request. Because handlers are attached to property items rather than the property set, a specific item within the property set must be specified in the Property parameter. This handler may deal with multiple properties within the set.
The KSEVENT, KSMETHOD, and KSPROPERTY structures are aliases for the KSIDENTIFIER structure. As such, their definitions are identical.
See related information in KS Properties.
KSPROPERTY_ITEM, KSPROPERTY_DESCRIPTION, KSMULTIPLE_ITEM, KSIDENTIFIER, KSEVENT, KSMETHOD, KSPROPERTY_SERIALHDR, KSPROPERTY_SERIAL, KsPropertyHandler