赤外線リモコンライブラリサーバのAPIについて

API document for IRLIB version 1.10

◎はじめに

赤外線リモコンライブラリサーバ IRLIB は API を通じてアプリケーションから呼び出されて初めて動作します。アプリケーションがなければ、存在意義が全くありません。ここではアプリケーションを作成するために必要な API の利用方法を解説します。

実例として、sample ディレクトリに SAMPLE.C を用意たのでそちらも参照して下さい。

◎アプリケーションから見た IRLIB の利用方法の概略

アプリケーションが、IRLIB を利用してデータの送信を行うまでの手順は以下のようになります。

APIエントリの取得
IRLファイルをサーバに登録
ライブラリを選択
目的の機器をさがす
機能を選ぶ
送信

1. APIエントリの取得

IRLIB はコマンドラインから常駐すると、"IRLIB$" という名前のキャラクタデバイスとして、DOS に登録されるようになっています。

アプリケーションは、まず、ファイル名"IRLIB$"をファイルオープンします。オープンに成功したら、得られたハンドルに対して read IOCTL(DOS function 4402h) を行います。成功すれば、APIエントリのアドレスが得られます。このとき、IOCTLのデータバイト数(reg.CX) は 4 として下さい。

IRLIB の各ファンクションは、一番目の引数にファンクション番号を入れて、ここで得たエントリアドレスをfar Cコールすることで呼び出します。

2. ライブラリをサーバに登録

ファンクション 1(load library) を使って IRLファイルをロードし、IRLIBにライブラリデータを登録します。

IRL ファイルは IDL ファイルから IDL2IRL を用いて変換して作成します。 IRL ファイルについては DOC\IRL.DOC を参照してください。

3. 登録済みライブラリを選択

ファンクション 3 (get library list) で得られる登録されているライブラリのリストのなかから目的のライブラリを選び、ファンクション 5 (get handle by library number) を使ってハンドルを得ます。

4. 目的の機器をさがす

3 で選択したライブラリの中から、ファンクション9 (get instrument list) を使って機器を選び、ファンクション10 (get handle by instrument number) でその機器を指定するハンドルを得ます。

4. 機能を選ぶ

ファンクション 14 (get function list) で機能を選びます。

5. 送信

選んだ機能に対応するデータをファンクション 16 (send main) を使って、リモコンデータ主部を送信します。
繰り返し部を送信する必要がある場合は、必要なだけファンクション17 (send repeat) を呼び、最後にファンクション 18 (send end) を使って終了データ (end IRD) を送信します。多くの機器では終了データを送信しなくても動作しますが、ファンクション 17 は必ず呼ぶようにしてください。

◎ファンクションの呼び出し方

IRLIB の API は、引数がファンクションにより可変長なので、引数の与え方を呼出側がスタックを補正するＣ形式としました。第１引数をファンクションナンバーとし、後の引数は各ファンクションに依るものとします。

例.1. C の場合:

	int (far *Entry)(unsigned short func, ...);
	...
	Entry(IRLIB_SendMain, Handle, Number);

例.2. Assemblerの場合:

	Entry   dd      ?
	...
	push    IRLIB_SendMain
	push    Handle
	push    Number
	call    Entry
	add     sp, 6

Ｃ形式の関数呼び出しなので、呼び出し側でスタックに積んだ引数の大きさだけスタックポインタを戻します。

◎名前リストを得るファンクションの使いかた

ファンクション 4 (get library list), 9 (get instrument list), 14 (get function list) は、いずれも番号から名前を得るファンクションです。アプリケーションが順番に番号を与えて、それに対応する名前を得ることになります。このとき、番号の上限はファンクション 3 (get number of libraries), 8 (get number of instruments), 13(get number of functions) で得たものを用いるようにしてください。

◎APIのファンクション

ファンクション番号は include ディレクトリの irlib.h, irlib.inc に定義してあります。それぞれ C, Assembler用です。
ファンクション番号 19 (get error code) までをユーザ向けファンクションとし、以下に番号順に解説します。19 より大きな番号のファンクションについてはここでは解説しません。

特に指定がないかぎり数値は 16bit, ポインタは far pointer、文字列は ASCIIZ で文字列長に０を含めます。また、名前を返すファンクションを呼ぶときのバッファは256bytes確保してください。
値を返すファンクションは返り値が０の場合エラーです。
以下の記述で "定義名" は irlib.h, irlib.inc における定義名です。

"引数" は第２引数以降に順番に与える引数です。
"返り値" はすべて、AX レジスタに返る値です。
"使用例" は C 言語で、irlib.h を include しており、

int (far *Entry)(u_short func);
で定義されるEntryに、IRLIBのAPIエントリを差す値が格納されていることを想定しています。

0. get version

機能: バージョン番号を得ます
定義名: IRLIB_GetVersion
引数: なし
返り値: バージョン番号
使用例: VersionNum = Entry(IRLIB_GetVersion);

1. load library

機能

IRLをサーバにロードします

定義名

IRLIB_LoadLibrary

引数

pointer to filename

返り値

ハンドル, 0 (if error)

使用例

if(!Entry(IRLIB_LoadLibrary,(char far *)filename))
	printf("failed\n");

2. unload library

機能

ライブラリをサーバから抹消します

定義名

IRLIB_UnloadLibrary

引数

ハンドル

返り値

