# カレンダとの統合

カレンダのアプリケーション・プログラム・インタフェース(API)は、ネットワーク環境でカレンダ・データにアクセスし、管理するためのプログラム的な方法を提供します。 APIは、項目の挿入、削除、変更だけでなく、ブラウズおよび検索機能もサポートします。また、カレンダ管理関数をサポートします。

カレンダAPIは、X.400 Application Programming Interface Association (XAPIA)のCalendaring and Scheduling API (CSA API)を実装しています。
CSA APIは、カレンダが有効なアプリケーションからカレンダおよびスケジュール・サービスのさまざまな機能へのアクセスを可能にする高水準の関数のセットを定義しています。 最新のXAPIA仕様の詳細については、X.400 API Association, 800 El Camino Real, Mountain View, California 94043に問い合わせてください。

この章では、以下の節でカレンダAPIを説明します。

PG.dndPG.mkr.3
PG.dndPG.mkr.4
PG.calmg.mkr.4
PG.calmg.mkr.5
PG.calmg.mkr.8
PG.calmg.mkr.12
PG.calmg.mkr.14
PG.calmg.mkr.16
PG.calmg.mkr.19
PG.calmg.mkr.20
PG.calmg.mkr.21
PG.calmg.mkr.22

## ライブラリとヘッダ・ファイル

カレンダAPIを使用するには、`
libcsa`ライブラリをリンクする必要があります。ヘッダ・ファイルは、`
csa/csa.h`です。

## デモ・プログラム

カレンダAPIの使用例を示すデモ・プログラムが、 `/usr/dt/examples/dtcalendar`にあります。

## カレンダAPIの使い方

### カレンダと統合するには

カレンダAPIは、ネットワーク環境でカレンダ・データにアクセスし、管理する方法を提供します。

1. アプリケーションに`csa/csa.h`を組み込みます。

2. カレンダAPIを使用して、アプリケーションの中で使いたいカレンダ操作を組み込みます。

3. `libcsa`とリンクします。

## CSA APIの概要

CSAインタフェースは、カレンダおよびスケジュール・サービスへの共通インタフェースを可能にします。 CSA実装のそれぞれについて、CSAによって与えられる表示と機能は、基本のカレンダ・サービスの表示と機能にマップされなければなりません。 インタフェースは、実際のカレンダおよびスケジュールの実装に依存しないように設計されています。 インタフェースは、また、カレンダ・サービスが使用するオペレーティング・システムと基本のハードウェアに依存しないように設計されています。

提供される関数呼び出しの数は、最小限のものです。一組の関数で複数の種類のカレンダ項目を管理します。

### C の命名規則

PG.calmg.mkr.7に示すように、C インタフェースの要素の識別子は、要素の属性名とそれに関連するデータ型に由来します。 属性名には、テーブルの２番目の欄の文字列が接頭辞として付けられます。 英字は、３番目の欄の大文字または小文字に変換されます。

### C 命名規則の由来

`要素の種類` | `接頭辞` | `大文字/小文字`
データ型 | `CSA_` | 小文字
データの値 | `CSA_` | 大文字
関数 | `csa_` | 小文字
関数の引き数 | `なし` | 小文字
関数の結果 | `なし` | 小文字
定数 | `CSA_` | 大文字
エラー | `CSA_E_` | 大文字
マクロ | `CSA_` | 大文字
拡張セットのために確保 | `CSA_XS_` | 大文字/小文字
拡張のために確保 | `CSA_X_` | 大文字/小文字
処理系作成者が使用するために確保 | `CSAP` | 大文字/小文字
ベンダ関数拡張のために確保 | csa_x | 小文字
構造体のタグ | `CSA_TAG_` | 大文字

接頭辞`CSAP`(大文字/小文字)がついている要素は、CSAサービスの実装の作成者が内部専用として使用するために確保されています。 CSAインタフェースによって書かれたプログラムが直接使用するためのものではありません。

接頭辞`CSA_XS_`、 `CSA_X_`(大文字/小文字)、および `csa_x`は、ベンダまたはグループによるインタフェース拡張のために確保されています。仕様では、これらのインタフェース拡張は、基本関数セットの拡張として定義されています。

定数データ値の場合、定数データ値のデータ構造体または関数を示すために、通常、追加の文字列が`CSA_`に追加されます。

## 機能のアーキテクチャ

本節では、CSA APIをサポートしているサービスの機能のアーキテクチャを説明します。抽象実装モデル、抽象データ・モデル、および機能の概要を示します。

### 実装モデル

CSA APIの適用範囲が理解できるように、抽象実装モデルが用意されています。

CSAインタフェースは、カレンダが使用可能なアプリケーションとカレンダ・サービスの間に定義されます。 このインタフェースの機能はすべて、カレンダ・サービスに依存しないように設計されています。 ただし、このAPIでは、拡張の使用によって実行される共通関数のプロトコル固有の拡張は許されています。詳しくは、 PG.calmg.mkr.11を参照してください。 カレンダが使用可能なアプリケーションとカレンダ・サービスのCSAインタフェースの関係を PG.calmg.mkr.9に示します。

