オブジェクトルーチン：
登録／通知

Max 4.5 以降では、オブジェクトは開発者が定義したネームスペースの中のシンボリックネームによって登録することができるようになっています。ネームスペースは、基本的に、メンバデータの高速検索機能を提供するハッシュテーブルです。開発者の立場から見たネームスペースの基本的な使い方は、クライアントの登録と通知です。

このシステムを使って、クライアント通知の仕組みを作るためには、次のようなステップを踏まなければなりません。

  1. object_register　関数を使って、サーバオブジェクトをネームスペース内に登録する必要があります。


  2. object_attach　関数を使って、クライアントオブジェクトをサーバに接続する必要があります。


  3. クライアントオブジェクトは、特別なクラスメソッド notify　を必要とします。このメソッドのためのプロトタイプ宣言は後述の object_notify　ルーチンのリファレンスに基づきます。


  4. メッセージのブロードキャストのためには、サーバオブジェクトは object_notify　関数を呼び出すだけです。すべてのクライアントオブジェクトは、その notify　メソッドを通してメッセージを受け取ります。


  5. クライアントをサーバから切り離すためには、object_detach ルーチンを呼び出します。


  6. 最後に、ネームスペースから登録済みのオブジェクトを取り除くために、object_unregister ルーチンを呼び出します。

次は、必要なルーチンのリファレンスです。リファレンスに含まれるソースコードのサンプル、myregob は原則的な使用法を示しています。

object_register
     
  オブジェクトをネームスペースに登録するために、object_register 関数を使います。
   
  void *object_register(t_symbol *name_space, t_symbol *s, void *x);
     
  name_space オブジェクトを登録するネームスペース。ネームスペースはどのようなシンボルでも可能です。ネームスペースがまだ存在しないものである場合には、自動的に作成されます。
  s ネームスペースの中のオブジェクト名。この名前は他のオブジェクトによって、登録されたオブジェクトへの接続、切り離しを行なうために使用されます。
  x 登録するオブジェクト
     
 

この関数は登録したオブジェクトへのポインタを返します。ある条件の下では、 object_register はあなたのオブジェクトを複製し、その複製へのポインタを返します。開発者は、渡されたポインタが登録されているものと同じであると決め込んではいけません。安全のために、返されたポインタを保存し、object_unregister() ルーチンでは、これを使用しなければなりません。


object_unregister
     
  ネームスペースから、登録されたオブジェクトを取り除くために、 object_unregister を使います。
   
  t_max_err object_unregister(void *x);
     
  x 登録を抹消されるオブジェクト。これは、object_register 関数から返されたポインタでなければなりません。
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONE を返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。


object_attach
     
  クライアントを、登録されているオブジェクトに接続するために、object_attach 関数を使います。登録されているオブジェクトが notify メソッドを定義し、実装している場合、クライアントのオブジェクトが接続されると、クライアントは登録されているオブジェクトから（object_notify 関数を通して）通知を受け取ります。後述の object_notify のリファレンスには、より詳しい情報があるので、参照して下さい。
   
  t_max_err object_attach(t_symbol *name_space, t_symbol *s, void *x);
     
  name_space 登録されたオブジェクトのネームスペース。これは object_register がオブジェクトを登録するために用いた値と同じでなければなりません。登録されたオブジェクトのネームスペースがわからない場合、それを判定するために object_findregisteredbyptrルーチンを使うことができます。
  s ネームスペースに登録されたオブジェクトの名前。登録されたオブジェクトの名前が分からない場合、それを判定するために object_findregisteredbyptr ルーチンを使うことができます。
  x 接続されるオブジェクト。通常、これはあなたの Max オブジェクトへのポインタになります。
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。


object_detach
     
  登録されたオブジェクトからクライアントを切り離すために、object_detach 関数を使います。
   
  t_max_err object_detach(t_symbol *name_space, t_symbol *s, void *x);
     
  name_space 登録されたオブジェクトのネームスペース。これは object_register がオブジェクトを登録するために用いた値と同じでなければなりません。登録されたオブジェクトのネームスペースがわからない場合、それを判定するために object_findregisteredbyptrルーチンを使うことができます。
  s ネームスペースに登録されたオブジェクトの名前。登録されたオブジェクトの名前がわからない場合、それを判定するために object_findregisteredbyptr ルーチンを使うことができます。
  x 切り離すオブジェクト。通常、これはあなたの Max オブジェクトへのポインタになります。
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。


object_notify
     
  登録されたオブジェクトから、接続されたすべてのクライアントオブジェクトへメッセージを（オブションのアーギュメントと共に）ブロードキャスト（一斉送信）するために、object_notify 関数を使います。
   
  t_max_err object_notify(void *x, t_symbol *s, void *data);
     
  x 登録されたオブジェクトへのポインタ
  s 送信するメッセージ
  data メッセージと一緒に渡されるオプションのアーギュメント。使用しない場合には、この引数を NULLにセットします。
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。

クライアントオブジェクトが通知を受け取るために、次のような特別なメソッド notify を定義し、実装しなければなりません。

class_addmethod(c, (method)myobject_notify, "notify", A_CANT, 0);

notify メソッドは次のようにプロトタイプ宣言されます。

void myobject_notify(t_myobject *x, t_symbol *s,
t_symbol *msg, void *sender, void *data);
   
x 受信するオブジェクトのポインタ
s ネームスペースの中で送信を行なう（登録された）オブジェクトの名前
msg 送信するメッセージ
sender 送信するオブジェクトのポインタ
data メッセージと共に送信される、オプションのアーギュメント。この値は、object_notify メソッドの 引数 data と一致します。

object_findregistered
     
  与えられたネームスペースと名前によって、登録されたオブジェクトのポインタを判定するために object_findregistered 関数を使います。
   
  void *object_findregistered(t_symbol *name_space, t_symbol *s);
     
  name_space 登録されたオブジェクトのネームスペース
  s ネームスペース内の、登録されたオブジェクトの名前
     
 

このルーチンは、成功すると登録されたオブジェクトのポインタを返します。失敗した場合は、NULL を返します。


object_findregisteredbyptr
     
  与えられたオブジェクトのポインタによって、登録されたオブジェクトのネームスペースや名前を判定するために、object_findregisteredbyptr　関数を使います。
   
 

t_max_err object_findregisteredbyptr(t_symbol **name_space, t_symbol **s, void *x);
     
  name_space t_symbol * へのポインタ。登録されたオブジェクトのネームスペースを受け取ります。
  s t_symbol * へのポインタ。ネームスーペース内の、登録されたオブジェクトの名前を受け取ります。
  x 登録されたオブジェクトへのポインタ
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONE を返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの１つを返します。