第 2 章   Calendar Server API (CSAPI) の概要


この章では、Calendar Server API (CSAPI) の概要を説明します。CSAPI は、iPlanet Calendar Server 5.0 の機能を変更または強化できる高性能のプログラム可能インタフェースのセットです。CSAPI により、速度、メモリ使用量、および負荷の面で、システムの実行可能ファイルもどの言語のスクリプトも上回る、非常に高速な実行時共有オブジェクトを作成できます。これらの要素はすべて、ハイエンドシステムのスケーラビリティに貢献します。

この章は、以下の節で構成されています。

• CSAPI のアーキテクチャ
  • スレッドに対する安全の要件

  • 依存性

• CSAPI の使用法
  • CSAPI モジュールの読み込み

  • プラグインインタフェース

  • クライアントおよびサーバの API

• CSAPI のサンプル

CSAPI のアーキテクチャ

---

CSAPI は、Calendar Server の機能への共有オブジェクト実行時インタフェースの集合です。プラグイン CSAPI モジュールを使用して、着信した要求や応答のためのサーバデータを操作できます。このアーキテクチャにより、サーバは未知のデータに対する単なるゲートウェイとして動作できます。また、このアーキテクチャにより、動的なログ記録や統計情報の追跡、外部認証スキーマ、ユーザ属性の操作、およびその他の機能も実装できます。

次の図 2-1 に、iPlanet Calendar Server 内での CSAPI モジュールとほかのサブシステムとの関係を示します。 CSAPI モジュールは、どの機能グループをサポートするかによって、データのフォーマット、認証、ディレクトリサービスなどの iPlanet Calendar Server の 1 つ以上の領域と連携して動作します。

モジュールとは、UNIX 上では共有オブジェクト (.so ファイル) を、Windows NT ではダイナミックリンクライブラリ (.dll ファイル) を指します。プログラマが提供する各モジュールは、このマニュアルで定義されている 1 つ以上の CSAPI インタフェース (または純粋な仮想基底クラス) を実装します。第 3 章 「CSAPI リファレンス」を参照してください。クライアント側の各インタフェースが、iPlanet Calendar Server の 1 つの機能領域に対応します。モジュールに実装するものによって、iPlanet Calendar Server とその領域のネイティブな機能を拡張したり置き換えたりすることができます。

サーバ側の API セットにより、CSAPI モジュールは、サーバのバージョン情報を取得したり、サーバの高速メモリ割り当てメカニズムを使用したりできます。

このシステムには、各 CSAPI インタフェースのプラグインがデフォルトのコードとともに含まれています (このプラグインをテンプレートとして使用して、独自のプラグインを作成できます)。また、サポートされているすべてのライブラリとヘッダーも装備されています。

図 2-1    CSAPI とほかのサブシステムとの関係

スレッドに対する安全の要件

数千ものスレッドが随時 1 つのモジュールにアクセスできるので、CSAPI モジュールのプラグインはスレッドに対して安全 (thread safe) である必要があります。スレッドに関する問題を認識できない (thread-aware でない) プラグインの場合は、プラグイン内の関数呼び出しレベルで単純な情報収集 (モニタ) のみを行なってください。NSPR スレッドの詳細は、mozilla.org の NSPR リファレンスマニュアルを参照してください。URL については、この章の「依存性」の節を参照してください。

依存性

CSAPI は、UNIX システムおよび Windows NT システム用の C および C++ のインタフェースです。CSAPI は、NSPR (Netscape Portable Runtime) と、インタフェースディスパッチ用の XPCOM を使用します。NSPR は、オペレーティングシステムサービスへのプラットフォームに依存しない API である mozilla.org ソースコードの一部です。

NSPR のマニュアルについては、次の mozilla の技術マニュアルのサイトを参照してください。

http://www.mozilla.org/docs/refList/refNSPR

XPCOM のマニュアルについては、次のサイトを参照してください。

http://www.mozilla.org/projects/xpcom

