GUIGUI01​/man0002 :: OSASK計画

「ぐいぐい01」のAPI(1)

• (by K, 2008.11.03)

註

• 一応API番号順です。
• API関数名はかなり適当なので、各自#defineで関数名を付け直すといいかもしれません。

通常API

• [000000] なにもしない。NOP。
• [000001] リマーク。skip。
• [000002] システムワークエリアの指定。
• [000003] APIパケット終端。
• [000004] void g01_exit_success()
  • 正常終了。
• [000004] void g01_exit_failure_int32(int i)
  • 異常終了。終了コードとして整数を一つシステムに返す。APIとしては32bit整数として受け取るが、OSによっては下位のビットしか伝わらないかもしれない。
• [000005] void g01_putc(int c)
  • 一文字表示。
• [000005] void g01_puts_c0(文字列定数 len, 文字列定数 str)
  • lenをgh4で書いて使う。例 g01_puts_c0("￥x8d", "hello, world￥n");
  • 意味がよく分からないなら、下のg01_puts_c255()を使うほうがいいだろう。
• [000005] void g01_puts_c255(文字列定数 len, 文字列定数 str)
  • 255バイト以下の文字列をコンソールに出力。
  • g01_puts_c255("￥x0d", "hello, world￥n"); のように使う。

ジャンクAPI 　 すべて[ffffff]のサブファンクション

• [000000] リザーブ。
• [000001] void jg01_getcmdlin(int n, char *p, int *len)
  • コマンドライン文字列取得。現状ではコマンドライン全体が無条件に見える。将来的には、この仕様は廃止され、コマンドライン全体を見る方法はなくなる。
  • 仕様が廃止された後でも、このAPIを使ったアプリを救済するために、このコマンドラインで渡せる文字列を指定する方法が提供される（詳細は未定だが、例： >efg01 app.g01 jg01_cmdlin:"abc def ghi"）。lenには実際の長さが入る。nが*lenよりも小さい場合、文字列はnまでしか格納されない。
• [000002] void jg01_fclose(int slot)
  • ファイルのクローズ。クローズはエラーにならない。というか、エラーの場合は何もしない。アプリの終了時にはオープンしたファイルは正しくクローズされるので、終了処理直前のクローズは省略してよい。
  • API番号の都合で逆になっているが、まずはfopenを読むこと。
• [000003] void jg01_fopen(int mode, int slot, int pathlen, char *path)
  • ファイルのオープン。オープンに成功するか失敗するまで帰ってこない（OSASKのような非同期式ではない・・・手抜きなので）。失敗した場合、slotは無効状態になる。
  • modeのbit0-2 : 0=タスクローカル, 1=ユーザ, 2=マシンローカル, 3=ネットワーク
    • 通常はとりあえず1にしておけばよい。
  • modeのbit3 : ライトするかどうか(1:でライトもする)
  • 以下はライトしない場合
    • modeのbit4 : 0のとき、オープンに先立って同名のファイルがない場合にエラー
  • 以下はライトもする場合
    • modeのbit4 : 1のとき、オープン後にファイルサイズを0にする
    • modeのbit5 : 1のとき、オープン後にファイルポインタを末尾に移動（bit4=0のとき）
    • modeのbit5 : 1のとき、オープンに先立って同名のファイルがある場合にエラー（bit4=1のとき）
  • テキストモードなどというものはない。「ぐいぐい01」での標準的なテキストはCRが入らないものとするが、各アプリにおいてこれをあえて出力するオプションがあってもよい。そしてCRを無視することができない（＝CRがあると誤動作する）テキストツールがあったとしても出来がよければK推奨はでる。
  • slotは4～63が使用可能。
• [000004] void jg01_fread(int slot, int n, char *p, int *len)
  • ファイルからの読み込み。*lenに読み込んだバイト数が返る。0が返るとEOF。-1だとエラー。slotがファイルオープンに失敗した状態でこのAPIを呼び出してもよい。その場合はなんら悪さをすることもなく*lenに-1が返るだけである。
