TrickPalace
  1. http://www.trickpalace.net/
  2. windows/
  3. logicool/
  4. lcdsdk/
  5. reference/
  6. lglcd.htm

logitech/logicool LCDSDK

lglcd.h - reference

contents

関数

lgLcdInit()

lgLcdInit() 関数は Logitech/Logicool LCD ライブラリを初期化します。必ず LCD ライブラリの他の関数よりも先に呼び出す必要があります。

DWORD WINAPI lgLcdInit(void);

引数

ありません。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
RPC_S_SERVER_UNAVAILABLELogitech/Logicool LCD サブシステムは利用可能ではありません。(このケースではシステムにソフトウェアがインストールされていません。)
ERROR_OLD_WIN_VERSIONWindows 9x で初期化を試みました。このライブラリは Windows 2000 以降のみで動作します。
ERROR_NO_SYSTEM_RESOURCESシステムリソースが不十分。
ERROR_ALREADY_INITIALIZED以前に lgLcdInit() が呼び出されています。

解説

lgLcdInit() を実行する前にこのライブラリの他の関数を呼び出すことはできません。 戻り値が RPC_S_SERVER_UNAVAILABLE, ERROR_OLD_WIN_VERSION そして ERROR_NO_SYSTEM_RESOURCES の場合、呼び出し元のアプリケーションは稼働中のマシンでは LCD 出力の準備できていない(この為、LCD に関連した機能は無効です)とみなすことができます。

参照

lgLcdDeInit()

lgLcdDeInit()

lgLcdInit() で割り当てた全てのリソースを解放する為にこのライブラリを使い終わった後で lgLcdDeInit() を使います。

DWORD WINAPI lgLcdDeInit(void);

引数

ありません。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗することはありません。

解説

このライブラリを使用中に割り当てられた全てのリソースはこの関数を呼び出すことで開放されます。この関数を呼び出した後では、lgLcdInit() を除いてこのライブラリの関数を呼び出すことは許されません。

参照

lgLcdInit()

lgLcdConnect()

LCD monitor プロセスとの接続(connection)を確立する為に lgLcdConnect() を使います。 この接続は他の多くの関数が LCD を探し、開き、LCD と通信する為に必要です。

DWORD WINAPI lgLcdConnect(IN OUT lgLcdConnectContext *ctx);

引数

引数名説明
ctx IN OUT lgLcdConnectContext * 確立したい接続についての全ての関連情報を含んだ構造体のポインタ。  この関数は呼び出すには connection メンバーを除く全てのフィールドを埋める必要があります。 関数呼び出しから返ると connection メンバーが設定されます。詳しくは lgLcdConnectContext を参照のこと。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_SERVICE_NOT_ACTIVElgLcdInit() がまだ呼び出されていません。
ERROR_INVALID_PARAMETERctx もしくは ctx->appFriendlyName が NULL です。
ERROR_FILE_NOT_FOUNDこのシステムで LCDMon が起動していません。
ERROR_ALREADY_EXISTS同じクライアントから既に接続されています。
RPC_X_WRONG_PIPE_VERSIONLCDMon がこのプロトコルを理解できません。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

アプリケーションが LCD デバイスを使い始めるには接続を確立する必要があります。 lgLcdConnect() は接続の確立を試みます。 ( LCD Monitor が起動していないあるいはインストールされていない(ユーザが異なるキーボードを使用中)などの理由により )もし LCD Monitor プロセスが稼働していないなら接続の試みは失敗するでしょう。 この場合、あなたのアプリケーションは LCD のサポートなしで稼働することを考慮するべきです。

この関数には lgLcdConnectContext 内の文字列部分が ANSI および UNICODE のバージョンが存在します。 ヘッダファイル(lglcd.h)は UNICODE マクロが定義されいるかどうかによって適切なバージョンを選択します。

参照

lgLcdConnectEx(), lgLcdDisconnect(), lgLcdEnumerate(), lgLcdOpen()

lgLcdConnectEx()

LCD monitor プロセスとの接続(connection)を確立する為に lgLcdConnectEx() を使います。 この接続は他の多くの関数が LCD を探し、開き、LCD と通信する為に必要です。

DWORD WINAPI lgLcdConnectEx(IN OUT lgLcdConnectContextEx *ctx);

引数

引数名説明
ctx IN OUT lgLcdConnectContextEx * 確立したい接続についての全ての関連情報を含んだ構造体のポインタ。  この関数は呼び出すには connection メンバーを除く全てのフィールドを埋める必要があります。 関数呼び出しから返ると connection メンバーが設定されます。詳しくは lgLcdConnectContextEx を参照のこと。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_SERVICE_NOT_ACTIVElgLcdInit() がまだ呼び出されていません。
ERROR_INVALID_PARAMETERctx もしくは ctx->appFriendlyName が NULL です。
ERROR_FILE_NOT_FOUNDこのシステムで LCDMon が起動していません。
ERROR_ALREADY_EXISTS同じクライアントから既に接続されています。
RPC_X_WRONG_PIPE_VERSIONLCDMon がこのプロトコルを理解できません。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

アプリケーションが LCD デバイスを使い始めるには接続を確立する必要があります。 lgLcdConnectEx() は接続の確立を試みます。 ( LCD Monitor が起動していないあるいはインストールされていない(ユーザが異なるキーボードを使用中)などの理由により )もし LCD Monitor プロセスが稼働していないなら接続の試みは失敗するでしょう。 この場合、あなたのアプリケーションは LCD のサポートなしで稼働することを考慮するべきです。

この関数には lgLcdConnectContext 内の文字列部分が ANSI および UNICODE のバージョンが存在します。 ヘッダファイル(lglcd.h)は UNICODE マクロが定義されいるかどうかによって適切なバージョンを選択します。

参照

lgLcdConnect(), lgLcdDisconnect(), lgLcdEnumerate(), lgLcdEnumerateEx(), lgLcdOpen()

lgLcdDisconnect()

LCD monitor プロセスとの接続(connection)を閉じるのに lgLcdDisconnect() を使います。

