LingrCom

概要

Webチャット"Lingr"のAPIをJavascriptから利用するためのライブラリです。lingrcom.jsと複数のcgiファイル(perlスクリプト)により構成されます。cgiをプロキシとして利用することで、www.lingr.comへのクロスドメイン通信を行います。

使い方の例

次の４文で、セッションを開始し、部屋へ入り、メッセージを監視します。メッセージを受信すると、observeの引数で渡したcallback関数が呼ばれます。

lingrobj = new LingrCom("lingrobj");
lingrobj.createSession();
lingrobj.enterRoom("roomid", "nickname");
lingrobj.observe(callback関数);

次の文で、部屋に対して発言をします。

lingrobj.say("発言する文字列");

LingrComを使ったサンプル

LingrComを使ったチャットです。→こちら

ダウンロード

lingrcom_v0051.zip (7KB)

利用前の設定

• LingrAPIキーを取得し、scripts/cgi/ses.cgi の3行目に取得したキーを設定します。

  $apikey = "xxxxxx";
  

• scripts/cgi ディレクトリ以下のファイルを、サーバ側のcgi実行可能なディレクトリにアップロードし、そのディレクトリのパスをlingrcom.jsファイルの下記の行に設定します。パスの最後の"/"も必要です。利用元のhtmlファイル、lingrcom.jsファイル、scriptsディレクトリをすべて同じ階層に設置する場合は初期設定のままでOKです。

  var lingrcom_cgipath = "./scripts/cgi/";
  

• cgiディレクトリ以下のすべてのファイルに実行権限を付与します。

  .htaccessファイルは、XREAの自動広告挿入の影響で、cgiで出力するContent-Typeが書き換えられてしまう問題を回避するためのものです。XREA以外ではたぶん不要です。

関数リファレンス

LingrCom(myname)

• 機能： コンストラクタです。

• 引数： (必須)生成するオブジェクトの名前を文字列で。内部的にJSONPする際に使用しています。

  (例)　lingrobj = new LingrCom("lingrobj");
  

• 返り値： なし。

createSession()

• 機能： セッションを開始します（同期関数）。

• 引数： なし。

• 返り値： true(成功), false(失敗)

createSessionA(cb)

• 機能： createSession()の非同期版。

• 引数： コールバック関数。cbの第１引数にはcreateSession()の返り値と同じ真偽値が渡されます。

• 返り値： true(リクエスト成功), false(XMLHttpRequest生成失敗)

enterRoom(roomid, nickname)

• 機能： roomidで指定した部屋へ入室します（同期関数）。

• 引数1： (必須)入室する部屋のID。

• 引数2： (オプション)入室する際の自分のニックネーム。省略した場合はanonymous observerとなり、発言する前に後述のsetNicknameでニックネームを設定する必要があります。

• 返り値： true(成功), false(失敗)

enterRoomA(roomid, nickname, cb)

• 機能： enterRoom()の非同期版。

• 引数1： (必須)入室する部屋のID。

• 引数2： (オプション)入室する際の自分のニックネーム。省略した場合はanonymous observerとなり、発言する前に後述のsetNicknameでニックネームを設定する必要があります。

• 引数3： コールバック関数。cbの第１引数にはenterRoom()の返り値と同じ真偽値が渡されます。

• 返り値： true(リクエスト成功), false(XMLHttpRequest生成失敗)

setNickname(nickname)

• 機能： ニックネームを設定します（同期関数）。

• 引数： (必須)設定するニックネーム。

• 返り値： true(成功), false(失敗)

say(str, cb)

• 機能： 入室している部屋に対して発言を行います（非同期関数）。

• 引数1： (必須)発言する文字列。

• 引数2： (オプション)sayに対するコールバック関数。cbの第１引数にはLingrAPIのMessageオブジェクトが渡されます。nullの場合はsayの失敗を意味します。

• 返り値： true(リクエスト成功), false(XMLHttpRequest生成失敗)

observe(cb)

• 機能： 入室している部屋の監視を開始します（非同期関数）。本関数はメッセージ受信後もobserveを自動で継続するため、最初に１度コールするだけでOKです。メッセージを受信する度にコールバック関数cbが呼び出されます。

• 引数： (必須)メッセージを受信した際のコールバック関数。cbの第１引数にはLingrAPIのMessageオブジェクトの配列が渡されます。nullの場合はobserveの失敗を意味し、observeの継続は中止されます。cbの第２引数には、入室している部屋での自分のoccupant_idが渡されます（自分のメッセージを選別する用途に使います）。

• 返り値： なし。

getMessages(num, cb)

• 機能： 指定カウンターから現在までのメッセージを受信します（非同期関数）。

• 引数1： (必須)受信する最初のメッセージのカウンター値。負の値を指定した場合は、現在から遡って受信するメッセージの個数を意味します。

• 引数2： (必須)メッセージを受信した際のコールバック関数。cbの第１引数にはLingrAPIのMessageオブジェクトの配列が渡されます。cbの第２引数には、入室している部屋での自分のoccupant_idが渡されます（自分のメッセージを選別する用途に使います）。cbの第３引数には、getMessageの結果が、true(成功), false(失敗)で渡されます。

• 返り値： true(リクエスト成功), false(XMLHttpRequest生成失敗)

setOcupantsChangeCallback(cb)

• 機能： チャット参加者が変化した際にコールバックされる関数を設定します。

• 引数： (必須)チャット参加者が変化した際のコールバック関数。cbの第１引数にはLingrAPIのOccupantオブジェクトの配列が渡されます。cbの第２引数には、入室している部屋での自分のoccupant_idが渡されます（自分のメッセージを選別する用途に使います）。

• 返り値： なし。

leaveRoom()

• 機能： 部屋を退室します（非同期関数）。

• 引数： なし。

• 返り値： true(成功), false(失敗)

destroySession()

• 機能： セッションを破棄します（非同期関数）。入室している場合は自動的に退室します。

• 引数： なし。

• 返り値： true(リクエスト成功), false(XMLHttpRequest生成失敗)

コメント、バグ報告等

コメント、バグ報告等は、日記のコメント欄へお願いします。

更新履歴

• 2007/05/05 ver. 0.01

• 2007/05/06 ver. 0.02 IEでのバグ修正

• 2007/05/09 ver. 0.03 leaveRoomへ返り値を追加、observe,getMessages,setOcupantsChangeCallbackのcbの第２引数を追加。

• 2007/05/12 ver. 0.04 sayでPOSTするメッセージをエンコードしていなかったバグ修正。

• 2007/05/14 ver. 0.05 createSessionとenterRoomの非同期版を作成。返り値の整理。

• 2008/01/20 ver. 0.051 Operaで正常に動作するよう修正