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


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

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

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

  • 依存性

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

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

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

• CSAPI のサンプル

CSAPI アーキテクチャ

---

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

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

モジュールは、UNIX の共有オブジェクト (.so ファイル)、または Windows NT のダイナミックリンクライブラリ (.dll ファイル) です。 ユーザーが提供する各モジュールは、このマニュアルで定義されている CSAPI インタフェース (または純粋な仮想基底クラス) を実装します (第 2 章 「CSAPI リファレンス」 を参照)。クライアント側の各インタフェースは、Sun ONE Calendar Server の 1 つの機能領域に対応します。 モジュール内の実装により、モジュールの領域にある Sun ONE 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™ の技術マニュアル Web サイトを参照してください。

http://www.mozilla.org/projects/nspr/reference/html/index.html

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

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

実装をさまざまなプラットフォームで行う必要がある場合は、プラットフォームに依存しない C データ型と実行時関数として NSPR を使用する必要があります。Sun ONE Calendar Server は XPCOM C++ API (QueryInterface) を使用して、特定のモジュールが実装するインタフェースを正確に検出します。

CSAPI の使用方法

---

ここでは、ユーザが提供するプラグインをシステムがどのようにロードし、使用するかを説明します。システムにはデフォルトのプラグインが用意されています。デフォルトのプラグインのいずれか、またはすべてのプラグインに対して、拡張またはオーバーライドできます。

CSAPI モジュールのロード

Sun ONE Calendar Server は、起動時に CSAPI モジュールを cal/bin/plugins ディレクトリからロードし、停止時にアンロードします。 すべてのプラグインモジュールはこのディレクトリ内に常駐し、ファイル名は cs_. で始まる必要があります。

サーバは、起動時に動的にロードするモジュールに関して ics.conf を確認します。 csapi.plugin.loadall の設定値が y の場合、サーバは、cal/bin/plugins ディレクトリ内の名前が接頭辞 cs_. で始まる共有オブジェクトをすべてロードします。 設定値が n の場合は、プラグインによって設定が異なります。 ics.conf の設定の詳細については、『Sun ONE 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」になります。

Sun ONE Calendar Server は、NSPR 関数 PR_LoadLibrary() を使用して起動時に共有オブジェクトをロードし、関数 PR_UnloadLibrary を使用して停止時に共有イメージをアンロードします。 共有オブジェクトがメモリーにロードされると、Sun ONE Calendar Server は関数 PR_FindSymbol を使用して、既知の API の実装に対するエントリポイントを探します。

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

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

プラグインのバージョン番号

デフォルトのプラグインインタフェースには、それぞれ異なるバージョン番号が付けられています。 Sun Microsystems, Inc によって API が更新されると、バージョン番号は整数で増加します。すべてのカスタムプラグインは、デフォルトのプラグイン API の現在のバージョンのメソッドを使用する必要があります。

以前のバージョンのデフォルトプラグインを基にしてカスタムプラグインを作成した場合、カスタムプラグインを更新して、すべて更新済みの新しいバージョンのメソッドを使用しければなりません。また、デフォルトのプラグインの現在のバージョン番号を反映させるために、バージョン番号を上げる必要があります。

システムは、現在のデフォルトのバージョン番号より以前のバージョン番号ではプラグインをロードできません。 プラグインのバージョン番号は、現在のデフォルトのプラグイン以降で、なおかつ次の整数よりも前でなければなりません。 たとえば、現在バージョン 2.0 である csIDatabaseLookup のカスタムプラグインを書く場合や、以前に作成したことがある場合、プラグインのバージョン番号は 2.0 以降で、なおかつ 3.0 以前にしなければなりません。

表 1-1 に各プラグイン API の現在のバージョンを一覧表示します。

表 1-1    プラグイン API の現在のバージョン

プラグイン API	デフォルトプラグインの現在のバージョン
csIAccessControl	1.0
csIAuthentication	1.0
csICalendarLookup	2.0
csIDataTranslator	2.0
csIPlugin	1.0
csIQualifiedCalidLookup	1.0
csIUserAttributes	2.0
csICalendarServer	1.0
csIMalloc	1.0

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

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

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

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

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

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

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

Init (nsISupports * aServer);

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

表 1-3    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-4    CSAPI インタフェースのサンプル

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