DWORD WINAPI lgLcdDisconnect(int connection);

引数

引数名説明
connectionint以前の lgLcdConnect() あるいは lgLcdConnectEx() の成功した呼び出しによって返された接続ハンドルを示します。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_SERVICE_NOT_ACTIVElgLcdInit() がまだ呼び出されていません。
ERROR_INVALID_PARAMETER指定された接続ハンドルは存在しません。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

接続の終了は接続によって開かれた全てのデバイスを無効にします。 接続の終了した後に無効となったハンドルを使用して lgLcdUpdateBitmap(), lgLcdReadSoftButtons() 及び lgLcdClose() を呼び出すとエラーを引き起こします。

加えて、lgLcdConnect() でコールバック関数を登録していた場合、それが呼び出されることはなくなります。

参照

lgLcdConnect(), lgLcdConnectEx()

lgLcdSetDeviceFamiliesToUse()

lgLcdSetDeviceFamiliestoUse() 関数はアプレットが使用する可能性のあるデバイスタイプ(ファミリー)を LCDManager に知らせるのに使用されます。 この呼び出しの後、以後全ての lgLcdEnumerate() もしくは lgLcdEnumerateEx() の呼び出しは要求したファミリーのデバイスのみを返します。

DWORD WINAPI lgLcdSetDeviceFamiliesToUse(IN int connection, IN DWORD dwDeviceFamiliesSupported, IN DWORD dwReserved1);

引数

引数名説明
connectionIN intこのコマンドの対象となる接続ハンドルを示します。
dwDeviceFamiliesSupportedIN DWORDアプレットが使用する可能性のあるデバイスファミリー定数の論理和。全てのサポートするデバイスファミリーの完全なリストは lglcd.h もしくは LCDファミリー定数を参照。
dwReserved1IN DWORDバージョン 1.03 では必ず 0 にしてください。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_SERVICE_NOT_ACTIVElgLcdInit() がまだ呼び出されていません。
ERROR_INVALID_PARAMETERdwDeviceFamiliesSupported が有効ではありません。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

connection 引数は lgLcdConnect() もしくは lgLcdConnectEx() の呼び出しで返った値です。

デバイスを列挙する前にこの関数を使います。 これによりアプレットが使用する可能性があり且つ通信方法を知っているデバイスのみが列挙されます。

参照

lgLcdConnect(), lgLcdConnectEx(), lgLcdConnectContext, lgLcdDeviceDesc, lgLcdDeviceDescEx(), lgLcdOpen(), lgLcdClose()

lgLcdEnumerate()

現在接続(attach)されているサポート可能な全ての Logitech/Logicool LCD デバイスについての情報を取得するのに lgLcdEnumerate() 関数は使われます。

DWORD WINAPI lgLcdEnumerate(IN int connection, IN int index, OUT lgLcdDeviceDesc *description);

引数

引数名説明
connectionIN intこのコマンドの対象となる接続ハンドルを示します。
IN indexint情報を要求するデバイスを示します。解説を参照。
descriptionOUT lgLcdDeviceDesc *デバイスについての情報が埋められる lgLcdDeviceDesc 構造体のポインタ。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_SERVICE_NOT_ACTIVElgLcdInit() がまだ呼び出されていません。
ERROR_NO_MORE_ITEMS列挙するデバイスがもうありません。最初の呼び出しでこのエラーが返ってきたら、それはデバイスがひとつも接続されていないことを意味します。
ERROR_INVALID_PARAMETERdescription が NULL 。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

connection 引数は lgLcdConnect() もしくは lgLcdConnectEx() の呼び出しで返った値です。

接続されているデバイスを列挙するには、index 引数を 0 でlgLcdEnumerate() で呼び出します。続く呼び出しでは関数が ERROR_NO_MORE_ITEMS を返すまで index 引数を 1 つずつインクリメントしていきます。

参照

lgLcdEnumerateEx(), lgLcdConnect(), lgLcdConnectEx(), lgLcdConnectContext, lgLcdDeviceDesc, lgLcdOpen(), lgLcdClose()

lgLcdEnumerateEx()

現在接続(attach)されているサポート可能な全ての Logitech/Logicool LCD デバイスについての情報を取得するのに lgLcdEnumerateEx() 関数は使われます。

DWORD WINAPI lgLcdEnumerateEx(IN int connection, IN int index, OUT lgLcdDeviceDescEx *description);

引数

引数名説明
connectionIN intこのコマンドの対象となる接続ハンドルを示します。
IN indexint情報を要求するデバイスを示します。解説を参照。
descriptionOUT lgLcdDeviceDescEx *デバイスについての情報が埋められる lgLcdDeviceDescEx 構造体のポインタ。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_SERVICE_NOT_ACTIVElgLcdInit() がまだ呼び出されていません。
ERROR_NO_MORE_ITEMS列挙するデバイスがもうありません。最初の呼び出しでこのエラーが返ってきたら、それはデバイスがひとつも接続されていないことを意味します。
ERROR_INVALID_PARAMETERdescription が NULL 。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

connection 引数は lgLcdConnect() もしくは lgLcdConnectEx() の呼び出しで返った値です。

接続されているデバイスを列挙するには、index 引数を 0 でlgLcdEnumerateEx() で呼び出します。続く呼び出しでは関数が ERROR_NO_MORE_ITEMS を返すまで index 引数を 1 つずつインクリメントしていきます。

参照

lgLcdEnumerate(), lgLcdConnect(), lgLcdConnectEx(), lgLcdConnectContext, lgLcdDeviceDescEx, lgLcdOpen(), lgLcdClose()

lgLcdOpen()

lgLcdOpen() 関数は接続(attach)されているデバイスのひとつと通信を開始します。ボタン情報の取得あるいは LCD ビットマップの更新の前にこの関数を呼ぶ必要があります。

DWORD WINAPI lgLcdOpen(IN OUT lgLcdOpenContext *ctx);

引数

