KSPROPSETID_Synth_Dls

KSPROPSETID_Synth_Dls 属性集包含用于将 DLS 样本和仪器下载到 MIDI 合成器的各个属性。 这些是 DirectMusic 筛选器的 DirectMusic 引脚上的合成器节点 (KSNODETYPE_SYNTHESIZER) 的属性（请参阅 MIDI 和 DirectMusic 筛选器）。

本部分介绍这些属性的行为，包括如何下载和卸载包含 DLS 数据的内存的“区块”。 下载的仪器和波形数据区块的实际格式在 Microsoft Windows SDK 文档中的低级别 DLS 讨论中指定。

DLS 下载和卸载可以在引脚存在期间随时发生。 与 DirectMusic 事件不同，它们不会加时间戳，应尽快处理。

在本部分中，术语“DLS 资源”或仅仅是“资源”是指 DLS 仪器区块或 DLS 波形块。 系统正确维护所有 DLS 资源的引用计数：

• 当客户端卸载引用波形的最后一个仪器时，系统将自动生成一个调用来卸载波。

• 相反，系统会延迟调用以卸载波形，直到客户端卸载引用波形的最后一个仪器。

此集中的属性项由 KSPROPERTY_SYNTH_DLS 枚举值指定，如标头文件 Dmusprop.h 中定义。

使用情况摘要表

KSPROPERTY_SYNTH_DLS_APPEND 属性指定客户端附加到其下载到合成器的每个缓冲区中的 DLS 数据的保留存储空间量。

获取	设置	目标	属性描述符类型	属性值类型
是	否	固定	KSNODEPROPERTY	ULONG

属性值（操作数据）的类型为 ULONG，并指定微型端口驱动程序在每个下载的 DLS 数据缓冲区末尾为供自己使用而保留的字节数。 然后，客户端分配每个下载缓冲区，使其足够大，以便在下载数据结束后包含请求的字节数。

返回值

KSPROPERTY_SYNTH_DLS_APPEND 属性请求返回 STATUS_SUCCESS，以指示已成功完成。 否则，请求将返回适当的错误状态代码。 下表显示了一些可能的错误代码。

状态代码	含义
STATUS_UNSUCCESSFUL	操作未成功完成。

这些额外的字节用于需要额外填充以满足对齐要求的驱动程序，或者用于复制样本的开始，以简化样本插值。

使用情况摘要表

KSPROPERTY_SYNTH_DLS_COMPACT 属性是要求合成器提供最大可用样本内存区块的请求。

获取	设置	目标	属性描述符类型	属性值类型
否	是	固定	KSNODEPROPERTY	无

没有与此属性关联的属性值（操作数据）。

返回值

KSPROPERTY_SYNTH_DLS_COMPACT 属性请求返回 STATUS_SUCCESS，以指示已成功完成。 否则，请求将返回适当的错误状态代码。 下表显示了一些可能的错误代码。

状态代码	含义
STATUS_UNSUCCESSFUL	操作未成功完成。

此属性的处理程序的实现不应中断播放。

有关详细信息，请参阅 Microsoft Windows SDK 文档中 IDirectMusicPort::Compact 方法的说明。

使用情况摘要表

KSPROPERTY_SYNTH_DLS_DOWNLOAD 属性用于将 DLS 数据下载到合成器。

获取	设置	目标	属性描述符类型	属性值类型
是	否	固定	KSNODEPROPERTY + SYNTH_BUFFER	SYNTHDOWNLOAD

属性描述符（实例数据）由 KSNODEPROPERTY 结构组成，紧接着是 SYNTH_BUFFER 结构，该结构指定正在下载的 DLS 数据缓冲区的位置和大小。

属性值（操作数据）是 SYNTHDOWNLOAD 结构。 微型端口驱动程序会传回此结构中的以下信息：

• 微型端口驱动程序生成的句柄，用于唯一标识下载的 DLS 数据。 此客户端保存此句柄，并在以后使用它来卸载数据（请参阅 KSPROPERTY_SYNTH_DLS_UNLOAD）。

