KSPROPERTY_SYNTH_DLS_DOWNLOAD

The KSPROPERTY_SYNTH_DLS_DOWNLOAD property is used to perform DLS downloads to the synthesizer.

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.

Headers

Declared in dmusprop.h. Include dmusprop.h.

Comments

For more information, see the discussion of the IDirectMusicPort::DownloadInstrument method in the Platform 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;
  }

See Also

KSNODEPROPERTY, SYNTH_BUFFER, SYNTHDOWNLOAD, KSPROPERTY_SYNTH_DLS_UNLOAD, IDirectMusicSynth::Download