引数名説明
ctx IN OUT lgLcdOpenContext * デバイスを開くの必要な全ての情報を含む構造体のポインタを示します。 詳細は lgLcdOpenContext を参照してください。 lgLcdOpen() を呼び出す前に、device メンバー以外の全て項目を設定する必要があります。 関数が正常終了したら、以後の lgLcdUpdateBitmap(), lgLcdReadSoftButtons() および lgLcdClose() の呼び出しに使用できるデバイスハンドルが device メンバに格納されます。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_SERVICE_NOT_ACTIVElgLcdInit() がまだ呼び出されていません。
ERROR_INVALID_PARAMETERctx が NULL 、もしくは ctx->connection が有効でない、あるいは ctx->index が有効なデバイスを保持していません。
ERROR_ALREADY_EXISTS指定されたデバイスはすでにその接続で開かれています。。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

この関数で取得したハンドルは以下の状態が発生するまで有効です。

lgLcdOpenContext の onSoftbuttonsChanged は LCD のソフトボタンの状態が変化したら呼び出されるコールバック関数のポインタです。 このコールバック関数はその LCD アプレットが LCD の前面に表示されている場合にのみ呼び出されます。 詳細は lgLcdOpenContext 及び lgLcdSoftbuttonsChangedContext の定義を参照してください。

参照

lgLcdOpenContext, lgLcdClose(), lgLcdEnumerate(), lgLcdEnumerateEx(), lgLcdUpdateBitmap(), lgLcdReadSoftButtons()

lgLcdClose()

lgLcdClose() 関数は以前に開かれたデバイスとの通信を停止します。

DWORD WINAPI lgLcdClose(IN int device);

引数

引数名説明
deviceIN int以前の lgLcdOpen() の呼び出しで lgLcdOpenContext の中に取得されたデバイスハンドルを示します。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_SERVICE_NOT_ACTIVElgLcdInit() がまだ呼び出されていません。
ERROR_INVALID_PARAMETERデバイスハンドルが無効です。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

lgLcdClose() を呼び出すと、lgLcdOpen() の呼び出しで指定したソフトボタンのコールバック関数はそれ以後呼び出されなくなります。

参照

lgLcdOpen()

lgLcdReadSoftButtons()

lgLcdReadSoftButtons() 関数は指定されたデバイスのソフトボタンの現在の状態を読み込みます。

DWORD WINAPI lgLcdReadSoftButtons(IN int device, OUT DWORD *buttons);

引数

引数名説明
deviceIN int状態を読み込む対象のソフトボタンのデバイスハンドルを示します。
buttonsOUT DWORD *この関数が呼び出された時点でのソフトボタンの状態を受け取る DWORD のポインタを示します。詳細はコメントを参照してください。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_SERVICE_NOT_ACTIVElgLcdInit() がまだ呼び出されていません。
ERROR_INVALID_PARAMETER指定されたデバイスハンドルもしくは結果を受け取るポインタが無効です。
ERROR_DEVICE_NOT_CONNECTED指定されたデバイスは切断されています。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

結果の DWORD 値は現在のソフトボタンの状態をひとつのボタンあたり 1 bit で格納しています。 LGLCDBUTTON_BUTTON0 から LGLCDBUTTON_BUTTON3 のマスク定数(マクロ)を使って DWORD 値から特定のボタンをチェックできます。

LCD の前面に表示されていないアプリケーションがこの関数を呼び出しても、その時、実際にはソフトボタンが押された状態であっても DWORD 値は 0 になります。 この挙動は LCD に表示されていないアプリケーションをユーザが気付かずに操作してしまうことを避ける為です。

参照

lgLcdOpen()

lgLcdUpdateBitmap()

lgLcdUpdateBitmap() 関数はデバイスのビットマップ( LCD 表示)を更新します。

DWORD WINAPI lgLcdUpdateBitmap(IN int device, IN const lgLcdBitmapHeader *bitmap, IN DWORD priority);

引数

引数名説明
deviceIN int表示を更新するデバイスのハンドルを示します。
bitmapIN const lgLcdBitmapHeader *ビットマップヘッダー構造体のポインタを示します。 詳細はコメントを参照してください。
priority IN DWORD

この画面更新の優先度及び同期更新もしくは非同期更新を示します。詳細はコメントを参照してください。

次のような優先度が定義されています。
定数名説明
LGLCD_PRIORITY_IDLE_NO_SHOWもっとも低い優先度で、表示を無効にします。なにかを表示したい時にはこの優先度を使わないでください。
LGLCD_PRIORITY_BACKGROUND低い優先度です。
LGLCD_PRIORITY_NORMAL普通の優先度で、多くのアプリケーションでもっとも多く使用されます。
LGLCD_PRIORITY_ALERTもっとも高い優先度です。"CPU温度が高すぎます" のような致命的な画面(表示)の為にのみ使用されます。
加えて、画面更新の同期(LGLCD_SYNC_UPDATE())もしくは非同期(LGLCD_ASYNC_UPDATE())を示すことのできる三つのマクロがあります。 マクロ(LGLCD_SYNC_COMPLETE_WITHIN_FRAME())を使って同期更新する時 LCD ライブラリ は LCD にビットマップが表示されたかどうかを呼び出し元のアプリケーション通知することができます。 これらのマクロを使ってライブラリの振る舞いを指示します。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_SERVICE_NOT_ACTIVElgLcdInit() がまだ呼び出されていません。
ERROR_INVALID_PARAMETER指定されたデバイスハンドル、lgLcdBitmapHeader のポインタもしくはビットマップの形式が無効です。
ERROR_DEVICE_NOT_CONNECTED指定されたデバイスは切断されています。
ERROR_ACCESS_DENIEDLCD への同期表示はフレームインターバル(30ミリ秒)内に行われませんでした。このエラーコードは lgLCDUpdateBitmap() 関数の priority 引数を LGLCD_SYNC_COMPLETE_WITHIN_FRAME マクロとともに使用した場合にしか返されません。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

