Chapter 8：
基本的な Max ユーティリティ

ここでは、Max環境と相互に働きかけあうための重要な関数を紹介します。

ドキュメントのこの章以降では、おそらく "sys..." で始まる関連した関数のグループがあることに気がつくことと思います。Max には、オペレーティングシステム特有のタスクの代わりに、これらの "Sys" という数多くの API があります。これらの API には、ファイル、ウィンドウ、メモリ割り当て、およびそれ以外の OS 特有のタスクが含まれています。Max では、 Macintosh からの遺産のため、これらの APIは Macintosh 風な名づけ方や実装のしかたが残っていますが、使われているオペレーティングシステムを問わず、同じように動作します。API はMax の Macintosh OSX と Windows の両バージョンで提供されていて、将来的に追加されていくでしょう。

一般的なユーティリティ

freeobject
     
  freeobject はMaxオブジェクトによって使用されていたメモリを開放する場合に使います。
   
  void freeobject (t_object *obj);
     
  obj 開放するオブジェクト
     
 

freeobjectは、オブジェクト開放関数を呼び出し、オブジェクト自身が使用していたメモリがあればそれを開放します。freeobjectは、Box、Qelem、Atombuf を除く、標準のMaxオブジェクトデータ構造体のインスタンスに対して使用することができます。Clock、 Binbuf、 Proxy、 Toolfile、 Expr、 Ed等はfreeobjectによって開放しなければなりません。