0 (if error)

使用例

if (!Entry(IRLIB_UnloadLibrary, Handle))
	 printf("failed\n");

3. get number of libraries

機能: 登録済みライブラリ数を得る
定義名: IRLIB_GetNumOfLibs
引数: なし
返り値: ライブラリの総数
使用例: Num=Entry(IRLIB_GetNumOfLibs);

4. get library list

機能

引数に与えた番号に対応するライブラリ名をバッファに返します。

定義名

IRLIB_GetLibList

引数

番号、バッファへのポインタ

返り値

格納した文字数

使用例

for (i = 0; i %3c NumOfLibs; i++) {
	Entry(IRLIB_GetLibList, i, (char far *)NameBuff);
	printf("\t%d: %s\n", i, NameBuff);
}

5. get handle by library number

機能: ライブラリの登録順番号からハンドルを得ます。
引数: の番号にはファンクション4で用いたものと同じ物を与えます。
定義名: IRLIB_GetHandleByLibNum
引数: 番号
返り値: ハンドル
使用例: LibHandle=Entry(IRLIB_GetHandleByLibNum, LibNum);

6. get handle by library name

機能: 名前でライブラリを選択します。
定義名: IRLIB_GetHandleByLibName
引数: ライブラリ名へのポインタ
返り値: ハンドル
使用例: LibHandle=Entry(IRLIB_GetHandleByLibName, (char far *)Name);

7. get library name by handle

機能: ハンドルに対応するライブラリ名をバッファに返します
定義名: IRLIB_GetLibNameByHandle
引数: ハンドル, バッファへのポインタ
返り値: バッファへ格納した文字数
使用例: Entry(IRLIB_GetLibNameByHandle, LibHandle, (char far *)NameBuff);

8. get number of instruments

機能: ハンドルで指定されたライブラリに含まれている機器の総数を返します。
定義名: IRLIB_GetNumOfInsts
引数: ハンドル
返り値: 機器数
使用例: Num=Entry(IRLIB_GetNumOfInsts, Handle);

9. get instrument list

機能

バッファに番号に対応する機器名を返します

定義名

IRLIB_GetInstList

引数

ハンドル, 番号, バッファへのポインタ

返り値

バッファに格納された機器名の長さ

使用例

for (i = 0; i %3c InstNum; i++){
	Entry(IRLIB_GetInstList, Handle, i, 
		(char far *)NameBuff);
	printf("\t%d: %s\n", i, NameBuff);
}

10. get handle by instrument number

機能: 番号に対応する機器のハンドルを得ます
定義名: IRLIB_GetHandleByInstNum
引数: ハンドル, 番号
返り値: ハンドル
使用例: InstHandle=Entry(IRLIB_GetHandleByInstNum, Handle, Number);

11. get handle by instrument name

機能: 機器を名前で指定してハンドルを得ます。
定義名: IRLIB_GetHandleByInstName
引数: ハンドル, 機器名へのポインタ
返り値: ハンドル
使用例: Entry(IRLIB_GetHandleByInstName, Handle, (char far *)NameBuff);

12. get instrument name by handle

機能: ハンドルに対応する機器名を得ます
定義名: IRLIB_GetInstNameByHandle
引数: ハンドル, バッファへのポインタ
返り値: 格納した文字数

13. get number of functions

機能: ハンドルで指定された機器に含まれている機能の総数を得ます
定義名: IRLIB_GetNumOfFuncs
引数: ハンドル
返り値: 機能数
使用例: Num=Entry(IRLIB_GetNumOfFuncs, Handle);

14. get function list

機能

番号に対応する機能名を得ます

定義名

IRLIB_GetFuncList

引数

ハンドル, 番号, バッファへのポインタ

返り値

格納した文字数

使用例

for (i = 0; i %3c FuncNum;i++){
	Entry(IRLIB_GetFuncList, Handle, i, 
		(char far *)NameBuff);
	printf("\t%d: %s\n", i, NameBuff);
}

15. get function number by name

機能: 名前でファンクションを指定し対応する番号を得ます
定義名: IRLIB_GetFuncNumByName
引数: ハンドル, 機能名へのポインタ
返り値: 番号

16. send main

機能: 赤外線リモコンデータの主部(main IRD)を送信します
定義名:: IRLIB_SendMain
引数:: ハンドル, 機能番号
返り値:: 0 (if error)
使用例: if(!Entry(IRLIB_SendMain, Handle, atoi(Buff))); puts("error");

17. send repeat

機能: 赤外線リモコンデータの繰り返し部(repeat IRD)を送信します通常のリモコンで、ボタンを押しっぱなしにしたときの状況をつくりだしたいときに使います
定義名:: IRLIB_SendRepeat
引数:: ハンドル, 機能番号
返り値:: 0 (if error)

18. send end

機能: 赤外線リモコンデータの終了部(end IRD)を送信しますリモコンデータの終了を意味するコードを送信します
定義名:: IRLIB_SendEnd
引数:: ハンドル, 機能番号
返り値:: 0 以外:成功、0 失敗

19. get error code

機能: 直前に実行したファンクションのエラーコードを得ます。
定義名:: IRLIB_GetError
引数:: なし
返り値:: エラーコード
使用例: printf("the error code is 0x%0x", Entry(IRLIB_GetError));

戻る佐藤益弘 thomas@fenix.ne.jp