#### カレンダおよびスケジュールAPIの位置付け

CSA インタフェースのモデルは、管理、カレンダ管理、および項目管理という３つのコンポーネントに分けることができます。これらのコンポーネントを PG.calmg.mkr.10に示します。

#### カレンダおよびスケジュールAPIのコンポーネント

カレンダ・サービスへのアクセスは、カレンダ・セッションを通して確立されます。セッションは、カレンダ・サービスへの有効な接続のために用意され、サービスによって保持されるカレンダ情報の整合性の確保を支援します。 カレンダが使用可能なアプリケーションは、カレンダ・サービス内の個々のカレンダにログインして、有効なセッションまたは接続を確立します。 セッションは、カレンダが使用可能なアプリケーションからログアウトすることによって終了します。

カレンダ・サービスは、１つ以上のカレンダを保持します。 カレンダ・サービスは、これらのカレンダに対して、いくつかのレベルの管理サポートを提供します。 カレンダが使用可能なアプリケーションは、特定のカレンダ・サービスによって保持されるカレンダのリストにアクセスすることができます。 さらに、カレンダ・サービスにより、実装固有の永続的形式にカレンダ情報を保管したり、復元することができます。 カレンダ・サービスが複数のカレンダの保持をサポートする場合には、カレンダの作成と削除のためのサポート関数が定義されます。 また、カレンダの特性を管理するための関数が定義されます。

CSAインタフェースのほとんどの関数は、個々のカレンダ項目を管理します。 カレンダ項目は、イベント、予定、またはメモです。 項目は、特定のカレンダへの追加、削除、更新、および読み取りができます。 カレンダが使用可能なアプリケーションは、また、カレンダ項目に通知を追加することができます。

### データ・モデル

CSA インタフェースは、カレンダ・サービスによって保持されるカレンダ情報の概念上のバックエンドの記憶領域へのアクセス方法です。 共通データ・モデルは、カレンダ・サービスによって保持されるカレンダ情報のコンポーネントを視覚化する際に役立ちます。

#### カレンダ・エンティティ

データ・モデルは、カレンダ・エンティティの概念に基づきます。 カレンダは、管理カレンダ属性とカレンダ項目の名前付きコレクションによって表されます。カレンダは、個々のユーザによって所有されます。 ユーザは、個人、グループ、またはリソースを表します。

カレンダ属性は、カレンダに関する共通、実装固有、またはアプリケーション固有の管理特性を表す名前付きの値のセットです。 たとえば、タイムゾーン、名前、所有者、およびカレンダへのアクセスの権利を、個々のカレンダ属性の中で指定することができます。

カレンダ項目は、カレンダの主要なコンポーネントです。 カレンダ項目の３つのクラスは、次のとおりです。

- イベント

- 予定

- メモ

カレンダ項目は、固有な名前を付けられた項目属性のコレクションによって表されます。 項目属性は、カレンダ項目の共通、実装固有、またはアプリケーション固有の特性を表す名前付きの値のセットです。 たとえば、イベントには、開始と終了の日付と時間、説明、およびサブタイプを指定できます。 予定には、作成日、期限、優先順位、およびステータスを指定できます。 メモには、作成日とテキスト内容または説明を入れることができます。

カレンダ項目と項目属性は、名前、型、値の３つの組からなります。 仕様によって定義されている共通属性を拡張することができます。 実装によって、実装固有の属性を定義することができます。 また実装によっては、アプリケーションでアプリケーション固有の属性を定義するための機能を提供します。 CDEでは、アプリケーション定義の属性をサポートします。

#### アクセスの権利

個々のユーザがカレンダにアクセスできるかどうかは、そのユーザに与えられるアクセスの権利によって制御されます。 アクセスの権利は、カレンダのユーザと対になっています。 CSAでは、ユーザは、個人、グループ、またはリソースです。 CDEでは、個々のユーザだけをサポートします。 アクセスの権利は、アクセス・リストで保持されます。 アクセス・リストは、特定のカレンダ属性です。 アクセスの権利は、個別に制御され、それを累積することによって、カレンダとその項目に対するユーザのアクセスの範囲を定義することができます。 アクセスの権利は、また、次のアクセスの役割の観点から指定することができます。

- カレンダの所有者

- カレンダ内の特定の項目の主催者

- カレンダ内の特定の項目のスポンサー

所有者の役割を与えられたユーザは、カレンダの所有者ができることであれば、カレンダまたはカレンダ項目に対して何でも行うことができます。 すなわち、カレンダの削除、カレンダ属性の表示、挿入、変更、カレンダ項目の追加と削除、項目属性の表示、挿入、変更ができます。

主催者の役割を与えられたユーザは、そのユーザが主催者として指定されたカレンダ項目に対して、項目の削除、または項目属性の表示と変更を行うことができます。 デフォルトでは、項目を作成したカレンダ・ユーザが主催者です。

