KSPROPERTY_SYNTH_PORTPARAMETERS
The KSPROPERTY_SYNTH_PORTPARAMETERS property is used to get the configuration parameters for a DirectMusic port, which is a DirectMusic term for a device that sends or receives music data. (In KS terminology, DirectMusic port does not correspond to a DMus port driver. It corresponds to a render or capture pin on a DirectMusic filter.)
Usage Summary Table
| Get | Set | Target | Property descriptor type | Property value type |
|---|---|---|---|---|
Yes |
No |
Pin |
The property descriptor (instance data) consists of a KSNODEPROPERTY structure that is immediately followed by a SYNTH_PORTPARAMS structure. Before sending the property request, the client specifies its requested parameter values by writing them into the SYNTH_PORTPARAMS structure.
The property value (operation data) is also of type SYNTH_PORTPARAMS. The miniport driver loads this structure with the parameter values that it actually uses to configure the port.
Return Value
If the miniport driver succeeds in configuring the DirectMusic port exactly as specified by the caller, it returns the STATUS_SUCCESS code. Otherwise, it returns an appropriate error code. The following table indicates some of the possible error status codes.
| Status Code | Meaning |
|---|---|
STATUS_NOT_ALL_ASSIGNED |
The operation succeeded, but the miniport driver had to modify one or more of the parameter values that the caller marked as valid in the property value. |
STATUS_UNSUCCESSFUL |
The operation did not complete successfully. |
Remarks
This is the most complicated of the DirectMusic property items to handle. Although this property supports only the get request, the get request also sets the port parameters. The port passes a SYNTH_PORTPARAMS structure as the property descriptor for the property request. A property-value buffer accompanies the property request, but because this is a get request, the buffer is only used to retrieve information from the miniport driver.
The miniport driver should first copy the SYNTH_PORTPARAMS structure from the property descriptor to the property-value buffer. Next, it should check to see if it is capable of supporting all the parameter values that the caller has requested (marked as valid). If the miniport driver is unable to support one or more of the requested parameter values, it should overwrite (in the SYNTH_PORTPARAMS structure in the property-value buffer) the requested values for these particular parameters with the values that it can support.
If the miniport driver makes no changes to the caller's SYNTH_PORTPARAMS, the caller should get back a property value that exactly matches the parameters in the property descriptor that the caller originally sent down to the miniport driver.
By convention, the driver also fills in values for parameters that do not have corresponding bits set in the dwValidParams member of SYNTH_PORTPARAMS. This allows the caller to see what default values the miniport driver used for these parameters. The miniport driver outputs the actual parameter values that it used to build the wave-interface device.
The miniport driver's KSPROPERTY_SYNTH_PORTPARAMETERS handler should be prepared to correctly handle requests for sample-rate changes.
Requirements
Header |
Dmusprop.h (include Dmusprop.h) |
See also