bitmap 引数は実際のビットマップを指定します。 現在のライブラリのリビジョンでは最初のメンバーにビットマップヘッダを持つ lgLcdBitmap160x43x1 と呼ばれる構造体を定義しています。 こうした構造体の典型的な例を一つあげると、hdr.Format に LGLCD_BMP_FORMAT_160x43x1 を設定し、そして pixels[] メンバー を表示するビットマップで埋めます。 最後に、ビットマップを更新する為に lgLcdUpdateBitmap(… &yourBitmap.hdr …) を呼び出します。 将来の SDK のバージョンでは、追加のビットマップ型が宣言される可能性がありますが、それらは全て同じヘッダで始まるでしょう。

いつなんどき数々のアプリケーションが LCD へのビットマップの表示を行うかわかりません。 priority 引数は LCDMon の表示スケジュールアルゴリズムに示唆します。 画面表示をどのように扱うかが問題になった状況で、LCDMon はどのアプリケーションのビットマップを表示するか決定する必要があります。 このスケジューリングを助ける為に、アプリケーションが priority 引数を通して示唆することができます(ただし、ユーザの設定に依存します)。 ユーザエクスペリエンスをよりよくするために各種画面更新のためにあなたのアプリケーションが適切な優先度を与えることは非常に望ましいです。 行儀の良い LCD 対応アプリケーションは、警報を除いて高い優先度を使わないでしょう。

非同期更新および同期更新の違いは、以下の通りです: 同期更新は LCDMon へ表示するビットマップを渡したらビットマップが実際にデバイスへ送出される前に戻ります。 同期更新のために lgLcdUpdateBitmap() が呼び出された場合、ビットマップがデバイスに送出された後で戻ります(ビットマップのデバイスへの送出は30ミリ秒もしくはそれ以上かかります)。 他のアプリケーションが表示されている為にアプリケーションが LCD に表示されていない状況であっても、同期更新はアプリケーションが表示されている場合と同等の時間を費やしたのに返ります。 またこのような状況下で LGLCD_SYNC_COMPLETE_WITHIN_FRAME() マクロが使用されていた場合、呼び出し元のアプリケーションにはエラーが返されます。

同期更新を行うことの利点は、あなたのアプリケーションが LCD の更新により "ロックされて" 動作するということです。 画面を書き出している間、アプリケーションはずっと止まった状態になり、ディスプレイが新しい画面を受け取る準備ができている時にのみ動き出します。 この振る舞いにより LCD 上のミニゲームはCPU使用率を最小に保って最高のフレームレートを得ることができます。

非同期更新は、多く他の処理を行わなず正確な画面更新のシーケンスとタイミングを気にかけなくてもよいアプリケーションに有効です。 そういったアプリケーションではその時々でデバイスに送出するビットマップを LCDMon に預けて、表示とその(表示を行う理由となった)イベントとの同期が取れるかについては注意を払いません。

参照

lgLcdOpen(), lgLcdBitmapHeader, lgLcdBitmap160x43x1

lgLcdSetAsLCDForegroundApp()

foregroundYesNoFlag 引数に LGLCD_LCD_FOREGROUND_APP_YES を指定して呼び出されると、アプリケーションが LCD に表示され且つ LCD ライブラリによって他のアプリケーションに切り替えられるのを防ぐことを lgLcdSetAsLCDForegroundApp() 関数は許可します。 foregroundYesNoFlag 引数に LGLCD_LCD_FOREGROUND_APP_NO が指定して呼び出されると、LCD ライブラリは切り替えアルゴリズムをユーザが選択したものに戻します。

DWORD WINAPI lgLcdSetAsLCDForegroundApp(IN int device, IN int foregroundYesNoFlag);

引数

引数名説明
deviceIN intコマンドの対象となるデバイスのハンドルを指定します。
foregroundYesNoFlag IN int

呼び出し元のアプリケーションが LCD の最前面に表示されることを望んでいる、あるいは最前面から除かれようとすることを示します。 詳細はコメントを参照してください。

次のような foregroundYesNoFlag 値が定義されています。
定数名説明
LGLCD_LCD_FOREGROUND_APP_NO呼び出し元のアプリケーションは LCD に表示される唯一のアプリケーションであることを望みません。
LGLCD_LCD_FOREGROUND_APP_YES呼び出し元のアプリケーションは LCD に表示される唯一のアプリケーションであることを望みます。

戻り値

この関数が成功すれば ERROR_SUCCESS を返します。

この関数が失敗すれば以下の値を返します。
説明
ERROR_LOCK_FAILED操作は完了できませんでした。
Xxxエラーコードで示されるその他の(システム)エラー。

解説

LCD 上に表示され他のアプリケーションによってスワップアウトされることを望まないゲームのようなアプリケーションは、この関数の呼び出しによって LCD の最前面に表示されるアプリケーションになることができます。 後で他のアプリケーションがこの関数を呼び出した場合を除いて、LCD ライブラリはそのアプリケーションをスワップアウトしません。 lgLcdUpdateBitmap() の呼び出しで提供された最前面のアプリケーションのビットマップは全て LCD に表示されます。

参照

lgLcdUpdateBitmap()

構造体

lgLcdDeviceDesc

lgLcdDeviceDesc 構造体はアタッチしているデバイスのプロパティを記載します。この情報は lgLcdEnumerate() 関数の呼び出しを通じて返されます。

typedef struct
{
    DWORD Width;
    DWORD Height;
    DWORD Bpp;
    DWORD NumSoftButtons;
} lgLcdDeviceDesc;

データメンバー

メンバー名説明
WidthDWORDディスプレイの幅をピクセル数で示します。
HeightDWORDディスプレイの高さをピクセル数で示します。
BppDWORDビットマップの深さをピクセルあたりのビット数で示します。(色数)
NumSoftButtonsDWORDデバイスに搭載されているソフトボタンの数を示します。

解説

この構造体は将来のデバイスとの互換性の為にあります。現時点で存在するハードウェアでは、160x43x1 ピクセルで 4 ソフトボタンを持つ LCD として報告されることしかありません。

参照

lgLcdEnumerate()

lgLcdDeviceDescEx