スポンサーの役割を与えられたユーザは、そのユーザがスポンサーとして指定されたカレンダ項目に対して、項目の削除、または項目属性の表示と変更を行うことができます。スポンサーは、カレンダ項目を実質的に所有するカレンダ・ユーザです。

これらの役割に加えて、アクセスの権利の設定によって、公用、半私用、私用の分類に応じて、空き時間の検索へのアクセス、カレンダ属性の表示、挿入、または変更、項目の表示、挿入、または変更を制限することができます。 項目の分類はアクセスできるかどうかの二次フィルタとして機能します。

### 機能の概要

CSA インタフェースは、主に３種類の作業をサポートします。

- 管理

- カレンダ管理

- エントリ管理

#### 管理

CSA関数呼び出しの大部分は、カレンダ・セッションの中で発生します。 カレンダ・セッションは、カレンダが使用可能なアプリケーションとカレンダ・サービスによって保持された特定のカレンダとの間の論理的な接続です。 セッションは、`csa_logon()`関数の呼び出しで確立され、 `csa_logoff()`関数の呼び出しで終了します。 セッションの状況は、セッション・ハンドルによって表されます。 このハンドルは、１つのカレンダ・セッションを他のセッションと見分けるためのトークンを各CSA関数の中で提供します。 `csa_logon()`関数は、また、カレンダ・サービスに対してユーザを認証し、セッション属性を設定します。 現時点では、アプリケーション間のカレンダ・セッションの共有はサポートされていません。

`csa_list_calendars()`関数は、特定のカレンダ・サービスによって管理されるカレンダの名前をリストするために使用されます。

`csa_query_configuration()`関数は、現在のカレンダ・サービスの構成に関する情報をリストするために使用されます。 この情報は、文字セット、テキスト文字列の行終了文字、デフォルトのサービス名、指定されたカレンダ・サービスのデフォルトの認証ユーザ識別子、ユーザ識別子を認証するためにパスワードが必要かどうかを示すインジケータ、ユーザ・インタフェース・ダイアログの共通拡張がサポートされるかどうかを示すインジケータ、および実装によってサポートされるCSA仕様などです。

CSAの実装では、サービスによって返されるカレンダ・オブジェクトおよび属性のためのメモリの管理をサポートします。 `csa_free()`関数は、このメモリが不要になったときに、解放するために使用されます。カレンダ・サービスによって割り当てられ、管理されるメモリを解放するのは、アプリケーションの責任です。

#### カレンダ管理

CSAインタフェースは、いくつかのカレンダ管理関数を提供します。 CDEでは、１つのカレンダ・サービスにつき複数のカレンダをサポートします。 カレンダが使用可能なアプリケーションは、カレンダを追加したり、削除することができます。 `csa_delete_calendar()`関数は、カレンダを削除するために使用されます。 `csa_add_calendar()`関数は、サービスに新しいカレンダを追加するために使用されます。

アプリケーションは、また、 `csa`_`list_calendar_attributes()`、 `csa_read_calendar_attributes()`、および `csa_update_calendar_attributes()`関数を使用して、カレンダ属性のリスト、読み取り、および更新を行うことができます。 アプリケーションは、カレンダ・ログイン、カレンダの削除、カレンダ属性の更新、新しいカレンダ項目の追加、カレンダ項目の削除、およびカレンダ項目の更新について通知を受けるためのコールバック関数を登録することができます。 コールバック関数は、カレンダ・セッションの継続中だけ登録されます。 いずれにせよ、この情報は、一部のカレンダ管理アプリケーションはにとっては貴重なものです。

#### エントリ管理

CSA インタフェースは、カレンダ項目を管理するための強力な関数のセットを備えています。 カレンダ・セッション中のカレンダ項目の状況は、項目ハンドルによって保持されています。 このハンドルは、１つのカレンダ項目を他の項目と見分けるためのトークンを CSA 関数の中で提供します。 項目ハンドルは、`csa_add_entry()`および `csa`_`list_entries()`関数によって返されます。項目ハンドルは、カレンダ・セッションの継続期間、あるいは項目が削除または更新されるまで有効です。 `csa_free()`の呼び出しによって解放されると、項目ハンドルは無効になります。

`csa_``add_entry()`関数は、カレンダに新しい項目を追加するために使用されます。 `csa_delete_entry()`関数は、カレンダの中の項目を削除するために使用されます。 `csa_` `list_entries()`関数は、項目属性基準の特定のセット一致するカレンダ項目を列挙するために使用されます。 `csa_read_entry_attributes()`関数は、特定のカレンダ項目に関連するすべてまたは一組の項目属性値を取り出すために使用されます。

カレンダに項目を追加するには、カレンダが使用可能なアプリケーションは、まず、`csa_logon()`関数を使用して、カレンダ・サービスとのセッションを確立しなければなりません。 次に、アプリケーションは、`csa_add_entry()`関数を、新しい項目を指定するために実行します。 カレンダが使用可能なアプリケーションは、`csa_add_entry()`関数の中で使われる属性を組み立てる責任があります。 セッションの終了には、`csa_logoff()`関数が使用されます。