• [000004] void jg01_fwrite(int slot, int n, char *p, int *len)
  • ファイルへの書き込み。サブファンクション番号がfreadと同じなのはミスではない（オプションコードで見分ける）。*lenに書き込めたバイト数が返る。-1だとエラー。slotがファイルオープンに失敗した状態でこのAPIを呼び出してもよい。その場合はなんら悪さをすることもなく*lenに-1が返るだけである。
• [000005] void jg01_fseek32(int mode, int slot, int ofs, int *pos)
  • ファイルポインタの移動・取得・ファイルサイズ変更。API的には32bit制限があるわけではないが、C言語ライブラリ化にあたって32bitに限定した。
• [000006] void jg01_testslot0(int slot, char *p)
  • slotの状態を返す。-1がslot値無効、0が未使用・無効、1がコンソール、2がファイル。
• [000007] void jg01_tekgetsize(char *p, int *dstsiz)
  • tek展開関係。詳細省略。srcsizフィールドがないが、pからは少なくとも32バイトくらいはアクセスできるようにしておくこと。
• [000007] void jg01_tekdecomp(int srcsiz, char *p, char *q, int *retcod)
  • tek展開関係。詳細省略。
• [000007] void jg01_rjc(int mod, int siz, char *p, int ofs0, int oofs, int oofs1, int *retcod)
  • rjc関係。詳細省略。
• [000008] void jg01_malloc(int bytes, void **p)
  • システムからメモリをもらう。これはbss領域の中を切り分けてもらうなどではなく、それとは別に追加でもらうメモリである。失敗する可能性は十分にあり、失敗すると*pに-1が返される。
  • このファンクションでもらったメモリは原則としてデータ用で、ページに実行可能属性を付与されることは保証していない。
• [000008] void jg01_malloc1(int bytes, void **p, int i)
  • システムからメモリをもらう。これはbss領域の中を切り分けてもらうなどではなく、それとは別に追加でもらうメモリである。このAPIは絶対に失敗しない。というのは失敗した場合はしかるべきメッセージが表示されてユーザに連絡した後、g01_exit_failure_int32(i);が直ちに実行されるためである。メッセージの内容は環境に依存する。
  • このAPIはメモリがなければ処理は続行できないという切実な意志をシステムに伝える意味もあり、システムはこのAPIが呼ばれたときにメモリが不足していても安易に異常終了させずに、アプリを少しの間sleepにして、その間にユーザーに対して、このままだと続行できないけどどうするか？何か他の重要ではないアプリを終了させるか？と問い合わせてくる可能性もある。
  • そういう事情により、このAPIを呼んだ場合しばらくアプリに帰ってこられない場合もありうる。それが困る場合は、上記のjg01_malloc()を使用すること。
  • このファンクションでもらったメモリは原則としてデータ用で、ページに実行可能属性を付与されることは保証していない。
• [000009] void jg01_mfree(int bytes, void *p)
  • jg01_malloc()類でもらったメモリを返す。部分的に返すこともできるし、bssの一部などもらってないメモリを返すこともできる。pが-1だと何もしない。アプリの終了時にはメモリは勝手に返されるので、終了処理中にmfreeする必要はない。
  • ちなみにefg01のひどい手抜き実装だと、mfreeが何もしないということもありうる（苦笑）。
• [00000a] void jg01_sleep1(unsigned int unit, unsigned int tim)
  • 指定した時間だけスリープする。待ち時間＝tim*2^(unit-32)[sec]。
• [00000b] int jg01_inkey2()
  • 標準コンソールからキーコードを取得。0の場合はキーバッファが空だった。キーコードはASCIIコードに変換される。Enterは0x0dになる。カーソルキー等は入力できない。
• [00000b] int jg01_inkey3()
  • 上記とほぼ同じだが、こちらは入力があるまで帰ってこない。
• [00000c] void jg01_consctrl4(int x, int y)
  • コンソールの大きさを指定（これをやらずに以下の制御（1と3）はできない）
• [00000c] void jg01_consctrl3()
  • コンソールをクリア
• [00000c] void jg01_consctrl1(int x, int y)
  • カーソルの移動
• [00000c] void jg01_consctrl2(int f, int b)
  • キャラクタの色指定（XRGBによる16色：Xは拡張色ビット）
• [00000d] int jg01_randomseed()
  • 乱数用の種を得る