XrmQGetSearchList(3) データベースのリソースと検索リストを取得する

Other Alias

XrmGetResource, XrmQGetResource, XrmQGetSearchResource

書式

Bool XrmGetResource(database, str_name, str_class, str_type_return, value_return)

     XrmDatabase database;

     char *str_name;

     char *str_class;

     char **str_type_return;

     XrmValue *value_return

Bool XrmQGetResource(database, quark_name, quark_class, quark_type_return, value_return)

     XrmDatabase database;

     XrmNameList quark_name;

     XrmClassList quark_class;

     XrmRepresentation *quark_type_return;

     XrmValue *value_return

typedef XrmHashTable *XrmSearchList;

Bool XrmQGetSearchList(database, names, classes, list_return, list_length)

     XrmDatabase database;

     XrmNameList names;

     XrmClassList classes;

     XrmSearchList list_return;

     int list_length;

Bool XrmQGetSearchResource(list, name, class, type_return, value_return)

     XrmSearchList list;

     XrmName name;

     XrmClass class;

     XrmRepresentation *type_return;

     XrmValue *value_return;

引き数

class
リソースクラスを指定する。
classes
リソースクラスのリストを指定する。
database
使われるデータベースを指定する。
list
XrmQGetSearchList が返す検索リストを指定する。
list_length
list_return に対して割り当てられたエントリーの数(バイト数ではない)を 指定する。
list_return
後で使用するための検索リストが返される。
name
リソース名を指定する。
names
リソース名のリストが返される。
quark_class
取り出す値の完全に限定されたクラスを(クォークとして)指定する。
quark_name
取り出す値の完全に限定された名前を(クォークとして)指定する。
quark_type_return
対象の表現型が(クォークとして)返される。
str_class
取り出す値の完全に限定されたクラスを(文字列として)指定する。
str_name
取り出す値の完全に限定された名前を(文字列として)指定する。
str_type_return
対象の表現型が(文字列として)返される。
type_return
データの表現型が返される。
value_return
データベース内での値が返される。

説明

関数 XrmGetResourceXrmQGetResource は、指定したデータベースからリソースを取り出す。 どちらの関数も完全に限定された名前/クラスの組、目的のリソース表現、値 のアドレス(サイズ/アドレスの組)を引き数として取る。 値と返される型はデータベースのメモリを指す。 したがって、このデータを変更してはならない。

データベースは XrmPutResource, XrmQPutResource, XrmMergeDatabases のいずれかのエントリーの解放または上書きだけを行う。 新しい値をデータベースに格納しないクライアントやデータベースのマージ をしないクライアントは、返されたアドレスが存在する限り、これをいつ使っ ても安全である。 XrmGetResourceXrmQGetResource のどちらもリソースが見つかった場合には True を返す。 見つからなかった場合には False が返される。

関数 XrmQGetSearchList は、名前とクラスのリストを引き数に取り、マッチが起こったと思われるデータ ベースのレベルのリストを返す。 返されるリストは最善から最悪の順で並んでおり、順位を決定するアルゴリズ ムは XrmGetResource と同じである。 list_return が検索リストを格納できる十分な大きさならば、 XrmQGetSearchListTrue を返し、そうでなければ False を返す。

関数を呼び出した側が割り当てなければならない検索リストの大きさは、 データベースに格納されているリソース指定子が含むレベル数とワイルドカー ドの数によって決まる。 最悪の場合には、この大きさは %3 sup n% である。 ここで、 n は名前やクラスが含んでいる名前やクラスのコンポーネン トの数である。

XrmQGetSearchList を用い、その後に共通の名前とクラスのプレフィックスを使って複数回リソー スを検索する場合、 XrmQGetSearchList に渡す名前やクラスのリスト中では、共通のプレフィクスだけを指定すべきで ある。

関数 XrmQGetSearchResource は、指定した名前とクラスで完全に識別されているリソースに対して、指定し たデータベースのレベルを検索する。 検索は最初にマッチした時点で終了する。 XrmQGetSearchResource はリソースが見つかった場合には True を返し、 見つからなかった場合には False を返す。

リソース名の最後のコンポーネント以外の全てを含む名前とクラスのリストを 使って XrmQGetSearchList を呼び出し、続いて 最後のコンポーネントである名前とクラスを使って XrmQGetSearchResource を呼び出すと、完全に限定された名前とクラスを使って XrmGetResourceXrmQGetResource を呼び出した場合と同じデータベースのエントリーが返される。

マッチングの規則

与えられた問い合わせにマッチするリソースデータベースのエントリを決定す るアルゴリズムは、リソースマネージャの中心部分である。 どんな問い合わせの場合でも、必要なリソースの名前とクラスを完全に指定し なければならない(文字 ``*''と ``?'' の使用は許されない)。 Xlib では、コンポーネント内で完全な名前とクラスを 100 個まで使用できる。 リソースは、パターンマッチングの組み合わせを使用して、一部だけ指定された名前 とクラスでデータベースに格納される。 アスタリスク(*)は緩い結合であり、任意の数のコンポーネントが間に入るこ とを表現するために使われる。これは、間にコンポーネントが全く入らないこ とを含む。 ピリオド(.)は強い結合であり、隣接するコンポーネント同士を分割するため に使われる。 疑問符(?)は、任意の名前かクラス 1 つにマッチさせるために使われる。 データベースのエントリーは、緩い結合で終えることはできない。 最後のコンポーネント(``?'' であってはならない)は必ず指定しなければならない。 検索アルゴリズムは、問い合わせられた完全な名前とクラスに最も近くマッチ する(最も明確である)エントリーについてデータベースを検索する。 データベース内の複数のエントリーが完全な名前とクラスにマッチした場合は、 1 つだけを選ぶために優先順位の規則が用いられる。

完全な名前とクラスのコンポーネントは、左から右へ(最も高いレベルから低 いレベルへ)向かって、一度に 1 つずつ調べられる。 各レベルでは、対応するコンポーネントかマッチするそれぞれのエントリーの 結合あるいはその両方が決定され、マッチしたコンポーネントや結合は優先順 位の規則に基づいて比較される。 全ての中から 1 つのエントリーが規則によって決まるまで、次のレベルに移動 する前に、規則の各項目がそれぞれのレベルに適用される。 このルールを優先度の順に示す。

1.
マッチするコンポーネント(名前、クラス、``?'' 文字のいずれか)を含む エントリーは、そのレベルを省いたエントリー(つまり、緩い結合でその レベルにマッチしているもの)よりも優先順位が高い。
2.
名前がマッチしているエントリーは、クラスがマッチしているエントリーや文 字 ``?'' を使ってマッチしているエントリーより優先順位が高い。 クラスがマッチしているエントリーは、文字 ``?'' を使ってマッチしている エントリーより優先順位が高い。
3.
強い結合の後にあるエントリーは、緩い結合の後にあるエントリー よりも優先順位が高い。