個々のカレンダ項目の中の項目属性は、`csa_list_entry_attributes()`関数で列挙することができます。 `csa_` `read_entry_attributes()`関数を使うと、１つ以上の属性の値を読み取ることができます。 個々の項目属性は、`csa_update_entry_attributes()`関数で変更することができます。

カレンダ情報を検索するためにCSAの実装によって割り当てられたメモリは、関連するメモリ・ポインタを`csa_free()`関数に渡すことによって解放されます。

再帰的活動に関連するカレンダ項目もあります。 `csa_list_entry_sequence()`関数を使うと、他の再帰的カレンダ項目を列挙することができます。 この関数は、再帰的項目の項目ハンドルのリストを返します。

CDE カレンダ・サーバは、カレンダ項目に関連付けられるアラームまたは通知のサポートをします。 通知は、端末のスピーカからの音声による通知、端末画面の点滅による通知、カレンダ・ユーザへのメール送信による通知、または端末画面にポップアップを表示することによる通知などの形を取ることができます。 カレンダ・サービスは通知を管理しますが、通知情報を検索し、それに対処するのはカレンダ・アプリケーションの責任です。 `csa_read_next_reminder()`関数は、次のスケジュール済みの通知に関する情報を読み込むために使用されます。

### 拡張

CSA 仕様で定義されている大半のデータ構造と関数は、整然と拡張することができます。 拡張は、データ構造にフィールドを追加したり、関数呼び出しにパラメータを追加するために行われます。 これらの拡張のための標準的な汎用データ構造が定義されています。 それは、拡張を識別するコード、拡張データまたはデータ自体の長さを保持する項目データ、拡張値が格納されている場所を示す項目参照(関連する項目の格納領域がない場合には`NULL`)、および拡張のフラグから成ります。

関数呼び出しにパラメータを追加するような拡張を、入力または出力時に行うことができます。 すなわち、拡張は、アプリケーションからCSAサービスへの入力パラメータとして渡すことができ、または、CSAサービスからアプリケーションへの出力パラメータとして渡すこともできます。 拡張が入力パラメータの場合には、アプリケーションは、拡張構造体とその拡張に関連するその他の構造体のためのメモリを割り当てます。 拡張が出力パラメータの場合には、CSAサービスは、必要に応じて、拡張の結果のための記憶領域を割り当てます。 この場合、アプリケーションは、割り当てられた記憶領域を`csa_free()`呼び出しによって解放しなければなりません。

サポートされていない拡張が要求された場合には、 `CSA_E_UNSUPPORTED_FUNCTION_EXT`が返されます。

## データ構造

PG.calmg.mkr.13に、CSAデータ構造をリストします。詳しい説明については、関連するマニュアル・ページを参照してください。

## CSAデータ構造

`データ型の名前` | `説明`
Access List | カレンダ・ユーザのアクセスの権利構造体のリスト
Attendee List | 出席者構造体のリスト
Attribute | 属性構造体
Attribute Reference | 属性参照構造体
Boolean | 論理的なtrueまたはfalseを示す値
Buffer | データ項目のポインタ
Calendar User | カレンダ・ユーザ構造体
Callback Data Structures | コールバック・データ構造体
Date and Time | 日付と時間の指定
Date and Time List | 日付と時間の値のリスト
Date and Time Range | 日付と時間の範囲
Entry Handle | カレンダ項目のハンドル
Enumerated | 計算の値を含むデータ型
Extension | 拡張構造体
Flags | ビット・マスクのコンテナ
Free Time | 空き時間構造体
Opaque Data | 不透明データ構造体
Reminder | 通知構造体
Reminder Reference | 通知参照構造体
Return Code | 関数が成功したこと、または失敗した理由を示す戻り値
Service Reference | サービス参照構造体
Session Handle | カレンダ・セッションのハンドル
String | 文字列ポインタ
Time Duration | 継続時間

## カレンダ属性

PG.calmg.mkr.15に、CDEでサポートされるカレンダ属性をリストします。 詳しくは、関連するマニュアル・ページを参照してください。 カレンダ属性のリストは、拡張命名規則による拡張が可能です。

## CSAカレンダ属性

`属性名` | `説明` | `読み取り専用`
Access List | アクセス・リスト属性Access list attribute | ×
Calendar Name | カレンダ名属性 | ○
Calendar Owner | カレンダ所有者属性 | ○
Calendar Size | (計算された)カレンダ・サイズ属性 | ○
Character Set | 文字セット属性 | ×
Date Created | カレンダ作成日付属性 | ○
Number Entries | (計算された)項目属性の数 | ○
Product Identifier | 製品識別子属性 | ○
Time Zone | タイムゾーン属性 | ×No
Version | 製品バージョン属性 | ○

次の節では、 PG.calmg.mkr.15にリストしたカレンダ属性について、追加の情報を提供します。

- `Access List`

  新しいカレンダが追加されるときにアクセス・リストが指定されなかった場合には、デフォルトのアクセス・リストには 特殊ユーザworldが指定され、それに対応するアクセスの権利は `CSA_VIEW_PUBLIC_ENTRIES`になります。 これは、公用のカレンダ・エントリのリストと読み取りのアクセスの権利を与えます。 特殊ユーザworldには、すべてのユーザが含まれます。

