KSPROPERTY_MIDILOOPEDSTREAMING_BUFFERプロパティは、MIDI データの転送に使用されるクロス プロセス ループ メモリ バッファーを割り当てるために使用されます。
次の表は、このプロパティの機能をまとめたものです。
使用状況の概要テーブル
| 取得 | オン | 目標 | プロパティ記述子の種類 | プロパティ値の型 |
|---|---|---|---|---|
| イエス | いいえ | ピン | KSMIDILOOPED_BUFFER_PROPERTY | KSMIDILOOPED_BUFFER |
プロパティ記述子は、KSPROPERTY と要求されたバッファー サイズを含むKSMIDILOOPED_BUFFER_PROPERTYで構成されます。 プロパティ値の型は KSMIDILOOPED_BUFFER。呼び出し元のプロセス領域にマップされたループ (循環) バッファーと、割り当てられた実際のサイズを返します。
戻り値
KSPROPERTY_MIDILOOPEDSTREAMING_BUFFER プロパティ要求は、正常に完了したことを示すSTATUS_SUCCESSを返します。 それ以外の場合、要求は適切なエラー状態コードを返します。 次の表に、考えられるエラー状態コードの一部を示します。
| 状態コード | Meaning |
|---|---|
| STATUS_ALREADY_INITIALIZED | レジスタが既に割り当てられている場合、またはKSPROPERTY_MIDILOOPEDSTREAMING_BUFFERが別のプロセスによって呼び出された場合に返されます。つまり、ループされたメモリ バッファーは既に割り当てられ、レジスタを要求するプロセスとは異なるプロセスにマップされています。 |
| STATUS_DEVICE_NOT_READY | デバイスの準備ができていない |
| STATUS_INSUFFICIENT_RESOURCES | レジスタを割り当てるためのメモリが不足している場合に返されます。 |
| STATUS_INVALID_PARAMETER | KSPROPERTY_MIDILOOPEDSTREAMING_BUFFERまたは指定されたKSMIDILOOPED_BUFFERが無効であるか、無効なバッファー サイズが要求された場合。 |
| STATUS_SUCCESS | 正常に完了したことを示します。 |
| STATUS_UNSUCCESSFUL | バッファー属性の組み合わせを指定した循環バッファーを割り当てることはできません。 |
注釈
KSPROPERTY_MIDILOOPEDSTREAMING_BUFFER は、要求されたバッファー サイズを含む KSMIDILOOPED_BUFFER_PROPERTYで呼び出されます。 呼び出し元プロセス領域にマップされた、割り当てられたバッファーと実際のバッファー サイズを含むKSMIDILOOPED_BUFFERが返されます。
バッファーは、読み取りと書き込みの操作を簡略化するためにダブル マップされます。 物理メモリは、仮想アドレス空間に 2 回マップされ、戻って戻ります。 ダブル マッピングを使用すると、プライマリ バッファーの末尾を超えて最大 1 つのバッファー サイズを読み取りまたは書き込みできます。 これらの操作は、プライマリ バッファーの先頭にマップされているのと同じ物理メモリに自動的にループ バックします。 これにより、アドレス計算を実行する必要がなくなります。
MIDI メッセージは一度に 1 つずつバッファーに読み取りまたは書き込まれるため、適用される最大単一メッセージ サイズは UMP128 (16 バイト) です。 プライマリ バッファーの末尾からダブル マップバッファーへの最大読み取りまたは書き込みは 16 バイトで、マッピングのサイズより小さくなります。
バッファー転送メカニズムは、リーダーとライターの共有ライブラリ実装を使用して、MIDI サービスとクライアント アプリケーション間でメッセージを移動するためにも使用されます。
MIDI バージョン 1 ドライバーと他の多くの KS/ACX ドライバーと同じ要件である、一度に開くことができるピン ハンドルは 1 つだけです。 共有メモリ バッファーを割り当てることができるのは、開いているピンを保持するプロセスだけです。
オーディオ ドライバーは、共有メモリ バッファーを割り当てて制御します。 割り当ては、意図しないカーネル メモリの露出を防ぐために、ページ境界で実行されます。 ピン ハンドルが閉じているか、呼び出し元のプロセスが終了すると、ワーカー スレッドがシャットダウンされ、割り当てられたバッファーがドライバーによって解放されます。
サンプル コード
_Use_decl_annotations_
HRESULT
KSMidiDevice::ConfigureLoopedBuffer(ULONG& bufferSize
)
{
KSMIDILOOPED_BUFFER_PROPERTY property {0};
KSMIDILOOPED_BUFFER buffer{0};
ULONG propertySize {sizeof(property)};
property.Property.Set = KSPROPSETID_MidiLoopedStreaming;
property.Property.Id = KSPROPERTY_MIDILOOPEDSTREAMING_BUFFER;
property.Property.Flags = KSPROPERTY_TYPE_GET;
property.RequestedBufferSize = bufferSize;
RETURN_IF_FAILED(SyncIoctl(
m_Pin.get(),
IOCTL_KS_PROPERTY,
&property,
propertySize,
&buffer,
sizeof(buffer),
nullptr));
m_MidiPipe->Data.BufferAddress = (PBYTE) buffer.BufferAddress;
bufferSize = m_MidiPipe->Data.BufferSize = buffer.ActualBufferSize;
return S_OK;
}
Requirements
| Item | Description |
|---|---|
| バージョン | Windows 11 バージョン 25H2 以降で使用できます。 |
| Header | Ksmedia.h |