訳注：ヘッダファイル ext.h には、次のようなマクロ定義があるため、clock_free( オブジェクトへのポインタ）でも同様に開放できてしまいますが、これはあくまでもマクロです。これに対し、qelem_free や box_freee は関数です。

#define clock_free freeobject
#define binbuf_free freeobject
#define wind_free freeobject

gensym
     
  文字列を t_symbol に変換する場合に、gensym を使います。
   
  t_symbol *gensym (char *string)
     
  string Maxのシンボルテーブルを参照するためのC文字列。もし該当の文字列が存在しない場合は、新しいシンボルが作られます。
     
 

gensym は、C文字列を受け取り、文字列と結び付けられた t_symbolへのポインタを返します。Maxは、メッセージの受け渡しをする際の高速な探索を行うために、あらゆる文字列からなるシンボルテーブルの保守を行います。例えば bang シンボルにアクセスする場合には、gensym("bang") という式を用いる必要があります。オブジェクトボックスの位置やアーギュメントの他に特別なデータを保存するユーザインタフェイスオブジェクトのpsaveメソッドを書く場合、gensym を使う必要があるでしょう。また、typemess や outlet_anything などのように、他のMaxオブジェクトに直接メッセージを送る場合にも gensym が必要となるでしょう。これらの関数は gensym の文字列ではなく、t_symbol が渡されることを要求します。

t_symbol データ構造体は、任意の値を格納するための場所を持っています。次の例では、この機能を使って、2つの異なるエクスターナルオブジェクトクラス間でシンボルによる値の共有を行なう方法について示しています。（同じクラスのオブジェクトでは、コードリソースのグローバル変数をデータ共有のスペースとして使うことができます。）このアイデアは次のようなものです。t_symbol の s_thing フィールドには、ある値をセットすることができます。そして gensym はSymbolへの参照を返します。このようにして、まさに2つのクラスで、使われている文字列が一致することになります。言い換えると、各々のオブジェクトがデータの共有に使われる t_symbol の受け渡しを行うことができるようになります。

値の格納:

t_symbol *s; s = gensym("some_weird_string"); s->s_thing = (t_object *)someValue;

値の取得:

t_symbol *s; s = gensym("some_weird_string "); someValue = s->s_thing;

post
     
  Maxウィンドウにテキストを表示する場合に post を使います。
   
  void post (char *fmtstring, void *items...);
     
  fmtstring テキストと、printf と同様なフォーマット文字を含むC文字列。後に続く引数のサイズを指定し、フォーマットを行います。
  items fmtStringのフォーマットコードに適合する任意の型の引数
     
 

post はMaxウィンドウのための printf です。これは割込みレベルで動作し、メインイベントレベルの処理がリジューム（再開）される際に、表示するテキストの4行までをキューに入れます。post はあなたのエクスターナルオブジェクトのデバッグに非常に役立ちます。

post は引数の16バイトを sprintf に渡すだけである点に注意して下さい。フォーマットされた追加の項目を1行で表示する必要がある場合は postatom を使います。

例：

short whatIsIt; whatIsIt = 999; post ("the variable is %ld",(long)whatIsIt);

このコードが実行された場合のMaxウィンドウの表示は次のようになります。

the variable is 999

error
     
  Maxウィンドウにエラーメッセージを表示する場合に error を使います。
   
  void error (char *fmtstring, void *items...);
     
  fmtstring テキストと、printf と同様なフォーマット文字を含むC文字列。後に続く引数のサイズを指定し、フォーマットを行います。
  items fmtStringのフォーマットコードに適合する任意の型の引数
     
 

error関数は、postと同様に printf スタイルのテキスト行を1行、Maxウィンドウに表示しますが、テキストの前にはエラーに注意を向けるための「* error」という文字列がつけられます。エラー表示にこのルーチンを使用することによって、ユーザに、errorオブジェクトを使ったメッセージへの割り込みを実行させている点に注意して下さい。

例：

error ("bad arguments to %s",myclassname);

Maxウィンドウの出力

* error: bad arguments to myclass

postatom
     
  複数の項目をMaxウィンドウのテキストの同じ行に表示する場合、postatom を使います。
   
  void postatom (t_atom *item);
     
  item 表示されるAtom。正確なフォーマットはAtomの a_type フィールドに従って行われます。
     
 

この関数は1つのAtomをMaxウィンドウの1行に表示しますが、postのように語の後にキャリッジリターンをつけることはしません。個々のAtomの後にはスペース文字が追加されます。Maxの print オブジェクトはリストを表示するために postatom を使っています。


ouchstring
     
  スクリーン上に、エラーあるいはアドバイスをあたえるアラートボックスを表示する場合、ouchstring を使います。
   
  void ouchstring (char *fmtstring, void *items...);
     
  fmtstring テキストと、printf と同様なフォーマット文字を含むC文字列。後に続く引数のサイズを指定し、フォーマットを行います。
  items fmtStringのフォーマットコードに適合する任意の型の引数
     
 

この関数は fmtstring と items によってsprintfのような働きをしますが、これをアラートボックスに表示します。ouchstring は割込みとして呼び出され、以前に要求されたアラートボックスがペンディング（保留）になってない場合、メッセージを低い優先レベルのキューに入れます。

ouchstringの使用例を１、２回はMaxで見たことがあるかも知れません。Maxのユーザインタフェイススタイルでは、エラーメッセージはMaxウィンドウに表示し、できるだけエラーダイアログを使用しないようにすることを推奨しています。

sprintf
     
  文字列をフォーマットする場合に、 sprintf を使います。
   
  short sprintf (char *dest, char *fmtString, void *items...);
     
  dest フォーマットされたC文字列がここに置かれます。
  fmtstring テキストと、printf のようなフォーマット文字を含むC文字列。後に続く引数のサイズを指定し、フォーマットを行います。
  items fmtStringのフォーマットコードに適合する任意の型の引数。
     
 

これは、Max カーネル内で、一般的なCライブラリ関数sprintf へのアクセスを提供するものです。そのため、あなたのエクスターナルコードリソースへこれをリンクする必要はありません。


sscanf
     
  テキストをバイナリデータに変換する場合に、sscanf を使います。
   
  short sscanf (char *src, char *fmtString, void *items...);
     
  src テキストを読み込むためのC文字列。
  fmtstring テキストと、printf のようなフォーマット文字を含むC文字列。これはサイズを指定し、後に続く引数のフォーマットを行います。
  items fmtStringのフォーマットコードに適合する任意の型の引数。
     
 

これは、Max カーネル内で、一般的なCライブラリ関数sscanf へのアクセスを提供するものです。そのため、あなたのエクスターナルコードリソースへこれをリンクする必要はありません。

maxversion
     
  現在のMax環境についての情報を得たい場合に、maxversion を使います。
   
  short maxversion (void);
     
 

この関数はMaxのバージョンを返します。Maxのバージョン2.1.4以降では、この値はMaxカーネルアプリケーションのバージョンナンバを2進化10進数で表したものになります。従って、2.1.4ならば16進数の214Hまたは10進数の532になります。バージョン3.0の場合は、16進数の300Hを返します。Maxのより新しいバージョンで新たに提供された特定の関数マクロの存在をチェックする場合にこれを使用します。2.1.4より前のバージョンでは1を返しますが、バージョン2.1.1-2.1.3の場合に限り2を返します。第14ビット（左から数えて）はMaxがスタンドアロンアプリケーションとして実行される場合にセットされます。このため、バージョンナンバを得るためには、下位12ビットをマスクする必要があります。


assist_string
     
  ユーザに、オブジェクトのインレットやアウトレットについての情報を提供する場合、assist_string を使います。
   
 

void assist_string (short rsrcID, long message, long arg, short firstin, short firstout,char *dstString, ...);

     
  rsrcID アシスタンス情報を持つ'STR#'リソースのID。このリソースはあらかじめrescopyによってMaxのテンポラリリソースファイルにコピーされていなければなりません。
  message ASSIST_INLETまたはASSIST_OUTLETによってアシスタンスがインレット用かアウトレット用かを指定します。この値はあなたのアシスタンスメソッドに引数として渡されます。
  arg 解説するインレットまたはアウトレット。値は0から始まります。この値は、あなたのアシストメソッドに引数として渡されます。
  firstin インレットについて説明している'STR#'リソースの最初の文字列のインデックス（1で始まり、相対的に指定）。通常1になります。
  firstout アウトレットについて説明している'STR#'リソースの最初の文字列のインデックス。
  dstString
...

リソースから抜き出された文字列がここにコピーされます。このポインタはアシストメソッドに引数として渡されますが、アシスト文字列をテンポラリの文字配列から呼び出し、それに追加の処理を行うこともできます。結果は、C文字列になります。

assist_stringへの追加の引数として最高16バイトを渡すことができます。これはsprintfヘ渡されますが、sprintf はリソースからコピーされた文字列をフォーマット済み文字列として使用します。。

     
 

このルーチンはassist メソッドの実装に役立ちます。次はその例です。ここでは、2つの文字列がオブジェクトのSTR#リソース ID 4534 に保存してあるものと仮定します。文字列は次のようなものです。

Sets the Value of the Bludgeon (Currently %ld) Outputs a bludgeon Message

このとき、このオブジェクトのアシストメソッドで次のように書くことができます。

void myobject_assist(MyObject *x, void *b, long msg, long arg, char *s) { assist_string(4534,msg,arg,1,2,s,x->m_bludgeon); }

drawstr
     
  C文字列を描画する場合に、drawstr を使います。
   
  void drawstr (char *str);
     
  str 現在のペン位置に、現在設定されているフォントとサイズで描画されるC文字列。

quittask_install
     
  　Maxの終了時に呼び出される関数を登録する場合に、quittask_install を使います。
   
  void quittask_install(method m, void *a);
     
  m Max の終了時に呼び出される関数
  a

メソッド m で使用されるアーギュメント

     
  quicktask_instll は、あなたのエクスターナルに対して、Maxがシャットダウンする直前に呼び出されるルーチンを登録しておくメカニズムを提供します。これは、Maxにおける標準の記憶装置メカニズム以外にディスク上に展開する領域を必要とするオブジェクトにとって、あるいは、ハードウェアやシステムソフトウェアとのコネクションを閉じる必要があり、コードフラグメントの終了ルーチンによってそれを行うことができない場合に役に立ちます。

quittask_remove
     
  quittask_installで登録した関数の登録を解除する場合に、quittask_removeを使います。
   
  void quittask_remove(method m);
     
  m シャットダウンメソッドとしての登録を解除する関数
     
  このルーチンによって、オブジェクトはすでに登録されているシャットダウンメソッドを任意に取り除くことができます。

object_subpatcher
     
  オブジェクトがサブパッチャーを含んでいるかどうかを判断するために、 object_subpatcher を使います。
   
  void *object_subpatcher(t_object *theobject, long *index, void *arg);
     
  theobject 問い合わせを受けるオブジェクト。
  index 返されるサブパッチャーのインデックス。最初の呼び出しでは0がセットされます。
  arg パッチャールーティンに渡されるアーギュメント。これは、主にMax内部で使用されます。
     
 

object_subpatcherはオブジェクトに「含まれる」どのようなパッチャーでもリストします。例えば、patcher や bpatcher オブジェクトはパッチャーを含んでいます。MSPオブジェクトの poly~ も同様なことを行ないます。

引数 index はobject_subpatcherの呼び出しの間にセットされます。0でない値が返された場合（サブパッチャーが見つかったことを意味します）、引数 index は返されたパッチャーへのポインタのインデックスナンバにセットされます。オブジェクトに関係付けられたすべてのパッチャーを見つけるためには、object_subpatcher が0を返すまで呼び出します。

メモリ管理ルーチン

リアルタイムのMax環境で動作するメモリ割当てのための関数がいくつか用意されています。Maxは割り込みレベルで割り当てることができる少量のメモリを保守します。これは、メモリマネージャがリエントラント（再入可能）でないため、割り込みレベルで標準のMacintoshのメモリ割り当て呼び出しが使用できないためです。割り込みレベルでのメモリ割当ての量が50%以上減少させられた場合、Maxがメインイベントレベルに戻った時に割り当てが補われます。

newhandle、disposhandle ルーチンはMacintoshの割り込みであるNewHandle、DisposeHandleの代りに使用されます。これらは、Maxのスキーム内で動作するため、メモリ割り当てがオペレーティングシステムが使用するために緊急用にリザーブされているメモリまで達してしまった場合、割り当てを中止してメモリ不足エラーを防ぎます。割込みレベルで呼び出された場合にも割り当ては行なわれません。

newhandle
     
  リロケータブル（再配置可能）なメモリの割当てを行う場合に、newhandleを使います。
   
  char **newhandle (long size);
     
  size バイト単位による割当てサイズ
     
 

この関数はNewHandleの代わりに用いられ、いくつかのエラーチェックを行います。また、割込みレベルで呼び出された場合にはNewHandleの呼び出しを行いません。


disposhandle
     
  必要のなくなったハンドルによって使用されているメモリの開放を行う場合に、disposehandleを使います。
   
  void disposhandle (char **handle);
     
  handle 処理されるMacintoshのハンドル
     
 

この関数は、Macintoshの割り込みである DisposeHandle を呼出します。割込みレベルでは呼出しを行わず、NIL値を返します。

growhandle
     
  ハンドルのサイズを変更する場合に、growhandleを使います。
   
  void growhandle (char **handle, long size);
     
  handle サイズ変更が行われる、Macitoshのハンドル
  size バイト単位による新しいサイズ
     
 

この関数はSetHandleSizeの代わりに用いられ、割込みレベルでの動作を拒否するためにいくつかのエラーチェックを行います。


getbytes
     
  非リロケータブル（再配置不可）な少ない量のメモリを割当てる場合に、getbytes を使います。
   
  void *getbytes (short size);
     
  size バイト単位による割当てサイズ
     
 

getbytes はNewPtrの代わりに、Maxによって管理されるプールからメモリを確保します。この呼び出しによって、32767バイトまでのメモリを要求することができます。サイズが16384バイトより大きい場合、getbytes は MacintoshのNewPtrルーティンを呼出します。このサイズでの要求が割込みレベルで行われた場合、 getbytes は0を返し、次のようなメッセージをMaxウィンドウに表示します。

･ check failed: t_newptr in overdrive

getbytes によって使用されるメモリプールは、どのような割込みの場合でも、Maxのバージョン4で256K、バージョン3で128K、それ以前のバージョンでは32Kまでに限られています。同様な "t_newptr in overdrive" というメッセージは、割込みレベルで割り当てようとする小さなメモリチャンクの数が多すぎる場合にも表示されます。これは、getbytes が非リロケータブル（再配置不可）なメモリプールに補給するためにNewPtrを使用するからです。getbytesで割当てられたメモリは、常にfreebytesによって開放されます。そのため、freebytes には、getbytes によって割り当てられたブロックサイズを渡す必要がある点に留意して下さい。


freebytes
     
  getbytes によって割当てられたメモリを開放する場合に、freebytes を使います。
   
  void freebytes (void *ptr, short size);
     
  ptr すでに割当てられていて、これから開放しようとするメモリブロックへのポインタ。
  size バイト単位によるこのブロックのサイズ。
     
 

getbytes と同様、freebytes は16384 バイトまでのブロックの処理を行なうために、割込みレベルで呼び出される可能性があります。

getbytes16
     
  ベクタ最適化のために16バイトサイズに調整された少量の非リロケータブルメモリの割当てを行う場合に、 getbytes16 を使用します。
   
  void *getbytes16 (short size);
     
  size バイト単位による割当てサイズ.
     
 

getbytes16は16バイトサイズに調整されたメモリを返すという以外は、getbytes と同様です。これによって、割込みレベルでベクタ最適化メモリとして記憶装置を割当てることができます。getbytes16によって割当てられたメモリは、必ずfreebytes16によって開放されなければならない点に注意して下さい。freebytes は使用できません。


freebytes16
     
  getbytes16によって割当てられたメモリを開放する場合、freebytes16を使用します。
   
  void freebytes16 (void *ptr, short size);
     
  ptr

すでにgetbytes16によって割当てられていて、これから開放しようとするメモリブロックへのポインタ
  size

バイト単位によるこのブロックのサイズ。
     
 

freebytes16にgetbytesによって割当てられたメモリを渡した場合、メモリ破壊が生じる点に注意して下さい。これはgetybytes16によって割当てられたメモリに対してのみ使用して下さい。

Sysmem API

System API はメモリ管理、割り当てのための多くのユーティリティを提供します。これは、Macintosh のメモリマネージャAPIと比較的よく似ていて、C の標準ライブラリと大きく異なるものではありません。これらのユーティリティを他のメモリルーチンと混ぜ合わせて使うことは、安全ではありません。（すなわち、malloc でメモリを割り当てたポインタを system_freeptr　で開放しないようにするということです）

sysmem_newptr
     
  メモリを割り当てる場合に、system_newptr を使います。
   
  t_ptr sysmem_newptr(long size);
     
  size 割り当てられるメモリをバイト単位で表した量。
     
 

この関数は、NewPtr や malloc と同様なものです。与えられたバイト数のメモリを割り当て、それへのポインタを返します。


sysmem_newptrclear
     
 

メモリを割り当て、それを０にセットします。
   
  t_ptr sysmem_newptrclear(long size);
     
  size 割り当てられるメモリをバイト単位で表した量。
     
 

この関数は、NewPtrClear や calloc と同様なものです。与えられたバイト数のメモリを割り当て、そのメモリをすべて0にして、それへのポインタを返します。


sysmem_resizeptr
     
  既存のポインタのサイズを変更する場合、sysmem_resizeptr を使います。
   
  t_ptr sysmem_resizeptr(void *ptr, long newsize);
     
  ptr サイズ変更されるメモリへのポインタ
  newsize ポインタに割り当てる新しいサイズのバイト数。
     
 

この関数は realloc と同様なものです。既存のポインタの指すメモリのサイズを変更し、変更されたサイズのメモリへのポインタを返します。


sysmem_ptrsize
     
  ポインタの指すメモリサイズを得る場合、system_prtsize を選択します。
   
  long sysmem_ptrsize(void *ptr);
     
  ptr サイズの問い合わせを受けるポインタ
     
 

この関数は _msize と同様なものです。指定されたポインタに割り当てられているメモリのバイト数を返します。


sysmem_freeptr
     
  sysmem_newptrで割り当てられたメモリを開放する場合、sysmem_freeptr を返します。
   
  void sysmem_freeptr(void *ptr);
     
  ptr 開放するメモリへのポインタ
     
 

この関数は、DispozePtr や free と同様なものです。与えられたポインタに割り当てられているメモリを開放します。


sysmem_copyptr
     
  ファイルの一部をディスクに書き出す場合、sysmem_copyptr を使います。
   
  void sysmem_copyptr (const void *src, void *dst,long bytes);
     
  src コピーされるメモリへのポインタ
  dst データをコピーする場所へのポインタ
  bytes コピーされるデータのバイト数
     
 

この関数は、BlockMove や memcpy と同様なものです。src のメモリの内容を dst のポインタが指す場所へコピーします。


sysmem_newhandle
     
  　ハンドル（ポインタへのポインタ）に対してメモリを割り当てる場合、sysmem_newhandle を使います。
   
  t_handle sysmem_newhandle(long size);
     
  size ハンドルに割り当てられるメモリのバイト数
     
 

この関数は　NewHandle と同様なものです。与えられたバイト数をハンドルに割り当て、t_handle を返します。


sysmem_resizehandle
     
  既存のハンドルのサイズを変更するために、sysmem_resizehandle を使います。
   
  long sysmem_resizehandle(t_handle handle, long newsize);
     
  handle サイズ変更されるハンドル
  newsize ハンドルの新しいサイズのバイト数
     
 

この関数は　SetHandleSize と同様なものです。既存のハンドルのサイズを指定したものに変更し、指定したハンドルに割り当てられたメモリのバイト数を返します。


sysmem_handlesize
     
  ハンドルのサイズを求める場合に、sysmem_handlesize を使います。
   
  long sysmem_handlesize(t_handle handle);
     
  handle 問い合わせを受けるハンドル
     
 

この関数は GetHandleSize と同様のものです。指定されたハンドルに割り当てられたメモリのバイト数を返します。


sysmem_freehandle
     
  sysmem_newhandle で割り当てられたメモリを開放する場合、sysmem_freehandle を使います。
   
  void sysmem_freehandle(t_handle *handle);
     
  handle メモリを開放されるハンドル
     
 

この関数は、DispozeHandle と同様のものです。与えられたハンドルに割り当てられたメモリを開放します。


sysmem_lockhandle
     
  ハンドルのロック／アンロックの状態をセットする場合、sysmem_lockhandle を使います。
   
  long sysmem_lockhandle(t_handle handle, long lock);
     
  handle ロックされるハンドル
  lock ハンドルの新しいロックの状態
     
 

この関数は、HLock や HUnlock と同様のものです。これは、ハンドルのロック状態を０あるいは0以外の値によって設定し、以前のロック状態を返します。


sysmem_ptrandhand
     
  既存のハンドルにメモリを追加し、その変更された部分にポインタからメモリをコピーする場合に、　sysmem_ptrandhand を使います。
   
  long sysmem_ ptrandhand (void *p, t_handle h, long size);
     
  p 既存のポインタ。このデータがサイズを変更したハンドルにコピーされます
  h ポインタのサイズだけ大きくサイズ変更されるハンドル
  size ハンドルに追加されるバイト数
     
 

この関数は、PtrAndHand と同様なものです。既存のハンドルに、与えられたバイト数を追加することによってサイズ変更し、そこにポインタからデータをコピーします。指定されたハンドルに割り当てられたバイト数を返します。


ファイルルーチン

これらのルーチンは、Maxサーチパス内にユーザファイルを置く場合だけでなく、あなたのオブジェクトが標準ファイルパッケージを使ってファイルを開いたり保存したりするのを助けます。これらのルーチンには（多くの関数の追加だけでなく）かなりな数の重要な変更点がありますが、その変遷を知っておくことは、これらの使用法を理解する上で役に立つと思います。

Maxのバージョン4までは、ファイルを指定するために「ワーキングディレクトリ」と呼ばれるMac OS9の機能を使っていました。locatefileサービスルーチンを使用すると、ファイル名とボリュームナンバを受け取ることができます。この名前（パスカル文字列に変換されています）とボリュームナンバはFSOpenに渡され、その場所にあるファイルを読込むためににオープンします。open_dialogルーチンも同様に働きます。

Max OS X では、ワーキングディレクトリはもはやサポートされていません。加えて、「ボリューム」ナンバの使用は、Maxのファイルルーチンを、絶対パス名（例えば、"C:\dir1\dir2\file.pat"というようなファイル名）を使用してファイルを指定するWindows XPのような他のオペレーティングシステムへ移植することをいくぶん困難にしています。

しかし、パスとファイル名を別々に参照することができることは役に立ちます。Max4の解決策には、ボリュームナンバ（パスIDと呼ばれています）の保存が含まれていますが、これは、その意味を解釈できる、プラットフォームから独立したラッパー（wrapper）によって行なわれます。ファイルの場所の指定、オープン、選択をC文字列とパスIDで行う呼び出しがありますが、同様に、ファイル指定のためのネイティブなフォーマット（Windowsのプルパス名やMacintoshのFSSpec等）と、C文字列とパスIDとの間の変換を行なうルーチンもあります。

Max4でのパス取り扱いシステムは2つのモードで動作します。コンパチビリティモードでは、パスIDはワーキングディレクトリの参照として働きます。このモードは、ユーザがMaxフォルダの中に、Path_Compatibilityと呼ばれるファイルを持っている場合に指定されます。ファイルが存在しない場合、パスIDはMaxカーネルによって保守されているパスのテーブルのインデックスになります。これらのパスはホストオペレーティングシステムに固有なフォーマット（MacではFSSpec、Windowsではフルパス名）で内部に保存されています。

パスコンパチビリティモードはオブジェクトがMax4のファイル処理用にアップデートされていない場合にのみ必要となります。すべてのオブジェクトがアップデートされた後は、コンパチビリティモードを使用する必要はありません。

ネイティブパスフォーマットは PATH_SPEC と呼ばれます。これは、個々のターゲットとなるプラットフォームによって異なった定義が行われます。PATH_SPEC を直接扱うコード（ファイルの内容の読み書きを行うようなコードや、後日それらを取り扱うかも知れない場合）はすべて、プラットフォーム依存のものであると考えなければなりません。

現在では、Max におけるパスは、旧式のMacintosh の「コロンスタイル」から、「スラッシュスタイル」を使うように変更されているため（Max 4.3 ドキュメントのファイルパススタイルに関する説明を参照して下さい）、様々な方法で示されるパスをカバーするための特別な関数が１つあります。これは、オペレーティングシステムのネイティブなパス表示を含め、様々な方法で表されるパスの間の変換を行なうために特に役立つものであることがわかるでしょう。この関数は、path_nameconform と呼ばれるものです。互換性を目的として パス API 関数は多くのスタイルのパスを受け入れますが、一般的に、パスは新しいスラッシュスタイルで使うように返され、あるいはインラインで修正されます。絶対パスに加えて、Max フォルダ、"Cycling'74" フォルダ、ブートボリュームからの相対パスもサポートされます。パスの様々なスタイルやタイプについての詳細は、conformpath.help や ext_path.h ファイルを参照して下さい。path 関数を使って、Max の名前とパスの参照用のペアをCreateFileで使用するためのWindows のネイティブパスにコンバートする方法の実例は、"filebyte" SDK サンプルプロジェクトを参照して下さい。

Max4のカーネルには、ファイルをサポートする多くのサービスルーチンがあります。しかし、大部分のエクスターナルオブジェクトで必要となるのはそのうちのほんの一握りです。加えて、後ほど説明するように、SDKに含まれるムービー、フォルダ、ファイル日時に関するサンプルを調べる必要があります。

open_dialog
     
  ユーザに標準のファイルオープンダイアログを提示する場合、open_dialog を使います。
 
  short open_dialog (char *filename, short *path, OSType *dstType, SFTypeList typelist, short numtypes);
     
  filename ユーザがオープンしようとするファイル名を受け取るC文字列。
  path ユーザがオープンしようとするファイルのパスIDを受け取ります。
  dstType ユーザがオープンしようとするファイルのファイルタイプ。
  typelist 表示するファイルタイプのリスト、これはSFGetFile割込みのように4つに限られてはいません。0を渡すとすべてのファイルタイプを表します。
  numtypes タイプリストのファイルタイプの数。0を渡すとすべてのファイルタイプを表します。
     
 

この関数は、Mac OSのナビゲーションサービスやファイルをオープンするための標準ファイルシステムのラッパーとして使用するのに便利です。open_dialogは、ユーザがダイアログボックスでOpenをクリックした時に0を返し、filenameにC文字列に抽出されたファイル名を、pathにそのボリューム参照ナンバを、dstType にそのファイルタイプを渡します。ユーザがキャンセルした場合、open_dialogは0以外の値を返します。

Maxファイルで使用される標準のタイプは、バイナリファイルでは 'maxb'、テキストファイルでは'TEXT'です。


saveas_dialog
     
  ユーザに標準のファイル保存ダイアログを提示する場合に、saveas_dialog を使用します。
   
  short saveas_dialog (char *filename, short *path, short format);
     
  filename 保存するファイルのデフォルトのファイル名のC文字列。ユーザがファイルの保存を決定した場合、そのファイル名はここに返されます。
  path ユーザがファイルの保存を決定した場合、選択された場所のパスIDがここに返されます。
  format ファイルを保存する場合の、デフォルトのMaxファイルフォーマット。formatが2に設定された場合は、通常のバイナリモードが選択されます。formatが0の場合は、Textが選択されます。ユーザがファイルの保存を決定した場合、選択されたファイルフォーマットはここに返されます。formatにshortへのポインタの代わりに0Lを渡すと、ファイルをバイナリで保存するか、キストで保存するかの選択はユーザに提示されません。これは、あなたのオブジェクトのファイルが、常に特別なフォーマットで保存される場合に適しています。format 1はMaxの前のバージョンで保存を行う際に "Old Format"として使用されていたものですが、現在ではサポートされていません。
     
 

この関数は、ナビゲーションサービスやファイルをオープンするための標準ファイルシステムのラッパーとして使用するのに便利です。これは、ユーザがファイルを保存する際に、テキストとして保存するか、バイナリフォーマットで保存するかのオプションを提供できるので、Binbuf を保存する場合に適しています。 saveas_dialog は、ユーザがファイルの保存を選択した場合には0を返し、キャンセルした場合には0以外の値を返します。


saveasdialog_extended
     
 

ユーザに、独自のファイルタイプリストを持つファイル保存ダイアログを提示したい場合、 saveasdialog_extended を使用します。
   
 

short saveasdialog_extended(char *filename, short *path,long *type ,long *typelist, short numtypes);

     
  filename 保存するファイルのデフォルトのファイル名のC文字列。ユーザがファイルの保存を決定した場合、そのファイル名はここに返されます。
  path ユーザがファイルの保存を決定した場合、選択された場所のパスIDがここに返されます。
  type ユーザに選択されたファイルタイプを返します
  typelist ユーザに提示されるファイルタイプリスト。
  numtypes タイプリストに表示されるタイプの数。
     
 

saveasdialog_extendedは、使用できるファイルタイプリストの指定を可能にする機能が追加されているという点以外はsaveas_dialogと同様です。これはポップアップメニューで表示されます。

タイプリストの引数で表示できるファイルタイプは、次に述べるような良く知られたMaxタイプにマッチしていなければいけません。マッチしないタイプは、単にタイプ名が表示されるだけです。（例えば、"foXx"は標準のタイプではないので、ポップアップメニューではfoXxと表示されます。

すでに知られているファイルタイプは次のようなものです。

TEXT- テキストファイル

maxb−Maxバイナリパッチャー

maxc−Maxコレクティブ

Midi−MIDIファイル

Sd2f−Sound Designer II オーディオファイル

NxTS−NeXT/Sun オーディオファイル

WAVE−WAVE オーディオファイル

AIFF−AIFF オーディオファイル

mP3f−Max 初期設定ファイル

PICT−PICTグラフィックファイル

MooV−Quicktimeムービーファイル

aPcs−VSTプラグイン

AFxP−VSTエフェクトパッチデータファイル

AFxB−VSTエフェクトバンクデータファイル

DATA−Rawデータ、オーディオファイル

ULAW−NeXT/Sunオーディオファイル


open_promptset
     
  open_dialog で表示されるファイルオープンダイアログにプロンプトメッセージを付け加えたい場合 open_promptset を使用します。
   
  short open_promptset (char *prompt);
     
  prompt ダイアログボックスに表示したいプロンプトのC文字列
     
 

open_dialogの前にこの関数を呼び出すことによって、ダイアログボックスに文字列を表示し、ファイルをオープンするためにユーザを導くことができます。これは、open_promptsetの直後にopen_dialogを呼び出した場合にのみ適用されます。


saveas_promptset
     
  saveas_dialog、またはsaveasdialog_extendedで表示されるファイルオープンダイアログにプロンプトメッセージを付け加えたい場合、saveas_promptsetを使用します。
   
  short saveas_promptset (char *prompt);
     
  prompt ダイアログボックスに表示したいプロンプトのC文字列
     
 

saveas_dialogの前にこの関数を呼出すことによって、ダイアログボックスに文字列を表示し、ファイルをセーブするようにユーザを誘導することができます。これは、saveas_promptsetの直後にopen_dialogを呼出した場合にのみ適用されます。


defvolume
     
  　ユーザが最後にアクセスしたボリュームまたはディレクトリを得るためには、defvolumeを使用します。
   
  short defvolume (void);
     
 

この関数は、最後にファイルがオープンされたボリュームまたはフォルダのパスIDを返します。このルーチンは path_getdefault ルーチンと同じ働きをします。


locatefile
     
  ファイル名で、サーチパス内のMaxドキュメントを探索する場合に、locatefile を使用します。
   
  short locatefile (char *filename, short *path, short *binary);
     
  filename

探索するファイル名のC文字列
  path

探索するファイルが見つかった場合、その場所のパスID
  binary 見つかったファイルがバイナリフォーマット（maxbタイプ）の場合、ここに1が返されます。テキストフォーマットの場合には0が返されます。
     
 

locatefileは、カレントのデフォルトパス（path_getdefaultを参照）やMaxアプリケーションが存在するディレクトリと同様に、ユーザーがFile Preferences　ダイアログでパッチャーファイルやテーブルの検索用に指定したディレクトリも検索します。

locatefileは、filenameで指定された名前のファイルが見つかると0を返し、そうでない場合は0でない値を返します。ファイルのパスIDはpathに返されます。ファイルがMaxのバイナリフォーマットの場合、binaryは0以外の値になり、テキストフォーマットの場合は0になります。filenameと path （訳注：原文ではvol）は、ファイルのオープン、読込みを行うために binbuf_read に渡すことができます。Maxplay を使う場合には、サーチパスはMaxplayアプリケーションが存在するディレクトリ、およびその全てのサブディレクトリで構成されたものになります。locatefileは'maxb'および'TEXT'タイプのファイルのみを検索します。

locatefiletype
     
  名前で指定されたファイル、またはファイルタイプとクリエータで指定されたファイル、およびその両方を指定されたファイルをサーチパス内で探す場合、locatefiletypeを使います。
   
  short locatefiletype (char *filename, short *path, OSType filetype, OSType creator);
     
  filename

探索するファイル名のC文字列
  path

探索するファイルが見つかった場合、その場所のパスID
  filetype 探索するファイルのファイルタイプ。0Lが渡されるとあらゆるファイルタイプのファイルが対象となります。
  creator 探索するファイルのクリエータ。0Lが渡されるとあらゆるクリエータのファイルが対象となります。
     
 

この関数は locatefile と同様なディレクトリを探索しますが、あなた自身でファイルタイプとクリエータを指定することができます。これに対しlocatefileはMaxのファイルの標準タイプであるの'maxb'と'TEXT'だけを探索します。locatefiletypeは探索に成功すると0を返し、そうでなければ０以外の値を返します。


locatefile_extended
     
  サーチパス内のMaxドキュメントをファイル名で検索する場合、locatefile_extended を使用します。これはMax4で推奨される方法です。
   
 

short locatefile_extended(char *name, short *outpath, long *outtype, long *typelist, short numtypes);
     
  name 探索するファイル名。実際のファイル名を受け取ります。
  outpath ファイルのパスID（見つかった場合）
  outtype ファイルのファイルタイプ（見つかった場合）
  typelist 探索したいファイルタイプ（複数可）
  numtypes タイプリスト配列のタイプの数。（1つならば1)
     
 