- `Calendar Name`

  カレンダ名は、`csa_add_calendar()`によってカレンダが作成されるときに指定されます。 読み取り専用であり、カレンダの作成後に変更することはできません。

- `Calendar Owner`

  カレンダ所有者は、`csa_add_calendar()`を呼び出してカレンダを作成するアプリケーションを実行しているユーザに設定されます。 読み取り専用であり、カレンダの作成後に変更することはできません。

- `Character Set`

  この値の読み取り設定には、CDE 共通ロケール名が使用されます。

### CDEカレンダ属性

CDE定義済みカレンダ属性は、次のとおりです。

- `Server Version`

  この読み取り専用の属性は、カレンダを管理しているサーバのバージョン番号を示します。 この属性は、`CSA_VALUE_UINT32`型の属性です。

- `Data Version`

  この読み取り専用の属性は、カレンダのデータ・バージョンを示します。 この属性は、`CSA_VALUE_UINT32`型の属性です。

## 項目属性

PG.calmg.mkr.17に、CDEでサポートされる項目属性をリストします。 詳しくは、関連するマニュアル・ページを参照して下さい。 項目属性のリストは、拡張命名規則による拡張が可能です。

## CSA 項目属性

`属性名` | `説明` | `読み取り専用`
Audio Reminder | 音声通知属性 | ×
Classification | 分類属性 | ×
Date Completed | 完了日付属性 | ×
Date Created | 項目作成日付属性 | ○
Description | 説明属性 | ×
Due Date | 期限属性 | ×
End Date | 終了日付属性 | ×
Exception Dates | 例外日付属性E | ×
Flashing Reminder | 点滅通知属性 | ×
Last Update | 前回更新属性 | ○
Mail Reminder | メール通知属性 | ×
Number Recurrences | (計算された)反復属性の数 | ○
Organizer | 編成者属性 | ○
Popup Reminder | ポップアップ通知属性 | ×
Priority | 優先順位属性 | ×
Recurrence Rule | 反復規則属性 | ×
Reference Identifier | 参照識別子属性 | ○
Sponsor | スポンサー属性 | ×
Start Date | 開始日付属性 | ×
Status | ステータス属性 | ×
Subtype | サブタイプ属性 | ×
Summary | 要約属性 | ×
Transparency | 時間の透過性またはブロック化属性 | ×
Type | 型属性 | ○

次の節では、 PG.calmg.mkr.17にリストした項目属性について、追加の情報を提供します。

- `Organizer`

  項目の主催者は、`csa_add_entry()`を呼び出してカレンダに項目を追加するアプリケーションを実行しているユーザに設定されます。 読み取り専用であり、項目の追加後に変更することはできません。

- `Reference Identifier`

  項目の参照識別子は、カレンダ内の項目の固有な識別子と、カレンダの名前と位置を含んだ文字列です。 形式は`n:calendar@location`です。 `n`は、カレンダ内の項目を固有に識別する番号です。 `calendar`は、カレンダの名前です。 `location`は、カレンダが格納されているマシンの名前です。

- `Status`

  CDE では、次の追加のステータス値を定義します。

  `CSA_X_DT_STATUS_ACTIVE`

  `CSA_X_DT_STATUS_DELETE_PENDING`

  `CSA_X_DT_STATUS_ADD_PENDING`

  `CSA_X_DT_STATUS_COMMITTED`

  `CSA_X_DT_STATUS_CANCELLED`

- `Type`

  この値は読み取り専用であり、項目の追加後に変更することはできません。 CDE では、次の追加の型を定義します。

  `CSA_X_DT_TYPE_OTHER`

### CDEエントリ属性

CDE定義済み属性は、次のとおりです。

- `Show Time`

  この属性の値は、項目の開始時間と終了時間をユーザに対して表示するかどうかを示します。 `csa_update_entry_attributes()`により変更できます。 この属性は、`CSA_VALUE_SINT32`型の属性です。

- `Repeat Type`

  項目の反復の頻度、すなわち、どれくらいの間隔で項目を繰り返すかを示します。これは読み取り専用の属性であり、項目属性`Recurrence Rule`から得られます。

  この属性は、`CSA_VALUE_UINT32`型の属性です。

  次の値が定義されています。

  `CSA_X_DT_REPEAT_ONETIME`

  `CSA_X_DT_REPEAT_DAILY`

  `CSA_X_DT_REPEAT_WEEKLY`

  `CSA_X_DT_REPEAT_BIWEEKLY`

  `CSA_X_DT_REPEAT_MONTHLY_BY_WEEKDAY`

  `CSA_X_DT_REPEAT_MONTHLY_BY_DATE`

  `CSA_X_DT_REPEAT_YEARLY`

  `CSA_X_DT_REPEAT_EVERY_NDAY`

  `CSA_X_DT_REPEAT_EVERY_NWEEK`

  `CSA_X_DT_REPEAT_EVERY_NMONTH`

  `CSA_X_DT_REPEAT_MON_TO_FRI`

  `CSA_X_DT_REPEAT_MONWEDFRI`

  `CSA_X_DT_REPEAT_TUETHUR`

  `CSA_X_DT_REPEAT_WEEKDAYCOMBO`

  `CSA_X_DT_REPEAT_OTHER`

  `CSA_X_DT_REPEAT_OTHER_WEEKLY`

  `CSA_X_DT_REPEAT_OTHER_MONTHLY`

  `CSA_X_DT_REPEAT_OTHER_YEARLY`