lgLcdDeviceDescEx 構造体はアタッチしているデバイスのプロパティ記載します。この情報は lgLcdEnumerateEx() 関数の呼び出しを通じて返されます。

typedef struct
{
    DWORD deviceFamilyId;
    TCHAR deviceDisplayName[MAX_PATH];
    DWORD Width;
    DWORD Height;
    DWORD Bpp;
    DWORD NumSoftButtons;
    DWORD Reserved1;
    DWORD Reserved2;
} lgLcdDeviceDescEx;

データメンバー

メンバー名説明
deviceFamilyIdDWORDデバイスのファミリーIDを示します。各々のデバイスは一つのファミリーに属します。
deviceDisplayNameTCHAR[MAX_PATH]デバイスの表示名を示します。
WidthDWORDディスプレイの幅をピクセル数で示します。
HeightDWORDディスプレイの高さをピクセル数で示します。
BppDWORDビットマップの深さをピクセルあたりのビット数で示します。(色数)
NumSoftButtonsDWORDデバイスに搭載されているソフトボタンの数を示します。
Reserved1DWORD使われていません。
Reserved2DWORD使われていません。

解説

この構造体は LCD Manager がデバイスについての情報を返すのに使用されます。

参照

lgLcdEnumerateEx()

lgLcdBitmapHeader/lgLcdBitmap160x43x1

lgLcdBitmapHeader は lgLcd で定義されるどのビットマップ構造体の先頭にも存在します。 下のヘッダーは lgLcdBitmap160x43x1 で図解したバイト配列による実際のビットマップです。

typedef struct
{
    DWORD Format;
} lgLcdBitmapHeader;
typedef struct
{
    lgLcdBitmapHeader hdr;
    BYTE pixels[LGLCD_BMP_WIDTH*LGLCD_BMP_HEIGHT];
} lgLcdBitmap160x43x1;

データメンバー

メンバー名説明
FormatDWORDこの構造体に続くヘッダのフォーマットを示します。現状では、LGLCD_BMP_FORMAT_160x43x1 しかサポートしていません。
pixelsBYTE[LGLCD_BMP_WIDTH*LGLCD_BMP_HEIGHT]160x43 の表示するビットマップを含みます。各々のバイトはそれぞれひとつのピクセルに対応し、128 以上であれば "on"、128 未満であれば "off" を意味します。

解説

ピクセルの配列は幅 160 バイトで高さ 43 バイトの矩形に整理されています。 ディスプレイはモノクロであるにもかかわらず、ここのピクセルを簡単に操作できるようにするために 1 ピクセルあたり 8 ビット が使用されます。 GDI描画関数の使い方を効果的に学べるように用意してあるサンプルコードを参照してください。

各ピクセルは下のような順序で整列されています。
byte 0
(0,0)
byte 1
(1,0)
byte 2
(2,0)
byte 157
(157,0)
byte 158
(158,0)
byte 159
(159,0)
byte 160
(0,1)
byte 161
(1,1)
byte 162
(2,1)
byte 317
(157,1)
byte 318
(158,1)
byte 319
(159,1)
byte 6560
(0,41)
byte 6561
(1,41)
byte 6562
(2,41)
byte 6717
(157,41)
byte 6718
(158,41)
byte 6719
(159,41)
byte 6720
(0,42)
byte 6721
(1,42)
byte 6722
(2,42)
byte 6877
(157,42)
byte 6878
(158,42)
byte 6879
(159,42)

参照

lgLcdUpdateBitmap()

lgLcdConfigureContext/lgLcdOnConfigureCB

lgLcdConfigureContext は lgLcdConnectContext の一部でユーザがあなたのアプリケーションを設定可能にする為に十分な情報をライブラリに提供する為に使用されます。 登録されたコールバックは LCDMon のアプリケーションのリスト画面でユーザが[設定...]ボタン(英語版では[Configure...]ボタン)をクリックした時に呼び出されます。

// ユーザが"設定画面"を表示することを可能にするコールバック
typedef DWORD (WINAPI *lgLcdOnConfigureCB)(IN int connection, IN const PVOID pContext);

typedef struct
{
    // 設定可能でないなら NULL にする
    lgLcdOnConfigureCB configCallback;
    PVOID configContext;
} lgLcdConfigureContext;

データメンバー

メンバー名説明
configCallback lgLcdOnConfigureCB ユーザがあなたのアプリケーションを設定しようとした時に呼ばれるコールバック関数のポインタを示します。設定画面が不要あるいは設定画面を提供しない場合、このパラメータは NULL のままにします。
configContext PVOID 登録された configCallback 関数が呼び出される際に引き渡される任意のデータを示します。

解説

LCD で表示されることを必要とする簡単で小さなユーティリティのような独立した UI を持たないアプリケーションの為に、共通の LCDMon フロントエンドによってユーザがあなたの UI にアクセスできるようにあなたは設定コールバック機構を使用することができます。 LCDMon のアプリケーションのリスト画面で、[設定...]ボタン(英語版では[Configure...]ボタン)が押下された時、登録された設定コールバックが呼び出されます。 もしあなたのアプリケーションのすべての UI が LCD に関連したものである場合、この機構により、あなたはその他の UI ( 通知アイコン(※)や普通のウィンドウ ) を実装しないで済むでしょう。

このコールバックはライブラリのあるスレッドから呼び出されることに注意する必要があります。 すなわちあなたのアプリケーションの他のスレッドとリソースを共有するコールバックのコードはスレッド安全である必要性があります。

Wraith the Trickster ※原文では tray icon となっていますが、... によると Windows 用語として tray icon (トレイアイコン)は誤りで、正しくは notify icon (通知アイコン) となります。
参照

lgLcdConnectContext, lgLcdConnect(), lgLcdConnectEx()

lgLcdNotificationContext/lgLcdOnNotificationCB

