FACEs

FACEs PROTOCOLの基本 FACEsプロトコルは、FACEsサーバとFlashファイルとの間でやりとりするXML文書の形式についての規定です。FACEsサーバは、ある一つのクライアント(Flash等)から送られてきたXML文書形式のデータを、同じ部屋に接続中の全てのクライアントに配ります。FlashのXMLエンジンはDTDを解釈しないので、、Flashとサーバの間でやりとりするデータは、整形式のXML文書である必要があります。 例として、以下のようなXML文書があったとします。 <CHAT message="aaaaa"/> このXML文書はCHATという要素(エレメント)のみで構成されています。CHATという名前の空要素タグの中に、messageと言う名前の属性(アトリビュート)があり、その値はaaaaaであることを示しています。要素、タグ、空要素タグ、属性、等のXML用語はFACEsプロトコルでもActionScriptでも同様に扱います。XMLの基本的な用語がわからない人はXML用語事典が参考になります。上記の例のXMLが送られて来たときに、「要素名がCHATのときはキャラクターのフキダシが現れてテキストフィールドの変数にmessage属性の値(aaaaa)を代入する」というような処理をクライアント(Flash)で設定しておけば、キャラクターが話をするチャットのようなものが作れます。 FlashではXML文書はXMLオブジェクトとして扱われます。XMLSocketオブジェクトのsendメソッドによって一回の送信で送られる情報の単位はXMLオブジェクト(XML文書)一つです。クライアントがサーバを通じて配布するXMLオブジェクトは、基本的には自由に定義できます。ただ、FACEsサーバの機能を引き出すために、XMLオブジェクトを定義するためのいくつかの決まりを設けています。FACEsプロトコルでは、ある決められたタグ、要素に対してサーバ側で行う処理を設定しています。よって、以下のFACEsプロトコルで定められたタグ名および属性名は、目的の効果を得るために使用する場合以外では使わないようにしてください。またプロトコルリファレンスにでてくる<USERNODE userattr="">という表現ですが、これは"USERNODE"というタグ名が実際にFACEsプロトコルの中で定義されているわけではなく、ユーザが自由に定義できる(サーバが解釈を行わずそのままクライアントに配布する)タグ名という意味です。"userattr"も同様で、ユーザ定義の属性名一般をuserattrという名前に代表させているだけです。 FACEsプロトコルには以下のような決まりとおおよその法則があります。 あらかじめ定義されているタグ名は クライアントからサーバに送るもの--QN,QR,QE,QF,QS,QT,QER サーバからクライアントに送るもの--N,R,SERVERMSG,S,T,ER,D ユーザ定義ノード用にあらかじめ定義されている属性名は save,key,self,to <QN ...../>のようにノード名の頭に「Q」がつくノードは、クライアント側からサーバに対してなにかリクエストを行うために用意されている。 Rノード以外で、FACEsプロトコルで定義されているノード名のノードは全て空要素タグ一つで単一のXMLオブジェクトを構成する。 FACEsプロトコルで定義されていないユーザ定義のルート要素は空要素である必要はなく、ネストも可能。 ユーザ定義ノードは、ルート要素にsave,key,self,to等の属性を指定することでサーバ上での機能を変える。 save,key属性はサーバメモリ上にユーザ定義のデータを保存するためにあり、同じ部屋に接続しているクライアント間で情報を非同期に共有するために頻繁に使われます。サーバメモリ上に保存されているデータを取り出すときには <QR/> を使いますが、ユーザ定義ノードで使われるsaveという属性は、 <QR n="..."/> という形で取り出すときに使います。keyという属性は、サーバメモリに保存するときに他のデータとの区別を付けるためにあります。例えば <A attr="geho" save="hoge" key="x1"/> というデータをクライアントからサーバに発信した後、 <QR n="hoge"/> とサーバに送信すると、 <hoge><A attr="geho"/></hoge> が返って来ます。さらに <A attr="gehoho" save="hoge" key="x2"/> をサーバに送ってから、 <QR n="hoge"/> とすると <hoge><A attr="geho"/><A attr="gehoho"/></hoge> がサーバから返ってきます。サーバに送信した二つのデータはsave属性の値は同じですがkeyが違うので、別のデータと認識されて、サーバメモリに保存されたデータが二つになり、さらにそれがsave属性で指定されたhogeというタグで括られています。この後例えば、 <A attr="hogeho" save="hoge" key="x1"/> というデータをサーバに送ると、 最初に送信したkey="x1"のデータが上書きされるので、さらに <QR n="hoge"/> とサーバに送ると、 <hoge><A attr="hogeho"/><A attr="gehoho"/></hoge> と返ってきます。 FACEsプロトコル version 0.1.1 リファレンス目次 データを共有する部屋の指定と、サーバに接続中のクライアントの区別 <QN app="..." r="..."/> <N n="..."/> ユーザ定義の要素から成るデータの送信と、サーバメモリ上へのデータ保存 <USERNODE save="..." key="..." self="..." to="..."> ... ... </USERNODE> サーバメモリ上に保存したデータのリクエスト <QR n="..." key="..."/> <R></R> サーバメモリ上に保存したデータを消去する <QE n="..." key="..."/> サーバメモリ上のXMLオブジェクトをファイルに出力し、他のプロセスで利用する <QF n="..."/> <SERVERMSG filename="..."/> <SERVERMSG error="..."/> サーバとの接続が切れたクライアントの固有の番号をを他クライアントに知らせる <D n="..."/> クライアント同士のタイミング同期 <QS n="..." max="..."/> <S n="..."/> サーバ時間情報を得る <QT/> <T y=".." m=".." d=".." w="..." hh=".." mm=".." ss=".."/> ロビーにユーザ情報を残しておく <LOG n="..." r="..." save="..." key="..."/> 定員に達していない最小の部屋番号を取得する <QER max="..."/> <ER r="..."/> 同一コンテンツ内の各部屋の人数を取得する <QM r="..."/> <M n="..."/> <MA><M r="..." n="..."/>...</MA> データを共有する部屋の指定と、サーバに接続中のクライアントの区別 <QN app="..." r="..."/> <N n="..."/> <QN app="コンテンツ名" /> <QN app="コンテンツ名" r="部屋番号" /> クライアント固有の番号をリクエスト 部屋番号は必ず整数。 <QN app="コンテンツ名" />は主にコンテンツロビー接続用に使い <QN app="コンテンツ名" r="部屋番号" />はコンテンツ接続用に使う。r属性にはコンテンツの部屋番号を入れる。 ※同じ部屋（同じコンテンツ名+同じ部屋番号）に接続中のクライアント同士でのみXMLオブジェクトのやり取りが行われる。 ※app="..."（コンテンツロビー）接続中にapp="..." r="..."（コンテンツ）に接続した場合app="..."（コンテンツロビー）への接続は失われる 　　同じく、 app="..." r="..."（コンテンツ）接続中にapp="..."（コンテンツロビー）に接続した場合app="..." r="..."（コンテンツ）への接続は失われる QN要素はサーバから固有番号を送る<N ・・・/>と対になっている。<QN ・・・/>をサーバに送ると送信したクライアントにのみ<N ・・・/>が返信される。 <N ・・・/>の説明については次の項目を参照。 <N n="クライアント固有の番号" />　　クライアント固有の番号を送信 <N n="クライアント固有の番号" />は、 <QN ・・・/>を送信したクライアントにサーバから返信される。 　※このクライアント固有の番号(整数)は、主にクライアント同士でどのクライアントから送られてきた情報かを区別する際に用いる。 　※一度n属性の値としてクライアント固有の番号が割り当てられると再び<QN ・・・/>で番号をリクエストしても同じ番号が送られてくる ユーザ定義のノードから成るデータの送信と、サーバメモリ上へのデータ保存 <USERNODE userattr="..." save=".." key="..." self="..." to=".."> ... ... </USERNODE> <USERNODE userattr="..." userattr2="..." ・・・> ... ... </USERNODE>　　 同じ部屋に接続中のユーザにデータを送信 ユーザ定義のノード名とユーザ定義属性の名前、数は自由に指定できる。送りたいデータをクライアントからサーバにXML形式で送信、同じ部屋（同じコンテンツ名、同じ部屋番号）に接続中のユーザに、変更せずそのままの形式で送信する。 <USERNODE userattr="..." save="1"> ... ... </USERNODE> 同じ部屋に接続中のユーザにデータを送信・サーバにはそのまま保存 ユーザ定義のノード名とユーザ定義属性の名前、数は自由に指定できる。送りたいデータをクライアントからXML形式で送信、そのままの形でサーバメモリ上に保存し同じ部屋（同じコンテンツ名、同じ部屋番号）に接続中のユーザにsave属性を取り除いた形式で送信する。 　※すでに同じルートノード名のXMLオブジェクトが保存されていた場合は上書きする。 　※サーバメモリ上に保存されたXMLオブジェクトの取り出し方については3.を、消去の仕方については4.を参照。 <USERNODE userattr="..." save="ハッシュ名" key="キー"> ... ... </USERNODE> 同じ部屋に接続中のユーザにデータを送信・サーバにはハッシュ形式で保存 ユーザ定義のノード名とユーザ定義属性の名前、数は自由に指定できる。送りたいデータをXML形式で送信、ハッシュ名[キー] ＝ そのキーを持つユーザ定義ノード； という形式でサーバメモリ上に保存し、同じ部屋（同じコンテンツ名、同じ部屋番号）に接続中のユーザにsave="ハッシュ名" key="キー"を取り除いた形式で送信する。同一のノード名で複数のデータを扱う場合に使用する。 　※すでに同じハッシュ名かつ同じキーのXMLが保存されていた場合は上書きします。 　※保存されたXMLの取り出し方については3.を、消去の仕方については4.を参照。 <USERNODE userattr="..." save="..." self="クライアント固有の番号"> ... ... </USERNODE> 同じ部屋に接続中のユーザにデータを送信・クライアントとの接続が切れた時にサーバメモリ上のデータを消去 ユーザ定義のルート要素名とユーザ定義属性の名前、数は自由に指定できる。self属性がない場合との違いは、クライアントのサーバとの接続が切断された場合、self属性の値が切断されたクライアント固有の番号と同じ(サーバメモリ上に保存された)XMLオブジェクトが消去されることである。save属性と同時に使用する。 サーバメモリ上への保存の形式は単独型(save="1")でもハッシュ型(key属性あり)でも可能。 　※すでに同じハッシュ名かつ同じキーのXMLオブジェクトが保存されていた場合は上書きする。 　※後述のto属性と同時に使用することも可能。 <USERNODE userattr="..." to="クライアント固有の番号"> ... ... </USERNODE> to属性で指定された番号を持つクライアントのみに送信 ユーザ定義のノード名とユーザ定義属性の名前、数は自由に指定できる。送りたいXMLオブジェクトを、to属性で指定された番号と同じ固有の番号をもつクライアントのみにXML形式で送信します。save属性、key属性、self属性と同時に使用することが可能。 　※すでに同じハッシュ名かつ同じキーのXMLが保存されていた場合は上書きする。 to="all"のときは、同じコンテンツ上の全ての部屋のクライアントに対して送信され、save属性が存在するときは全ての部屋に保存される。 to="lobby"のときは、同じコンテンツ上のロビーに対して送信され、save属性が存在するときはロビーに保存される。 サーバメモリ上に保存したデータのリクエスト <QR n="..." key="..."/> <R></R> <QR/>　　現在いる部屋でサーバメモリ上に保存された、全てのXMLをリクエスト 現在いる部屋でサーバメモリ上に保存された、全てのXMLをリクエストするためのノード リクエストを送信したユーザにのみ返信する。 <R> ・・・ </R>　　現在いる部屋でサーバメモリ上に保存された、全てのXMLオブジェクトを送信 サーバに保存されてるXMLオブジェクトはRという名前のルートノードの子ノードとして並列に付加され、まとめて一つのXMLオブジェクトとして送信されてくるので、クライアント側で分解する必要がある 　※例 　　<R> <save属性で指定されたハッシュ名1> 　　<USERNODE userattr="..." ・・・ /> 　　<USERNODE userattr="..." ・・・ /> 　　<USERNODE userattr="..." ・・・ /> </save属性で指定されたハッシュ名1> <save属性で指定されたハッシュ名2> 　　<USERNODE userattr="..." ・・・ /> 　　<USERNODE userattr="..." ・・・ /> </save属性で指定されたハッシュ名2> 　　</R> <QR n="リクエストしたいXMLオブジェクトのルートノード名"/>　　現在いる部屋でサーバメモリ上に保存された、特定のXMLオブジェクトをリクエスト <USERNODE userattr="..." save="1" />形式で保存したXMLオブジェクトをリクエストするためのノード。保存したときと同じノード名をn属性の値として指定する。リクエストを送信したユーザにのみ返信する。 <リクエストされたXMLオブジェクトのルートノード名 ・・・ />　　サーバメモリ上に保存されてるXMLオブジェクトの中で、ルートノード名がn="リクエストしたいXMLオブジェクトのルートノード名" と一致するXMLを送信 save属性は取り除かれた形式で返信される 　※例 　　<リクエストされたXMLオブジェクトのルート要素名 ユーザ定義属性="..." /> <QR n="リクエストしたいXMLオブジェクトのルート要素名"/>　　現在いる部屋でサーバメモリ上に保存された、特定のXMLオブジェクトをリクエスト <USERNODE userattr="..." save="ハッシュ名" key="キー" />形式で保存したXMLをリクエストするための要素 リクエストを送信したユーザにのみ返信する。 <ハッシュ名> ・・・ <ハッシュ名/>と言う形でデータが返って来る。　　サーバに保存されてるハッシュ名がn="リクエストしたいXMLオブジェクトのルート要素名" と一致するハッシュの内容を、指定されたハッシュ名をルート要素名にした1つのXMLオブジェクトで送信。 save="ハッシュ名" key="キー"は取り除かれ、 <ハッシュ名></ハッシュ名>に囲まれて一つのXMLオブジェクトとして送信されてくるので、クライアント側で分解する必要がある 　※サーバから返ってくるXMLオブジェクトは以下のような形になる。 　　<save属性で指定されたハッシュ名> 　　<USERNODE userattr="..."/> 　　<USERNODE userattr="..."/> 　　<USERNODE userattr="..."/> 　　</save属性で指定されたハッシュ名> <QR n="リクエストしたいXMLオブジェクトのルート要素名" key="キー"/>　　現在いる部屋でサーバメモリ上に保存された、特定のXMLオブジェクト内の特定のキーのデータをリクエスト <USERNODE userattr="..." save="ハッシュ名" key="キー" />形式で保存したXMLをリクエストするための要素 リクエストを送信したユーザにのみ返信する。 サーバに保存されてるハッシュ名がn="リクエストしたXMLオブジェクトのルート要素名" と一致するハッシュの内容の中で、指定されたキーのデータを一つのXMLオブジェクトとして送信。 save="ハッシュ名" key="キー"は取り除かれ、 一つのXMLオブジェクトとして送信されてくる。 ※使用例 <A userattr="hoge" save="B" key="x"/>という形でサーバメモリ上に保存した以下のデータ <B> <A userattr="hoge" key="key1"/> <A userattr="geho" key="key2"/> ... ... </B> で特定のをkeyを手がかりにして取り出したいときに <QR n="B" key="key1"/> というように使用する。この場合save="ハッシュ名" key="キー"は取り除かれ、 <A userattr="hoge"/> という形でデータがサーバからクライアントに返ってくる。 サーバメモリ上に保存したデータを消去する <QE n="..." key="..."/> <QE/>　　現在いる部屋でサーバメモリ上に保存された、全てのXMLオブジェクトを消去 現在いる部屋でサーバメモリ上に保存された、全てのXMLオブジェクトを消去するためのノード <QE n="消去したいXMLオブジェクトのルートノード名"/>　　現在いる部屋でサーバメモリ上に保存された、特定のXMLオブジェクトを消去 現在いる部屋でサーバメモリ上に保存された、XMLオブジェクトのルートノード名がn="消去したいノード名" と一致するXMLオブジェクトを消去 <QE n="消去したいハッシュ名"/>　　現在いる部屋でサーバメモリ上に保存された、特定のXMLオブジェクトを消去 現在いる部屋でサーバメモリ上に保存された、XMLオブジェクトのルートノード名がn属性で指定された"消去したいノード名" と一致するXMLオブジェクトを消去 <QE n="消去したいハッシュ名" key="キー" />　　現在いる部屋でサーバメモリ上に保存された、特定のハッシュ内の特定キーを持つXMLオブジェクトを消去 現在いる部屋でハッシュ名とkeyがQEノードのn属性とkey属性で指定したものと一致するXMLオブジェクトをサーバメモリ上から消去 <QE n="all" key="キー" />　　現在いる部屋でサーバメモリ上に保存された、全てのハッシュ内の特定キーを持つXMLオブジェクトを消去 現在いる部屋でkeyがQEノードのkey属性で指定したものと一致する全てのXMLオブジェクトをサーバメモリ上から消去 <QE n="all" />　　<QE />と同じ 他のプロセスで利用するために、現在いる部屋でサーバメモリ上に保存されたXMLオブジェクトをファイルに出力する <QF n="..."/> <SERVERMSG filename="..."/> <SERVERMSG error="..."/> <QF/>　　現在いる部屋でサーバメモリ上に保存された全てのXMLオブジェクトを、サーバプロセスの起動されたディレクトリにファイルで保存 サーバメモリ上にあるXMLオブジェクトのルートノード名が、n属性で指定された"保存したいノードの名前"と一致するXMLオブジェクトをディレクトリにファイルで保存する <QF n="保存したいハッシュ名" />　　現在いる部屋でサーバメモリ上に保存された特定のハッシュを、サーバプロセスの起動されたディレクトリにファイルで保存 サーバが保存しているハッシュ名が、n属性で指定された"保存したいハッシュ名"と一致するハッシュの内容全てを、ハッシュ名をルートノード名にしたXMLオブジェクトの子要素として並列して付加し(<QR n=".."/>で返されるデータと同じ形(Rノードがルートノード)で>)一つのXMLオブジェクトとしてディレクトリにファイルで保存する <SERVERMSG filename="ファイル名" />　　保存が成功した場合、保存したファイル名を送信 保存したファイル名をfilename属性の値として返す。 <SERVERMSG error="エラーメッセージ"/>　　保存が成功しなかった場合、エラーメッセージを送信 サーバからエラーメッセージをerror属性の値として返す サーバとの接続が切れたクライアントの固有の番号を同じ部屋の他クライアントに知らせる <D n="..."/> <D n="固有の番号"/>　　サーバとの接続が切断されたクライアントの固有の番号を同じ部屋にいるクライアントに送信 コンテンツをプレイ中、フリーズ・回線の切断・ウインドウを閉じるなどで接続が切れたクライアントを 他のクライアントに知らせるためのノード。 　※ログアウト時になどにクライアント側から使用してもよい。 同じ部屋にいるクライアント同士のタイミング同期 <QS n="..." max="..."/> <QS n="..." flag="..."/> <S n="..."/> <QS n="カウンター名" max="待機カウント" />　　サーバにカウンター名と待機カウントを送信 クライアントが<QS ・・・・/>を送信、 サーバが<QS ・・・・>を受信した時 　 n="カウンター名"で指定されたカウンター（初期値=1）を作る。 　 すでにカウンターが存在する場合はカウンター+1 　 カウンターがmax="X"(Xは正の整数)のXの値以上になったとき クライアントに<S ・・・/>を送信する 　　サーバはカウンターを消去 <QS n="カウンター名" flag="Rx" />　　サーバにカウンター名と全員にフラグを立てる部屋番号を送信。Rxのxには部屋番号が入る クライアントが<QS ・・・・/>を送信、 サーバが<QS ・・・・>を受信した時 　 n="カウンター名"で指定されたカウンター（初期値=1）を作る。 　 すでにカウンターが存在する場合はカウンター+1 　 カウンターがflag="Rx"(xは正の整数)のx番の部屋の人数以上になったとき クライアントに<S ・・・/>を送信する 　　サーバはカウンターを消去 <S n="カウンター名"/>　　クライアントにカウンター名と待機カウントを送信 サーバ時間情報を得る <QT/> <T y="..." m="..." d=""..." w="..." hh="..." mm="..." ss="..."/> <QT/> クライアントからサーバ時間を問い合わせる <T y="年" m="月" d="日" w="曜日" hh="時" mm="分" ss="秒"/> サーバからクライアントにサーバ時間を返す y属性は4桁の西暦年、m属性は1～12の整数値、d属性は1～31の整数値、w属性は、Sun,Mon,Tue,Wed,Thu,Fri,Satの三文字表記、hh,mm,ss属性は2桁の数字。 ロビーにユーザ情報を残しておく <LOG userattr="..." n="..." r="..." save="..." key="..."/> <LOG userattr="..." n="クライアント固有の番号" r="これから向かう部屋の番号" ・・・ save="..." key="クライアント固有の番号" />　　ロビーに残しておきたい情報をサーバメモリ上に保存 LOGノードはコンテンツに接続中のユーザの情報をコンテンツロビーに残す(サーバメモリ上に置く)ためのノード。後からコンテンツロビーに入って来たクライアントが参照する。ユーザ定義属性は自由に定義できる。 コンテンツロビー内でQN要素を発行して部屋を移動する直前に発行し、コンテンツロビーからコンテンツをプレーする部屋に入る前にコンテンツロビーにクライアント情報(これから向かう部屋番号や、ユーザ定義属性の値)を残しておくことができる。 コンテンツプレー中(コンテンツロビー以外の部屋にいる状態)のユーザとサーバとの間の接続が切断された場合には、クライアント固有の番号が(そのLOGノードの)n属性の値と一致する、コンテンツロビーに残されたLOG要素を消去し、切断されたユーザがプレーしていたコンテンツのロビーと切断されたユーザがいた部屋に接続中の他のユーザに対して<D n="接続を切断したクライアントの固有の番号"/>を送信する。 定員に達していない最小の部屋番号を取得する <QER max="..."/> <ER r="..."/> <QER max="部屋の定員(部屋に入れる最大人数)"/> max属性で指定した人数に達していない部屋のうち、最小の部屋番号をもつ部屋の番号をサーバに問い合わせる。 LOGノードでロビーにこれから向かう部屋の番号を(LOGノードの)r属性で指定してから(ロビーから)部屋に移動した場合にのみ有効。 <ER r="定員に達していない最小の部屋番号"/> QERノードに呼応して定員に達していない最小の部屋番号を(サーバがクライアントに対して)返す。 同一コンテンツ内の各部屋の人数を取得する <QM r="..."/> <M n="..."/> <MA><M r="..." n="..."/>...</MA> <QM/> 同一コンテンツ内に存在する各部屋の人数を(クライアントがサーバに対して)問い合わせる。 <MA><M r="部屋番号" n="部屋の中の人数"/>...</MA> 同一コンテンツ内に存在する各部屋の人数を(サーバがクライアントに対して)返す。 <QM r="部屋番号"/> 同一コンテンツ内に存在する特定の部屋番号を持つ部屋の人数を(クライアントがサーバに対して)問い合わせる。 <M n="部屋の中の人数"/> 問い合わせを受けた特定の部屋番号を持つ部屋の人数を(サーバがクライアントに対して)返す。