KSPROPERTY_SYNTH_DLS_DOWNLOAD

The KSPROPERTY_SYNTH_DLS_DOWNLOAD property is used to download DLS data to the synthesizer.

Usage Summary Table

GetSetTargetProperty descriptor typeProperty value type

Yes

No

Pin

KSNODEPROPERTY + SYNTH_BUFFER

SYNTHDOWNLOAD

 

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 CodeMeaning

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

KSNODEPROPERTY
SYNTH_BUFFER
SYNTHDOWNLOAD
KSPROPERTY_SYNTH_DLS_UNLOAD
IDirectMusicSynth::Download

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft