KSPROPSETID_Synth_Dls

屬性 KSPROPSETID_Synth_Dls 集包含用來將 DLS 範例和檢測下載至 MIDI 合成器的屬性。 這些是 DirectMusic 篩選 (DirectMusic 針腳上的 synth-節點 (KSNODETYPE_SYNTHESIZER) 的屬性，請參閱 MIDI 和 DirectMusic Filters) 。

本節說明這些屬性的行為，這些屬性如何下載和卸載包含 DLS 資料的記憶體「區塊」。 下載的檢測和波浪資料區塊的實際格式是在Microsoft Windows SDK檔中的低階 DLS 討論中指定。

DLS 下載和卸載會在針腳存在期間隨時發生。 不同于 DirectMusic 事件，它們不是時間戳記，應該儘快處理。

在本節中，DLS 資源或只是資源一詞是指 DLS 檢測區塊或 DLS 波浪區塊。 系統會正確維護所有 DLS 資源的參考計數：

• 當用戶端卸載最後一個參考波的檢測時，系統會自動產生呼叫以卸載波段。

• 相反地，系統會延遲呼叫以卸載波段，直到用戶端卸載最後一個參考波的檢測為止。

這個集合中的屬性專案是由KSPROPERTY_SYNTH_DLS列舉值所指定，如標頭檔 Dmusprop.h 中所定義。

使用量摘要資料表

KSPROPERTY_SYNTH_DLS_APPEND 屬性會指定用戶端附加至其下載至合成器之每個緩衝區中 DLS 資料的保留儲存空間數量。

Get	集合	目標	屬性描述項類型	屬性值類型
是	否	Pin	KSNODEPROPERTY	ULONG

(作業資料) 屬性值為 ULONG 類型，並指定迷你埠驅動程式在每個下載的 DLS 資料緩衝區結束時，必須保留供自己使用的位元組數目。 然後，用戶端會配置每個下載緩衝區，以足以在下載的資料結束時包含要求的位元組數目。

傳回值

KSPROPERTY_SYNTH_DLS_APPEND屬性要求會傳回STATUS_SUCCESS，表示它已順利完成。 否則，要求會傳回適當的錯誤狀態碼。 下表顯示一些可能的錯誤碼。

狀態碼	意義
STATUS_UNSUCCESSFUL	作業未順利完成。

這些額外的位元組適用于需要額外填補的驅動程式，以符合對齊需求或複寫樣本的開頭，以簡化樣本插補。

使用量摘要資料表

KSPROPERTY_SYNTH_DLS_COMPACT屬性是合成器的要求，可讓可用的最大可用樣本記憶體區塊。

Get	集合	目標	屬性描述項類型	屬性值類型
否	是	Pin	KSNODEPROPERTY	無

) 與此屬性相關聯的作業資料 (屬性值。

傳回值

KSPROPERTY_SYNTH_DLS_COMPACT屬性要求會傳回STATUS_SUCCESS，表示它已順利完成。 否則，要求會傳回適當的錯誤狀態碼。 下表顯示一些可能的錯誤碼。

狀態碼	意義
STATUS_UNSUCCESSFUL	作業未順利完成。

這個屬性的處理常式實作不應該中斷播放。

如需詳細資訊，請參閱Microsoft Windows SDK檔中的 IDirectMusicPort：：Compact方法描述。

使用量摘要資料表

KSPROPERTY_SYNTH_DLS_DOWNLOAD 屬性可用來將 DLS 資料下載至合成器。

Get	集合	目標	屬性描述項類型	屬性值類型
是	否	Pin	KSNODEPROPERTY + SYNTH_BUFFER	SYNTHDOWNLOAD

屬性描述項 (實例資料) 是由緊接在SYNTH_BUFFER結構之後的 KSNODEPROPERTY 結構所組成，該結構會指定要下載之 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：:D ownloadInstrument方法的討論。

範例

KSPROPERTY_SYNTH_DLS_DOWNLOAD屬性要求會指定 DLS 下載資料與使用者記憶體位址的位置。 迷你埠驅動程式應該先探查並鎖定包含 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 資料資源。

Get	集合	目標	屬性描述元類型	屬性值類型
否	是	Pin	KSNODEPROPERTY	HANDLE

(作業資料) 屬性值為 HANDLE 類型，並包含要釋放的下載 DLS 資料資源的控制碼。 這是迷你埠驅動程式在先前 KSPROPERTY_SYNTH_DLS_DOWNLOADget-property 要求中識別 DLS 資料的控制碼。

傳回值

KSPROPERTY_SYNTH_DLS_UNLOAD屬性要求會傳回STATUS_SUCCESS，表示它已順利完成。 否則，要求會傳回適當的錯誤狀態碼。 下表顯示一些可能的錯誤碼。

狀態碼	意義
STATUS_BUFFER_TOO_SMALL	緩衝區太小而無法完成作業。
STATUS_UNSUCCESSFUL	作業未順利完成。
STATUS_PENDING	作業將在稍後完成。

迷你埠驅動程式應該會在沒有使用 DLS 資料的筆記播放時立即卸載 DLS 資料。 如果合成器無法在KSPROPERTY_SYNTH_DLS_UNLOAD set-property 要求時釋放與 DLS 資料資源相關聯的記憶體，則可以使用非同步屬性完成，稍後完成要求。

如果在卸載 DLS 資料資源之後，合成器會收到使用資源的附注事件，除非在過渡期間下載新的 DLS 資料資源，否則迷你埠驅動程式應該忽略事件。

如需詳細資訊，請參閱Microsoft Windows SDK檔中的IDirectMusicPort：：UnloadInstrument方法的討論。

使用量摘要表格

KSPROPERTY_SYNTH_DLS_WAVEFORMAT 屬性可用來查詢合成器是否有其輸出波格式。

Get	集合	目標	屬性描述元類型	屬性值類型
是	否	Pin	KSNODEPROPERTY	波擷取

作業資料 (屬性值) 類型為 WAVEATEX，並指定合成器輸出資料流程的波浪格式。

傳回值

KSPROPERTY_SYNTH_DLS_WAVEFORMAT屬性要求會傳回STATUS_SUCCESS，表示它已順利完成。 否則，要求會傳回適當的錯誤狀態碼。 下表顯示一些可能的錯誤碼。

狀態碼	意義
STATUS_BUFFER_TOO_SMALL	緩衝區太小而無法完成作業。

sizeof (WAVEATEX) 位元組的屬性值緩衝區可能不足以容納所有波浪格式。 例如，多重通道格式需要sizeof (其 SIZEof) BYTESATEXTENSIBLE) 位元組。 如果屬性要求傳回STATUS_BUFFER_TOO_SMALL的狀態碼，用戶端可以檢查迷你埠驅動程式輸出的屬性值大小、配置較大的緩衝區，然後提交第二個要求。

如需詳細資訊，請參閱Microsoft Windows SDK檔中的IDirectMusicPort：：GetFormat方法描述。