Max4では既存のファイル探索ルーチンlocatefileとlocatefiletypeが今まで通りサポートされていますが、新しいルーチンlocatefile_extendedの使用を強く推奨します。しかし、locatefile_extendedには locatefile や locatefiletypeとの間に重要な相違点があり、そのため多少のコードの変更が必要となります。それは、この関数では、ある特定のケースで name パラメータの変更が行なわれるということです。これは locatefile や locatefiletype では生じません。入力されて来るファイル名の文字列を変更するケースには、1)エイリアスが指定された場合には、エイリアスで指定されたファイルが返される、2)フルパスが指定された場合には、ファイル名にそのフォルダのパスナンバを加えたものが出力される、の2つがあります。

このことは、t_symbolの s_name フィールドが locatefile に渡されることが多いため重要です。 シンボルの name フィールドが変更された場合、シンボルテーブルは破壊されてしまいます。この問題を避けるためには、まず、strcpy　を使って次のように　t_symbo lの内容を文字列にコピーします。

char filename[256]; strcpy(filename,str->s_name); result = locatefile_extended(filename,&path,&type,typelist,1);

nameinpath
     
  Maxサーチパス内で指定したフォルダを検索する場合に、nameinpath を使用します。
   
  short nameinpath(char *name, short *path);
     
  name 検索するファイル名
  path 検索するパスID

