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

API document for IRLIB version 1.10

◎はじめに

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

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

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

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

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

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 は、引数がファンクションにより可変長なので、引数の与え方 を呼出側がスタックを補正するC形式としました。 第1引数をファンクションナンバーとし、後の引数は各ファンクションに依る ものとします。

例.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

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

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

ファンクション 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 で文字列長に0を含めます。また、名前を返すファンクションを呼ぶ ときのバッファは256bytes確保してください。
値を返すファンクションは返り値が0の場合エラーです。
以下の記述で "定義名" は irlib.h, irlib.inc における定義名です。

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