lgLcdNotificationContext は lgLcdConnectContext の一部でユーザがあなたのアプリケーションに通知可能にする為に十分な情報をライブラリに提供する為に使用されます。 登録されたコールバックはアプリケーションへの通知がある時に呼び出されます。 この通知は新しいデバイスの接続と除去についてです。 この機能は LCD Manager ソフトウェアのリリース 1.03 (現バージョン)ではサポートされていません。

// LCD Manager からのイベントの通知に使用されるコールバック
typedef DWORD (WINAPI *lgLcdOnNotificationCB)(IN int connection, IN const PVOID pContext, IN DWORD notificationCode, IN DWORD notifyParm1, IN DWORD notifyParm2, IN DWORD notifyParm3, IN DWORD notifyParm4);

typedef struct
{
    // 設定可能でないなら NULL にする
    lgLcdOnNotificationCB notificationCallback;
    PVOID notificationContext;
} lgLcdNotificationContext;

データメンバー

メンバー名説明
notificationCallback lgLcdOnNotificationCB LCD Manager でアプリケーションに対する通知がある時に呼ばれるコールバック関数のポインタを示します。 あなたのアプリケーションが通知に興味がない場合、このパラメータは NULL のままにします。
notificationContext PVOID 登録された notificationCallback 関数が呼び出される際に引き渡される任意のデータを示します。

解説

この機能は LCD Manager のリリース 1.03 (現バージョン)ではサポートされていません。

参照

lgLcdConnectContextEx, lgLcdConnectEx()

lgLcdConnectContext

lgLcdConnectContext はあなたのアプリケーションが lgLcdConnect() を通じて LCDMon に接続するのに必要な全ての情報を含みます。 接続に成功したら、続く lgLcdEnumerate() 及び lgLcdOpen() の呼び出しで使用する接続ハンドルが格納されます。

typedef struct
{
    // リスト上に表示される"フレンドリな名前"
    LPCTSTR appFriendlyName;
    // この接続がリスト上に残るかどうか
    BOOL isPersistent;
    // LCDMon による自動起動が可能かどうか
    BOOL isAutostartable;
    lgLcdConfigureContext onConfigure;
    // APIから返される接続ハンドル
    int connection;
} lgLcdConnectContext;

データメンバー

メンバー名説明
appFriendlyName LPCTSTR あなたのアプリケーションの"フレンドリな名前"を含む文字列を示します。 この名前はアプリケーションリストの表示によりユーザに提示されます。
isPersistent BOOL リストに追加される接続が一時的なもの(.isPersistent = FALSE)であるのか、継続するもの(.isPersistent = TRUE)なのかを示します。
isAutostartable BOOL LCDMon によってあなたのアプリケーションが起動かどうかを示します。
onConfigure lgLcdConfigureContext あなたのアプリケーションの設定の為に必要なコールバックに関係する情報を示します。 より詳細には lgLcdConfigureContext を参照してください。
connection int 接続に成功したら、続く lgLcdEnumerate() 及び lgLcdOpen() の呼び出しで使用する接続ハンドルがこのメンバーに保持されます。 この値が LGLCD_INVALID_CONNECTION の場合、それは無効な接続であること示します。

解説

一般的に、アプリケーションは(例えばゲームのようなアプリケーションで機能の一つとして)"LCD対応"しているもしくは"LCD専用"アプリケーション(例えば LCD 上にのみ表示される時計アプリ)のどちらかになります。 LCD対応している種類のアプリケーションは、共通して .isAutostartable を FALSE に"設定コールバック"を NULL に設定します。 LCD専用アプリでは、通常 .isAutostartable は TRUE で、そして(例えば時刻表示の12時間制もしくは24時間制の切り替えが可能になる)"設定コールバック"を実装するこはよき判断となり得えます。 特有のアプリケーションで必要とされるどのような UI でも設定コールバックのインプリメントによって実現できます。

接続は開いてから lgLcdDisconnect() が呼び出されるか lgLcdDeInit() によってライブラリの終了処理が実行されるまで持続されます。

返された接続ハンドルは lgLcdEnumerate()lgLcdOpen() で使用します。 接続ハンドルが有効か無効かを区別するには LGLCD_INVALID_CONNECTION 定数と比較します(同じなら無効)。

ひとつのアプリケーションが LCDMon に対して複数の接続を開くことができます。 これにより望むならクライアントアプリが LCDMon のアプリケーションリスト上に複数のエントリを表示することができます。 例えば、あなたのアプリケーションが株価の表示と電子メールチェックの両方を提供しているアプリケーションだとします。 このような場合、あなたのアプリケーションは lgLcdConnect() を呼び出す時にフレンドリ名を1回目は "株価表示" に、そして2回目は "電子メールチェック" にします。 この二つの LCD クライアントは同じ枠組みを共有していても、(設定画面が個別に必要なことも含め)全ての目的・動作が個別のものとなり、したがって個別の接続が必要になります。

参照

lgLcdConnect(), lgLcdDisconnect(), lgLcdEnumerate(), lgLcdOpen()

lgLcdConnectContextEx

lgLcdConnectContextEx はあなたのアプリケーションが lgLcdConnectEx() を通じて LCDMon に接続するのに必要な全ての情報を含みます。 接続に成功したら、続く lgLcdEnumerate(), lgLcdEnumerateEx() 及び lgLcdOpen() の呼び出しで使用する接続ハンドルが格納されます。

typedef struct
{
    // リスト上に表示される"フレンドリな名前"
    LPCTSTR appFriendlyName;
    // この接続がリスト上に残るかどうか
    BOOL isPersistent;
    // LCDMon による自動起動が可能かどうか
    BOOL isAutostartable;
    lgLcdConfigureContext onConfigure;
    // APIから返される接続ハンドル
    int connection;
    DWORD dwAppletCapabilitiesSupported;
    DWORD dwReserved1;
    lgLcdNotificationContext onNotify;
} lgLcdConnectContextEx;

データメンバー