- `Repeat Times`

  この属性は、項目を繰り返す回数を示します。 これは読み取り専用の属性であり、項目属性`Recurrence Rule`から得られます。 この属性は、`CSA_VALUE_UINT32`型の属性です。

- `Repeat Interval`

  この属性は、Repeat Typeの `CSA_X_DT_REPEAT_EVERY_NDAY、 CSA_X_DT_REPEAT_EVERY_NWEEK`、 または`CSA_X_DT_REPEAT_EVERY_NMONTH`の何倍で項目を繰り返すかを示します。 これは読み取り専用の属性であり、項目属性`Recurrence Rule`から得られます。 たとえば、この属性の値が３であり、Repeat Typeが`CSA_X_DT_REPEAT_EVERY_NWEEK`の場合には、項目は３週間ごとに繰り返されます。 この属性は、`CSA_VALUE_UINT32`型の属性です。

- `Repeat Occurrence Number`

  項目の、Repeat Typeが `CSA_X_DT_REPEAT_MONTHLY_BY_WEEKDAY`の場合、この属性は、項目を繰り返す週を示します。 これは読み取り専用の属性であり、 項目属性`Recurrence Rule`から得られます。 この属性は、`CSA_VALUE_SINT32`型の属性です。

- `Sequence End Date`

  この項目属性は、シーケンスの終了日付を示します。 これは読み取り専用の属性であり、 項目属性`Recurrence Rule`から得られます。 この属性は、`CSA_VALUE_DATE_TIME`型の属性です。

## 関数についての一般的な情報

次の一般的な情報は、すべての関数に適用されます。

- 文字セットの制限

  カレンダ属性`CSA_CAL_ATTR_CHARACTER_SET`は、カレンダのロケール情報を格納するために使用されます。

  ライブラリの中で渡されるテキストでの説明以外のデータはすべて、ASCII形式でなければなりませんが、ライブラリはシングルバイトだけでなくマルチバイト文字列もサポートします。

- 属性値の型チェックは、事前定義済み属性に対してだけ行われます。

- 関数がセッション・ハンドルと項目ハンドルの両方を取るときには、セッション・ハンドルは、CDEでは常に無視されます。

- 項目属性`CSA_ENTRY_ATTR_RECURRENCE_RULE`と `CSA_ENTRY_ATTR_EXCEPTION_DATES`は、カレンダ項目の反復情報を指定するために使用されます。 `CSA_ENTRY_ATTR_RECURRENCE_RULE`属性の情報は、次の属性を使用して問い合わせることができます。 `CSA_X_DT_ENTRY_ATTR_REPEAT_TYPE`、 `CSA_X_DT_ENTRY_ATTR_REPEAT_TIMES`、 `CSA_X_DT_ENTRY_ATTR_REPEAT_INTERVAL`、 `CSA_X_DT_ENTRY_ATTR_REPEAT_OCCURRENCE_NUM`、および `CSA_X_DT_ENTRY_ATTR_SEQUENCE_END_DATE`。 これらの計算された属性は、読み取り専用です。

- `CSA_calendar_user`データ構造体は、ユーザまたはカレンダを指定します。 前者の場合、たとえば、アクセス・リスト内のユーザを指定するときには、`user_name`フィールドだけが使われ、他のフィールドはすべて無視されます。 後者の場合、たとえば、ログインするカレンダを指定するときには、 `calendar_address`フィールドだけが使われ、他のフィールドはすべて無視されます。 形式は`calendar@location`です。 `calendar`はカレンダの名前であり、 `location`はカレンダが格納されているマシンの名前です。

- 値の型が`CSA_VALUE_ATTENDEE_LIST`の属性はサポートされず、それらが指定された場合には `CSA_E_INVALID_ATTRIBUTE_VALUE`が返されます。

- `CSA_reminder`データ構造体の中の `repeat_count`フィールドと `snooze_time`フィールドはカレンダに格納されますが、 カレンダ・サービスはそれらの値を解釈せず、関連する通知はサーバによって一度しか返されません。

- ユーザ・インタフェース拡張`CSA_X_UI_ID_EXT`はサポートされていません。

## 管理関数

この節では、CDEでサポートされる管理関数について説明します。 詳しくは、関連するマニュアル・ページを参照してください。

- 解放 - カレンダ・サービスによって割り当てられたメモリを解放します。

      CSA_return_code
      csa_free(
        CSA_buffer      memory
      );

