KSPROPERTY_SYNTH_DLS_DOWNLOAD
The KSPROPERTY_SYNTH_DLS_DOWNLOAD property is used to download DLS data to the synthesizer.
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_BUFFER structure, which specifies the location and size of the DLS data buffer that is being downloaded.
The property value (operation data) is a SYNTHDOWNLOAD structure. The miniport driver passes back the following information in this structure:
A handle that the miniport driver generates to uniquely identify the downloaded DLS data. This client should save this handle and use it later to unload the data (see KSPROPERTY_SYNTH_DLS_UNLOAD).
A Boolean value that indicates whether the client can free the buffer containing the DLS data after the property request completes. If the miniport driver has made its own copy of the DLS data, the client can free the buffer. Otherwise, if the miniport driver continues to use the client's original DLS data buffer, the client should not free the buffer until the miniport driver unloads the DLS data.
Return Value
A KSPROPERTY_SYNTH_DLS_DOWNLOAD property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate error status code. The following table shows some of the possible error codes.
| Status Code | Meaning |
|---|---|
STATUS_BUFFER_TOO_SMALL |
The buffer was too small to complete the operation. |
STATUS_UNSUCCESSFUL |
The operation did not complete successfully. |
STATUS_NO_MEMORY |
No memory is available to complete this request. |
Remarks
For more information, see the discussion of the IDirectMusicPort::DownloadInstrument method in the Microsoft Windows SDK documentation.
Example
The KSPROPERTY_SYNTH_DLS_DOWNLOAD property request specifies the location of the DLS download data with a user memory address. The miniport driver should probe and lock the user memory containing the DLS data before attempting to access it. The following example code shows how to do this:
NTSTATUS Status = STATUS_UNSUCCESSFUL;
PSYNTH_BUFFER pDlsBuffer = (PSYNTH_BUFFER)pRequest->Instance;
PMDL pMdl = IoAllocateMdl(pDlsBuffer->BufferAddress, pDlsBuffer->BufferSize,
FALSE, FALSE, NULL);
if (pMdl)
{
__try
{
MmProbeAndLockPages(pMdl, KernelMode, IoReadAccess);
PVOID pvUserData = MmGetSystemAddressForMdlSafe(pMdl, NormalPagePriority);
// do something with the data here
}
__except (EXCEPTION_EXECUTE_HANDLER)
{
Status = GetExceptionCode();
}
MmUnlockPages(pMdl);
IoFreeMdl(pMdl);
}
else
{
Status = STATUS_NO_MEMORY;
}
Requirements
Header |
Dmusprop.h (include Dmusprop.h) |
See also