genpath
     
  PATH_SPECからパスIDを生成する場合に genpath を使用します。
   
  short genpath(PATH_SPEC *fs);
     
  fs 有効なPATH_SPEC
     
 

genpathは有効なPATH_SPECにパスIDを返します。PATH_SPECがすでにMaxのパステーブルで検索されている場合、存在するパスIDが返されます。そうでない場合、新しいパスIDが作成され、パスはMaxパステーブルに追加されます。


path_lookup
     
  PATH_SPECが Max のパステーブルにすでに存在するかどうかを調べたい場合、path_lookup を使用します。
   
  short path_lookup(PATH_SPEC *fs);
     
  fs 有効なPATH_SPEC
     
 

PATH_SPECがパステーブルで見つかった場合は、カレントのパスIDが返されます。見つからなかった場合には path_lookup は0を返します。


path_new
     
  PATH_SPEC を Maxのパステーブルに追加したい場合に、path_new を使用します。
   
  short path_new(PATH_SPEC *fs);
     
  fs 有効なPATH_SPEC
     
 

path_new はパステーブルに PATH_SPEC を追加し、パスIDを返します。エラーが生じた場合や、新たなパステーブルエントリへのメモリ割当てに失敗した場合、このルーチンは0を返します。


path_tospec
     
  パスIDと名前の組み合わせによって PATH_SPEC をロードする場合に、path_tospec を使用します。
   
  short path_tospec(short path, char *name, PATH_SPEC *fs);
     
  path パスIDまたは0（引数nameがプルパスで指定されている場合)
  name ファイル名（ファイル名、部分的なパス、またはフルパスを含むことも可能です)
  fs このルーチンで読込まれる PATH_SPEC 構造体
     
 