メンバー名説明
appFriendlyName LPCTSTR あなたのアプリケーションの"フレンドリな名前"を含む文字列を示します。 この名前はアプリケーションリストの表示によりユーザに提示されます。
isPersistent BOOL リストに追加される接続が一時的なもの(.isPersistent = FALSE)であるのか、継続するもの(.isPersistent = TRUE)なのかを示します。
isAutostartable BOOL LCDMon によってあなたのアプリケーションが起動かどうかを示します。
onConfigure lgLcdConfigureContext あなたのアプリケーションの設定の為に必要なコールバックに関係する情報を示します。 より詳細には lgLcdConfigureContext を参照してください。
connection int 接続に成功したら、続く lgLcdEnumerate(), lgLcdEnumerateEx() 及び lgLcdOpen() の呼び出しで使用する接続ハンドルがこのメンバーに保持されます。 この値が LGLCD_INVALID_CONNECTION の場合、それは無効な接続であること示します。
dwAppletCapabilitiesSupported DWORD このフィールドはアプレットでサポートしている機能ごとに割り当てられた定数を論理和で結合した値を格納します。 この機能は LCD Manager ソフトウェアのリリース 1.03 (現在のバージョン)ではまだ実装されていません。 この引数に使用する定数については機能定数を参照してください。
name dwReserved1 予約。
onNotify lgLcdNotificationContext あなたのアプリケーションに通知の為のコールバックを行う為に必要な情報を示します。 より詳細には lgLcdNotificationContext を参照してください。 この機能は LCD Manager ソフトウェアのリリース 1.03 (現在のバージョン)ではまだ実装されていません。 この引数に使用する定数については通知定数を参照してください。

解説

一般的に、アプリケーションは(例えばゲームのようなアプリケーションで機能の一つとして)"LCD対応"しているもしくは"LCD専用"アプリケーション(例えば LCD 上にのみ表示される時計アプリ)のどちらかになります。 LCD対応している種類のアプリケーションは、共通して .isAutostartable を FALSE に"設定コールバック"を NULL に設定します。 LCD専用アプリでは、通常 .isAutostartable は TRUE で、そして(例えば時刻表示の12時間制もしくは24時間制の切り替えが可能になる)"設定コールバック"を実装するこはよき判断となり得えます。 特有のアプリケーションで必要とされるどのような UI でも設定コールバックのインプリメントによって実現できます。

接続は開いてから lgLcdDisconnect() が呼び出されるか lgLcdDeInit() によってライブラリの終了処理が実行されるまで持続されます。

返された接続ハンドルは lgLcdEnumerate(), lgLcdEnumerateEx()lgLcdOpen() で使用します。 接続ハンドルが有効か無効かを区別するには LGLCD_INVALID_CONNECTION 定数と比較します(同じなら無効)。

ひとつのアプリケーションが LCDMon に対して複数の接続を開くことができます。 これにより望むならクライアントアプリが LCDMon のアプリケーションリスト上に複数のエントリを表示することができます。 例えば、あなたのアプリケーションが株価の表示と電子メールチェックの両方を提供しているアプリケーションだとします。 このような場合、あなたのアプリケーションは lgLcdConnectEx() を呼び出す時にフレンドリ名を1回目は "株価表示" に、そして2回目は "電子メールチェック" にします。 この二つの LCD クライアントは同じ枠組みを共有していても、(設定画面が個別に必要なことも含め)全ての目的・動作が個別のものとなり、したがって個別の接続が必要になります。

参照

lgLcdConnectEx(), lgLcdDisconnect(), lgLcdEnumerate(), lgLcdEnumerateEx(), lgLcdOpen()

lgLcdSoftbuttonsChangedContext/lgLcdOnSoftButtonsCB

lgLcdSoftbuttonsChangedContext は lgLcdOpenContext の一部で、ソフトボタンの状態の変化を呼び出し元のアプリケーションにコールバックを通じて知らせるのに十分な情報をライブラリに提供する為に使用されます。

// ソフトボタンの変化をクライアントに通知するの使用されるコールバック
typedef DWORD (WINAPI *lgLcdOnSoftButtonsCB)(IN int device, IN DWORD dwButtons, IN const PVOID pContext);

typedef struct
{
    // ソフトボタン通知が不要な場合は NULL に設定
    lgLcdOnSoftButtonsCB softbuttonsChangedCallback;
    PVOID softbuttonsChangedContext;
} lgLcdSoftbuttonsChangedContext;

データメンバー

メンバー名説明
softButtonsChangedCallback lgLcdOnSoftButtonsCB ソフトボタンの状態が変化したときに呼び出されるコールバック関数のポインタを示します。 通知が様な場合、このパラメータは NULL のままにします。
softbuttonsChangedContext PVOID ソフトボタンが押されたもしくは離されたイベントでコールバック関数が呼び出される際に引き渡される任意のデータを示します。 ソフトボタンの新しい状態はコールバック関数の dwButtons 引数にて報告されます。

解説

ソフトボタンの状態を取得するのには二つの方法があります。 ひとつはその都度 lgLcdReadSoftButtons() によって状態を監視することで、 もうひとつは変化が発生する度にアプリケーションに発せられるこの通知コールバックを使用することです。

このコールバックはライブラリのあるスレッドから呼び出されることに注意する必要があります。 すなわちあなたのアプリケーションの他のスレッドとリソースを共有するコールバックのコードはスレッド安全である必要性があります。

参照

lgLcdOpenContext, lgLcdOpen(), lgLcdReadSoftButtons()

lgLcdOpenContext

lgLcdOpenContext は特定の LCD ディスプレイを lgLcdOpen() によって開くのに必要な全ての情報を含みます。 LCD を完全に開くのに成功したら、続く lgLcdReadSoftButtons(), lgLcdUpdateBitmap() 及び lgLcdClose() の呼び出しで使用するデバイスハンドルが格納されます。

typedef struct
{
    int connection;
    // 開くデバイスのインデックス
    int index;
    lgLcdSoftbuttonsChangedContext onSoftbuttonsChanged;
    // APIから返されるデバイスハンドル
    int device;
} lgLcdOpenContext;

データメンバー