• 一个布尔值，指示客户端是否可以在属性请求完成后释放包含 DLS 数据的缓冲区。 如果微型端口驱动程序已创建自己的 DLS 数据副本，则客户端可以释放缓冲区。 否则，如果微型端口驱动程序继续使用客户端的原始 DLS 数据缓冲区，则在微型端口驱动程序卸载 DLS 数据之前，客户端都不能释放缓冲区。

返回值

KSPROPERTY_SYNTH_DLS_DOWNLOAD 属性请求返回 STATUS_SUCCESS，以指示已成功完成。 否则，请求将返回适当的错误状态代码。 下表显示了一些可能的错误代码。

状态代码	含义
STATUS_BUFFER_TOO_SMALL	缓冲区太小，无法完成操作。
STATUS_UNSUCCESSFUL	操作未成功完成。
STATUS_NO_MEMORY	没有内存可用于完成此请求。

有关详细信息，请参阅 Microsoft Windows SDK 文档中 IDirectMusicPort::DownloadInstrument 方法的说明。

示例

KSPROPERTY_SYNTH_DLS_DOWNLOAD 属性请求使用用户内存地址指定 DLS 下载数据的位置。 微型端口驱动程序在尝试访问 DLLS 数据之前探测并锁定包含 DLS 数据的用户内存。 以下示例代码显示如何执行此操作：

  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;
  }

使用情况摘要表

KSPROPERTY_SYNTH_DLS_UNLOAD 属性卸载以前下载的 DLS 数据资源。

获取	设置	目标	属性描述符类型	属性值类型
否	是	固定	KSNODEPROPERTY	HANDLE

属性值（操作数据）的类型为 HANDLE，包含要释放的已下载 DLS 数据资源的句柄。 这是微型端口驱动程序生成的用于标识之前 KSPROPERTY_SYNTH_DLS_DOWNLOADget 属性请求中的 DLS 数据的句柄。

返回值

KSPROPERTY_SYNTH_DLS_UNLOAD 属性请求返回 STATUS_SUCCESS，以指示已成功完成。 否则，请求将返回适当的错误状态代码。 下表显示了一些可能的错误代码。

状态代码	含义
STATUS_BUFFER_TOO_SMALL	缓冲区太小，无法完成操作。
STATUS_UNSUCCESSFUL	操作未成功完成。
STATUS_PENDING	此操作将在稍后完成。

在没有使用 DLS 数据的音符播放时，微型端口驱动程序会立即卸载 DLS 数据。 如果合成器在 KSPROPERTY_SYNTH_DLS_UNLOAD set 属性请求时无法释放与 DLS 数据资源关联的内存，则它可以使用异步属性完成来在稍后完成请求。

如果在卸载 DLS 数据资源后，合成器收到使用该资源的便笺事件，则微型端口驱动程序会忽略该事件，除非在此期间下载了新的 DLS 数据源。

有关详细信息，请参阅 Microsoft Windows SDK 文档中 IDirectMusicPort::UnloadInstrument 方法的讨论。

使用情况摘要表

KSPROPERTY_SYNTH_DLS_WAVEFORMAT 属性用于查询合成器的输出波形格式。

获取	设置	目标	属性描述符类型	属性值类型
是	否	固定	KSNODEPROPERTY	WAVEFORMATEX

属性值（操作数据）的类型为 WAVEFORMATEX，并指定合成器输出流的波形格式。

返回值

KSPROPERTY_SYNTH_DLS_WAVEFORMAT 属性请求返回 STATUS_SUCCESS，以指示已成功完成。 否则，请求将返回适当的错误状态代码。 下表显示了一些可能的错误代码。

状态代码	含义
STATUS_BUFFER_TOO_SMALL	缓冲区太小，无法完成操作。

sizeof(WAVEFORMATEX) 字节的属性值缓冲区可能不足以容纳所有波形格式。 例如，多通道格式需要一个大小为 (WAVEFORMATEXTENSIBLE) 字节的缓冲区。 如果属性请求返回状态代码 STATUS_BUFFER_TOO_SMALL，客户端会检查微型端口驱动程序输出的属性值大小，分配更大的缓冲区，然后提交第二个请求。

有关详细信息，请参阅 Microsoft Windows SDK 文档中 IDirectMusicPort::GetFormat 方法的说明。