Microsoft DirectX 8.0 |
The IKsPropertySet interface was originally designed as an efficient way to set and retrieve device properties on WDM drivers, using KSProxy to translate the user-mode COM method calls into kernel-mode "property sets" used by WDM streaming class drivers. This interface is now also used to pass information strictly between software components. In some cases, software components must implement this interface. For example, if you are writing a software MPEG-2 decoder for use with the Microsoft® DVD Navigator, you must implement this interface and also support the DVD-related property sets that the Navigator will send to the decoder using the IKsPropertySet::Get and IKsPropertySet::Set methods. Pins may support this interface in order to allow other pins or filters to set or retrieve its properties.
Methods in Vtable Order
IUnknown methods Description QueryInterface Returns pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IKsPropertySet methods Description Set Sets a property identified by a property set GUID and a property ID. Get Retrieves a property identified by a property set GUID and a property ID. QuerySupported Determines whether an object supports a specified property set.
Retrieves a property identified by a property set GUID and a property ID.
Syntax
HRESULT Get(
REFGUID guidPropSet,
DWORD dwPropID,
LPVOID pInstanceData,
DWORD cbInstanceData,
LPVOID pPropData,
DWORD cbPropData,
DWORD *pcbReturned
);
Parameters
- guidPropSet
- [in] Property set GUID.
- dwPropID
- [in] Identifier of the property within the property set.
- pInstanceData
- [out, size_is(cbInstanceData)] Pointer to instance data for the property.
- cbInstanceData
- [in] Number of bytes in the buffer to which pInstanceData points.
- pPropData
- [out, size_is(cbPropData)] Pointer to the retrieved buffer, which contains the value of the property.
- cbPropData
- [in] Number of bytes in the buffer to which pPropData points.
- pcbReturned
- [out] Pointer to the number of bytes returned in the buffer to which pPropData points.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
The current Microsoft® DirectShow® implementation returns E_PROP_SET_UNSUPPORTED if the property set is not supported or E_PROP_ID_UNSUPPORTED if the property ID is not supported for the specified property set.
Remarks
To retrieve a property, allocate a buffer which this method will then fill in. To determine the necessary buffer size, specify NULL for pPropData and zero (0) for cbPropData. This method returns the necessary buffer size in pcbReturned.
Determines whether an object supports a specified property set.
Syntax
HRESULT QuerySupported(
REFGUID guidPropSet,
DWORD dwPropID,
DWORD *pTypeSupport
);
Parameters
- guidPropSet
- [in] Property set GUID.
- dwPropID
- [in] Identifier of the property within the property set.
- pTypeSupport
- [out] Pointer to a value in which to store flags indicating the support provided by the driver. Supported flags include the following:
KSPROPERTY_SUPPORT_GET You can retrieve the property by calling the IKsPropertySet::Get method. KSPROPERTY_SUPPORT_SET You can change the property by calling IKsPropertySet::Set.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
The return values for the current DirectShow implementation include the following:
E_NOTIMPL Property set is not supported. E_PROP_ID_UNSUPPORTED Property ID is not supported for the specified property set. E_PROP_SET_UNSUPPORTED Property set is not supported. S_OK Specified property set and property ID combination is supported.
Sets a property identified by a property set GUID and a property ID.
Syntax
HRESULT Set(
REFGUID guidPropSet,
DWORD dwPropID,
LPVOID pInstanceData,
DWORD cbInstanceData,
LPVOID pPropData,
DWORD cbPropData
);
Parameters
- guidPropSet
- [in] Property set GUID.
- dwPropID
- [in] Identifier of the property within the property set.
- pInstanceData
- [out, size_is(cbInstanceData)] Pointer to instance data for the property.
- cbInstanceData
- [in] Number of bytes in the buffer to which pInstanceData points.
- pPropData
- [out, size_is(cbPropData)] Pointer to the retrieved buffer, which contains the value of the property.
- cbPropData
- [in] Number of bytes in the buffer to which pPropData points.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
The current DirectShow implementation returns E_PROP_SET_UNSUPPORTED if the property set is not supported or E_PROP_ID_UNSUPPORTED if the property ID is not supported for the specified property set.