異なるプラットフォーム上で実行する必要のあるシステムでは、プラットフォームに依存しない C データ型と実行時関数に NSPR を使用する必要があります。iPlanet Calendar Server は、XPCOM C++ API (QueryInterface) を使用して、特定のモジュールが実装しているインタフェースを見つけます。

CSAPI の使用法

---

次の節では、プログラマが提供するプラグインをシステムがどのように読み込み、使用するか説明します。システムには、デフォルトのプラグインが付属しています。デフォルトのプラグインはその一部、またはすべてを拡張したり置き換えたりすることができます。

CSAPI モジュールの読み込み

iPlanet Calendar Server は、起動時に CSAPI モジュールを cal/bin/plugins ディレクトリから読み込み、サーバの停止時に読み込み解除します。すべてのプラグインモジュールは、このディレクトリに存在し、ファイル名の先頭に cs_ を持つ必要があります。

サーバは、サーバ起動時に動的に読み込まれるモジュールを決めるために、ics.conf を検査します。csapi.plugin.loadall の設定の値が y の場合、サーバは
cal/bin/plugins ディレクトリ内の名前が接頭辞 cs_ で始まるすべての共有オブジェクトを読み込みます。値が n の場合、設定はプラグインによって異なります。ics.conf の設定の詳細は、『iPlanet Calendar Server 管理ガイド』を参照してください。

特定のプラグインの読み込みを指定するには、csapi.plugin.loadall を n に設定する必要があります。このほかに 2 つの設定を使用する必要があります。それは、値を y に設定した csapi.plugin.plugin name と、値にプラグインの名前を設定した
csapi.plugin.plugin name.name です。たとえば、my_lookup という名前のカレンダー検索プラグインの場合、設定は次のとおりです。

csapi.plugin.loadall = "n"

csapi.plugin.calendarlookup = "y"

csapi.plugin.calendarlookup.name = "my_lookup"

設定の plugin name の部分は、両方の設定で一致している必要がありますが、.name 設定の値と同じである必要はありません。したがって、cs_myown_plugin というプラグインを作成する場合、設定を csapi.plugin.anyname および csapi.plugin.anyname.name と呼ぶことができます。 csapi.plugin.anyname.name の値は、「cs_myown_plugin」になります。

iPlanet Calendar Server は、NSPR 関数 PR_LoadLibrary() を使用して起動時に共有オブジェクトを読み込み、関数 PR_UnloadLibrary を使用して停止時に共有イメージを読み込み解除します。共有オブジェクトがメモリに読み込まれると、iPlanet Calendar Server は関数 PR_FindSymbol を使用してサーバが把握している API の実装へのエントリポイントを探します。

プラグインインタフェース

すべての CSAPI プラグインは、XPCOM 仕様で要求されている、エクスポートされる唯一のシンボル NSGetFactory をサポートします。このエントリポイントから、Calendar Server は XPCOM メソッドの QueryInterface を呼び出して、csIPlugin インタフェースを実装しているオブジェクトを見つけます。これにより、サーバはプラグインのバージョン、説明、およびベンダー情報を照会できます。このインタフェースはオプションです。ただし、サーバがバージョン管理できるようにこのインタフェースの実装をお勧めします。

クライアントおよびサーバの API

CSAPI は、クライアント API とサーバ API の 2 つに分けられます。

表 2-1 に、1 つ以上のプラグインで実装できる CSAPI クライアントインタフェースを一覧表示します。

表 2-1 CSAPI クライアントの API 

CSAPI モジュールインタフェース	説明
csIAccessControl	デフォルトのアクセスコントロールメカニズムを拡張または置き換える
csIAuthentication	ログイン認証メカニズムを拡張または置き換える
csICalendarLookup	デフォルトのカレンダー検索メカニズムを拡張または置き換える
csIDataTranslator	着信データおよび発信データの形式変換を拡張または置き換える
csIPlugin	モジュールのバージョン管理情報と内容に関する情報を提供する
csIUserAttributes	ユーザ属性の格納および検索メカニズムを拡張または置き換える
csIQualifiedCalidLookup	指定された完全修飾の URL のカレンダー ID を検索する