path_tospec は、パスIDとファイル名を与えると、ファイルに対する完全な形の PATH_SPEC を返します。 name がフルパスで与えられる場合には、pathに0をセットすることができます。戻り値はMacOSのファイルシステムコールと同様に、成功した場合は値0、失敗した場合は0以外（この値がエラーコードを表す場合があります）の値が返されます。


path_nameconform
     
  ファイルパスの形式をあるスタイルから他のスタイルにコンバートする場合に、path_nameconform を使います。
   
  short path_nameconform(char *src, char *dst, longstyle, long type);
     
  src コンバート元の文字列へのポインタ
  dst コンバート先の文字列へのポインタ
  style コンバートするファイルパススタイル (スラッシュスタイル, コロンスタイル, etc…).
  type コンバート先のファイルパスタイプ (絶対パス, 相対パス, etc…).
     
  指定したスタイルとタイプを用いて、コンバート元のパス文字列をコンバート先のパス文字列に変換します。以下のようなスタイルに変換できます。

  PATH_STYLE_MAX 現行のバージョン4.3の Max のパススタイルは、スラッシュスタイルです
  PATH_STYLE_NATIVE オペーレーティングシステムのネイティブなパススタイル
  PATH_STYLE_COLON Max 4.1 以前で用いられていた、MacOS 9 のパススタイル
  PATH_STYLE_SLASH Max 4.3 and 以降で用いられる、クロスプラットフォームなパススタイル
  PATH_STYLE_NATIVE_WIN Windows のバックスラッシュパススタイル(Maxでは、バックスラッシュは特別なキャラクタなので、推奨できません。).
     
  変換できるパスタイプ
     
  PATH_TYPE_IGNORE パスタイプを使わない
  PATH_TYPE_ABSOLUTE フルパス名
  PATH_TYPE_RELATIVE Maxapplication フォルダからの相対パス
  PATH_TYPE_BOOT 起動ボリュームからの相対パス
  PATH_TYPE_C74 “Cycling’74”フォルダからの相対パス
     
  関数の戻り値はエラーコードになります。