- カレンダのリスト - カレンダ・サーバによってサポートされるカレンダをリストします。

      CSA_return_code
      csa_list_calendars(
        CSA_service_reference   calendar_service,
        CSA_uint32              *number_names,
        CSA_calendar_user       **calendar_names,
        CSA_extension           *list_calendars_extensions
      );

  サーバが実行しているホスト名を`calendar_server`で渡さなければなりません。

- ログイン - カレンダ・サービスにログインして、カレンダとのセッションを確立します。

      CSA_return_code
      csa_logon(
        CSA_service_reference  calendar_service,
        CSA_calendar_user      *user,
        CSA_string             password,
        CSA_string             character_set,
        CSA_string             required_csa_version,
        CSA_session_handle     *session,
        CSA_extension          *logon_extensions
      );

  引き数`calendar_service,password, character_set`、 および`required_csa_version`は使用されません。

  `user`によって指し示される `CSA_calendar_user`構造体の `calendar_address`フィールドは、ログインするカレンダを指定します。形式は`calendar@location`です。 `calendar`はカレンダの名前であり、 `location`はカレンダが格納されているホスト名です。

  CDE 定義済み拡張`CSA_X_DT_GET_USER_ACCESS_EXT`がサポートされます。 この拡張を使うと、呼び出しているユーザがカレンダに関して持っているアクセスの権利を取り出すことができます。 ユーザのアクセスの権利は、拡張構造体の `item_data`フィールドで返されます。

- ログアウト - カレンダとのセッションを終了します。

      CSA_return_code
      csa_logoff(
        CSA_session_handle     session,
        CSA-extension     *logoff_extensions
      );

- 構成の問い合わせ - インストールされたCSA構成に関する情報を判断します。

      CSA_return_code
      csa_query_configuration(
              CSA_session_handle      session,
              CSA_enum                item,
              CSA_buffer              *reference,
              CSA_extension           *query_configuration_extensions
      );

  CDEでは、以下の項目はサポートされません。

  `CSA_CONFIG_CHARACTER_SET`

  `CSA_CONFIG_LINE_TERM`

  `CSA_CONFIG_VER_IMPLEM`

## カレンダ管理関数

この節では、CDEでサポートされるカレンダ管理関数について説明します。 詳しくは、関連するマニュアル・ページを参照して下さい。

- カレンダの追加 - カレンダ・サービスにカレンダを追加します。

      CSA_return_code
      csa_add_calendar(
              CSA_session_handle      session,
              CSA_calendar_user       *user,
              CSA_uint32              number_attributes,
              CSA_attribute           *calendar_attributes,
              CSA_extension           *add_calendar_extensions
      );

  最初の引き数`session`は無視されます。

  `user`によって示される `CSA_calendar_user`構造体の `calendar_address`フィールドは、作成されるカレンダの名前と位置を指定します。形式は`calendar@location`です。 `calendar`はカレンダの名前であり、 `location`はカレンダが格納されるホスト名です。 たとえば、`my_calendar@my_host`のようになります。

- コールバックの呼び出し - 指定されたコールバック・リストに関連するコールバック関数を強制的に呼び出します。

      CSA_return_code
      csa_call_callbacks(
        CSA_session_handle      session,
        CSA_flags      reason,
        CSA_extension      *call_callbacks_extensions
      );

- カレンダの削除 - カレンダ・サービスからカレンダを削除します。

      CSA_return_code
      csa_delete_calendar(
        CSA_session_handle      session,
        csa_extension      *delete_calendar_extensions
      );

- カレンダ属性のリスト - カレンダに関連するカレンダ属性の名前をリストします。

      CSA_return_code
      csa_list_calendar_attributes(
        CSA_session_handle      session,
        CSA_uint32      *number_names,
        CSA_attribute_reference **calendar_attributes_names,
        CSA_extension      *list_calendar_attributes_extensions
      );

- カレンダ属性の読み取り - カレンダのカレンダ属性値を読み取り、それを返します。

      CSA_return_code
      csa_read_calendar_attributes(
        CSA_session_handle      session,
        CSA_uint32              number_names,
        CSA_attribute_reference *attribute_names,
        CSA_uint32              *number_attributes,
        CSA_attribute           **calendar_attributes,
        CSA_extension      *read_calendar_attributes_extensions
      );

- コールバック関数の登録 - カレンダの中で、指定された種類の更新が行われるときに実行されるコールバック関数を登録します。

      CSA_return_code
      csa_register_callback(
        CSA_session_handle     session,
        CSA_flags              reason,
        CSA_callback           callback,
        CSA_buffer             client_data,
        CSA_extension          *register_callback_extensions
      );

- コールバック関数の登録解除 - 指定されたコールバック関数の登録を解除します。

      CSA_return_code
      csa_unregister_callback(
        CSA_session_handle     session,
        CSA_flags              reason,
        CSA_callback           callback,
        CSA_buffer             client_data,
        CSA_extension          *unregister_callback_extensions
      );

