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


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

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

• CSAPI アーキテクチャ
  • スレッドセーフ (Thread Safe) の条件

  • 依存性

• CSAPI の使用方法
  • CSAPI モジュールのロード

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

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

• CSAPI のサンプル

CSAPI アーキテクチャ

---

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

図 1-1 に、iPlanet Calendar Server における CSAPI モジュールと他のサブシステムとの関係を示します。CSAPI モジュールはサポートする関数グループに基づいて、 iPlanet Calendar Server 機能 (データのフォーマット、認証、ディレクトリサービスなど) の 1 つ以上の領域に作用することができます。

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

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

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

図 1-1    CSAPI と他のサブシステムとの関係

スレッドセーフ (Thread Safe) の条件

何千ものスレッドがいつでもモジュールにアクセスできるように、CSAPI モジュールのプラグインはスレッド・セーフである必要があります。スレッドを認識できないプラグインの場合は、プラグイン内の関数呼び出しレベルで簡単なモニタを使用します。NSPR (Netscape Portable Runtime) スレッドの詳細は、mozilla.org の NSPR リファレンスマニュアルを参照してください。URL については、この章の「依存性」の節を参照してください。

依存性

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

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

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

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

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 つの設定を行います。具体的には、csapi.plugin.plugin name の値に y を設定し、csapi.plugin.plugin name.name にプラグインの名前を設定します。たとえば、カレンダー検索プラグインの場合は、設定は次のようになります。

csapi.plugin.loadall = "n"

csapi.plugin.calendarlookup = "n"

csapi.plugin.calendarlookup.name = " "

設定の 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 プラグインは、エクスポートされた唯一のシンボル NSGetFactory を、XPCOM の仕様で定義されているとおりにサポートします。Calendar Server はこのエントリポイントから XPCOM メソッド QueryInterface を呼び出して、csIPlugin インタフェースを実装するオブジェクトを検索します。これによって、サーバはプラグインのバージョン、説明、およびベンダー情報を照会できます。このインタフェースはオプションです。ただし、サーバがバージョンを管理できるように、このインタフェースを実装することをお勧めします。

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

CSAPI は、クライアント API とサーバ API の 2 つに分けることができます。

表 1-1 に、1 つまたは複数のプラグインに実装される CSAPI クライアントインタフェースについて示します。

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

CSAPI モジュールインタフェース	説明
csIAccessControl	デフォルトのアクセス制御メカニズムを拡張またはオーバーライドする
csIAuthentication	ログイン認証メカニズムを拡張またはオーバーライドする
csICalendarLookup	デフォルトのカレンダー検索メカニズムを拡張またはオーバーライドする
csIDataTranslator	入力および出力データの形式変換を拡張またはオーバーライドする
csIPlugin	モジュールのバージョン管理情報と詳細情報を提供する
csIQualifiedCalidLookup	指定された修飾 URL のカレンダー ID を取得する
csIUserAttributes	ユーザ属性の格納および検索メカニズムを拡張またはオーバーライドする

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

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

Init (nsISupports * aServer);

サーバは、新しくロードしたモジュールのインタフェースを登録すると、すぐにこのメソッドを呼び出します。モジュール内では、サーバが返すパラメータ aServer をバインドし、このパラメータを使用してサーバインスタンスを参照できます。カスタムプラグインでは、QueryInterface メソッドを使用して、表 1-2 に記載されているサーバインタフェースを見つけることができます。

表 1-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 モジュールを作成する場合は、これらのファイルをテンプレートとして使用できます。

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

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

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