このページでは、LampArray コールバックを登録し、ILampArray および ILampInfo インスタンスと対話する方法について説明します。
注意
March 2023 リカバリの時点では、GDK Lighting API はコンソールで次のデバイスのみをサポートしています。 今後のリカバリ リリースでは、追加のデバイスのサポートが追加される予定です。
- Xbox One 用 Razer Turret (キーボードとマウス)
- Razer BlackWidow Tournament Edition Chroma V2
ILampArray と ILampInfo
システムに接続された互換性のある各照明デバイスは、ILampArray インスタンスによって表されます。
ILampArray は、寸法、デバイスの種類、製造元、ランプの数など、デバイスに関する情報を提供します。 また、ランプの明るさと色の値を変更するメソッドも公開します。
ILampInfo オブジェクトは、ランプの相対位置、色のサポート、目的など、LampArray 内の個々のランプのプロパティをカプセル化します。
ILampInfoンスタンスは、ILampArray::GetLampInfo を使用して取得できます。
グラフィックス、オーディオ、GameInput API と同様に、ILampArray と ILampInfo は、IUnknown から派生するインターフェイスを公開している場合でも、真の COM API ではありません。 このスタイルの API は、"COM lite" または "nano-COM" と呼ばれることもあります。IUnknown は参照カウントとリフレクションに使用されますが、COM ランタイム インフラストラクチャは ILampArray または ILampInfoでは使用されません。 具体的には、次のことを意味します。
- アプリケーションは、オブジェクトのインスタンスを取得するために
CoInitializeもCoCreateInstanceも呼び出すことはありません。 - 集約や呼び出し元提供のインターフェイスの実装などの COM 機能はサポートされません。
- プロセスの境界を越えたマーシャリングはサポートされず、またアパートメント/スレッド モデルはありません。 すべてのオブジェクトはアジャイルです。
-
IUnknownを介さずにインターフェイス ポインターのオブジェクト ID を直接比較できます。 - メソッドでは
HRESULTコードを返す必要はありません。多くの場合、これによって関数シグネチャが単純になります。
LampArray コールバック
LampArray コールバックは、ILampArray インスタンスを取得し、LampArrays がシステムにアタッチまたは削除されたときに通知を受け取るためのメカニズムです。
RegisterLampArrayStatusCallback
注意
LampArray コールバックに RegisterLampArrayCallback ではなく、RegisterLampArrayStatusCallback 関数を使用します。
enum class LampArrayEnumerationKind : uint32_t
{
Async = 1,
Blocking = 2
};
enum class LampArrayStatus : uint32_t
{
None = 0x00000000,
Connected = 0x00000001,
Available = 0x00000002
};
DEFINE_ENUM_FLAG_OPERATORS(LampArrayStatus);
typedef interface ILampArray ILampArray;
typedef uint64_t LampArrayCallbackToken;
typedef void (CALLBACK * LampArrayStatusCallback)(
_In_opt_ void * context,
LampArrayStatus currentStatus,
LampArrayStatus previousStatus,
_In_ ILampArray * lampArray);
STDAPI RegisterLampArrayStatusCallback(
_In_ LampArrayStatusCallback callbackFunc,
LampArrayEnumerationKind enumerationKind,
_In_opt_ void * context,
_Out_ _Result_zeroonfailure_ LampArrayCallbackToken * callbackToken);
コールバックのスレッド
LampArrayStatusCallback が LampArrayEnumerationKind::Blocking に登録された時点で LampArray デバイスがアタッチされている場合、RegisterLampArrayStatusCallback 関数は、アタッチされたデバイスごとにコールバックが呼び出されるまでブロックされます (つまり、コールバックは呼び出し元のスレッドで呼び出されます)。
最初のコールバックが登録されると、LampArray API はワーカー スレッドを開始して、ILampArray デバイスのアタッチと削除の通知を処理します。 これらのイベントは頻度が低く、それ以外の場合、ワーカー スレッドは待機状態のままです。 登録呼び出しが返されると、後続のすべての LampArrayStatusCallbacks がこのワーカー スレッドで順番に呼び出されます。
LampArrayStatusCallback が LampArrayEnumerationKind::Async に登録された時点で接続されたデバイスもワーカー スレッドで処理されます。
LampArray ワーカー スレッドのプロセッサ アフィニティは、TrySetLampArrayWorkerThreadAffinityMask を使用して制御できます。 この API は、プロセスごとに最大 1 回呼び出すことができます。 API への後続の呼び出しは有効になりません。
HRESULT TrySetLampArrayWorkerThreadAffinityMask(
uint64_t threadAffinityMask);
コールバックの登録解除
コールバックが正常に登録されたら、アプリケーションでは、コールバックの実行に必要なすべてのリソースが有効な状態を維持することを保証する必要があります。 これには、コールバックのコードによって使用されるリソースと、コールバック関数自体によって使用されるリソース (たとえば、アプリケーションがオンデマンドでロード/アンロードする DLL でコールバック関数がホストされている場合) の両方が含まれます。
これらのリソースを安全に再利用するには、アプリケーションはまず、RegisterLampArrayStatusCallback メソッドから受け取ったトークンを UnregisterLampArrayCallback メソッドに渡すことによって、コールバックを登録解除する必要があります。 登録されている LampArray コールバック内から LampArray コールバックの登録を解除することはサポートされていません。登録を試みると、プロセスが終了します。
bool UnregisterLampArrayCallback(
LampArrayCallbackToken callbackToken,
uint64_t timeoutInMicroseconds);