これらのインタフェースの詳細は、第 3 章 「CSAPI リファレンス」を参照してください。

すべてのインタフェースには、実装する必要のある次の初期化メソッドがあります。

Init (nsISupports * aServer);

サーバは、新しく読み込まれたモジュールにインタフェースを登録した直後にこのメソッドを呼び出します。モジュール内では、サーバが返すパラメータ aServer をバインドし、このパラメータを使用してサーバインスタンスを参照できます。カスタムプラグインでは、QueryInterface メソッドを使用して、表 2-2に一覧表示したサーバインタフェースを取得できます。

表 2-2 CSAPI サーバの API

サーバインタフェース	説明
csICalendarServer	バージョン番号などの全般的なサーバ情報を提供する
csIMalloc	サーバのメモリ割り当てメカニズムへアクセスする

サーバに対する照会の例

次の例では、Calendar Server のバージョンを確認します。この例では、以下の処理を行う方法を示します。

• Init メソッドから戻された参照をバインドする

• サーバのインタフェースを照会する

• そのインタフェースでサーバメソッドを呼び出す

• サーバへの参照を解放する

  NS_IMETHODIMP csDataTranslator ::Init(nsISupports * aServer)
  {
  nsresult res = NS_COMFALSE ;
  PRUint32 min, maj;
  csICalendarServer * cs;
  /* CalendarServer の QueryInterface。呼び出しが成功したら、サーバは
  リファレンスカウントを増分します */
  if (aServer)
    res = aServer->QueryInterface(kICalendarServerIID,(void**)&cs);
  /* サーバへの参照の取得に成功したら、バージョンを確認する */
  if (NS_SUCCEEDED(res)) {
    cs->GetVersion(maj,min);
    if (min > 0 && maj >= 1)
      res = NS_OK;
    else
      res = NS_COMFALSE;
  /* サーバインスタンスに対するこの参照を解放する */
    cs->Release();
    }
  return res;
  }

CSAPI のサンプル

---

csapi/samples ディレクトリには、3 つの CSAPI インタフェースのコーディング例が含まれています。独自の CSAPI モジュールを作成する際、それらのファイルをテンプレートとして使用できます。

以下のサンプルモジュールが用意されています。

表 2-3 CSAPI インタフェースのサンプル

CSAPI モジュールのサンプル	説明
authentication	このサンプルでは、デフォルトのログイン認証メカニズムを置き換え、ローカルの認証を使用してユーザを確認する。このサンプルは、Solaris と Window NT で実行できる Solaris では、このサンプルは pam ライブラリを使用してローカルの /etc/passwd ファイルまたは NIS に対して認証を行う Windows NT では、このサンプルは、Microsoft クライアントに対して認証を行う WIN32 API LogonUser を使用する。このサンプルを NT で正常に実行できるようにするには、管理者はバッチジョブを介したユーザのログオン権を有効にする必要がある。これは、ユーザー マネージャ管理ツールの「原則/ユーザーの権利」セクションから実行できる
dataTranslator	このサンプルは、着信データおよび発信データのデフォルトの形式変換を拡張または置き換える。このサンプルは、icalendar データを Microsoft Outlook の CSV 形式に変換する方法を示している。CSV 形式は単純な行指向のファイルで、各項目にそれぞれの行があり、プロパティはコンマで区切られている
userAttributes	このサンプルは、ユーザ属性の格納および検索用のデフォルトのメカニズムを拡張または置き換える。このサンプルは、ローカルのユーザ設定を格納するバークレーデータベースの使い方を示している。このコードは、サポートされているすべてのプラットフォームで実行できる。データベースは、単純な表形式のキーと値のペアで構成される。ユーザ設定を格納するためのキーは、$user.$pref として格納された文字列である。キーは一意である必要がある