第 7 章「共通デスクトップ環境の Motif ウィジェット」から第 10 章「カレンダとの統合」では、次のオプションの統合方法の作業を実行する方法について説明します。
ワークスペース・マネージャと統合し、アプリケーションがセッションの開始時に各セッションのワークスペースの位置を判断できるようにする
CDE カスタム・ウィジェットを使用する
アプリケーションの内部からアクションを呼び出す
データ型データベースにアクセスする
カレンダの API にアクセスする
ワークスペース・マネージャは、デスクトップの複数のワークスペース環境の中でアプリケーションがウィンドウを管理するための手段を提供します。アプリケーションは、ワークスペース・マネージャと通信することによって、主に次の 4 つのタスクを実行できます。
アプリケーションのウィンドウを 1 つ以上のワークスペースに置く
アプリケーションのウィンドウが位置するワークスペースを識別する
アプリケーションのウィンドウが別のワークスペースに移動するのを防止する
ユーザが別のワークスペースに切り替えるなど、ワークスペースに対する変更を監視する
通常、セッション・マネージャはプログラマに干渉されることなく、アプリケーションのメイン・ウィンドウを正しいワークスペースに取り出します。ただし、アプリケーションが複数のトップレベル・ウィンドウを持つ場合には、ワークスペース・マネージャの API を使用してウィンドウの位置を特定し、このデータをセッション状態の一部として保存しなければなりません。
セッション間のアプリケーション関連情報の保存の詳細は、第 4 章「セッション・マネージャとの統合」を参照してください。
アプリケーションは、デスクトップが提供する関数を使用して、ワークスペース・マネージャと通信します。これらの関数を使用すると、ワークスペースの管理に関連するさまざまなタスクをすばやく簡単に実行できます。次に、これらの関数のリストを示します。
DtWsmAddCurrentWorkspaceCallback()
DtWsmAddWorkspaceFunctions ()
DtWsmAddWorkspaceModifiedCallback ()
DtWsmFreeWorkspaceInfo ()
DtWsmGetCurrentBackdropWindows ()
DtWsmGetCurrentWorkspace ()
DtWsmGetWorkspaceInfo ()
DtWsmGetWorkspaceList ()
DtWsmGetWorkspacesOccupied ()
DtWsmOccupyAllWorkspaces ()
DtWsmRemoveWorkspaceCallback ()
DtWsmRemoveWorkspaceFunctions ()
DtWsmSetCurrentWorkspace ()
DtWsmSetWorkspacesOccupied()
2 つのデモ・プログラム (occupy.c と wsinfo.c) の中に、これらの関数の使用方法を示すコードの一部分があります。occupy.c、wsinfo.c、およびいくつかのブランドのワークステーションの makefile をリストしたものがディレクトリ /usr/dt/examples/dtwsm にあります。各関数の詳細は、該当するマニュアル・ページを参照してください。
アプリケーションは、ウィンドウを任意のまたは全部の既存のワークスペースに置くことができます。DtWsmOccupyAllWorkspaces() は、現在定義されているすべてのワークスペースにウィンドウを置きます。一方、DtWsmSetWorkspacesOccupied() は、この関数に渡されたリストの中で指定されている、すべてのワークスペースにウィンドウを置きます。
DtWsmOccupyAllWorkspaces() を使用します。
occupy.c では、[すべてのワークスペースに配置] プッシュ・ボタンのコールバック allWsCB() がこの関数を呼び出します。
DtWsmOccupyAllWorkspaces (XtDisplay(toplevel), XtWindow(toplevel));
XtDisplay(toplevel) は、X ディスプレイです。
XtWindow(toplevel) は、すべてのワークスペースに置かれるウィンドウです。
この関数の詳細は、DtWsmOccupyAllWorkspaces() のマニュアル・ページを参照してください。
DtWsmSetWorkspacesOccupied() を使用します。
occupy.c では、[配置するワークスペース] プッシュ・ボタンのコールバック setCB() がこの関数を呼び出します。
DtWsmSetWorkSpacesOccupied XtDisplay(toplevel), XtWindow(toplevel), paWsSet, numSet);
XtDisplay(toplevel) は、X ディスプレイです。
XtWindow(toplevel) は、ワークスペースに置かれるウィンドウです。
paWsSet は、X のアトムに変換されたワークスペース名のリストを指すポインタです。
numSet は、リスト内のワークスペースの番号です。
この関数の詳細は、DtWsmSetWorkspacesOccupied() のマニュアル・ページを参照してください。
関数 DtWsmGetWorkspacesOccupied() は、指定されたアプリケーション・ウィンドウがあるワークスペースのリストを返します。occupy.c では、プロシージャ ShowWorkspaceOccupancy() がこの関数を呼び出します。この呼び出しの結果に基づいて、ShowWorkspaceOccupancy() はワークスペースを表すトグル・ボタンの外観を変更します。アプリケーション・ウィンドウがあるワークスペースの各トグル・ボタンには、チェック・マークが表示されます。
DtWsmGetWorkspacesOccupied() を使用します。
rval = DtWsmGetWorkspacesOccupied(XtDisplay(toplevel) XtWindow(toplevel), &paWsIn, &numWsIn);
XtDisplay(toplevel) は、X ディスプレイです。
XtWindow(toplevel) は、ワークスペースで検索されるウィンドウです。
paWsIn は、X のアトムに変換されたワークスペース名のリストを指すポインタのアドレスです。
numWsIn は、リスト内のワークスペースの番号を表す整数のアドレスです。
この呼び出しの後、ループが設定され、ワークスペースのリスト (DtWsmGetWorkspaceList() によってプロシージャ SetUpWorkspaceButtons() で検索されます) と、アプリケーション・ウィンドウがあることがわかったワークスペースのリストとを比較します。各トグル・ボタンがアプリケーション・ウィンドウがあるワークスペースを表す場合は、トグル・ボタン・リソース XmNset に True が設定されます。
関数 DtWsmRemoveWorkspaceFunctions() は、アプリケーションが次の作業を実行しないようにします。
他のワークスペースへの切り替え
すべてのワークスペースの占有
現在のワークスペースからの削除
DtWsmRemoveWorkspaceFunctions() が上記の作業を実行する場合は、デスクトップ・ワークスペース・マネージャ (dtwm) のウィンドウ・メニューの一部分をアクティブにしないようにします。dtwm はアプリケーションのトップレベル・ウィンドウを管理するときにワークスペース情報をチェックするだけなので、アプリケーションはトップレベル・ウィンドウがマップされる前に DtWsmRemoveWorkspaceFunctions() を呼び出さなければなりません。アプリケーションのトップレベル・ウィンドウが管理された後で DtWsmRemoveWorkspaceFunctions() を呼び出す必要がある場合には、最初に Xlib 関数 XWithdrawWindow() を呼び出してから DtWsmRemoveWorkspaceFunctions() を呼び出し、次に XMapWindow() を呼び出して、トップレベル・ウィンドウを再マップしなければなりません。
DtWsmRemoveWorkspaceFunctions() を使用します。
DtWsmRemoveWorkspaceFunctions(XtDisplay(toplevel), XtWindow(toplevel));
XtDisplay(toplevel) は、X ディスプレイです。
XtWindow(toplevel) は、ワークスペースの移動を防止するウィンドウです。
次の関数の 1 つまたは両方を使用して、ワークスペースの変更を監視できます。
DtWsmAddCurrentWorkspaceCallback() は、ワークスペース・マネージャが新しいワークスペースに切り替えられるときに、必ず呼び出されるアプリケーション・コールバックを登録します。詳細は、DtWsmAddCurrentWorkspaceCallback(3) のマニュアル・ページを参照してください。
DtWsmWorkspaceModifiedCallback() は、ワークスペースが追加、削除、または変更されるときに必ず呼び出されるアプリケーション・コールバックを登録します。詳細は、DtWsmWorkspaceModifiedCallback(3) のマニュアル・ページを参照してください。
DtWsmAddCurrentWorkspaceCallback() を使用します。
デモ・プログラム wsinfo.c では、この関数は、トップレベル・ウィジェットが実体化された後で呼び出されます。
DtWsmAddCurrentWorkspaceCallback (toplevel, wschangecb, NULL);
toplevel は、アプリケーションのトップレベル・ウィジェットです。
wschangecb() は、呼び出される関数名です。
NULL は、コールバックに渡されるクライアント・データのパラメータです。この場合、データは渡されません。
DtWsmWorkspaceModifiedCallback() を使用します。
DtWsmWorkspaceModifiedCallback toplevel, wschangecb, NULL);
toplevel は、アプリケーションのトップレベル・ウィジェットです。
wschangecb() は、呼び出される関数名です。
NULL は、コールバックに渡されるクライアント・データのパラメータです。この場合、データは渡されません。
共通デスクトップ環境 (CDE) は、Motif 2.1 ライブラリ (バグ修正付き) および拡張機能を提供します。さらに、CDE は、OPEN LOOK と Microsoft Windows の特定の機能を提供するために使用できる 4 つのカスタム・ウィジェットを提供します。この章では、これらの Motif カスタム・ウィジェットについて説明します。
ウィジェット・ライブラリ (libDtWidget) には、既存の Motif 2.1 ウィジェットの機能を組み合わせたり、拡張したりする 4 つのウィジェットがあります。
DtMenuButton は、メニュー・バーの外側にメニュー階層機能を提供します。
DtEditor は、カット & ペーストなどの単純なテキスト・エディタ関数を組み込みます。
DtSpinBox は、テキスト・フィールドと矢印ボタンを組み合わせたコントロールを作成して、数値またはテキスト値を増減できます。このウィジェットは Motif ウィジェットの XmSpinBox を引き継いでいます。
DtComboBox は、テキスト・フィールドとリスト・ボックスを組み合わせたコントロールを作成して、テキスト・フィールドに対する多数の有効な選択項目の 1 つを表示します。このウィジェットは Motif ウィジェットの XmComboBox を引き継いでいます。
これらのウィジェットは、すべての CDE アプリケーションに共通の機能を提供します。これらのウィジェットは、サブクラス化はサポートしていません。
カスタム・ウィジェット・ライブラリは、次のライブラリに直接依存します。
Motif スーパークラスのサポートについては Xm ライブラリ
ウィジェットの作成と操作については Xt ライブラリ
ベース X Window System については X11 ライブラリ
DtEditor が利用するデスクトップ・サポートについては DtSvc
DtMenuButton ウィジェットは、メニュー区画の外側にメニュー階層機能を提供するために使用します。
DtMenuButton ウィジェットは、XmCascadeButton ウィジェットのメニュー階層機能を補足するコマンド・ウィジェットです。XmCascadeButton ウィジェットを補うものとして、メニュー・バー、プルダウン、またはポップアップの外側で示すことができます (MenuPane の内部では XmCascadeButton ウィジェットを使用します)。図 7-1 に、DtMenuButton ウィジェットの使用例を示します。
DtMenuButton ウィジェットは、libDtWidget ライブラリにあります。ヘッダ・ファイルは、Dt/MenuButton.h です。
DtMenuButton ウィジェットの使用例が入っているデモが、/usr/dt/examples/dtwidget/controls.c にあります。
DtCreateMenuButton() は、CDE ウィジェットを作成する簡易関数です。
DtMenuButton ウィジェットは、XmLabel クラスのサブクラスです。視覚的には、DtMenuButton ウィジェットは、ラベル文字列とメニュー・グリフ (絵文字) を持ちます。メニュー・グリフは、常にウィジェットの右端に表示され、デフォルトでは下向き矢印です。
DtMenuButton ウィジェットには、暗黙的に作成されたサブメニューが接続されています。サブメニューは、この DtMenuButton ウィジェットを親とするポップアップ・メニューです。暗黙的に作成されたサブメニュー名は、この DtMenuButton ウィジェットの名前の前に submenu_ を付けたものです。サブメニューのウィジェット ID は、この DtMenuButton ウィジェットの DtNsubMenuId リソースに XtGetValues を設定することにより取得できます。暗黙的に作成されたサブメニューは、このウィジェットの利用者によって破壊されることはありません。
サブメニューは、DtMenuButton ウィジェットのどこかで [メニュー・ポスト] ボタン(XmRowColumn の XmNmenuPost リソースを参照) を押すことによって、または Motif の取り消しキー (通常は [Escape] キー) を押すことによってポップアップできます。
DtMenuButtonWidget は、Core、XmPrimitive、および XmLabel クラスから動作とリソースを継承します。
クラス・ポインタは、dtMenuButtonWidgetClass です。
クラス名は、DtMenuButtonWidget です。
DtMenuButtonWidget は、サブクラス化をサポートしません。
DtMenuButtonWidget は、次のリソースを提供します。これらのリソースのクラス、型、デフォルト、およびアクセスを表 7-1 に示します。
DtNcascadingCallback は、接続されたサブメニューが表示される前に呼び出されるコールバックのリストを指定します。
DtNcascadePixmap は、メニュー・グリフとして表示されるピックスマップを指定します。ピックスマップが指定されない場合は、下向き矢印が表示されます。
DtNsubMenuId は、この DtMenuButton ウィジェットと関連付けられるポップアップ・メニュー区画のウィジェット ID を指定します。この DtMenuButton を親としてポップアップ・メニュー区画を作成しなければなりません。リソースの設定時に、このウィジェットによってサブメニューが自動的に破壊されるので、ウィジェットの作成時にこのリソースを指定できません。
詳細は、DtMenuButtonwidget(3X) のマニュアル・ページを参照してください。
アクセス欄のコードは、次の作業が可能かどうかを示します。
作成時にリソースを設定する (C)
XtSetValues を使用して設定する (S)
XtGetValues を使用して検索する(G)
名前 |
クラス |
型 |
デフォルト |
アクセス |
---|---|---|---|---|
DtNcascadingCallback |
DtCCallback |
XtCallbackList |
NULL |
C |
DtNcascadePixmap |
DtCPixmap |
Pixmap |
XmUNSPECIFIED_PIXMAP |
CSG |
DtNsubMenuId |
DtCMenuWidget |
Widget |
NULL |
SG |
コールバックのための構造体を次に示し、表 7-2 で説明します。
typedef struct { int reason; XEvent *event; } XmAnyCallbackStruct;表 7-2 DtMenuButtonWidget コールバックのための構造体
構造体 |
説明 |
---|---|
reason |
コールバックが呼び出された reason を返します。 |
event |
コールバックをトリガした XEvent へのポインタ。コールバックが XEvent によってトリガされなかった場合には NULL になります。 |
次の例は、DtMenuButton ウィジェットの作成方法と使用方法を示しています。このコードは、/usr/dt/examples/dtwidget ディレクトリの controls.c デモの一部です。
/* * Example code for DtMenuButton */ #include Dt/DtMenuButton.h /* MenuButton custom glyph */ #define menu_glyph_width 16 #define menu_glyph_height 16 static unsigned char menu_glyph_bits[] = { 0xe0, 0x03, 0x98, 0x0f, 0x84, 0x1f, 0x82, 0x3f, 0x82, 0x3f, 0x81, 0x7f, 0x81, 0x7f, 0xff, 0x7f, 0xff, 0x40, 0xff, 0x40, 0xfe, 0x20, 0xfe, 0x20, 0xfc, 0x10, 0xf8, 0x0c, 0xe0, 0x03, 0x00, 0x00}; static void CreateMenuButtons(Widget parent) { Widget menuButton, submenu, titleLabel, button; Pixmap cascadePixmap; Pixel fg, bg; Cardinal depth; XmString labelString; Arg args[20]; int i, n; /* Create title label */ labelString = XmStringCreateLocalized("MenuButton Widget"); n = 0; XtSetArg(args[n], XmNlabelString, labelString); n++; titleLabel = XmCreateLabel(parent, "title", args, n); XtManageChild(titleLabel); XmStringFree(labelString); /* * Create a MenuButton. * Add push buttons to the built-in popup menu. */ labelString = XmStringCreateLocalized("Action"); n = 0; XtSetArg(args[n], XmNlabelString, labelString); n++; menuButton = DtCreateMenuButton(parent, "menuButton1", args, n); XtManageChild(menuButton); XmStringFree(labelString); XtVaGetValues(menuButton, DtNsubMenuId, &submenu, NULL); button = XmCreatePushButton(submenu, "Push", NULL, 0); XtManageChild(button); button = XmCreatePushButton(submenu, "Pull", NULL, 0); XtManageChild(button); button = XmCreatePushButton(submenu, "Turn", NULL, 0); XtManageChild(button); /* * Create a MenuButton. * Replace the built-in popup menu with a tear-off menu. * Add a custom pixmap in the colors of the MenuButton. */ labelString = XmStringCreateLocalized("Movement"); n = 0; XtSetArg(args[n], XmNlabelString, labelString); n++; menuButton = DtCreateMenuButton(parent, "menuButton1", args, n); XtManageChild(menuButton); XmStringFree(labelString); /* Create a tear-off menu */ n = 0; XtSetArg(args[0], XmNtearOffModel, XmTEAR_OFF_ENABLED); n++; submenu = XmCreatePopupMenu(menuButton, "submenu", args, n); button = XmCreatePushButton(submenu, "Run", NULL, 0); XtManageChild(button); button = XmCreatePushButton(submenu, "Jump", NULL, 0); XtManageChild(button); button = XmCreatePushButton(submenu, "Stop", NULL, 0); XtManageChild(button); XtVaSetValues(menuButton, DtNsubMenuId, submenu, NULL); /* Create a pixmap using the menu button's colors and depth */ XtVaGetValues(menuButton, XmNforeground, &fg, XmNbackground, &bg, XmNdepth, &depth, NULL); cascadePixmap = XCreatePixmapFromBitmapData(XtDisplay (menuButton),DefaultRootWindow(XtDisplay (menuButton)), (char*)menu_glyph_bits, menu_glyph_width, menu_glyph_height, fg, bg, depth); XtVaSetValues(menuButton, DtNcascadePixmap, cascadePixmap, NULL); }
共通デスクトップ環境のテキスト編集システムは、次の 2 つのコンポーネントから成ります。
グラフィカル・インタフェース、アクション・インタフェース、および ToolTalk インタフェースを介して編集サービスを提供するテキスト・エディタ・クライアントの dtpad
次の編集サービスのためのプログラム・インタフェースを提供するエディタ・ウィジェットの DtEditor(3)
カット & ペースト
検索と置換
単純な書式化
スペルチェック (8 ビット・ロケール用)
以前の編集を元に戻す
ASCII テキスト、マルチバイト・テキスト、およびバッファ・データの入出力をサポートする拡張入出力処理機能
ファイルの直接読み書きのサポート
OSF/Motif テキスト・ウィジェットはプログラム・インタフェースも提供しますが、システム全体で一貫したエディタを使用するアプリケーションは、DtEditor(3) ウィジェットを使用しなければなりません。CDE のテキスト・エディタとメール・プログラムは、エディタ・ウィジェットを使用します。このウィジェットは、次のような状況のときに使用してください。
[スペルチェック]、[元に戻す]、および [検索/変更] など、DtEditor(3) ウィジェットが提供する機能を使いたい場合
ユーザがファイルからデータを読み込んだり、ファイルにデータを書き込んだりするコードを作成したくない場合
ユーザが入力した文字またはユーザが行なったカーソル移動を調べる必要がないプログラムを作成する場合
この節では、テキスト・エディタ・ウィジェット DtEditor(3) について説明します。
エディタ・ウィジェット・ライブラリは、テキスト・ファイルの作成と編集のためのサポートを提供します。デスクトップ環境で実行するアプリケーションで、一貫した方法でテキスト・データを編集できるようにします。DtEditor(3) ウィジェットは、テキスト用のスクロールする編集ウィンドウ、オプションのステータス行と、テキストの検索と置換、スペルチェック、および書式オプションの指定を行うためのダイアログから成ります。テキスト・エディタ・ウィジェットには、ウィジェットをプログラム的に制御するための簡易関数のセットが含まれています。
DtEditor ウィジェットは、libDtWidget ライブラリにあります。ヘッダ・ファイルは、Dt/Editor.h です。
DtEditor ウィジェットの使用例が入っているデモが、/usr/dt/examples/dtwidget/editor.c にあります。
DtEditor ウィジェット・クラスについては、ウィジェットのサブクラス化はサポートされません。
DtEditor は、Core、Composite、Constraints、XmManager、および XmForm クラスから動作とリソースを継承します。
エディタ・ウィジェットのクラス名は、DtEditorWidget です。
クラス・ポインタは、dtEditorWidgetClass です。
DtEditor 簡易関数を、次の表に示します。
DtEditor ライフ・サイクル関数を表 7-3 に示します。
表 7-3 DtEditor ライフ・サイクル関数
関数 |
説明 |
---|---|
DtCreateEditor |
DtEditor ウィジェットの新規インスタンスとその子を作成します。 |
DtEditorReset |
DtEditor ウィジェットを初期状態に復元します。 |
DtEditor 入出力関数を表 7-4 に示します。
表 7-4 DtEditor 入出力関数
関数 |
説明 |
---|---|
DtEditorAppend |
エディタ・ウィジェットの最後に内容データを追加します。 |
DtEditorAppendFromFile |
エディタ・ウィジェットの最後にファイルの内容を追加します。 |
DtEditorGetContents |
エディタ・ウィジェットの内容全体を検索します。 |
DtEditorInsert |
内容データを現在の挿入位置に挿入します。 |
DtEditorInsertFromFile |
ファイルの内容を現在の挿入位置に挿入します。 |
DtEditorReplace |
テキストの一部を与えられたデータと置き換えます。 |
DtEditorReplaceFromFile |
テキストの一部をファイルの内容と置き換えます。 |
DtEditorSaveContentsToFile |
現在選択されている内容を空白に置き換えます。 |
DtEditorSetContents |
内容データをエディタ・ウィジェットに読み込んで、ウィジェットの内容全体を置き換えます。 |
DtEditorSetContentsFromFile |
ファイルの内容をエディタ・ウィジェットに読み込んで、ウィジェットの内容全体を置き換えます。 |
DtEditor 選択関数を表 7-5 に示します。
表 7-5 DtEditor 選択関数
関数 |
説明 |
---|---|
DtEditorClearSelection |
現在選択されている内容を空白に置き換えます。 |
DtEditorCopyToClipboard |
現在選択されている内容をクリップボードにコピーします。 |
DtEditorCutToClipboard |
現在選択されている内容を削除して、クリップボードに入れます。 |
DtEditorDeleteSelection |
現在選択されている内容を削除します。 |
DtEditorDeselect |
選択されている内容を選択解除します。 |
DtEditorPasteFromClipboard |
クリップボードの内容をエディタ・ウィジェットにペーストして、現在選択されている内容を置き換えます。 |
DtEditorSelectAll |
エディタ・ウィジェットの内容全体を選択します。 |
DtEditor 書式化関数を表 7-6 に示します。
表 7-6 DtEditor 書式化関数
関数 |
説明 |
---|---|
DtEditorFormat |
エディタ・ウィジェットの内容の全部または一部を書式化します。 |
DtEditorInvokeFormatDialog |
[書式] ダイアログ・ボックスを表示して、マージンと位置揃えのスタイルに関する書式設定を指定し、書式操作を実行できます。 |
DtEditor検索/変更関数を表 7-7 に示します。
表 7-7 DtEditArea 検索/変更関数
関数 |
説明 |
---|---|
DtEditorChange |
文字列の 1 つまたはすべての存在箇所を置換します。 |
DtEditorFind |
文字列の次の出現箇所を検索します。 |
DtEditorInvokeFindChangeDialog |
文字列を検索 (オプションで置換も) するためのダイアログ・ボックスを表示します。 |
DtEditorInvokeSpellDialog |
現在の内容の中でスペルが間違っている単語のリストがあるダイアログ・ボックスを表示します。 |
DtEditor 補助関数を表 7-8 に示します。
表 7-8 DtEditor 補助関数
関数 |
説明 |
---|---|
DtEditorCheckForUnsavedChanges |
エディタ・ウィジェットの内容が前回の検索または保存以後に変更されているかどうかを報告します。 |
DtEditorDisableRedisplay |
ビジュアル属性が変更された場合でも、エディタ・ウィジェットの再表示をしません。 |
DtEditorEnableRedisplay |
エディタ・ウィジェットの表示の更新を強制します。 |
DtEditorGetInsertPosition |
エディタ・ウィジェットの挿入カーソル位置を返します。 |
DtEditorGetLastPosition |
編集ウィンドウの最後の文字の位置を返します。 |
DtEditorGetMessageTextFieldID |
アプリケーション・メッセージを表示するために使用されるテキスト・フィールド・ウィジェットのウィジェット ID を検索します。 |
DtEditorGetSizeHints |
エディタ・ウィジェットからサイズ情報を検索します。 |
DtEditorGoToLine |
挿入カーソルを指定された行へ移動します。 |
DtEditorSetInsertionPosition |
挿入カーソルの位置を設定します。 |
DtEditorTraverseToEditor |
エディタ・ウィジェットの編集ウィンドウへのキーボード移動を設定します。 |
DtEditorUndoEdit |
ユーザが行なった最後の編集を元に戻します。 |
DtEditor ウィジェットは、次のリソースのセットを提供します。
DtNautoShowCursorPosition に True が設定された場合は、スクロール編集ウィンドウに表示されるテキストに挿入カーソルが必ずあるようにします。挿入カーソルが変わると、エディタの内容をスクロールして、挿入ポイントがウィンドウに入るようにします。
DtNblinkRate は、テキスト・カーソルの点滅間隔をミリ秒単位で指定します。挿入カーソルの点滅に要する時間は、点滅間隔の 2 倍です。点滅間隔が 0 に設定された場合は、カーソルは点滅しません。値を負にすることはできません。
DtNbuttonFontList は、DtEditor のダイアログ・ボックスに表示されるボタンのフォント・リストを指定します。
DtNcolumns は、エディタの初期の幅を整数の文字単位で指定します。値は 0 より大きくなければなりません。
DtNcursorPosition は、エディタの中で現在の挿入カーソルが置かれる位置を指定します。位置は、テキストの先頭からの文字数によって決められます。最初の文字位置は 0 です。
DtNcursorPositionVisible は、論理値が True のときに点滅しているテキスト・カーソルで、挿入カーソルの位置をマークします。
DtNdialogTitle は、DtEditor によって表示されるすべてのダイアログのタイトルを指定します。これには、単語の検索と置換、スペルが間違っている単語、および書式設定のためのダイアログが含まれます。
DtNeditable に True が設定されている場合は、ユーザはデータを編集できます。False が設定されている場合は、ユーザはデータを編集できません。
DtNlabelFontList は、DtEditor ラベルとして使用されるフォント・リストを指定します (ラベルは、ステータス行と DtEditor ダイアログ・ボックスに表示されます)。
DtNoverstrike に False が設定されている場合、エディタ・ウィジェットに入力された文字は、カーソルの位置に挿入されます (デフォルト)。True が設定されている場合、エディタ・ウィジェットに入力された文字は、挿入カーソルの直後の文字を置き換えます。行末に達した場合は、文字は行末に追加されます。ステータス行が表示されている場合、DtNoverstrike が True のときは DtNoverstrikeIndicatorLabel が必ずステータス行に表示されます。
DtNrows は、エディタの初期の高さを文字単位で指定します。値は 0 より大きくなければなりません。
DtNscrollHorizontal は論理値が True の場合、テキストを水平方向にスクロールできるスクロール・バーを追加します。
DtNscrollLeftSide は論理値が True の場合は、スクロール編集ウィンドウの左側に垂直スクロール・バーを置きます。
DtNshowStatusLine は、True が設定された場合、テキスト・ウィンドウの下にステータス行を表示します。ステータス行のフィールドには、挿入カーソルの現在の行番号、ドキュメント内の総行数、およびエディタが上書きモードかどうかを表示します。ユーザは、行番号表示に行番号を入力することによって、直接その行を表示できます。
ステータス行は、アプリケーションによって提供されるメッセージを表示するための Motif の XmTextField(3x) ウィジェットも含んでいます。このフィールドは、アプリケーションが編集中のドキュメントについてのステータスとフィードバックを表示するのに便利です。テキスト・フィールドの ID は、DtEditorGetMessageTextFieldID(3) を使用して検索されます。メッセージは、このウィジェットの XmNvalue または XmNvalueWcs リソースを設定することによって表示されます。テキスト・フィールドが必要ない場合には、その ID で XtUnmanageWidget(3X) を呼び出すことによって管理からはずことができます。
DtNspellFilter は、スペルチェックに使用するフィルタを指定します。関数 DtEditorInvokeSpellDialog(3) は、DtNspellFilter によって指定されたフィルタを使用してエディタの内容をチェックします。指定されたフィルタは、ファイル名を受け入れて、このファイルの中のスペルが間違っている単語と認識不能の単語のリストを標準出力に出力しなければなりません。デフォルトのフィルタは、spell(1) です。
DtNtextBackground は、編集ウィンドウのバックグラウンドを指定します。
DtNtextDeselectCallback は、編集領域内でテキストが選択されていない場合に呼び出される関数を指定します。コールバックによって送られる reason は、DtEDITOR_TEXT_DESELECT です。
DtNtextFontList は、DtEditor 編集ウィンドウとテキスト・フィールドに使用されるフォント・リストを指定します。テキスト・フィールドは、ステータス行と DtEditor ダイアログ・ボックスに表示されます。
DtNtextForeground は、編集ウィンドウのフォアグラウンドを指定します。
DtNtextSelectcallback は、編集領域内でテキストが選択された場合に呼び出される関数を指定します。コールバックによって送られる reason は、DtEDITOR_TEXT_SELECT です。
DtNtextTranslations は、編集ウィンドウに追加される変換を指定します。このリソースで指定された変換は、編集ウィンドウに対して定義された重複する変換を無効にします。DtEditor によって提供される変換のリストについては、DtEditor(3) のマニュアル・ページを参照してください。
DtNtopCharacter は、スクロールした編集ウィンドウの最上部にテキストの位置がある行を表示します。行はテキストを左右に移動することなくウィジェットの最上部に表示されます。位置は、テキストの先頭からの文字数によって決められます。最初の文字位置は 0 です。
DtNtopCharacter に対する XGetValues(3X) は、ウィジェットの最上部に表示される行の最初の文字の位置を返します。
DtNwordWrap は、ウィンドウの右端に達した場合に、語の切れ目でソフト・キャリッジ・リターンによる行分割を行います。行折返しは、エディタ・ウィジェットの内容の視覚的外観だけに影響を及ぼすので注意してください。行分割 (ソフト・キャリッジ・リターン) は、テキストに物理的に挿入されるわけではありません。エディタは、ウィジェットの内容が検索される場合またはファイルに保存される場合に、ハード・キャリッジ・リターンへの置換をサポートします。詳細は、DtEditorGetContents(3) および DtEditorSaveContentsToFile(3) のマニュアル・ページを参照してください。
各リソースのクラス、型、デフォルト、およびアクセスを表 7-9 にリストします。継承クラスのリソース値を設定することによって、このウィジェットの属性を設定することもできます。.Xdefaults ファイルの中で名前またはクラスによってリソースを参照するには、DtN または DtC の接頭辞を除いて、残りの文字を使用します。.Xdefaults ファイルでリソースに対して定義済みの値の 1 つを指定するには、Dt 接頭辞を除いて、残りの文字を使用します (小文字または大文字で、単語の間に下線を入れます)。
アクセス欄のコードは、次の作業が可能かどうかを示します。
作成時にリソースを設定する (C)
XtSetvalues を使用して設定する (S)
XtGetValues を使用して検索する (G)
詳細は、DtEditor(3) のマニュアル・ページを参照してください。
表 7-9 DtEditor リソース
名前 |
クラス |
型 |
デフォルト |
アクセス |
---|---|---|---|---|
DtNautoShowCursorPosition |
DtCAutoShowCursorPosition |
Boolean |
True |
CSG |
DtNblinkRate |
DtCBlinkRate |
int |
500 |
CSG |
DtNbuttonFontList |
DtCFontList |
XmFontList |
Dynamic |
CSG |
DtNcolumns |
DtCColumns |
XmNcolumns |
Dynamic |
CSG |
DtNcursorPosition |
DtCCursorPosition |
XmTextPosition |
0 |
CSG |
DtNcursorPositionVisible |
DtCCursorPositionVisible |
Boolean |
True |
CSG |
DtNdialogTitle |
DtCDialogTitle |
XmString |
NULL |
CSG |
DtNeditable |
DtCEditable |
Boolean |
True |
CSG |
DtNlabelFontList |
DtCFontList |
XmFontList |
Dynamic |
CSG |
DtNmaxLength |
DtCMaxLength |
int |
Largest integer |
CSG |
DtNoverstrike |
DtCOverstrike |
Boolean |
False |
CSG |
DtNrows |
DtCRows |
XmNrows |
Dynamic |
CSG |
DtNscrollHorizontal |
DtCScroll |
Boolean |
True |
CG |
DtNscrollLeftSide |
DtCScrollSide |
Boolean |
Dynamic |
CG |
DtNscrollTopSide |
DtCScrollSide |
Boolean |
False |
CG |
DtNscrollVertical |
DtCScroll |
Boolean |
True |
CG |
DtNshowStatusLine |
DtCShowStatusLine |
Boolean |
False |
CSG |
DtNspellFilter |
DtCspellFilter |
char * |
Spell |
CSG |
DtNtextBackground |
DtCBackground |
Pixel |
Dynamic |
CSG |
DtNtextDeselectCallback |
DtCCallback |
XtCallbackList |
NULL |
C |
DtNtextFontList |
DtCFontList |
XmFontList |
Dynamic |
CSG |
DtNtextForeground |
DtCForeground |
Pixel |
Dynamic |
CSG |
DtNtextTranslations |
DtCTranslations |
XtTranslations |
NULL |
CS |
DtNtextSelectCallback |
DtCCallback |
XtCallbackList |
NULL |
C |
DtNtopCharacter |
DtCTextPosition |
XmTextPosition |
0 |
CSG |
DtNwordWrap |
DtCWordWrap |
Boolean |
True |
CSG |
DtEditor は、次のスーパークラスから動作とリソースを継承します。
XmForm
XmManager
Composite
Core
詳細は、該当するマニュアル・ページを参照してください。
次のリストは、DtEditor ウィジェットとそのダイアログ・ボックスのローカライズのために設計されるウィジェット・リソースのセットを示しています。これらのリソースのデフォルト値は、ロケールに依存します。
DtNcenterToggleLabel は、[書式の設定] ダイアログ・ボックスの中央に揃えるトグル・ボタンのラベルを指定します。C ロケールでのデフォルト値は、[Center] です。日本語ロケールでは [中央] です。
DtNchangeAllButtonLabel は、ドキュメントの中の検索文字列のすべての存在箇所を置換する [検索/変更] ダイアログ・ボックスにあるボタンのラベルを指定します。C ロケールでのデフォルト値は、[Change all] です。日本語ロケールでは [すべてを変更] です。
DtNchangeButtonLabel は、ドキュメントの中の検索文字列の次の存在箇所を置換する [検索/変更] ダイアログ・ボックスにあるボタンのラベルを指定します。C ロケールでのデフォルト値は、[Change] です。日本語ロケールでは [変更] です。
DtNchangeFieldLabel は、ユーザが置換文字列を指定する [検索/変更] ダイアログ・ボックスにあるフィールドのラベルを指定します。C ロケールでのデフォルト値は、[Change To] です。日本語ロケールでは [変更後の単語] です。
DtNcurrentLineLabel は、ステータス行の現在の行番号フィールドのラベルを指定します。C ロケールでのデフォルト値は、[line] です。日本語ロケールでは [行] です。
DtNfindButtonLabel は、ドキュメントの中の検索文字列の次の存在箇所を検索する [検索/変更] ダイアログ・ボックスにあるボタンのラベルを指定します。C ロケールでのデフォルト値は、[Find] です。日本語ロケールでは [検索] です。
DtNfindChangeDialogTitle は、[検索/変更] ダイアログ・ボックスのタイトルを指定します。DtNdialogTitle がヌルでない場合は、このリソースの前面に追加されてタイトルを形成します。C ロケールでのデフォルト値は、 [Change To] です。日本語ロケールでは [検索/変更] です。
DtNfindFieldLabel は、ユーザが検索文字列を指定する [検索/変更] ダイアログ・ボックスにあるフィールドのラベルを指定します。C ロケールでのデフォルト値は、[Find] です。日本語ロケールでは [検索] です。
DtNformatAllButtonLabel は、ドキュメント全体を書式化する [書式の設定] ダイアログ・ボックスにあるボタンのラベルを指定します。C ロケールでのデフォルト値は、[All] です。日本語ロケールでは [すべて] です。
DtNformatParagraphButtonLabel は、挿入カーソルを含んでいるパラグラフを書式化する [書式の設定] ダイアログ・ボックスにあるボタンのラベルを指定します。C ロケールでのデフォルト値は、[Paragraph] です。日本語ロケールでは [パラグラフ] です。
DtNformatSettingsDialogTitle は、[書式の設定] ダイアログ・ボックスのタイトルを指定します。DtNdialogTitle がヌルでない場合は、このリソースの前面に追加されてタイトルを形成します。C ロケールでのデフォルト値は、[Format Setting] です。日本語ロケールでは [書式の設定] です。
DtNinformationDialogTitle は、ユーザにフィードバックと一般情報を提示するのに使用される [インフォメーション] ダイアログ・ボックスのタイトルを指定します。DtNdialogTitle がヌルでない場合は、このリソースの前面に追加されてタイトルを形成します。C ロケールでのデフォルト値は、[Infomation] です。日本語ロケールでは [インフォメーション] です。
DtNjustifyToggleLabel は、[書式の設定] ダイアログ・ボックスにある両端揃えトグル・ボタンのラベルを指定します。C ロケールでのデフォルト値は、[Justify] です。日本語ロケールでは [両端揃え] です。
DtNleftAlignToggleLabel は、[書式の設定] ダイアログ・ボックスにある左揃えトグル・ボタンのラベルを指定します。C ロケールでのデフォルト値は、[Left Align] です。日本語ロケールでは [左揃え] です。
DtNleftMarginFieldLabel は、[書式の設定] ダイアログ・ボックスにある左マージン値フィールドのラベルを指定します。C ロケールでのデフォルト値は、[Left Margin] です。日本語ロケールでは [左マージン] です。
DtNmisspelledListLabel は、[スペルチェック] ダイアログ・ボックスにある認識できない、またはスペルが間違っている単語のリストのラベルを指定します。C ロケールでのデフォルト値は、[Misspelled Words] です。日本語ロケールでは [スペルミスの単語] です。
DtNoverstrikeLabel は、エディタが上書きモードであることを示すステータス行にあるラベルを指定します。C ロケールでのデフォルト値は、[Overstrike] です。日本語ロケールでは [上書き] です。
DtNrightAlignToggleLabel は、[書式の設定] ダイアログ・ボックスにある右揃えトグル・ボタンのラベルを指定します。C ロケールでのデフォルト値は、[Right Align] です。日本語ロケールでは [右揃え] です。
DtNrightMarginFieldLabel は、[書式の設定] ダイアログ・ボックスにある右マージン値フィールドのラベルを指定します。C ロケールでのデフォルト値は、[Right Margin] です。日本語ロケールでは [右マージン] です。
DtNspellDialogTitle は、[書式の設定] ダイアログ・ボックスのタイトルを指定します。DtNdialogTitle がヌルでない場合は、このリソースの前方に追加されてタイトルを形成します。C ロケールでのデフォルト値は、[Spell] です。日本語ロケールでは [スペルチェック] です。
DtNtotalLineCountLabel は、ドキュメントの総行数を示すステータス行にあるディスプレイのラベルを指定します。C ロケールでのデフォルト値は、[Total] です。日本語ロケールでは [合計] です。
ローカライズ・リソースのそれぞれのクラス、型、デフォルト、およびアクセスを表 7-10 にリストします。アクセス欄のコードは、次の作業が可能かどうかを示します。
作成時にリソースを設定する (C)
XtSetvalues を使用して設定する (S)
XtGetValues を使用して検索する (G)
詳細は、DtEditor(3) のマニュアル・ページを参照してください。
表 7-10 DtEditor ローカライズ・リソース
名前 |
クラス |
型 |
デフォルト |
アクセス |
---|---|---|---|---|
DtNcenterToggleLabel |
DtCCenterToggleLabel |
XmString |
Dynamic |
CSG |
DtNchangeAllButtonLabel |
DtCChangeAllButtonLabel |
XmString |
Dynamic |
CSG |
DtNchangeButtonLabel |
DtCChangeButtonLabel |
XmString |
Dynamic |
CSG |
DtNchangeFieldLabel |
DtCChangeFieldLabel |
XmString |
Dynamic |
CSG |
DtNcurrentLineLabel |
DtCCurrentLineLabel |
XmString |
Dynamic |
CSG |
DtNfindButtonLabel |
DtCFindButtonLabel |
XmString |
Dynamic |
CSG |
DtNfindChangeDialogTitle |
DtCFindChangeDialogTitle |
XmString |
Dynamic |
CSG |
DtNfindFieldLabel |
DtCFindFieldLabel |
XmString |
Dynamic |
CSG |
DtNformatAllButtonLabel |
DtCFormatAllButtonLabel |
XmString |
Dynamic |
CSG |
DtNformatParagraphButtonLabel |
DtCFormatParagraphButtonLabel |
XmString |
Dynamic |
CSG |
DtNformatSettingsDialogTitle |
DtCFormatSettingsDialogTitle |
XmString |
Dynamic |
CSG |
DtNinformationDialogTitle |
DtCInformationDialogTitle |
XmString |
Dynamic |
CSG |
DtNjustifyToggleLabel |
DtCJustifyToggleLabel |
XmString |
Dynamic |
CSG |
DtNleftAlignToggleLabel |
DtCLeftAlignToggleLabel |
XmString |
Dynamic |
CSG |
DtNleftMarginFieldLabel |
DtCLeftMarginFieldLabel |
XmString |
Dynamic |
CSG |
DtNmisspelledListLabel |
DtCMisspelledListLabel |
XmString |
Dynamic |
CSG |
DtNoverstrikeLabel |
DtCOverstrikeLabel |
XmString |
Dynamic |
CSG |
DtNrightAlignToggleLabel |
DtCRightAlignToggleLabel |
XmString |
Dynamic |
CSG |
DtNrightMarginFieldLabel |
DtCRightMarginFieldLabel |
XmString |
Dynamic |
CSG |
DtNspellDialogTitle |
DtCSpellDialogTitle |
XmString |
Dynamic |
CSG |
DtNtotalLineCountLabel |
DtCTotalLineCountLabel |
XmString |
Dynamic |
CSG |
DtEditor ウィジェットは、次の 3 つのコールバック関数をサポートします。
DtEditorNHelpCallback
DtNtextSelectCallback
DtNtextDeselectCallback
エディタ・ウィジェットとそのダイアログ・ボックスについてのヘルプ情報を表示する場合は、XmNhelpCallback リソースを設定し、DtEditorHelpCallbackStruct の一部として渡される reason フィールドを使用して、[ヘルプ] ダイアログ・ボックスの内容を設定します。次の構造体へのポインタが XmNHelpCallback に渡されます。コールバックのための構造体を次に示し、表 7-11 で説明します。
typedef struct { int reason; XEvent *event; } DtEditorHelpCallbackStruct;表 7-11 DtEditorHelp コールバックのための構造体
構造体 |
説明 |
---|---|
reason |
コールバックが呼び出された reason。reason のリストについては、DtEditor(3) のマニュアル・ページを参照してください。 |
event |
このコールバックを呼び出したイベントへのポインタ。値は、NULL になることもあります。 |
テキストが選択されているかどうかによって、メニュー項目とコマンドを有効か無効にする場合は、DtNtextSelectCallback リソースおよび DtNtextDeselectCallback リソースを使用します。DtNtextSelectCallback は、編集ウィンドウでテキストが選択されたときに呼び出される関数を指定します。DtNtextDeselectCallback は、編集ウィンドウでテキストが選択されていないときに呼び出される関数を指定します。コールバックによって送られる reason は、DtEDITOR_TEXT_SELECT と DtEDITOR_TEXT_DESELECT です。
アプリケーションが拡張性のある一連のデータ型を管理する場合には、アクションの実行によりデータ型を直接実行しなければなりません。この章では、アプリケーションからアクションを実行する方法について説明します。アクションの実行方法を示すサンプル・プログラムも示します。
アクションとアクションの作成の詳細は、第 9 章「データ型データベースのアクセス」「データ型データベースのアクセス」と、『Solaris 共通デスクトップ環境 上級ユーザ及びシステム管理者ガイド』の次の章を参照してください。
第 10 章「アクションおよびデータ型の概要」
第 11 章「アクション作成ツールを使ったアクションとデータ型の作成」
第 12 章「手入力によるアクションの作成」
第 13 章「手入力によるデータ型の作成」
デスクトップ・サービス・ライブラリによってエクスポートされたアクション実行 API は、アプリケーションから別のアプリケーションを実行したり、操作を実行したりするための方法の 1 つです。その他の方法として、次のものがあります。
fork/exec システム・コール
ToolTalk メッセージ
これらの方法は、それぞれ利点と制約があるので、具体的な状況を評価して、どちらが適切かを判断しなければなりません。
アクションは、従来のコマンド行アプリケーション (すなわち、COMMAND アクション) と ToolTalk アプリケーション (すなわち、TT_MSG アクション) の両方をカプセル化できます。アクションを実行するアプリケーションは、コマンドがフォークされたのか、それともメッセージが送られたのかを知る必要はありません。
アクションは多様性を持ち、デスクトップのデータ型機構と統合されます。これは、[開く] や [印刷] などのアクションは、与えられる引き数の型に基づいて異なる動作をするが、動作の違いは、アクションを呼び出すアプリケーションに対して透過されることです。
アクションは、アプリケーション開発者、システム統合者、システム管理者、およびエンドユーザに対して、構成の大きな可能性を提供します。これらのユーザは、アクション・データベースを編集して、アクションの実行方法の定義を変更できます。
アクションは、分散環境でも有効です。アプリケーションが fork/exec により別のアプリケーションを直接実行する場合には、両方のアプリケーションが同じシステム上で使用可能でなければならず、同じシステム上で実行可能でなければなりません。それに対して、アクション実行 API は、アクション・データベース内の情報に基づいて、どのシステム上で COMMAND アクションを実行するかを判断します。
アクションによって、デスクトップの動作と常に一貫性のあるアプリケーションの動作が可能になります。これは、デスクトップのコンポーネントがユーザのデータ・ファイルを操作するときに、アクションを使用することで対話するからです。
アクション実行 API の欠点は、戻り値機能が制限されている実行方法であり、実行されたアクション・ハンドラとの対話機能がないことです。これらの機能が必要な場合には、fork/exec/pipes を使用できます。ただし、共通デスクトップ環境 (CDE) で望ましいプロセス間通信の方法は、一般化されたクライアント/サーバ・パラダイムを持つ ToolTalk です。
実行について説明します。アプリケーションがいくつかの異なる形式 (テキストとグラフィック) のデータ・ファイルを管理すると仮定し、これらのファイルの編集と表示の手段をユーザに提供する必要があると仮定します。アクションを使用せずにこれを実現するには、次の方法の 1 つを使用することになります。
fork/exec を使用して、適切なエディタを起動し、ユーザがエディタの名前を指定するための何らかの方法 (環境変数など) を考えてください。このアプローチには次のような制約があります。
システム・コールによりサブプロセスを実行し、その結果のシグナルを監視する複雑なコードを書かなければなりません。
アプリケーションと同じシステム上で使用できるエディタが必要であり、システム管理者は、rsh などの機能を使用する複雑な構成を提供しなければなりません。
システム管理者とユーザは、アプリケーションの固有の構成モデルを学び、管理しなければなりません。
ToolTalk メッセージを使用して、編集や表示などの操作をデータに対して実行することを要求します。このアプローチには、すべてのデータ型に対して使用可能な ToolTalk 形式のエディタが必要であるという制約があります。
アクションによりこれを実現するには、バッファまたはデータ・ファイルに対して [開く] アクションを実行するだけです。アクション実行 API はアクション・データベースに基づいて、送信する適切なメッセージまたは実行するコマンドを判断し、一時ファイルの作成や削除、必要なシグナルの取り込みなどのすべての詳細を処理します。
アクションのアプリケーション・プログラム・インタフェース (API) は、どの種類のアクションに対しても機能します。デスクトップでのアクションの種類は、次のとおりです。
コマンド・アクション |
実行するコマンド行を指定します。 |
ToolTalk アクション |
送信する ToolTalk メッセージを指定します。メッセージは、適切なアプリケーションによって受信されます。 |
マップ・アクション |
特定の動作を定義する代わりに、別のアクションを参照します。 |
詳細は、『Solaris 共通デスクトップ環境 上級ユーザ及びシステム管理者ガイド』の第 10 章「アクションおよびデータ型の概要」を参照してください。
アクション実行 API は、デスクトップ・サービス・ライブラリからエクスポートされて、次のような多数のタスクを実行する関数を提供します。
アクションおよびデータ型定義のデータベースを初期化し、読み込みます。アクションを実行するためには、その前にデータベースが読み込まれていなければなりません。
データベースに問い合わせます。指定されたアクション、アクションに関連付けられたアイコン・イメージ、ラベル、または記述が存在するかどうかを判断する関数があります。
アクションを実行します。アプリケーションは、ファイルまたはバッファ引き数をアクションに渡すことができます。
アクション・ステータスを受け取り、引き数を返すコールバックを登録します。
アクション・コマンド、関数、およびデータ形式の詳細は、次のマニュアル・ページを参照してください。
dtaction(1)
dtactionfile(4)
DtActionCallbackProc(3)
DtActionDescription(3)
DtActionExists(3)
DtActionIcon(3)
DtActionInvoke(3)
DtActionLabel(3)
DtActionQuit(3)
DtActionQuitType(3)
DtActionStUpCb(3)
dtexec(1)
この節では、簡単なサンプル・プログラム actions.c について説明します。actions.c の完全なリストは、この章の終わりにあります。
アプリケーションがアクションを実行するには、その前に、デスクトップ・サービス・ライブラリ (アクション実行 API を含む) を初期化して、アクションおよびデータ型定義のデータベースを読み込まなければなりません。
デスクトップ・サービス・ライブラリを初期化するには、DtInitialize() 関数を使用します。
DtInitialize(*display,widget,*name,*tool_class)
DtInitialize() は、デフォルトのイントリンシクス関数 XtAppContext を使用します。API は、アプリケーションが app_context を指定しなければならないときに使用する追加の関数 DtAppInitialize() を提供します。
DtAppInitialize(app_context,*display,widget,*name, tool_class)
次のコードの一部分は、サンプル・プログラム actions.c の中で DtInitialize() がどのように使用されているかを示しています。
if (DtInitialize(XtDisplay(shell), shell, argv[0],ApplicationClass)==False) { /* DtInitialize() has already logged an appropriate error msg */ exit(-1); }
アクションおよびデータ型データベースを読み込むには、DtDbLoad() 関数を使用します。
DtDbLoad(void)
DtDbLoad() は、アクションおよびデータ型データベースを読み込みます。この関数は、データベース・ファイルを検索するディレクトリのセット (データベース検索パス) を判断して、データベース内で見つかった *.dt ファイルを読み込みます。ディレクトリ検索パスは、DTDATABASESEARCHPATH 環境変数と内部のデフォルト値に基づきます。
次のコードの一部分は、サンプル・プログラム actions.c の中で DtDbLoad() がどのように使用されているかを示しています。
/* Load the filetype/action databases */ DtDbLoad();
長時間実行中のアプリケーションの中で DtDbLoad() を使用する場合、データベースが変更されたときには、動的に再読み込みしなければなりません。
DtDbReloadNotify() 関数を使用して、再読み込みイベントの通知を要求します。
/* Notice changes to the database without needing to restart application */ DtDbReloadNotify(DbReloadCallbackProc, callback_proc, XTPointer, client_data);
次の作業を実行するコールバックを指定します。
アプリケーションによって保持されている、キャッシュされたデータベース情報を破棄する。
DtDbLoad() 関数を再コールする。
callback_proc は、アプリケーションが保持している、キャッシュされたデータベース情報をクリーンアップしてから、DtDbLoad() を呼び出します。client_data を使用して、追加のクライアント情報をコールバック・ルーチンに渡すことができます。
アプリケーションは、アクションのアイコンまたはラベルを表示する必要がある場合には、データベースにアクセスします。また、アクションを実行することによって、アプリケーションはアクションの存在をチェックできます。データベース内のアクションは、アクション名によって識別されます。
ACTION action_name { ... }
たとえば、[電卓] アクションの定義は次のとおりです。
ACTION Dtcalc { LABEL 電卓 ICON Dtcalc ARG_COUNT 0 TYPE COMMAND WINDOW_TYPE NO_STDIO EXEC_STRING /usr/dt/bin/dtcalc DESCRIPTION 電卓 (Dtcalc) アクションは、デスクトップ電卓 ¥ アプリケーションを起動します }
[電卓] アクションのアクション名は Dtcalc です。
実行形式ファイルがデータベース内のアクション名と一致するファイル名を持つ場合には、そのファイルはアクション・ファイルです。すなわち、基本のアクションの表現です。そのファイルのアイコンとラベルに関する情報は、データベースに格納されます。
指定されたアクション定義が存在するかどうかを判断するには、DtActionExists() 関数を使用します。
DtActionExists(*name)
DtActionExists() は、指定された名前がデータベース内のアクションの名前に一致するかどうかをチェックします。この関数は、名前がアクション名に一致する場合には True を返し、その名前のアクションが見つからない場合には False を返します。
アイコン・イメージ情報を取り出すには、DtActionIcon() 関数を使用します。
DtActionIcon(char *action_name)
アクション定義は、アクションを表すために使われるアイコン・イメージを定義の ICON フィールドで指定します。
ACTION action_name { ICON icon_image_base_name ... }
DtActionIcon() は、アイコン・イメージ・フィールドの値にある文字列を返します。アクション定義にアイコン・フィールドがない場合には、この関数はデフォルトのアクション・アイコン・イメージの値 Dtactn を返します。
次に、使用したいアイコンとサイズの位置を決めます。アイコンには 4 つのサイズがあり、ビットマップまたはピックスマップ形式で使用できます。たとえば、[電卓] のアクション定義からアイコン・ファイルのベース名を見つけることができます。次に、そのベース名と表 8-1 の情報の組み合わせと、すべてのアイコンの格納情報から、目的のアイコン・ファイルを見つけ出せます。
[電卓] アクションのアイコン名は Dtcalc ですが、これはファイル名全体ではありません。アイコン・ファイル名はアイコンのサイズに基づき、4 つのサイズがあります。表 8-1 は、デスクトップ・アイコンのサイズとファイル名の命名規則を示します。
表 8-1 アイコンのサイズとファイル名
アイコンのサイズ |
ビットマップ名 |
ピックスマップ名 |
---|---|---|
16 * 16 (極小) |
name.t.bm |
name.t.pm |
24 * 24 (小) |
name.s.bm |
name.s.pm |
32 * 32 (中) |
name.m.bm |
name.m.pm |
48 * 48 (大) |
name.l.bm |
name.l.pm |
デスクトップ・アイコン・ファイルの詳細は、『Solaris 共通デスクトップ環境 上級ユーザ及びシステム管理者ガイド』の第 14 章「デスクトップのアイコンの作成」を参照してください。
ビットマップの場合、マスクとして使われる追加のファイルがあり、そのファイルの拡張子 _m.bm で終わります。したがって、各サイズのアイコンに対して合計 3 個のファイルがあります。次に、電卓のアイコン・ファイルを示します。
Dtcalc.t.bm Dtcalc.t.pm Dtcalc.t_m.bm Dtcalc.m.bm Dtcalc.m.pm Dtcalc.m_m.bm Dtcalc.l.bm Dtcalc.l.pm Dtcalc.l_m.bm
電卓には小型アイコン (Dtcalc.s.bm、Dtcalc.s.pm、Dtcalc.s_m.bm) がない点に注意してください。
DtActionIcon() はベース名だけを返します。電卓の場合は Dtcalc です。種類 (ピックスマップまたはビットマップ) とサイズ (極小、小、中、大) を選択して、適用可能な拡張子をベース名に追加してください。また、ファイルがどこにあるかを知っておいてください。
アクションのローカライズ・ラベルを取り出すには、DtActionLabel() 関数を使用します。
char *DtActionLabel(char *actionName)
アクション定義にはラベルを入れることができます。ラベルは、label_text フィールドを使用して定義されます。
ACTION action_name { LABEL label_text ... } |
このラベルは、グラフィック・コンポーネント (ファイル・マネージャやアプリケーション・マネージャなど) の中でアクションのアイコンにラベルを付けるために使用されます。アクション定義に label_text フィールドがない場合には、action_name が使用されます。
label_text 文字列の値は、エンドユーザがアクションを見分けられるように、すべてのインタフェース・コンポーネントによって使用されなければなりません。
DtActionLabel() 関数は、actionName という名前のアクションのアクション定義の中の label_text フィールドの値を返します。label_text フィールドがない場合には、この関数は actionName を返します。
アプリケーションがデスクトップ・サービス・ライブラリを初期化した後は、アクションを実行できます。
アクションを実行するには、DtActionInvoke() 関数を使用します。
DtActionInvoke (widget, action, args, argCount, termOpts, execHost,, contexDir, useIndicator,statusUpdateCb, client_data)
DtActionInvoke() は、アクション・データベースから、指定されたアクション名に一致するエントリを探して、指定されたクラス、型、およびカウントの引き数を受け入れます。アクションを実行する前に、アプリケーションはデータベースを初期化し、読み込まなければならないので注意してください。
次のコードは、actions.c の中の activateCB() (描画ボタンの起動コールバック) の一部です。
DtActionInvocationID actionId; /* If a file was specified, build the file argument list */ printf("%s(%s)¥n",action,file); if (file != NULL && strlen(file) != 0) { ap = (DtActionArg*) XtCalloc(1, sizeof(DtActionArg)); ap[0].argClass = DtACTION_FILE; ap[0].u.file.name = file; nap = 1; } /* Invoke the specified action */ actionId = DtActionInvoke(shell,action,ap,nap,NULL,NULL,NULL,True,NULL,NULL);
この章では、データ型関数とデータ型データベースの使い方について説明します。
データ型により、従来の UNIX ファイル・システムによって提供される機能を越えて、ファイルとデータの属性が拡張されます。これらの拡張は、アイコン名、記述、アクションなどの属性から成っており、ファイルがデータ上で実行できます。この情報は、DATA_ATTRIBUTES テーブル (またはデータベース) に名前と値の対として格納されます。デスクトップは、次のパラグラフで説明する特定の DATA_ATTRIBUTES のセットを使用します。DATA_ATTRIBUTES テーブルは、将来およびアプリケーション固有の成長のために拡張可能ですが、他のアプリケーションでは追加をチェックできないので、このテーブルを拡張することは推奨しません。
データを、特定のファイルまたは DATA_CRITERIA テーブルのデータ・エントリに一致させます。DATA_CRITERIA テーブルのエントリは、具体性が高いものから具体性が低いものへ降順で並べられます。たとえば、/usr/lib/lib* は /usr/* よりも具体的なので、/usr/* より前に置かれます。ファイルまたはデータの型の検査が要求されると、このテーブルが始めから順にチェックされ、ファイルまたはデータから与えられた情報を使用して最も一致するものが検索されます。情報に一致するエントリが見つかると、DATA_ATTRIBUTES_NAME を使用して、正しい DATA_ATTRIBUTES エントリが検索されます。
アプリケーションがデスクトップと同じ方法でデータ・オブジェクト (ファイルまたはデータ・バッファ) をユーザに提示するようにする場合は、DtDts* API を使用して、データ・オブジェクトの表示方法とデータ・オブジェクトの操作方法を指定します。たとえば、アプリケーションは、ICON 属性に対して DtDtsDataTypeToAttributeValue() 関数を呼び出すことによって、データ・オブジェクトを表すアイコンを判断できます。
データ型を使用するには、libDtSvc ライブラリをリンクしてください。アクションは、通常はデータ型情報と一緒に読み込まれます。アクションは、libXm ライブラリと libX11 ライブラリのリンクを必要とします。ヘッダ・ファイルは、Dt/Dts.h と Dt/Dt.h です。
データ型データベースの使用例が入っているデモ・プログラムが、/usr/dt/examples/dtdts/datatypes/datatyping.c にあります。
データ型検査は、次の 2 つの部分から成ります。
データの基準とデータの属性を格納するデータベース
データベースに問い合わせるルーチンの集まり
CONTENT
DATA_ATTRIBUTES_NAME
LINK_NAME
LINK_PATH
MODE
NAME_PATTERN
PATH_PATTERN
データの基準を使用頻度が高いものから順に表 9-1 に示します。
表 9-1 データの基準 (使用頻度順)
基準 |
説明 |
使用例 |
---|---|---|
DATA_ATTRIBUTES_NAME |
このデータ型の名前。この値は、データ属性テーブルの中の record_name です。 |
POSTSCRIPT |
NAME_PATTERN |
このデータに一致するファイル名を記述するシェル・パターン照合表現。デフォルトは空の文字列で、照合の際にファイル名のパターンを無視することを意味します。 |
*.ps |
CONTENT |
ファイル・ユーティリティが使用し、マジック・ファイルの開始、型、および値のフィールドとして解釈される 3 つの値。詳細は、file(1) のマニュアル・ページを参照してください。デフォルトは空のフィールドで、照合の際に内容を無視することを意味します。一致する型の例としては、文字列、バイト、ショート、ロング、およびファイル名があります。 |
0 string !% |
MODE |
stat 構造体のモード・フィールドに一致する 0 〜 4 文字の文字列。詳細は、stat(2) のマニュアル・ページを参照してください。最初の文字は、次のとおりです。
d は、ディレクトリに一致します。 s は、ソケットに一致します。 l は、シンボリック・リンクに一致します。 f は、通常ファイルに一致します。 b は、ブロック・ファイルに一致します。 c は、文字型特殊ファイルに一致します。 |
f&!x
|
|
次の文字は、最初または後続の文字にできます。
r は、ユーザ、グループ、またはその他の読み取り権ビットが設定されたファイルに一致します。 w は、ユーザ、グループ、またはその他の書き込み権ビットが設定されたファイルに一致します。 x は、ユーザ、グループ、またはその他の実行あるいはディレクトリ検索のアクセス権ビットが設定されているファイルに一致します。
|
|
|
たとえば、frw の MODE フィールドは、読み取り可能または書き込み可能な通常ファイルに一致します。x は、実行可能なビットまたは検索ビットが設定されたファイルに一致します。 デフォルトは空のフィールドで、照合の際にモードを無視することを意味します。 |
|
PATH_PATTERN |
このデータに一致する絶対パス名を記述するシェル・パターン照合式。デフォルトは空の文字列で、照合の際にパス・パターンを無視することを意味します。 |
*/mysubdir /* |
LINK_NAME |
dtdtsfile(4) のマニュアル・ページを参照してください。 |
|
LINK_PATH |
dtdtsfile(4) のマニュアル・ページを参照してください。 |
|
データ型の一般的な属性のいくつかをアルファベット順に示します。
ACTIONS
COPY_TO_ACTION
DESCRIPTION
ICON
INSTANCE_ICON
IS_EXECUTABLE
IS_TEXT
LINK_TO_ACTION
MEDIA
MIME_TYPE
MOVE_TO_ACTION
NAME_TEMPLATE
PROPERTIES
X400_TYPE
これらのデータの属性を使用頻度が高い順に表 9-2 に示します。
表 9-2 データの属性 (使用頻度順)
基準 |
説明 |
使用例 |
---|---|---|
DESCRIPTION |
人間が読める形式で書かれたデータの説明。このフィールドが NULL か、データ属性レコードに含まれていない場合は、データ属性名が使用されます。 |
This is a PostScript page description. |
ICON |
このデータに対して使用されるアイコン名。このフィールドが NULL か、データ属性レコードに含まれていない場合は、標準のアイコンが使用されます。アイコンの命名の詳細は、dtdtsfile(4) のマニュアルページを参照してください。 |
Dtps |
PROPERTIES |
このデータの属性を示すキーワード。有効な値は、見える場合と見えない場合があります。このフィールドが NULL か、データ属性レコードに含まれていない場合は、可視属性とみなされます。これは、ファイルをユーザから完全に隠したい場合に使用します。 |
invisible |
ACTIONS |
このデータに対して実行できるアクションのリスト。このリストは、この型のオブジェクトに対してユーザに提示されるアクションのアクション・テーブル内の名前を参照します。このフィールドが NULL か、データ属性レコードに含まれていない場合は、どのアクションも使用できません。 |
Open,Print |
NAME_TEMPLATE フィールド
|
この型のデータの新規ファイル作成に使用される文字列。文字列は、ファイル名と共に 1 つの引き数として sprintf(3) に渡されます。デフォルトは空です。このフィールドをデータ抽出条件テーブルの NAME_PATTERN フィールドと比較してみてください。テンプレートは %s.c など、特定のファイルを作成するために使用されますが、パターンは *.c などのファイルを検索するために使用されます。 |
%s.ps |
IS_EXECUTABLE フィールド |
このデータ型をアプリケーションとして実行できることをユーザに知らせる文字列論理値。IS_EXECUTABLE に true が設定されている場合 (DtDtsIsTrue() 参照)、データは実行可能です。このフィールドが NULL かデータ属性レコードに含まれていない、または true に設定されていない場合は、データは実行可能ではないとみなされます。 |
true |
MOVE_TO_ACTION |
オブジェクトが現在のオブジェクトに移動されるときに実行されるアクション名 |
FILESYSTEM_MOVE |
COPY_TO_ACTION |
オブジェクトが現在のオブジェクトにコピーされるときに実行されるアクション名 |
FILESYSTEM_COPY |
LINK_TO_ACTION |
オブジェクトが現在のオブジェクトにリンクされるときに実行されるアクション名 |
FILESYSTEM_LINK |
IS_TEXT |
このデータ型がテキスト・エディタまたはテキスト・ウィジェットでの操作 (表示または編集) に適していることをユーザに知らせる文字列論理値。データが本来はテキストである場合や、ユーザに対してテキスト形式で表示される場合、IS_TEXT フィールドには true が設定されます (DtDtsIsTrue() 参照)。その基準は、データが人間の言語から成るものか、手動で生成および管理されているか、テキスト・エディタでの表示と編集が可能か、構造体と書式の情報をまったく (あるいはごくわずかしか) ないかどうかという点から決定されます。 |
詳細な例については、表 9-3 を参照してください。 |
|
IS_TEXT フィールドが true の場合、データはアプリケーションから直接表示できます。すなわち、アプリケーションは XmText などのテキスト編集ウィジェットにデータを直接読み込むことができます。 |
|
MEDIA フィールド |
MEDIA ネーム・スペース名は、データそのものの形式について記述します。MEDIA 名は、ICCCM 選択ターゲットとして使用され、データ型レコードの MEDIA フィールドで名前が付けられ、ToolTalk メディア交換メッセージの型パラメータの中で使用されます。
MEDIA ネーム・スペースは、ICCCM によって定義された選択ターゲット・アトムのネーム・スペースのサブセットです。データ書式を指定する選択ターゲットは、すべて有効な MEDIA 名です。有効な MEDIA 名は選択ターゲットとして直接使用できます。データ書式ではなく、選択の属性 (たとえば、LIST_LENGTH) や発生する副作用 (たとえば、DELETE) を指定する選択ターゲットもあります。これらの属性選択ターゲットは、MEDIA ネーム・スペースの一部ではありません。 |
POSTSCRIPT |
MIME_TYPE |
MEDIA は、デスクトップ内部にあり、データ型を表す一意の名前です。ただし、外部の他の命名組織もネーム・スペースを設定しています。MIME RFC で述べられている Multipurpose Internet Message Extensions (MIME)は、そのような外部登録の 1 つであり、デスクトップ・メール・プログラムのための標準的なネーム・スペースです。 |
application/postscript |
X400_TYPE |
X.400 型は、構造は MEDIA 型に似ていますが、異なる規則を使用して書式化され、異なる命名組織を持ちます。 |
1 2 840 113556 3 2 850 |
INSTANCE_ICON フィールド |
データのインスタンスのために使用されるアイコン名で、通常は %name%.icon などの値 (dtdtsfile(4) のマニュアル・ページの「バグ」も参照)。INSTANCE_ICON が設定されている場合は、アプリケーションは ICON の代わりに使用しなければなりません。このフィールドが NULL か、データ属性レコードに含まれていない場合は、ICON フィールドが使用されます。 |
/myicondir/%name%.bm |
DATA_HOST |
DATA_HOST 属性は、*.dt ファイルのデータ属性テーブルに追加できるフィールドではありませんが、テーブルから属性を読み込むアプリケーションに返すことができます。データ型検査サービスはこの属性を自動的に追加して、データ型の読み込み元のホスト・システムを示します。このフィールドが NULL か、データ属性レコードに含まれていない場合、データ型はローカル・システムから読み込まれています。 |
|
IS_TEXT フィールドは、MIME_RFC で述べられている MIME コンテント・タイプである MIME_TYPE フィールドのテキスト属性とは異なります。MIME コンテント・タイプから、データがテキスト文字とバイト値のどちらで作成されているかがわかります。データがテキスト文字で作成され、データに text/* というラベルが付けられている場合、IS_TEXT フィールドはテキスト形式でユーザに表示するのに適したデータかどうかを判別します。
さまざまな MIME_TYPE属性での IS_TEXTの使用例を表 9-3 に示します。
表 9-3 IS_TEXT 属性の例
説明と MIME_TYPE 属性 |
IS_TEXT 値 |
---|---|
ASCII でコード化された人間の言語 (MIME_TYPE text/plain) |
IS_TEXT true |
*EUC、JIS、Unicode、または ISO ラテン文字セットにコード化された人間の言語 (MIME-TYPE text/plain; charset=XXX) |
IS_TEXT true |
カレンダ・アポイント (MIME_TYPE text/plain) |
IS_TEXT false |
ハイパーテキスト・マークアップ言語 (HTML) (MIME_TYPE text/html) |
IS_TEXT true |
PostScript (MIME_TYPE application/postscript) |
IS_TEXT false |
C プログラム・ソース (C_SRC) (MIME_TYPE text/plain) |
IS_TEXT true |
ビットマップとピックスマップ (XBM と XPM) (MIME_TYPE text/plain) |
IS_TEXT false |
デスクトップ・アプリケーション・ビルド・サービスのためのプロジェクトまたはモジュール・ファイル (MIME_TYPE text/plain) |
IS_TEXT false |
シェル・スクリプト (MIME_TYPE text/plain) |
IS_TEXT false |
uuencode(1) によって生成されたコード化テキスト (MIME_TYPE text/plain) |
IS_TEXT false |
*MIME_TYPE text/plain |
IS_TEXT false |
データ型属性の詳細は、dtdtsfile(4) のマニュアル・ページを参照してください。
データ・オブジェクトの属性を調べるには、まずオブジェクトの型を判断し、その型の適切な属性値を求めなければなりません。データベースにデータ情報を問い合わせるための関数を表 9-4 に示します。セクション 3 にこれらの関数のマニュアル・ページがあります。詳細は、該当するマニュアル・ページを参照してください。
表 9-4 データ型データベース問い合わせ関数
関数 |
説明 |
---|---|
DtDtsBufferToAttributeList() |
指定バッファのデータ属性のリストを検索します。 |
DtDtsBufferToAttributeValue() |
指定バッファのデータ属性を検索します。 |
DtDtsBufferToDataType() |
指定バッファのデータ型名を検索します。 |
DtDtsDataToDataType() |
指定データ・セットのデータ型を検索します。 |
DtDtsDataTypeIsAction() |
結果として保存されたディレクトリのデータ型を返します。 |
DtDtsDataTypeNames() |
使用可能なデータ型のリストを検索します。 |
DtDtsDataTypeToAttributeList() |
指定データ属性名の属性リストを検索します。 |
DtDtsDataTypeToAttributeValue() |
指定データ属性名の属性値を検索します。 |
DtDtsFileToAttributeList() |
指定ファイルのデータ属性のリストを検索します。 |
DtDtsFileToAttributeValue() |
指定ファイルのデータ属性値を検索します。 |
DtDtsFileToDataType() |
指定ファイルのデータ型を検索します。 |
DtDtsFindAttribute() |
属性 name が value に一致するデータ型のリストを検索します。 |
DtDtsFreeAttributeList() |
指定属性リストのメモリを解放します。 |
DtDtsFreeAttributeValue() |
指定属性値のメモリを解放します。 |
DtDtsFreeDataType() |
指定データ型名のアプリケーション・メモリを解放します。 |
DtDtsFreeDataTypeNames() |
DtDtsDataTypeNames() または DtDtsFindAttribute() を呼び出して作成されたメモリを解放します。 |
DtDtsIsTrue() |
文字列を論理値に変換する簡易関数 |
DtDtsRelease() |
一般的には再読み込みの準備として、データ型データベース情報の読み込みを解除します。 |
DtDtsSetDataType() |
指定されたディレクトリのデータ型を設定します。 |
DtsLoadDataTypes() |
データ型関数のためにデータベース・フィールドを初期化し、読み込みます。アクションまたはアクション型を使用する必要がなく、パフォーマンスを向上させたい場合は、DtDbLoad() の代わりに使用します。アクションを使用する必要がある場合は DtDbLoad() を使用します。 |
データ型を検査して属性を検索するには、簡易、中間、拡張の 3 つの方法があります。
データ型を検査するための最も簡単な方法は、次の関数を使用することです。
DtDtsFileToAttributeList()
DtDtsFileToAttributeValue()
これらの関数を使用すると、ファイルの型が検査され、単一の属性またはリスト全体が検索されます。システム・コールが行われ、データ型の検査と属性の検索が行われます。次の関数は、中間データ型検査関数を呼び出します。
DtDtsBufferToAttributeList()
DtDtsBufferToAttributeValue()
バッファは、読み取り権/書き込み権を持つ通常ファイルに一致するモードを持つと想定されます。読み専用バッファの型の検査については、「拡張データ型検査」を参照してください。
データの型を検査して属性を検索する場合、プロセスのデータ型検査部分は、パフォーマンスの点で最もコストがかかります。データ型の検査を 2 番目の方法で行うと、データ型検査のための関数と属性検索のための関数を切り離すことによって、パフォーマンスを改善できます。中間データ型検査には、次の関数を使用します。
DtDtsBufferToDataType()
DtDtsFileToDataType()
DtDtsDataTypeToAttributeList()
DtDtsDataTypeToAttributeValue()
アプリケーションが複数の属性値を問い合わせる場合には、これらの関数を使用します。これらの関数を使用すると、オブジェクトの型が検査され、その型を使用して属性リストから 1 つ以上の属性を検索します。
データ型検査と属性の検索を行うには、中間データ型関数を使用するようにしてください。これらの関数は、拡張データ型関数を呼び出し、バッファについて簡易データ型検査と同様に想定します。
拡張データ型検査では、システム・コール、データ型、さらには属性検索も別々に行われます。拡張データ型検査では、あらかじめ初期化されてデータ型関数の一部としては含まれない既存のシステム・コールからのデータを使用するので、コード化が複雑になります。拡張データ型検査には、次の関数を使用してください。
DtDtsDataToDataType()
読み取り専用バッファの型を検査するには、st_mode フィールドが S_IFREG | S_IROTH |S_IRGRP | S_IRUSR に設定された stat 構造体が渡されなければなりません。
データベースが読み込まれるとアクションの検査ができるようになるため、データベースの各アクションに対して合成データ型が生成されます。これらのデータ型は、次の 2 つの追加の属性を持つことができます。
IS_ACTION は、このデータ型がアクションであることをユーザに知らせる文字列論理値です。IS_ACTION に文字列 true (大文字と小文字の区別はありません) が設定されている場合、データはアクションです。
IS_SYNTHETIC は、このデータ型が ACTION テーブルのエントリから生成されたことをユーザに知らせる文字列論理値です。IS_SYNTHETIC に true が設定されている場合、データ型は生成されています。
アプリケーションがデータ型を定義する場合は、次の手順に従ってプログラマが意図したドラッグ & ドロップ動作のすべてが提供されているか確認してください。
アプリケーションの中で、データ型を定義する必要があるかどうかを指定します。
定義する各データ型について、関連するオブジェクトをドロップ領域にするかどうかを指定します。
ドロップ領域として登録する各オブジェクトについて、どの操作 (移動、コピー、またはリンク) を定義するかを指定します。
各オブジェクトに対して有効なドロップ操作について、適切なドロップ・アクションを定義します (MOVE_TO_ACTION、COPY_TO_ACTION、および LINK_TO_ACTION 属性を設定してください)。
アプリケーションがデータ・オブジェクトのアイコンを表示する場合、それらのアイコンをドロップ領域としてサポートしなければならないこともあります。その場合、MOVE_TO_ACTION、COPY_TO_ACTION、または LINK_TO_ACTION 属性を問い合わせて、それらのデータ・オブジェクトのドロップ動作を指定する必要があります。対応する属性値が NULL でない場合だけ、オブジェクトはドロップ操作をサポートしなければなりません。3 つの属性すべてが NULL の値を持つ場合、オブジェクトはドロップ領域として登録されません。データ型が定義されているオブジェクトの属性を最低 1 つでも設定すると、アプリケーションはそのオブジェクトをドロップ領域として登録できます。
ユーザがオブジェクトをドロップ領域にドラッグすると、アプリケーションはドロップを行うためにどのジェスチャ (すなわち、どのドラッグ操作) が使用されたかを判断します。ドラッグ操作とドロップ領域のデータ型に基づいて、アプリケーションはデータ型データベースからドロップ属性を検索します。次に、DtActionInvoke を呼び出して、次の 2 つの規則によってパラメータを判断します。
ユーザがオブジェクト A と B をオブジェクト C 上にドロップした場合は、C、A、B を args として DtActionInvoke を呼び出します。action は、C の MOVE_TO_ACTION、COPY_TO_ACTION、LINK_TO_ACTION のいずれかの値です。オブジェクト C がアクションの場合、args リストは C を含みません。また、action は C です。
ファイル・マネージャとそのディレクトリおよびフォルダ・オブジェクトは、デスクトップが移動、コピー、およびリンクされたドロップ属性を使用する方法を示す例となります。ユーザは、オブジェクト (ファイル) をディレクトリ・フォルダへドラッグ & ドロップできます。ファイル・マネージャは、フォルダ・オブジェクトに対して、MOVE_TO_ACTION、COPY_TO_ACTION、および LINK_TO_ACTION アクションを定義します。これらのアクションは、適切なファイル・システムの移動、コピー、およびリンクのためのシステム関数を実行します。
MOVE_TO_ACTION、COPY_TO_ACTION、および LINK_TO_ACTION 属性の定義の例については、/usr/dt/appconfig/types/C/dtfile.dt を参照してください。ドラッグ & ドロップの使用方法の詳細は、第 5 章「ドラッグ & ドロップとの統合」を参照してください。
この節では、データ型検査のコード例を示します。このコード例は、/usr/dt/examples/dtdts/datatyping.c にあります。このサンプル・コードは、渡された各ファイルのデータ型、アイコン名、およびサポートされるアクションを示します。dtaction クライアントを使用して、サポートされているアクションをファイルで実行することもできます。datatyping の使い方は、次のとおりです。
datatyping file1 [file2 ...] #include <Xm/Form.h> #include <Xm/Text.h> #include <Dt/Dts.h> #define ApplicationClass "DtDatatyping" static Widget text; static void DisplayTypeInfo(int, char**); int main(int argc, char **argv) { XtAppContext appContext; Widget toplevel, form; Arg args[20]; int n; toplevel = XtAppInitialize(&appContext, ApplicationClass, NULL, 0, argc, argv, NULL, NULL, 0); if (argc == 1) { printf("%s: No files specified.¥n", argv[0]); exit(1); } form = XmCreateForm(toplevel, "form", NULL, 0); XtManageChild(form); n = 0; XtSetArg(args[n], XmNleftAttachment, XmATTACH_FORM); n++; XtSetArg(args[n], XmNrightAttachment, XmATTACH_FORM); n++; XtSetArg(args[n], XmNtopAttachment, XmATTACH_FORM); n++; XtSetArg(args[n], XmNbottomAttachment, XmATTACH_FORM); n++; XtSetArg(args[n], XmNeditable, False); n++; XtSetArg(args[n], XmNeditMode, XmMULTI_LINE_EDIT); n++; XtSetArg(args[n], XmNrows, 25); n++; XtSetArg(args[n], XmNcolumns, 90); n++; text = XmCreateScrolledText(form, "text", args, n); XtManageChild(text); XtRealizeWidget(toplevel); if (DtAppInitialize(appContext, XtDisplay(toplevel), toplevel, argv[0], ApplicationClass) == False) { printf("%s: Couldn't initialize Dt¥n", argv[0]); exit(1); } DtDbLoad(); DisplayTypeInfo(argc, argv); XtAppMainLoop(appContext); } static void DisplayTypeInfo(int argc, char **argv) { char *file; char *datatype; char *icon; char *actions; char str[100]; int i; sprintf(str, "%-30s¥t%-10s¥t%-8s¥t%-20s¥n", "File", "DataType", "Icon", "Actions"); XmTextInsert(text, XmTextGetLastPosition(text), str); sprintf(str, "%-30s¥t%-10s¥t%-8s¥t%-20s¥n", "-------------------", "--------", "----", "-------"); XmTextInsert(text, XmTextGetLastPosition(text), str); for(i=1; i < argc; i++) { char *file = argv[i]; /* find out the Dts data type */ datatype = DtDtsFileToDataType(file); if(datatype) { /* find the icon attribute for the data type */ icon = DtDtsDataTypeToAttributeValue(datatype, DtDTS_DA_ICON, file); } /* Directly find the action attribute for a file */ actions = DtDtsFileToAttributeValue(file, DtDTS_DA_ACTION_LIST); sprintf(str, "%-30s¥t%-10s¥t%-8s¥t%s¥n", file, datatype?datatype:"unknown", icon?icon:"unknown", actions?actions:"unknown"); XmTextInsert(text, XmTextGetLastPosition(text), str); /* Free the space allocated by Dts */ DtDtsFreeAttributeValue(icon); DtDtsFreeAttributeValue(actions); DtDtsFreeDataType(datatype); }
カレンダのアプリケーション・プログラム・インタフェース (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 を説明します。
カレンダ API を使用するには、libcsa ライブラリをリンクする必要があります。ヘッダ・ファイルは、csa/csa.h です。
カレンダ API の使用例を示すデモ・プログラムが、/usr/dt/examples/dtcalendar にあります。
カレンダ API は、ネットワーク環境でカレンダ・データにアクセスし、管理する方法を提供します。
CSA インタフェースは、カレンダおよびスケジュール・サービスへの共通インタフェースを可能にします。CSA 実装のそれぞれについて、CSA によって与えられる表示と機能は、基本のカレンダ・サービスの表示と機能にマップされなければなりません。インタフェースは、実際のカレンダおよびスケジュールの実装に依存しないように設計されています。また、インタフェースは、カレンダ・サービスが使用するオペレーティング・システムと基本のハードウェアに依存しないように設計されています。
提供される関数呼び出しの数は、最小限のものです。一組の関数で複数の種類のカレンダ項目を管理します。
表 10-1 に示すように、C インタフェースの要素の識別子は、要素の属性名とそれに関連するデータ型に由来します。属性名には、テーブルの 2 番目の欄の文字列が接頭辞として付けられます。英字は、3 番目の欄の大文字または小文字に変換されます。
表 10-1 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 では、拡張の使用によって実行される共通関数のプロトコル固有の拡張は許されています。詳細は、「拡張」を参照してください。カレンダが使用可能なアプリケーションとカレンダ・サービスの CSA インタフェースの関係を図 10-1 に示します。
CSA インタフェースのモデルは、管理、カレンダ管理、および項目管理という 3 つのコンポーネントに分けることができます。これらのコンポーネントを図 10-2 に示します。
カレンダ・サービスへのアクセスは、カレンダ・セッションを通して確立されます。セッションは、カレンダ・サービスへの有効な接続のために用意され、サービスによって保持されるカレンダ情報の整合性の確保を支援します。カレンダが使用可能なアプリケーションは、カレンダ・サービス内の個々のカレンダにログインして、有効なセッションまたは接続を確立します。セッションは、カレンダが使用可能なアプリケーションがカレンダからログアウトすることによって終了します。
カレンダ・サービスは、1 つ以上のカレンダを保持します。カレンダ・サービスは、これらのカレンダに対して、いくつかのレベルの管理サポートを提供します。カレンダが使用可能なアプリケーションは、特定のカレンダ・サービスによって保持されるカレンダのリストにアクセスできます。さらに、カレンダ・サービスにより、実装固有の永続的形式にカレンダ情報を保管したり復元したりできます。カレンダ・サービスが複数のカレンダの保持をサポートする場合には、カレンダの作成と削除のためのサポート関数が定義されます。また、カレンダの特性を管理するための関数が定義されます。
CSA インタフェースのほとんどの関数は、個々のカレンダ項目を管理します。カレンダ項目は、イベント、予定、またはメモです。項目は、特定のカレンダへの追加、削除、更新、および読み取りができます。カレンダが使用可能なアプリケーションは、カレンダ項目に通知方法を追加できます。
CSA インタフェースは、カレンダ・サービスによって保持されるカレンダ情報の概念上のバックエンドの記憶領域へのアクセス方法です。共通データ・モデルは、カレンダ・サービスによって保持されるカレンダ情報のコンポーネントを視覚化する際に役に立ちます。
データ・モデルは、カレンダ・エンティティの概念に基づきます。カレンダは、管理カレンダ属性とカレンダ項目の名前付きコレクションによって表されます。カレンダは、個々のユーザによって所有されます。ユーザは、個人、グループ、またはリソースを表します。
カレンダ属性は、カレンダに関する共通、実装固有、またはアプリケーション固有の管理特性を表す名前付きの値のセットです。たとえば、タイムゾーン、名前、所有者、およびカレンダへのアクセスの権利を、個々のカレンダ属性の中で指定できます。
カレンダ項目は、カレンダの主要なコンポーネントです。カレンダ項目の 3 つのクラスは、次のとおりです。
イベント
予定
メモ
カレンダ項目は、固有な名前を付けられた項目属性のコレクションによって表されます。項目属性は、カレンダ項目の共通、実装固有、またはアプリケーション固有の特性を表す名前付きの値のセットです。たとえばイベントには、開始と終了の日付と時間、説明、およびサブタイプを指定できます。予定には、作成日、期限、優先順位、およびステータスを指定できます。メモには、作成日とテキスト内容または説明を入れることができます。
カレンダ属性と項目属性は、名前、型、値の 3 つの組から成ります。仕様によって定義されている共通属性を拡張できます。実装によって、固有の属性を定義できます。また、アプリケーションでアプリケーション固有の属性を定義するための機能を提供するものもあります。共通デスクトップ環境では、アプリケーション定義の属性をサポートします。
個々のユーザがカレンダにアクセスできるかどうかは、そのユーザに与えられるアクセス権によって制御されます。アクセス権は、カレンダのユーザと対になっています。CSA では、ユーザは、個人、グループ、またはリソースです。共通デスクトップ環境では、個々のユーザだけをサポートします。アクセス権は、アクセス・リストで保持されます。アクセス・リストは、特定のカレンダ属性です。アクセス権は、個別に制御され、それを累積することによって、カレンダとその項目に対するユーザのアクセスの範囲を定義できます。アクセス権は、次のアクセスの役割の観点から指定できます。
カレンダの所有者
カレンダ内の特定の項目の主催者
カレンダ内の特定の項目のスポンサー
所有者の役割を与えられたユーザは、カレンダの所有者ができることであれば、カレンダまたはカレンダ項目に対して何でも実行できます。すなわち、カレンダの削除、カレンダ属性の表示、挿入、変更、カレンダ項目の追加と削除、項目属性の表示、挿入、および変更を実行できます。
主催者の役割を与えられたユーザは、そのユーザが主催者として指定されたカレンダ項目に対して、項目の削除、または項目属性の表示や変更を実行できます。デフォルトでは、項目を作成したカレンダ・ユーザが主催者です。
スポンサーの役割を与えられたユーザは、そのユーザがスポンサーとして指定されたカレンダ項目に対して、項目の削除、または項目属性の表示や変更を実行できます。スポンサーは、カレンダ項目を実質的に所有するカレンダ・ユーザです。
これらの役割に加えて、アクセス権の設定によって、公用、半私用、私用の分類に応じて、空き時間の検索へのアクセス、カレンダ属性の表示、挿入、変更、あるいは項目の表示、挿入、変更を制限できます。項目の分類は、アクセスできるかどうかの二次フィルタとして機能します。
CSA インタフェースは、主に 3 種類の作業をサポートします。
管理
カレンダ管理
エントリ管理
CSA 関数呼び出しの大部分は、カレンダ・セッションの中で発生します。カレンダ・セッションは、カレンダが使用可能なアプリケーションとカレンダ・サービスによって保持された特定のカレンダとの間の論理的な接続です。セッションは、csa_logon() 関数の呼び出しで確立され、csa_logoff() 関数の呼び出しで終了します。セッションの状況は、セッション・ハンドルによって表されます。このハンドルは、1 つのカレンダ・セッションを他のセッションと見分けるためのトークンを各 CSA 関数の中で提供します。csa_logon() 関数は、また、カレンダ・サービスに対してユーザを認証し、セッション属性を設定します。現時点では、アプリケーション間でのカレンダ・セッションの共有はサポートされていません。
csa_list_calendars() 関数は、特定のカレンダ・サービスによって管理されるカレンダ名をリストするために使用されます。
csa_query_configuration()関数は、現在のカレンダ・サービスの構成に関する情報をリストするために使用されます。この情報は、文字セット、テキスト文字列の行終了文字、デフォルトのサービス名、指定されたカレンダ・サービスのデフォルトの認証ユーザ識別子、ユーザ識別子を認証するためにパスワードが必要かどうかを示すインジケータ、ユーザ・インタフェース・ダイアログの共通拡張がサポートされるかどうかを示すインジケータ、および実装によってサポートされる CSA 仕様などです。
CSA の実装は、サービスによって返されるカレンダ・オブジェクトおよび属性のためのメモリの管理をサポートします。csa_free() 関数は、このメモリが不要になったときに、解放するために使用されます。カレンダ・サービスによって割り当てられ、管理されるメモリを解放するのは、アプリケーションの責任です。
CSA インタフェースは、いくつかのカレンダ管理関数を提供します。共通デスクトップ環境では、1 つのカレンダ・サービスにつき複数のカレンダをサポートします。カレンダが使用可能なアプリケーションは、カレンダを追加したり削除したりできます。csa_delete_calendar() 関数は、カレンダを削除するために使用されます。csa_add_calendar() 関数は、サービスに新しいカレンダを追加するために使用されます。
アプリケーションは、また、csa_list_calendar_attributes()、csa_read_calendar_attributes()、および csa_update_calendar_attributes() 関数を使用して、カレンダ属性のリスト、読み取り、および更新を実行できます。アプリケーションは、カレンダ・ログイン、カレンダの削除、カレンダ属性の更新、新しいカレンダ項目の追加、カレンダ項目の削除、およびカレンダ項目の更新について通知を受けるためのコールバック関数を登録できます。コールバック関数は、カレンダ・セッションの継続中だけ登録されます。この情報は、一部のカレンダ管理アプリケーションにとっては貴重なものです。
CSA インタフェースは、カレンダ項目を管理するための強力な関数のセットを備えています。カレンダ・セッション中のカレンダ項目の状況は、項目ハンドルによって保持されます。このハンドルは、1 つのカレンダ項目を他の項目と見分けるためのトークンを 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() 関数を使用すると、1 つ以上の属性の値を読み取ることができます。個々の項目属性は、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 が返されます。
CSA API の CDE 実装は、CDE カレンダ・サーバへのアクセスを可能にするライブラリです。ライブラリとサーバとの通信には、ONC の RPC が使用されます。CDE 実装におけるカレンダ・サーバは、カレンダ・プロトコル・バージョン 2 から 5、およびデータ・バージョン 3 と 4 をサポートするバージョン 5 です。カレンダ・プロトコルのバージョン 2 から 4 とデータ・バージョン 3 は、OpenWindows カレンダ・マネージャへの下位互換を確保するためのものです。カレンダ・プロトコル・バージョン 5 とデータ・バージョン 4 は CSA インタフェースとデータの拡張性をサポートします。
表 10-2 サポートされるサーバのバージョンとデータのバージョン
サーバのバージョン |
データのバージョン |
---|---|
2 |
1 |
3 |
2 |
4 |
3 |
5 |
3、4 |
2 つのアクセス・モデルがカレンダ API によってサポートされています。XAPIA CSA 仕様において指定されているアクセス・モデルは、データ・バージョン 4 のためだけにサポートされています。OpenWindows カレンダ・マネージャのアクセス・モデルは、データ・バージョン 1 から 3 までのためにサポートされています。OpenWindows のカレンダ・マネージャ・アクセス・モデルでは、カレンダのアクセス許可は、アクセス権を指定するアクセス・リストにより制御されます。次の 3 種類のアクセス権が定義されています。
CSA_X_DT_BROWSE_ACCESS (ユーザはカレンダのエントリをリストして、読み取ることができる)
CSA_X_DT_INSERT_ACCESS (ユーザはカレンダのエントリを挿入できる)
CSA_X_DT_DELETE_ACCESS (ユーザはカレンダのエントリを削除できる)
カレンダ API はすべてのバージョンのカレンダへのアクセスを可能にするので、プログラマは、データ・バージョンに対応する正しいアクセス・モデルを使用して、アクセス・リストに含まれるアクセス権を解釈しなければなりません。
カレンダが作成されるとき、アクセス・リストを指定しないかぎり、デフォルトのアクセス・リストにユーザ名として world という 1 つのエントリが含まれます。world のアクセス権では、公開エントリをブラウズできます。world というユーザ名は、すべてのユーザを意味する特別の名前です。
デフォルトでは、カレンダの所有者と同じユーザ名を持つユーザは、任意のマシンから、所有者のアクセス権でカレンダにアクセスできます。さらに厳しいアクセス制御をするには、owner-user-name@host という書式の名前をカレンダのアクセス・リストに追加できます。このようなエントリをアクセス・リストに追加するときは、対応するアクセス権は、データ・バージョン 4 では CSA_OWNER_RIGHTS
、データ・バージョン 3 では (CSA_X_DT_BROWSE_ACCESS|CSA_X_DT_INSERT_ACCESS|CSA_X_DT_DELETE_ACCESS
) です。このようなエントリをアクセス・リストに追加した後は、指定されたホストからのユーザだけが所有者のすべての権利でカレンダにアクセスできます。
表 10-3 に、CSA データ構造をリストします。詳細は、関連するマニュアル・ページを参照してください。
表 10-3 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 |
継続時間 |
表 10-4 に、共通デスクトップ環境でサポートされるカレンダ属性をリストします。詳細は、関連するマニュアル・ページを参照してください。カレンダ属性のリストは、拡張命名規則による拡張が可能です。
表 10-4 CSA カレンダ属性
属性名 |
記号名 |
サーバのバージョン |
データのバージョン |
読み取り専用 |
---|---|---|---|---|
Access List |
CSA_CAL_ATTR_ACCESS_LIST_ |
2-5 |
1-4 |
* |
Calendar Name |
CSA_CAL_ATTR_CALENDAR_NAME |
2-5 |
1-4 |
○ * |
Calendar Owner |
CSA_CAL_ATTR_CALENDAR_OWNER |
2-5 |
1-4 |
○ * |
Calendar Size |
CSA_CAL_ATTR_CALENDAR_SIZE |
5 |
3,4 |
○ |
Character Set |
CSA_CAL_ATTR_CHARACTER_SET |
5 |
4 |
○ |
Data Version** |
CSA_X_DT_CAL_ATTR_DATA_VERSION |
2-5 |
1-4 |
○ |
Date Created |
CSA_CAL_ATTR_DATE_CREATED |
5 |
4 |
○ |
Number Entries |
CSA_CAL_ATTR_NUMBER_ENTRIES |
2-5 |
1-4 |
○ |
Product Identifier |
CSA_CAL_ATTR_PRODUCT_IDENTIFIER |
2-5 |
1-4 |
○ |
Server Version** |
CSA_X_DT_CAL_ATTR_SERVER_VERSION |
2-5 |
1-4 |
○ |
Time Zone |
CSA_CAL_ATTR_TIME_ZONE |
5 |
4 |
○ |
Version |
CSA_CAL_ATTR_VERSION |
2-5 |
1-4 |
○ |
* カレンダ作成時に指定し、その後は読み取り専用になります。
** CDE のみ
次のカレンダ属性はサポートされません。
CSA_CAL_ATTR_COUNTRY CSA_CAL_ATTR_LANGUAGE CSA_CAL_ATTR_WORK_SCHEDULE
次の節では、表 10-4 にリストしたカレンダ属性について、追加の情報を提供します。
Access List
新しいカレンダが追加されるときにアクセス・リストが指定されなかった場合には、デフォルトのアクセス・リストには特殊ユーザ world が指定され、それに対応するアクセス権は CSA_VIEW_PUBLIC_ENTRIES になります。これは、公用のカレンダ・エントリのリストと読み取りのアクセス権を与えます。特殊ユーザ world には、すべてのユーザが含まれます。
Calendar Name
カレンダ名は、csa_add_calendar() によってカレンダが作成されるときに指定されます。読み取り専用であり、カレンダの作成後に変更できません。
Calendar Owner
カレンダ所有者は、csa_add_calendar() を呼び出してカレンダを作成するアプリケーションを実行しているユーザに設定されます。読み取り専用で、カレンダの作成後に変更できません。
Character Set
この値の読み取り設定には、CDE 共通ロケール名が使用されます。
CDE 定義済みカレンダ属性は、次のとおりです。
Server Version
この読み取り専用の属性は、カレンダを管理しているサーバのバージョン番号を示します。この属性は、CSA_VALUE_UINT32 型の属性です。
Data Version
この読み取り専用の属性は、カレンダのデータ・バージョンを示します。この属性は、CSA_VALUE_UINT32 型の属性です。
表 10-5 に、共通デスクトップ環境でサポートされる項目属性をリストします。詳細は、関連するマニュアル・ページを参照してください。項目属性のリストは、拡張命名規則による拡張が可能です。
表 10-5 CSA 項目属性
属性名 |
記号名 |
サーバのバージョン |
データのバージョン |
読み取り専用 |
---|---|---|---|---|
Audio Reminder |
CSA_ENTRY_ATTR_AUDIO_REMINDER |
2-5 |
1-4 |
* |
Character Set* |
CSA_X_DT_ENTRY_ATTR_CHARACTER _SET |
5 |
4 |
* |
Classification |
CSA_ENTRY_ATTR_CLASSIFICATION |
5 |
2-4 |
* |
Date Completed |
CSA_ENTRY_ATTR_DATE_COMPLETED |
5 |
4 |
* |
Date Created |
CSA_ENTRY_ATTR_DATE_CREATED |
5 |
4 |
○ |
Description |
CSA_ENTRY_ATTR_DESCRIPTION |
5 |
4 |
* |
Due Date |
CSA_ENTRY_ATTR_DUE_DATE |
5 |
4 |
* |
End Date |
CSA_ENTRY_ATTR_END_DATE |
2-5 |
1-4 |
* |
Exception Dates |
CSA_ENTRY_ATTR_EXCEPTION_DATES |
5 |
4 |
* |
Flashing Reminder |
CSA_ENTRY_ATTR_FLASHING_ REMINDER |
2-5 |
1-4 |
* |
Last Update |
CSA_ENTRY_ATTR_LAST_UPDATE |
5 |
4 |
○ |
Mail Reminder |
CSA_ENTRY_ATTR_MAIL_REMINDER |
2-5 |
1-4 |
* |
Number Recurrences |
CSA_ENTRY_ATTR_NUMBER_ RECURRENCES |
5 |
4 |
○ |
Organizer |
CSA_ENTRY_ATTR_ORGANIZER |
2-5 |
1-4 |
○ |
Popup Reminder |
CSA_ENTRY_ATTR_POPUP_REMINDER |
2-5 |
1-4 |
* |
Priority |
CSA_ENTRY_ATTR_PRIORITY |
5 |
4 |
* |
Recurrence Rule |
CSA_ENTRY_ATTR_RECURRENCE_RULE |
5 |
4 |
* |
Reference Identifier |
CSA_ENTRY_ATTR_REFERENCE_ IDENTIFIER |
2-5 |
1-4 |
○ |
Repeat Interval* |
CSA_X_ENTRY_ATTR_REPEAT_INTERVAL |
2-5 |
1-4 |
** |
Repeat Occurrence* |
CSA_X_ENTRY_ATTR_REPEAT_ OCCURRENCE_NUM |
2-5 |
1-4 |
** |
Repeat Times* |
CSA_X_ENTRY_ATTR_REPEAT_TIMES |
2-5 |
1-4 |
** |
Repeat Type* |
CSA_X_DT_ENTRY_ATTR_REPEAT_TYPE |
2-5 |
1-4 |
** |
Sequence End Date* |
CSA_X_ENTRY_ATTR_SEQUENCE_END_ DATE |
2-5 |
1-4 |
** |
Showtimes* |
CSA_X_ENTRY_ATTR_SHOWTIME |
2-5 |
1-4 |
* |
Sponsor |
CSA_ENTRY_ATTR_SPONSOR |
5 |
4 |
* |
Start Date |
CSA_ENTRY_ATTR_START_DATE |
2-5 |
1-4 |
* |
Status |
CSA_ENTRY_ATTR_STATUS |
2-5 |
1-4 |
* |
Subtype |
CSA_ENTRY_ATTR_SUBTYPE |
2-5 |
1-4 |
* |
Summary |
CSA_ENTRY_ATTR_SUMMARY |
2-5 |
1-4 |
* |
Transparency |
CSA_ENTRY_ATTR_TIME_ TRANSPARENCY |
5 |
4 |
* |
Type |
CSA_ENTRY_ATTR_TYPE |
2-5 |
1-4 |
○*** |
* CDE のみ
** データ・バージョン 1 から 3 については、この属性は指定または変更できます。ただし、データ・バージョン 4 については読み取り専用です。データ・バージョン 4 では、エントリ属性 CSA_ENTRY_ATTR_RECURRENCE_RULE から値が取られます。
***カレンダ作成時に指定し、その後は読み取り専用になります。
次のカレンダ属性はサポートされません。
CSA_ENTRY_ATTR_ATTENDEE_LIST CSA_ENTRY_ATTR_EXCEPTION_RULE CSA_ENTRY_ATTR_RECURRING_DATES CSA_ENTRY_ATTR_SEQUENCE_NUMBER
次の節では、表 10-5 にリストした項目属性について、追加の情報を提供します。
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 定義済み項目属性は、次のとおりです。
Show Time
この属性の値は、項目の開始時間と終了時間をユーザに対して表示するかどうかを示します。csa_update_entry_attributes() により変更できます。この属性は、CSA_VALUE_SINT32 型の属性です。
Repeat Type
項目の反復の頻度、すなわち、どれくらいの間隔で項目を繰り返すかを示します。
この属性は、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
この属性は、項目を繰り返す回数を示します。この属性は、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 の何倍で項目を繰り返すかを示します。たとえば、この属性の値が 3 であり、Repeat Type が CSA_X_DT_REPEAT_EVERY_NWEEK の場合には、項目は 3 週間ごとに繰り返されます。この属性は、CSA_VALUE_UINT32 型の属性です。
Repeat Occurrence Number
項目の Repeat Type が CSA_X_DT_REPEAT_MONTHLY_BY_WEEKDAY の場合、この属性は、項目を繰り返す週を示します。この属性は、CSA_VALUE_SINT32 型の属性です。
Sequence End Date
この項目属性は、シーケンスの終了日付を示します。この属性は、CSA_VALUE_DATE_TIME 型の属性です。
データ・バージョン 1 から 3 については、次の属性を使用してエントリの反復情報を指定します。すべて読み取りおよび書き込み属性です。
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
データ・バージョン 4 については、エントリ属性 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
これらの計算された属性は、データ・バージョン 4 に対して読み取り専用です。
CSA_ENTRY_ATTR_STATUS
データ・バージョン 1 はこの属性をサポートしません。
データ・バージョン 2 と 3 は次の値をサポートします。
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
データ・バージョン 4 はすべての状態値をサポートします。
CSA_STATUS_ACCEPTED CSA_STATUS_NEEDS_ACTION CSA_STATUS_SENT CSA_STATUS_TENTATIVE CSA_STATUS_CONFIRMED CSA_STATUS_REJECTED CSA_STATUS_COMPLETED CSA_STATUS_DELEGATED 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
CSA_ENTRY_ATTR_SUBTYPE
データ・バージョン 1 から 3 は次の値をサポートします。
CSA_SUBTYPE_APPOINTMENT CSA_SUBTYPE_HOLIDAY
データ・バージョン 4 はすべての定義値と、アプリケーションで定義する次のような値をサポートします。
CSA_SUBTYPE_APPOINTMENT CSA_SUBTYPE_CLASS CSA_SUBTYPE_HOLIDAY CSA_SUBTYPE_MEETING CSA_SUBTYPE_MISCELLANEOUS CSA_SUBTYPE_PHONE_CALL CSA_SUBTYPE_SICK_DAY CSA_SUBTYPE_SPECIAL_OCCASION CSA_SUBTYPE_TRAVEL CSA_SUBTYPE_VACATION
CSA_ENTRY_ATTR_TYPE
データ・バージョン 1 から 3 は次の値をサポートします。
CSA_TYPE_EVENT CSA_TYPE_TODO CSA_X_DT_TYPE_OTHER
データ・バージョン 4 は次のすべての定義値をサポートします。
CSA_TYPE_EVENT CSA_TYPE_TODO CSA_TYPE_MEMO CSA_X_DT_TYPE_OTHER
次に示すように、タイプとサブタイプの組み合わせによっては、データ・バージョン 1 から 3 でサポートします。
データ・バージョン 1 でサポートする組み合わせ
サブタイプ CSA_SUBTYPE_APPOINTMENT を持つ CSA_TYPE_EVENT サブタイプ値を持たない CSA_X_DT_TYPE_OTHER
データ・バージョン 2 と 3 でサポートする組み合わせ
サブタイプ CSA_SUBTYPE_APPOINTMENT を持つ CSA_TYPE_EVENT サブタイプ CSA_SUBTYPE_HOLIDAY を持つ CSA_TYPE_EVENT サブタイプ値を持たない CSA_TYPE_TODO サブタイプ値を持たない CSA_X_DT_TYPE_OTHER
CSA_X_ENTRY_ATTR_REPEAT_TYPE
データ・バージョン 1 から 3 については、この属性を使用してエントリの反復のタイプを指定します。
データ・バージョン 1 と 2 でサポートする値
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_DATE C SA_X_DT_REPEAT_YEARLY
データ・バージョン 3 でサポートする値
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 C SA_X_DT_REPEAT_OTHER
データ・バージョン 4 については、これは読み取り専用属性です。この値は、エントリ属性 CSA_ENTRY_ATTR_RECURRENCE_RULE から取られます。
次の一般的な情報は、すべての関数に適用されます。
文字セットの制限
カレンダ属性 CSA_CAL_ATTR_CHARACTER_SET は、カレンダのロケール情報を格納するために使用されます。
ライブラリの中で渡されるテキストでの説明以外のデータは、すべて ASCII 形式でなければなりませんが、ライブラリはシングルバイトだけでなくマルチバイト文字列もサポートします。
属性値の型チェックは、事前定義済み属性に対してだけ行われます。
項目属性 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 はサポートされていません。
Xt アプリケーション・コンテキスト (CSA_X_XT_APP_CONTEXT_EXT)
- Xt アプリケーション・コンテキストを指定する- csa_register_callback() により使用される- 入力
item_data: Xt アプリケーション・コンテキスト (XtAppContext)
- 出力なし
ユーザアクセス権の取得 (CSA_X_DT_GET_USER_ACCESS_EXT)
- カレンダに関するユーザのアクセス権を取得する
- csa_logon() により使用される
- 入力なし
- 出力
item_data: ユーザのアクセス権 (CSA_flags)
カレンダの文字セット属性の取得 (CSA_X_DT_GET_CAL_CHARSET_EXT)
- カレンダの文字セット属性を取得する
- csa_logon() により使用される
- 入力なし
- 出力
item_data: item_reference の文字列の長さ (CSA_uint32)
item_reference: 文字セット (CSA_string)
カレンダのサーバ・バージョンの取得 (CSA_X_DT_GET_SERVER_VERSION_EXT)
- カレンダのサーバ・バージョンを取得する
- csa_logon() と csa_list_calendars() により使用される
- 入力なし
- 出力
item_data: サーバ・バージョン (CSA_uint32)
カレンダのデータ・バージョンの取得 (CSA_X_DT_GET_DATA_VERSION_EXT)
- カレンダのデータ・バージョンを取得する
- csa_logon() により使用される
- 入力なし
- 出力
item_data: データ・バージョン (CSA_uint32)
この節では、CDE でサポートされる管理関数について説明します。関数のプロトタイプと戻りコードのリストは、各関数に含まれています。詳細は、関連するマニュアル・ページを参照してください。
解放 - カレンダ・サービスによって割り当てられたメモリを解放します。
プロトタイプ
CSA_return_code csa_free( CSA_buffer memory );
csa_free の戻り値
CSA_SUCCESS CSA_E_INVALID_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_list_calendars の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_NOT_SUPPORTED CSA_E_SERVICE_UNAVAILABLE
ログイン - カレンダ・サービスにログインして、カレンダとのセッションを確立します。
プロトタイプ
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 はカレンダが格納されているホスト名です。
csa_logon の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_CALENDAR_NOT_EXIST CSA_E_INSUFFICIENT_MEMORY CSA_E_NO_AUTHORITY CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE CSA_X_DT_E_BACKING_STORE_PROBLEM
ログアウト - カレンダとのセッションを終了します。
プロトタイプ
CSA_return_code csa_logoff( CSA_session_handle session, CSA-extension *logoff_extensions);
csa_logoff の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE
構成の問い合わせ - インストールされた 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 C SA_CONFIG_VER_IMPLEM
csa_query_configuration の戻り値
CSA_SUCCESS CSA_E_INVALID_ENUM CSA_E_INVALID_PARAMETER CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_UNSUPPORTED_ENUM CSA_E_UNSUPPORTED_FUNCTION_EXT
この節では、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_add_calendar の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_CALENDAR_EXISTS CSA_E_NO_AUTHORITY CSA_E_READONLY CSA_E_INVALID_ATTRIBUTE CSA_E_INVALID_ATTRIBUTE_VALUE CSA_E_UNSUPPORTED_ATTRIBUTE CSA_E_INVALID_DATE_TIME CSA_E_DISK_FULL CSA_X_DT_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
コールバックの呼び出し - 指定されたコールバック・リストに関連するコールバック関数を強制的に呼び出します。
プロトタイプ
CSA_return_code csa_call_callbacks( CSA_session_handle session, CSA_flags reason, CSA_extension *call_callbacks_extensions);
csa_call_callbacks の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INVALID_FLAG CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_X_DT_E_MT_UNSAFE
カレンダの削除 - カレンダ・サービスからカレンダを削除します。
プロトタイプ
CSA_return_code csa_delete_calendar( CSA_session_handle session, csa_extension *delete_calendar_extensions);
csa_delete_calendar の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_NOT_SUPPORTED CSA_E_NO_AUTHORITY CSA_X_DT_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
カレンダ属性のリスト - カレンダに関連するカレンダ属性名をリストします。
プロトタイプ
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_list_calendar_attributes の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_NOT_SUPPORTED CSA_E_NO_AUTHORITY CSA_X_DT_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
カレンダ属性の読み取り - カレンダのカレンダ属性値を読み取り、返します。
プロトタイプ
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_read_calendar_attributes の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
コールバック関数の登録 - カレンダの中で指定された種類の更新が行われるときに実行されるコールバック関数を登録します。
プロトタイプ
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_register_callbacks の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_INVALID_FLAG CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
コールバック関数の登録解除 - 指定されたコールバック関数の登録を解除します。
プロトタイプ
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_unregister_callback の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INVALID_SESSION_HANDLE CSA_E_INVALID_FLAG CSA_E_CALLBACK_NOT_REGISTERED CSA_E_FAILURE
カレンダ属性の更新 - カレンダのカレンダ属性値を更新します。
プロトタイプ
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);
csa_update_calendar_attributes の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_NO_AUTHORITY CSA_E_INVALID_ATTRIBUTE_VALUE CSA_E_INVALID_ATTRIBUTE CSA_E_UNSUPPORTED_ATTRIBUTE CSA_E_READONLY CSA_E_INVALID_DATE_TIME CSA_E_DISK_FULL CSA_X_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
この節では、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_add_entry の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_NO_AUTHORITY CSA_E_READONLY CSA_E_UNSUPPORTED_ATTRIBUTE CSA_E_INVALID_ATTRIBUTE CSA_E_INVALID_ATTRIBUTE_VALUE CSA_E_INVALID_DATE_TIME CSA_E_INVALID_RULE CSA_E_DISK_FULL CSA_X_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
エントリを追加するときに指定する最小限の属性セットは次のとおりです。
データ・バージョン 1 から 3 の場合
指定する必要があるもの
CSA_ENTRY_ATTR_START_DATE CSA_ENTRY_ATTR_TYPE
指定しないとデフォルトで設定されるもの
CSA_ENTRY_ATTR_CLASSIFICATION (CSA_CLASS_PUBLIC) CSA_ENTRY_ATTR_STATUS (CSA_X_DT_STATUS_ACTIVE) CSA_ENTRY_ATTR_SUBTYPE (CSA_SUBTYPE_APPOINTMENT for type CSA_TYPE_EVENT; this attribute is not supported for type CSA_TYPE_TODO) CSA_ENTRY_ATTR_SUMMARY (NULL string) CSA_X_ENTRY_ATTR_REPEAT_TYPE (CSA_X_REPEAT_ONETIME) CSA_X_ENTRY_ATTR_SHOWTIME (1 => true)
データ・バージョン 4 の場合
指定する必要があるもの
CSA_ENTRY_ATTR_START_DATE CSA_ENTRY_ATTR_TYPE
指定しないとデフォルトで設定されるもの
CSA_ENTRY_ATTR_CLASSIFICATION (CSA_CLASS_PUBLIC) CSA_ENTRY_ATTR_STATUS (CSA_X_STATUS_ACTIVE) CSA_ENTRY_ATTR_SUBTYPE (CSA_SUBTYPE_APPOINTMENT for type CSA_TYPE_EVENT) CSA_ENTRY_ATTR_SUMMARY (NULL string) CSA_X_ENTRY_ATTR_SHOWTIME (1 =>true)
項目の削除 - 指定されたカレンダから項目を削除します。
プロトタイプ
CSA_return_code csa_delete_entry( CSA_session_handle session, CSA_entry_handle entry, CSA_enum delete_scope, CSA_extension *delete_entry_extensions);
csa_delete_entry の戻り値
CSA_SUCCESS CSA_E_INVALID_ENUM CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_INVALID_ENTRY_HANDLE CSA_E_NO_AUTHORITY CSA_X_DT_E_ENTRY_NOT_FOUND CSA_E_DISK_FULL CSA_X_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
項目のリスト - 属性検索基準のすべてに一致するカレンダ項目をリストします。
プロトタイプ
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_list_entries の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_NO_AUTHORITY CSA_E_INVALID_ATTRIBUTE_VALUE CSA_E_INVALID_DATE_TIME CSA_E_INVALID_ENUM CSA_E_UNSUPPORTED_ENUM CSA_X_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
項目属性のリスト - 指定された項目に関連する項目の属性名をリストします。
プロトタイプ
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_list_entry_attributes の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_INVALID_ENTRY_HANDLE CSA_X_E_ENTRY_NOT_FOUND CSA_X_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
項目シーケンスのリスト - カレンダ項目に関連する再帰的カレンダ項目をリストします。
プロトタイプ
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_list_entry_sequence の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_INVALID_ENTRY_HANDLE CSA_E_INVALID_DATE_TIME CSA_X_E_ENTRY_NOT_FOUND CSA_X_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
項目属性の読み取り - 指定された項目のカレンダ項目属性値を読み取り、返します。
プロトタイプ
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_read_entry_attributes の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_INVALID_ENTRY_HANDLE CSA_X_E_ENTRY_NOT_FOUND CSA_X_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
次の通知方法の読み取り - 特定の時間を基準として、指定されたカレンダの中の特定の種類の次の通知方法を読み取ります。
プロトタイプ
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_reminder_reference **reminder_references, CSA_extension *read_next_reminder_extensions);
csa_read_next_reminder の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_INVALID_DATE_TIME CSA_E_NO_AUTHORITY CSA_X_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
項目属性の更新 - カレンダ項目属性を更新します。
プロトタイプ
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に設定してください。
csa_update_entry_attributes の戻り値
CSA_SUCCESS CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE CSA_E_INVALID_ENTRY_HANDLE CSA_E_NO_AUTHORITY CSA_E_READONLY CSA_E_INVALID_ENUM CSA_E_UNSUPPORTED_ATTRIBUTE CSA_E_INVALID_ATTRIBUTE CSA_E_INVALID_ATTRIBUTE_VALUE CSA_E_INVALID_DATE_TIME CSA_E_INVALID_RULE CSA_E_DISK_FULL CSA_X_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE CSA_E_SERVICE_UNAVAILABLE
サポートされない関数
次の関数は CDE でサポートされません。CSA_E_NOT_SUPPORTED
だけが返されます。
csa_add_event csa_add_memo csa_add_todo csa_free_time_search csa_look_up csa_restore csa_save
logoff() { CSA_return_code stat; /* セッションが必要ない場合は、csa_logoff を呼び出すことにより終了できます。 * 前の例で csa_logon により返されたセッションを終了します。 */ stat = csa_logoff(cal, NULL); } |
delete_calendar() { /* csa_logon() を呼び出すことによりカレンダ・セッションを確立後、 * csa_delete_calender() を使用してカレンダを削除できます。 */ CSA_return_code stat; stat = csa_delete_calendar(cal, NULL); } |