path_namefromspec
     
  PATH_SPEC からファイル名を取り出す場合に、path_namefromspecを使います。
   
  void path_namefromspec(PATH_SPEC *fs, char *name);
     
  fs 有効なPATH_SPEC
  name 受け取られたファイル名の文字列へのポインタ
     
 

PATH_SPECからファイル名が抽出され、nameパラメータにコピーされます。


path_resolvefile
     
  パスIDと（場合によっては拡張された）ファイル名を合わせたものを、ファイルのディレクトリとファイル名を識別するパス名に変換したい場合には、path_resolvefile を使います。
   
  short path_resolvefile(char *name, short path, short *outpath);
     
  name ファイル名(フルパス名または部分的なパス名),ファイル名を入れて返されます
  path 分けられるパスID
  outpath 返されたファイル名のパスID
     
 

このルーチンはファイル名とパスID を標準的な形に変換します。これは、パス情報を持たず、エイリアスファイルを参照しません。成功した場合は０を返します。


path_fileinfo
     
  ファイル／パスの組み合わせからt_fileinfo 構造体を取り出す場合に、path_fileinfo を使います。
   
  short path_fileinfo(char *name, short path, void *info);
     
  name 問い合わせを受けるファイル名
  path ファイルのパスID
  info ファイル情報を持ったt_fileinfo 型構造体
     
 

path_fileinfo はファイルに関するOSに依存した情報を取り出し、OSに依存しない t_fileinfo 構造体を返します。これは、次のように宣言されています。