メンバー名説明
connection int この lgLcdOpen() の呼び出しで必要な( lgLcdConnect() で返された )接続ハンドルを示します。
index int 開くデバイスのインデックスを示します。( 詳細は lgLcdEnumerate() もしくは lgLcdEnumerateEx() を参照してください。 )
onSoftbuttonsChanged lgLcdSoftbuttonsChangedContext ユーザがソフトボタンを押したり放したりすることで生じるこのデバイスのソフトボタンの状態が変化した時に呼び出されるコールバック関数の詳細を示します。 詳細については、lgLcdSoftbuttonsChangedContext を参照してください。
device int 開くのに成功したら、続く lgLcdReadSoftButtons(), lgLcdUpdateBitmap() 及び lgLcdClose() の呼び出しで使用するデバイスハンドルがこのメンバー格納されます。 この値が LGLCD_INVALID_DEVICE であれば無効なデバイスであることを意味します。

解説

この構造体はデバイスを開きそのハンドルを受け取る為に使用します。 このハンドルはそのデバイスが物理的に引き抜かれるか lgLcdClose() が呼び出されるまで有効です。 デバイスハンドルが有効か無効かを区別するには LGLCD_INVALID_DEVICE 定数と比較します(同じなら無効)。

一つの接続で、複数のデバイスを開くことができます。 この機能は一つのキーボードではあまり意味がありません(それは同じシステムへの複数の接続となります)、この機能は複数の独立したディスプレイへの柔軟な接続を提供します。

参照

lgLcdConnect(), lgLcdEnumerate(), lgLcdConnectEx(), lgLcdEnumerateEx(), lgLcdOpen()

マクロ定数・マクロ定義

無効なハンドル値

マクロ名定義説明
LGLCD_INVALID_CONNECTION(-1)無効なコネクション。
LGLCD_INVALID_DEVICE(-1)無効なデバイス。

ソフトボタンマスク値

マクロ名定義説明
LGLCDBUTTON_BUTTON0(0x00000001)ソフトボタン0のマスク。
LGLCDBUTTON_BUTTON1(0x00000002)ソフトボタン1のマスク。
LGLCDBUTTON_BUTTON2(0x00000004)ソフトボタン2のマスク。
LGLCDBUTTON_BUTTON3(0x00000008)ソフトボタン3のマスク。

ビットマップ定数

マクロ名定義説明
LGLCD_BMP_FORMAT_160x43x1(0x00000001)ピクセル数:160x43, カラービット数:1 のLCD。
LGLCD_BMP_WIDTH(160)LCDの横幅(ピクセル数)。
LGLCD_BMP_HEIGHT(43)LCDの縦幅(ピクセル数)。

優先度定数・優先度マクロ定義

マクロ名定義説明
LGLCD_PRIORITY_IDLE_NO_SHOW(0)もっとも低い優先度で、表示を無効にします。なにかを表示したい時にはこの優先度を使わないでください。
LGLCD_PRIORITY_BACKGROUND(64)低い優先度です。
LGLCD_PRIORITY_NORMAL(128)普通の優先度で、多くのアプリケーションでもっとも多く使用されます。
LGLCD_PRIORITY_ALERT(255)もっとも高い優先度です。"CPU温度が高すぎます" のような致命的な画面(表示)の為にのみ使用されます。
LGLCD_SYNC_UPDATE(priority)(0x80000000 | (priority))同期更新を行います。
LGLCD_SYNC_COMPLETE_WITHIN_FRAME(priority)(0xC0000000 | (priority))同期更新を行い、実際に LCD への同期表示がフレームインターバル(30ミリ秒)内に行われなかった際にはエラーを返します。
LGLCD_ASYNC_UPDATE(priority)(priority)非同期更新を行います。

前面モード定数

マクロ名定義説明
LGLCD_LCD_FOREGROUND_APP_NO(0)アプリケーションは LCD に表示される唯一のアプリケーションであることを望みません。
LGLCD_LCD_FOREGROUND_APP_YES(1)アプリケーションは LCD に表示される唯一のアプリケーションであることを望みます。

LCDファミリー定数

マクロ名定義説明
LGLCD_DEVICE_FAMILY_KEYBOARD_G15(0x00000001)G15キーボードファミリー。
LGLCD_DEVICE_FAMILY_SPEAKERS_Z10(0x00000002)Z10スピーカーファミリー。
LGLCD_DEVICE_FAMILY_JACKBOX(0x00000004)委細不明。
LGLCD_DEVICE_FAMILY_LCDEMULATOR_G15(0x00000008)G15エミュレーターファミリー。
LGLCD_DEVICE_FAMILY_OTHER(0x80000000)その他のファミリー。

機能定数

※1.03 release でサポートされているのは LGLCD_APPLET_CAP_BASIC のみです。
マクロ名定義説明
LGLCD_APPLET_CAP_BASIC(0x00000000)委細不明。
LGLCD_APPLET_CAP_CAN_CLOSE_DEVICE(0x00000001)委細不明。
LGLCD_APPLET_CAP_CAN_CLOSE_CONNECTION(0x00000002)委細不明。
LGLCD_APPLET_CAP_CAN_CLOSE_AND_REOPEN_DEVICE(0x00000004)委細不明。
LGLCD_APPLET_CAP_CAN_RUN_ON_MULTIPLE_DEVICES(0x00000008)委細不明。

通知定数

※LCD Manager から LCD アプレットへの通知は 1.03 release ではインプリメントされていません。
マクロ名定義説明
LGLCD_NOTIFICATION_DEVICE_ARRIVAL(0x00000001)委細不明。
LGLCD_NOTIFICATION_DEVICE_REMOVAL(0x00000002)委細不明。
LGLCD_NOTIFICATION_CLOSE_DEVICE(0x00000003)委細不明。
LGLCD_NOTIFICATION_CLOSE_AND_REOPEN_DEVICE(0x00000004)委細不明。
LGLCD_NOTIFICATION_CLOSE_CONNECTION(0x00000005)委細不明。
LGLCD_NOTIFICATION_RUN_NEW_INSTANCE_ON_DEVICE(0x00000006)委細不明。