- カレンダ属性の更新 - カレンダのカレンダ属性値を更新します。

      CSA_return_code
      csa_update_calendar_attributes(
        CSA_session_handle     session,
        CSA_uint32     number_attributes,
        CSA_attribute     *calendar_attributes,
        CSA_extension      *update_calendar_attributes_extensions
      );

## 項目管理関数

この節では、CDEでサポートされる項目管理関数について説明します。 詳しくは、関連するマニュアル・ページを参照して下さい。

- 項目の追加 - 指定されたカレンダに項目を追加します。

      CSA_return_code
      csa_add_entry(
        CSA_session_handle      session,
        CSA_uint32      number_attributes,
        CSA_attribute      *entry_attributes,
        CSA_entry_handle      *entry,
        CSA_extension      *add_entry_extensions
      );

- 項目の削除 - 指定されたカレンダから項目を削除します。

      CSA_return_code
      csa_delete_entry(
              CSA_session_handle      session,
              CSA_entry_handle        entry,
              CSA_enum                delete_scope,
              CSA_extension           *delete_entry_extensions
      );

- 項目のリスト - 属性検索基準のすべてに一致するカレンダ項目をリストします。

      CSA_return_code
      csa_list_entries(
              CSA_session_handle      session,
              CSA_uint32              number_attributes,
              CSA_attribute           *entry_attributes,
              CSA_enum                *list_operators,
              CSA_uint32              *number_entries,
              CSA_entry_handle        **entries,
              CSA_extension           *list_entries_extensions
      );

  `list_operators`で指定される演算子について、さらに詳しく説明します。

  属性値の型`CSA_VALUE_REMINDER`、 `CSA_VALUE_CALENDAR_USER`、および `CSA_VALUE_DATE_TIME_RANGE`については、 演算子`CSA_MATCH_ANY`と `CSA_MATCH_EQUAL_TO`だけがサポートされます。

  属性値の型`CSA_VALUE_STRING`については、 演算子`CSA_MATCH_ANY`、 `CSA_MATCH_EQUAL_TO`、 `CSA_MATCH_NOT_EQUAL_TO`、および `CSA_MATCH_CONTAIN`だけがサポートされます。 `CSA_MATCH_CONTAIN`は、 `CSA_VALUE_STRING`型の属性にだけ適用されます。

  値の型が`CSA_VALUE_OPAQUE_DATA`、 `CSA_VALUE_ACCESS_LIST,CSA_VALUE_ATTENDEE_LIST`、および `CSA_VALUE_DATE_TIME_LIST`の属性の照合はサポートされません。 唯一の例外は、属性`CSA_ENTRY_ATTR_REFERENCE_IDENTIFIER`です。演算子`CSA_MATCH_EQUAL_TO`は、この属性に対してサポートされます。

- 項目属性のリスト - 指定された項目に関連する項目属性の名前をリストします。

      CSA_return_code
      csa_list_entry_attributes(
        CSA_session_handle       session,
            CSA_entry_handle       entry,
        CSA_uint32       *number_names,
        CSA_attribute_reference       **entry_attribute_names,
        CSA_extension       *list_entry_attributes_extensions
      );

- 項目シーケンスのリスト - カレンダ項目に関連する再帰的カレンダ項目をリストします。

      CSA_return_code
      csa_list_entry_sequence(
        CSA_session_handle      session,
        CSA_entry_handle      entry,
        CSA_date_time_range      time_range,
        CSA_uint32      *number_entries,
        CSA_entry_handle      **entry_list,
        CSA_extension      *list_entry_sequences_extensions
      );

  指定された項目が一回限りの場合には、 `CSA_E_INVALID_PARAMETER`が返されます。

- 項目属性の読み取り - 指定された項目のカレンダ項目属性値を読み取り、それを返します。

      CSA_return_code
      csa_read_entry_attributes(
             CSA_session_handle        session,
             CSA_entry_handle        entry,
             CSA_uint32        number_names,
             CSA_attribute_reference *attribute_names,
             CSA_uint32        *number_attributes,
             CSA_attribute        **entry_attributes,
             CSA_extension        *read_entry_attributes_extensions
      );

- 次の通知の読み取り - 特定の時間を基準として、指定されたカレンダの中の特定の種類の次の通知を読み取ります。

      CSA_return_code
      csa_read_next_reminder(
        CSA_session_handle      session,
        CSA_uint32      number_names,
        CSA_attribute_reference *reminder_names,
        CSA_date_time      given_time,
        CSA_uint32      *number_reminders,
        CSA_remainder_reference **reminder_references,
        CSA_extension      *read_next_reminder_extensions
      );

- 項目属性の更新 - カレンダ項目属性を更新します。

      CSA_return_code
      csa_update_entry_attributes(
              CSA_session_handle        session,
              CSA_entry_handle        entry,
              CSA_enum        update_scope,
              CSA_boolean        update_propagation,
              CSA_uint32        number_attributes,
              CSA_attribute        *entry_attributes,
              CSA_entry_handle        *new_entry,
              CSA_extension        *update_entry_attributes_extensions
      );

  更新の伝達はサポートされません。 `update_propagation`引き数は `CSA_FALSE`に設定して下さい。