typedef struct _fileinfo { long type; long creator; // Macでのみ使用 long date; long flags; } t_fileinfo;

変数 flags は次のようなフラグの値を持ちます

// fileinfo フラグ enum { FILEINFO_ALIAS = 1, FILEINFO_FOLDER = 2 };

成功した場合には０、そうでない場合にはOSに特有なエラーコードを返します。

path_opensysfile
     
  与えられたファイル名とパスIDによってファイルを開く場合、path_openssysfile を使います。
   
  short path_opensysfile(char *name, short path, t_filehandle *ref, short perm);
     
  name オープンするファイルのファイル名
  path オープンするファイルのパスID
  ref OSに依存したファイルへのポインタを持つFILE_REF。 Mac OS では、FSRead に渡すrefNum になります。
  perm オープンしたファイルのパーミッション（権限）
     
 

このルーチンは、プラットフォームに依存しない Max のSysfile ルーチンを使って、ファイルの読み込み、書き込みのためにファイルを開きます。引数 perm には 列挙された値、READ_PERM、 WRITE_PERM、 RW_PERM のいずれか１つを与えなければなりません。他のファイルシステムコールのように、このルーチンも成功すれば０を返します。また、失敗した場合には、OSが持つエラーコードを返します。


path_createsysfile
     
  与えられたタイプコード、ファイル名、パスID によってファイルを作成する場合、path_createsysfile を使います。
   
  short path_createsysfile(char *name, short path,long type, t_filehandle *ref);
     
  name 作成されるファイルのファイル名.
  path 作成されるファイルのパスID
  type 作成されるファイルのファイルタイプ
  ref 開かれたファイルへのポインタを持つ t_filehandle
     
 

path_createsysfile はMax の Sysfile ルーチン（後述）と互換性を持つOSに依存しない方法で、新しいファイルを作成し、読み込み、書き込みのためにファイルを開きます。ファイルが存在する場合には、その場所に新しいファイルが作成されます。他のファイルシステムコールのように、このルーチンも成功すれば０を、失敗した場合にはOS が持つエラーコードを返します。


path_translate
     
  PATH_SPEC から有効なパスIDとファイル名を生成します。オプションとしてエイリアスの解決も行います。
   
  short path_translate(PATH_SPEC *fs, char *name, short *vol, short resolvealias);
     
  fs 解釈されるPATH_SPEC
  name PATH_SPEC の fs が持つファイル名
  vol PATH_SPEC のfs によって識別されるファイルのパスID
  resolvealias この値が0以外で、PATH_SPEC がエイリアスの場合、返されるファイル名／パスIDは、エイリアスが指すファイルを参照します。
     
 

path_translate はPATH_SPEC をパスID とファイル名の組み合わせに完全に変換するために用いられます。path_namefromspec やgenpath と異なり、エイリアスの解決も行えます。他のファイルシステムコールのように、このルーチンも成功すれば０を、失敗した場合はエラーコードを返します。


path_topathname
     
  パスID／ファイル名の組み合わせから、完全に有効なファイル名を生成するために、path_topathname を使います。
   
  short path_topathname(short path, char *file, char *name);
     
  path 使用されるパス
  file 使用されるファイル名
  name 返される時には、完全に拡張されたファイル名がロードされます。
     
 

path_topotentialname と異なり、このルーチンはパスが存在する場合にのみ、パス名のペアを有効なパス文字列にコンバートします。成功すれば０、失敗した場合はエラーコードを返します。


path_topotentialname
     
  ファイルがディスクに存在するかどうかに関わらず、パスID／ファイル名の組み合わせから完全に有効なファイル名を作成する場合に、path_topotentialname を使います。
   
  short path_topotentialname(short path, char *file, char *name, short check);
     
  path 使用されるパス
  file 使用されるファイル名
  name 返される時には、完全に拡張されたファイル名がロードされます。
  check 与えられたパスのファイルが存在するかどうかをチェックするためのフラグ
     
 

check フラグがfalse の場合、この関数はパスが有効かどうかをチェックせず、常にフルパス文字列を返します。フラグが trueの場合には、このルーチンは path_topathname と全く同じ動作をします。成功すれば０を、失敗した場合はエラーコードを返します。


path_frompathname
     
  完全な形のファイルパス名からファイル名とパスID の組み合わせを生成する場合に、path_frompathname を使います。
   
  short path_frompathname(char *name, short *path, char *filename);
     
  name コンバートされる、拡張されたファイルパス名
  path 返された時には、パスIDが入れられます。
  filename 返された時には、ファイル名が入れられます。
     
 

path_frompathname はファイルパスを与えると、パスID とファイル名を返します。変換の中で、エイリアスの解決を行います。このルーチンは成功すれば０を、失敗した場合はエラーコードを返します。path_frompathnameは、ファイルが存在していなくても実行できる点に注意して下さい。この関数を用いて、引数として受け取ったフルパスを変換し、path_createfile のようなルーチンに送るファイル書き出しメッセージとして適切な形にフォーマットすることができます。


path_setdefault
     
  パスをデフォルトサーチパスとして設定する場合に、path_setdefault を使います。
   
  void path_setdefault(short path, short recursive);
     
  path サーチパスとして使用するパス
  recursive ０でない場合、すべてのサブディレクトリがデフォルトサーチリストとしてインストールされます。
     
 

デフォルトサーチパスはMax サーチパスの前に探索されます。例えば、サーチパス以外の場所からパッチャーがロードされると、サーチパスの前にパッチャーのディレクトリ内のファイルが探索されます。path_setdefault によって、デフォルトのサーチパスを設定することが可能になります。

そのパスがMax のサーチパスとしてすでに登録されている場合には、サーチパスの追加は行われません。（デフォルトでその場所がファイル検索の際に使用されるためです）。引数 recursive の使用は特に注意して下さい。これにより、フォルダのリストが生成されるため、ファイル検索が劇的に遅くなる可能性があります。Max 自身は、階層的なデフォルトサーチパスの生成は決して行いません。

path_getdefault
     
  デフォルトサーチパスのパスID を取得する場合に、path_getdefault を使います。
   
  short path_getdefault(void);
     
 

path_getdefault はpath_setdefault に最後に渡されたパスのパスID を返します。このルーチンは、以前のバージョンでデフォルトパスを取り出すためのものでしたが、defvolume は現在でも使用でき、 path_getdefault を呼び出した場合と同じ効果を得ることができます。


path_getmoddate
     
  選択されたパスの修正日時を調べる場合に、path_getmoddate を使います
   
  short path_getmoddate(short path, unsigned long *date);
     
  path チェックするディレクトリのパスID
  date ディレクトリが最後に修正された日時.

path_getfilemoddate
     
  指定したファイルの修正日時を取り出す場合に、path_getfilemoddate を使います。
   
  short path_getfilemoddate(char *filename, shortpath, unsigned long *date);
     
  filename 対象となるファイル
  path ファイルのパスID.
  date 返された時に、最終の修正日時が入れられます。

path_getapppath
     
  Max アプリケーションのパスID を取り出す場合に、path_getapppath を使います。
   
 

戻り値はMax アプリケーション、またはランタイム版のパスID です。


フォルダに関する繰り返し処理のルーチン

これらのルーチンは、パス内にあるすべてのファイルでの繰り返し処理を可能にするものです。

path_openfolder
     
  繰り返し処理を行うディレクトリを準備する場合に、path_openfolder を使います。
   
  void *path_openfolder(short path);
     
  path オープンするディレクトリのパス ID
     
 

このルーチンの戻り値は、これに続くフォルダ操作で使う、内部的な「フォルダステート」構造体です。これは、 path_foldernextfile および path_closefolder の呼出しのために保存されなくてはなりません。フォルダが見つからない場合や、アクセスできない場合は、path_openfolder は０を返します。


path_foldernextfile
     
  ディレクトリの次のファイルを得る場合に、path_foldernextfile を使います。
   
  short path_foldernextfile(void *xx, long *filetype, char *name, short descend);
     
  xx path_openfolderによって返される「フォルダステート」の値
  filetype 返された時に、次のファイルのファイルタイプが入れられます。
  name 返された時に、次のファイルのファイル名が入れられます。
  descend 使用されません。
     
 

このルーチンを path_openfolder や path_closefolder と併せて使うことにより、パス内のすべてのファイルを通じて繰り返し処理を行うことができます。path_foldernextfile がフォルダを返すことがあるかも知れませんが、その場合、引数 filetype には、”fold”が含まれます。このルーチンは成功すれば０を、失敗した場合はエラーコードを返します。


path_foldergetspec
     
  ディレクトリ内のファイルからより詳しい情報を得る場合に、path_foldergetspec を使います。
   
  short path_foldergetspec(void *xx, PATH_SPEC *spec, short resolve);
     
  xx path_openfolderによって返される「フォルダステート」の値
  spec 追加情報を持ったPATH_SPEC
  resolve 0以外の場合、エイリアスを実際のファイルに解決します。
     
 

フォルダ内の繰り返し処理の中で、現在の位置にあるファイルの PATH_SPEC 構造体に保存されている情報を取り出す場合に、path_foldergetspec を使います。


path_closefolder
     
  ディレクトリの繰り返し処理を終了する場合に、path_closefolder を使います。
   
  void path_closefolder(void *x);
     
  x 最初に path_openfolder によって返された「フォルダステート」の値
     
 

このルーチンはディレクトリの繰り返し処理が完了した場合に必ず呼び出されなくてはなりません。


Sysfile API

Sysfile API は path_creatsysfile や同様な関数によって開かれたファイルを読み書きする手段を提供します。これらの関数は全て新しい「ブラックボックス」のような構造体 t_filehandle を使います。path_createfile のような古いパス関数はMacintoshに特化されていて、クロスプラットフォームでの開発にとっては旧式のものでした。新しいパス関数 path_opensysfile や path_createsysfile についてはすでに述べましたので、この章ではより詳しい情報について書きたいと思います。Sysfile API は旧式のMacintosh ファイルマネージャAPI の一部と比較的良く似ていて、標準Cライブラリともそれほど大きな違いはありません。SDK の “filebyte”サンプルプロジェクトでは、これらの関数を使ってファイルを読み出す方法を見ることができます。これらのルーチンを他のファイル関係ルーチンと混用することは危険です。（例えば、fopen で開いたファイルを sysfile_close で閉じてはいけないということです。）

Max エクスターナルでクロスプラットフォームなコードを書くためにこれらのルーチンが使えるということに加え、Max 4.3で新しくなったコレクティブファイルフォーマット内に保存されたファイルを、Windows XP と MaxOSX の両方のバージョンで読むことができるという利点があります。

sysfile_read
     
  ディスクからファイルを読み込む場合に、sysfile_read を使います。
   
  long sysfile_read(t_filehandle fh, long *count, void *bufptr);
     
  fh

ユーザがオープンするファイルの t_filehandle 構造体
  count 現在のファイル位置から読み込まれるバイト数へのポインタ。実際に読み込まれるバイト数がこの値として返されます。
  bufptr データを読み込むバッファへのポインタ.
     
 

この関数はFSRead あるいは fread と同様なものです。この関数は、Max エクスターナルのコードをクロスプラットフォームなものにコンパイルするために、FSReadなどの関数（または、それ以外の、システムに特有なファイル読み込みルーチン）の代わりに使われるべきものです。sysfile_read はファイルハンドルの現在のファイル位置から“count”の値のバイト数を “bufptr”へ読み込みます。実際に読み込まれたバイト数は “count” にセットされ、ファイル位置は実際に読み込まれたバイト数だけ移動します。戻り値はエラーコードです。


sysfile_write
     
  ファイルの一部をディスクに書き出す場合に、sysfile_write を使います。
   
  long sysfile_write(t_filehandle fh, long *count, const void *bufptr);
     
  fh ユーザが書き込もうとするファイルのt_filehandle 構造体
  count 現在のファイル位置から書き込むバイト数へのポインタ。実際に書き込まれたバイト数がこの値として返されます。
  bufptr データを読み出すバッファへのポインタ 。
     
 

この関数は、FSWrite あるいは fwrite と同様なものです。この関数はMax エクスターナルのコードをクロスプラットフォームなものにコンパイルするために、FSWriteなどの関数（または、それ以外の、システムに特有なファイル書き込みルーチン）の代わりに使われるべきものです。sysfile_write はファイルハンドルの現在のファイル位置へ “bufptr” から “count” の値のバイト数を書き込みます。実際に書き込まれたバイト数は、”count” にセットされ、ファイル位置は実際に書き込まれたバイト数だけ移動します。戻り値はエラーコードです。


sysfile_close
     
  sysfile_open で開いたファイルを閉じるために、sysfile_close を使います。
   
  long sysfile_close(t_filehandle fh);
     
  fh ユーザがクローズしようとするファイルのt_filehandle 構造体
     
 

この関数は、FSClose あるいは fclose と同様なものです。これは、Max エクスターナルのコードをクロスプラットフォームなものにコンパイルするために、システムに特有なファイルクローズルーチンの代わりに使われるべきものです。戻り値はエラーコードです。


sysfile_geteof
     
  ファイルハンドルのサイズを得るために、sysfile_geteof を使います。
   
  f long sysfile_geteof(t_filehandle fh, long *logeof);
     
  fh ファイルの t_filehandle 構造体
  logeof ファイルサイズのバイト数がこの値として返されます。
     
 

この関数は、GetEOF と同様なもので、その代わりに使われるべきものです。この関数はファイルハンドルのサイズをバイト数で取得し、 “logeof” に保存します。戻り値はエラーコードです。


sysfile_seteof
     
  ファイルハンドルのサイズをセットするために、sysfile_seteof を使います。
   
  long sysfile_seteof(t_filehandle fh, long logeof);
     
  fh ファイルの t_filehandle 構造体
  logeof ファイルサイズのバイト数.
     
 

この関数は SetEOF と同様なもので、その代わりに使われるべきものです。この関数はファイルハンドルのサイズを “logeof”で指定した値に設定します。戻り値はエラーコードです。


sysfile_getpos
     
  ファイルハンドルの現在のファイル位置を取得する場合に、sysfile_getpos を使います。
   
  long sysfile_getpos(t_filehandle fh, long *filepos);
     
  fh ファイルの t_filehandle 構造体
  filepos 現在の読み込み／書き出しの位置が、バイト数で、この値として返されます。
     
 

この関数は GetPos と同様なもので、その代わりに使われるべきものです。この関数はファイルハンドルの現在のファイル位置をバイト数で取得し、 “filepos”に保存します。戻り値はエラーコードです。


sysfile_setpos
     
  ファイルハンドルの現在のファイル位置をセットする場合に、sysfile_setpos を使います。
   
  long sysfile_setpos(t_filehandle fh, long mode, long offset);
     
  fh ファイルの t_filehandle 構造体
  mode オフセットの計算をどこから行うかのモード
  offset モードと関連づけられるオフセットのバイト数
     
 

この関数は SetPos と同様なもので、その代わりに使われるべきものです。この関数はファイルハンドルの現在のファイル位置を、与えられたオフセットのバイト数とモードによって設定するために使われます。次の３つのモードがあります。


  SYSFILE_FROMSTART ファイルの先頭から、セットするファイル位置を計算します。
  SYSFILE_FROMLEOF ファイルの論理的な最後尾から、セットするファイル位置を計算します。
  SYSFILE_FROMMARK 現在のファイル位置から、セットするファイル位置を計算します。
     
 

戻り値はエラーコードです。

sysfile_readtextfile
     
  ディスクからテキストファイルを読み込む場合に、sysfile_readtextfile を使います。
   
  long sysfile_readtextfile(t_filehandle fh, t_handle htext, long maxlen, long flags);
     
  fh ユーザがオープンしようとするテキストファイルのt_filehandle 構造体
  htext データが読み込まれるハンドル
  maxlen ハンドルに読み込まれる最大の長さをバイト数で表した値。０を渡した場合は、最大値を持たないことを表します（従って、ファイル全体が読み込まれます）。
  flags 改行の解釈の方法をセットするフラグ
     
 

この関数は、ファイルハンドルの現在のファイル位置から、maxlen で与えられたバイト数までを、ハンドル htext に読み込みます。その際、フラグがセットされていれば、改行を解釈して実行します。改行フラグは、次の４種類の設定が可能です。


  TEXT_LB_NATIVE 現在のプラットフォームのネイティブな改行フォーマットを使います。
  TEXT_LB_MAC Macintosh の改行フォーマットを使います。
  TEXT_LB_PC PC の改行フォーマットを使います。
  TEXT_LB_UNIX Unix の改行フォーマットを使います。
     
 

戻り値はエラーコードです。

sysfile_writetextfile
     
  テキストファイルをディスクに書き込む場合に、sysfile_writetextfile を使います。
   
  long sysfile_writetextfile(t_filehandle fh, t_handle htext, long flags);
     
  fh ユーザが書き込みを行おうとするファイルのt_filehandle 構造体
  htext 読み込まれるデータのためのハンドル
  flags 改行の解釈の方法をセットするフラグ
     
 

この関数は、テキストファイルにテキストハンドルの内容を書き込みます。その際、フラグがセットされていれば、改行を解釈して実行します。フラグ設定のリストは、上記の sysfile_readtextfile の説明を参照して下さい。戻り値はエラーコードです。


ファイル処理の例

次は、オブジェクトのread メソッドでopen_dialog と locatefile_extended を使用する例です。これは、初期化ルーチンでread メソッドを結びつけた方法です。

// 名前を指定するための、オブションのシンボルアーギュメント addmess((method)myobject_read, "read", A_DEFSYM, 0);

これは、実際のread メソッドの最初の部分です。myobject_doread というルーチンによって処理を遅らせています。（訳注：Chapter 7 の割り込みレベルに関する章を参照）

void myobject_read(t_myobject *x, t_symbol *s) { // 常にこのメッセージは処理を遅らせます defer(x,(method)myobject_doread,s,0,0);

}

void myobject_doread(t_myobject *x, t_symbol *s, short argc, t_atom *argv) { char filename[256]; short path, err; long type = 'DATA'; // 検索しようとするファイルタイプ long outtype, count; Byte data[128]; t_filehandle fh; // おそらく、これをオブジェクトのデータ構造体のインスタンス変数 // にしようと思うでしょう。 if (!s->s_name[0]) { // 空のシンボル if (open_dialog(filename, &path, &outtype, &type, 1)) return; // ユーザのキャンセル } else { strcpy(filename, s->s_name); // 重要: シンボル arg をローカル文字列にコピー if (locatefile_extended(filename, &path, &outtype, &type, 1)) return; // 見つからない場合 } // この時点で、filename には有効なファイル名が入れられ、 // path には有効なパスが入れられています。 err = path_opensysfile(ps, path, &fh, READ_PERM); if (err) { fh = 0; error("error %d opening file", err); return; }

t_filehandle はオープンしたファイルの参照をクロスプラットフォームで行うものです。これは、データ構造体の個々の要素にアクセスしないという意味で、「ブラックボックス」のような構造体です。t_filehandle はSysfile API のファイルルーチンでのみ使用できます。これらの関数と他のプラットフォーム依存のファイル関数を一緒に使わないで下さい。perm というパラメータは READ_PERM、WRITE_PERM、RW_PERM のうちのどれかになります。

ファイルへの書き込み処理の場合、一般的に path_opensysfile の代わりに path_createsysfile を使う必要があるでしょう。path_createsysfile は既にファイルが存在していないかどうかに注意してファイルを作成します。既存の名前でファイルを作ろうとするとエラーを返され、ファイルを無事に開くことができるよう再度試さなくてはなりません。そのためこの関数は、通常必要となる多くのコードをシステムに特有なファイルルーチンで置き換えます。path_createsysfile はこれらの機能のすべてを提供します。

myobject_doread の例を続けます:

// ファイルを読み込み用にオープンします err = path_opensysfile(filename, path, &fh, READ_PERM); if (err) { // エラーがあれば報告します。 error("%s: error %d opening file", filename, err); return; } // ファイルから128バイトを読み込みます。 count = 128; err = sysfile_read(fh, &count, &data);

// ここで、読み込んだデータによって必要な処理を行います。 // 処理の終了後、ファイルをクローズします。 sysfile_close(fh); }