第 3 章 サービスプロバイダ層の API
この章では、パブリックモジュールによってエクスポートされ、フレームワーク構成層によって使用される API 関数をリストし、説明します。関数は目的によってセクションに分類されています。各セクション内では、関数は使用が予想される順にリストされています。
この章は、次の節から構成されています。
特定バージョンのサービスプロバイダ層の API に基づくすべての実装は、実装する API 関数についてのこの仕様に準拠しなければなりません。後のバージョンの API は、前のバージョンの API との後方互換性がなければなりません。したがって、新たに API 呼び出しを追加することはできますが、既存のものを変更したり、削除してはなりません。
関数についての詳細は、インクルードファイル /usr/include/dhcp_svc_public.h を参照してください。
一般的なデータ格納関数
この節では、一般的なデータ格納活動に関する関数について説明します。
configure()
目的
構成文字列をデータ格納に渡します。
形式
int configure(const char *configp);
説明
configure() 関数はオプション (省略可能) です。必要とされるパブリックモジュール管理ビーンとともにこの関数が提供されている場合 (データサービス構成ツールと DHCP 管理ツールを参照)、フレームワーク構成層は、パブリックモジュールのロード時にこの関数を呼び出し、パブリックモジュール固有の構成文字列内に渡します。この文字列は、データ格納モジュールのために DHCP サーバー上のフレームワーク構成層によってキャッシュされます。
戻り値
DSVC_SUCCESS, DSVC_MODULE_CFG_ERR
configure() 関数は、モジュールがモジュールのロードをフレームワーク構成層に続けてもらいたければ DSVC_SUCCESS を返し、モジュールのロードを行なってもらいたくなければ DSVC_MODULE_CFG_ERR を返します。後者の例は、構成文字列の形式が適切でないためにモジュールの必要な構成を行えないような場合です。
mklocation()
目的
データ格納コンテナを置くディレクトリを作成します。
形式
int mklocation(const char *location);
説明
データ格納コンテナを置く場所として、location で指定されたディレクトリを作成します (ディレクトリが存在しない場合)。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_EXISTS, DSVC_BUSY, DSVC_INTERNAL, DSVC_UNSUPPORTED
status()
目的
データ格納の一般的な状態を取得します。
形式
int status(const char *location);
説明
status() 関数は、データ格納に対してその一般的な状態を返すよう指示します。もし location が NULL でなければ、そのコンテナが実際に存在し、アクセス可能であり、かつ形式がそのデータ格納タイプにとって正しいかどうかを判定することによって、データ格納コンテナのロケーションを検証します。データ格納は、必要な機能が利用できなかったり、準備されていない場合には、適切なエラーコードを返す必要があります。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL
version()
目的
データ格納によって実装される API のバージョン番号を取得します。
形式
int version(int *versionp);
説明
このマニュアルに記載されているサービスプロバイダ層 API をサポートするデータ格納はバージョン 1 です。バージョンは、int 内で versionp で示して返されます。
戻り値
DSVC_SUCCESS, DSVC_INTERNAL, DSVC_MODULE_ERR
dhcptab 関数
この節に記載される API 関数は、dhcptab コンテナとともに使用されます。
list_dt()
目的
dhcptab コンテナの名前をリストします。
形式
int list_dt(const char *location, char ***listppp, uint_t *count);
説明
location で見つかった dhcptab コンテナオブジェクトの動的に割り当てたリストを生成し (listppp) 、リストの項目数を count 内に格納します。dhcptab コンテナオブジェクトが全く存在しない場合は、DSVC_SUCCESS が返され、listppp は NULL に設定され、count は 0 に設定されます。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_NO_LOCATION
open_dt()
目的
dhcptab コンテナをオープンするか、または新たに作成します。
形式
int open_dt(void **handpp, const char *location, uint_t flags);
説明
既存の dhcptab コンテナをオープンするか、または新しいコンテナを location に作成し、そのインスタンスハンドルを指すように handpp を初期設定します。データ格納にとって必要な初期設定があれば、それを行います。新しい dhcptab を作成する場合には、所有者/アクセス権に呼び出し元の ID が使用されます。有効なフラグには、DSVC_CREATE、DSVC_READ、DSVC_WRITE、DSVC_NONBLOCK があります。dhcptab コンテナの読み取り専用 (DSVC_CREATE | DSVC_READ) としての作成は無効であることに注意してください。
戻り値
DSVC_SUCCESS, DSVC_EXISTS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL
lookup_dt()
目的
dhcptab コンテナ内のレコードに対するクエリー検索を行います。
形式
int lookup_dt(void *handp, boolean_t partial, uint_t query, int count, const dt_rec_t *targetp, dt_rec_list_t **resultp, uint_t *records);
説明
query と targetp の組み合わせで指定されたクエリーにマッチするインスタンスを dhcptab コンテナから検索します。partial 引数が B_TRUE の場合は、呼び出し元にとって部分的なクエリー結果も適用可能であることを意味します。したがって、partial が B_TRUE の場合は、マッチするレコードが 1 つでもあれば、クエリーは有効と見なされます。partial が B_FALSE の場合は、クエリーがコンテナ全体に適用された場合だけ、DSVC_SUCCESS が返されます。
query 引数は、長さがそれぞれ 16 ビットの 2 つのフィールドからなります。下位 16 ビットでは、targetp のどのフィールド {key, type} をクエリーの対象とするかを選択します。上位 16 ビットでは、下位 16 ビットで選択された特定のフィールド値がマッチするものを検索するのか (ビットセット)、マッチしないものを検索するのか (ビットクリア) を指定します。両方の 16 ビットフィールドとも、ビット 2 から 15 は現在のところ使用されておらず、0 に設定されていなければなりません。クエリーを構築するために有用なマクロを例 3–1 に示します。
count フィールドは、マッチするレコードを最大でいくつ返すかを指定します。count 値に -1 を指定すると、マッチするレコードがいくつあっても、すべて返すことを要求します。count 値に 0 を指定すると、lookup_dt はデータ無しでただちに返されます。
resultp は、返されるレコードのリストを指すよう設定されます。resultp に NULL が指定される場合、呼び出し元は単にクエリーにマッチするレコードがいくつあるかに関心があるということになります。これらのレコードは動的に割り当てられるため、呼び出し元でこれを解放する必要があることに注意してください。lookup_dt() は、records 引数内にマッチするレコードの数を返します。records の値 0 は、クエリーにマッチするレコードは全く無いことを示します。
次の例には、DHCP ネットワークおよび dhcptab のコンテナに対するクエリー検索の構築や操作に有用なマクロが含まれています。
例 3–1 クエリー検索に有用なマクロ
/* * Query macros - used for initializing query fields (lookup_d?) */ /* dhcp network container */ #define DN_QCID 0x0001 #define DN_QCIP 0x0002 #define DN_QSIP 0x0004 #define DN_QLEASE 0x0008 #define DN_QMACRO 0x0010 #define DN_QFDYNAMIC 0x0020 #define DN_QFAUTOMATIC 0x0040 #define DN_QFMANUAL 0x0080 #define DN_QFUNUSABLE 0x0100 #define DN_QFBOOTP_ONLY 0x0200 #define DN_QALL (DN_QCID | DN_QCIP | DN_QSIP | DN_QLEASE | \ DN_QMACRO | DN_QFDYNAMIC DN_QFAUTOMATIC |\ DN_QFMANUAL | DN_QFUNUSABLE | \ DN_QFBOOTP_ONLY) /* dhcptab */ #define DT_DHCPTAB "dhcptab" /* default name of container */ #define DT_QKEY 0x01 #define DT_QTYPE 0x02 #define DT_QALL (DT_QKEY | DT_QTYPE) /* general query macros */ #define DSVC_QINIT(q) ((q) = 0) #define DSVC_QEQ(q, v) ((q) = ((q) | (v) | ((v) << 16))) #define DSVC_QNEQ(q, v) ((q) = ((~(v << 16)) & (q)) | (v))) #define DSVC_QISEQ(q, v) (((q) & (v)) && ((q) & ((v) << 16))) #define DSVC_QISNEQ(q, v) (((q) & (v)) && (!((q) & ((v) << 16)))) /* Examples */ uint_t query; /* search for dhcptab record with key value, but not flags value */ DSVC_QINIT(query); DSVC_QEQ(query, DT_QKEY); DSVC_QNEQ(query, DT_QTYPE); /* search for dhcp network record that matches cid, client ip, server ip. */ DSVC_QINIT(query); DSVC_QEQ(query, (DN_QCID | DN_QCIP | DN_QSIP));
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL
add_dt()
目的
dhcptab コンテナにレコードを追加します。
形式
int add_dt(void *handp, dt_rec_t *newp);
説明
handp で参照される dhcptab コンテナにレコード newp を追加します。newp に対応するシグニチャは、基盤となるパブリックモジュールによって更新されます。更新における衝突が発生する場合には、データ格納は更新されません。動的に割り当てられた引数は、呼び出し元で解放する必要があります。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL, DSVC_EXISTS
modify_dt()
目的
dhcptab コンテナ内のレコードを変更します。
形式
int modify_dt(void *handp, const dt_rec_t *origp, dt_rec_t *newp);
説明
handp で参照される dhcptab コンテナ内のレコード origp をレコード newp に変更します。newp に対応するシグニチャは、基盤となるパブリックモジュールによって更新されます。更新における衝突が発生する場合には、データ格納は更新されません。動的に割り当てられた引数は、呼び出し元で解放する必要があります。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_COLLISION, DSVC_INTERNAL, DSVC_NOENT
delete_dt()
目的
dhcptab コンテナからレコードを削除します。
形式
int delete_dt(void *handp, const dt_rec_t *dtp);
説明
ハンドル handp で参照される dhcptab コンテナから、dtp の key、type、dt_sig フィールドで指定されるレコードを削除します。更新における衝突が発生する場合には、マッチするレコードはデータ格納から削除されず、DSVC_COLLISION が返されます。動的に割り当てられた引数は、呼び出し元で解放する必要があります。
dtp シグニチャ (dt_sig) に 0 を指定すると、更新における衝突があるかどうかの検知は行なわれず、マッチするレコードが単純に削除されます。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_BUSY, DSVC_INTERNAL, DSVC_COLLISION
close_dt()
目的
dhcptab コンテナをクローズします。
形式
int close_dt(void **handpp);
説明
インスタンスハンドルを解放し、インスタンスごとの状態を消去します。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_INTERNAL
remove_dt()
目的
データ格納のロケーションから dhcptab コンテナを削除します。
形式
int remove_dt(const char *location);
説明
データ格納から location 内の dhcptab コンテナを削除します。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL
DHCP ネットワークコンテナ関数
この節で説明する API 関数は、DHCP ネットワークコンテナやその中の IP アドレスレコードを処理するときに使用します。
list_dn()
目的
ネットワークコンテナのリストを返します。
形式
int list_dn(const char *location, char ***listppp, uint_t *count);
説明
location 内で見つかったネットワークコンテナオブジェクトの動的に割り当てられたリストを生成し (listppp) 、リストの項目数を count 内に格納します。ネットワークコンテナオブジェクトが全く存在しない場合は、DSVC_SUCCESS が返され、listppp は NULL に設定され、count は 0 に設定されます。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_NO_LOCATION
open_dn()
目的
ネットワークコンテナをオープンするか、または新たに作成します。
形式
int open_dn(void **handpp, const char *location, uint_t flags, const struct in_addr *netp, const struct in_addr *maskp);
説明
既存の DHCP ネットワークコンテナをオープンするか、または netp および maskp (両方ともホスト順) で指定された新しいコンテナを location 内に作成し、そのインスタンスハンドルを指すように handpp を初期設定します。データ格納にとって必要な初期設定があれば、それを行います。新しい DHCP ネットワークコンテナを作成する場合には、所有者/アクセス権に呼び出し元の ID が使用されます。有効なフラグには、DSVC_CREATE、DSVC_READ、DSVC_WRITE、DSVC_NONBLOCK が含まれます。DHCP ネットワークコンテナの読み取り専用 (DSVC_CREATE | DSVC_READ) としての作成は無効であることに注意してください。
戻り値
DSVC_SUCCESS, DSVC_EXISTS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL, DSVC_UNSUPPORTED
lookup_dn()
目的
DHCP ネットワークコンテナ内のレコードに対するクエリー検索を行います。
形式
int lookup_dn(void *handp, boolean_t partial, uint_t query, int count, const dn_rec_t *targetp, dn_rec_list_t **resultp, uint_t *records);
説明
query と targetp の組み合わせで指定されたクエリーにマッチするインスタンスを DHCP ネットワークコンテナから検索します。partial 引数が B_TRUE の場合は、呼び出し元にとって部分的なクエリー結果も適用可能であることを意味します。したがって、partial が B_TRUE の場合は、マッチするレコードが 1 つでもあれば、クエリーは有効と見なされます。partial が B_FALSE の場合は、クエリーがコンテナ全体に適用された場合だけ DSVC_SUCCESS が返されます。
クエリー引数は、長さがそれぞれ 16 ビットの 2 つのフィールドからなります。下位 16 ビットでは、targetp のどのフィールド {クライアント id、フラグ、クライアント IP、サーバー IP、有効期限、マクロ、またはコメント} をクエリーの対象とするかを選択します。上位 16 ビットでは、下位 16 ビットで選択された特定のフィールド値がマッチするものを検索するのか (ビットセット)、マッチしないものを検索するのか (ビットクリア) を指定します。両方の 16 ビットフィールドとも、ビット 7 から 15 は現在のところ使用されておらず、0 に設定されていなければなりません。クエリーを構築するために有用なマクロを例 3–1 に示します。
count フィールドは、マッチするレコードを最大でいくつ返すかを指定します。count 値に -1 を指定すると、マッチするレコードがいくつあっても、すべて返すことを要求します。count 値に 0 を指定すると、lookup_dn データ無しでただちに返されます。
resultp は、返されるレコードのリストを指すよう設定されます。resultp に NULL が指定される場合、呼び出し元は単にクエリーにマッチするレコードがいくつあるかに関心があるということになります。これらのレコードは動的に割り当てられるため、呼び出し元でこれを解放する必要があることに注意してください。lookup_dn() は、records 引数内にマッチするレコードの数を返します。records の値 0 は、クエリーにマッチするレコードは全く無いことを示します。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL
add_dn()
目的
DHCP ネットワークコンテナにレコードを追加します。
形式
int add_dn(void *handp, dn_rec_t *newp);
説明
ハンドル handp で参照される DHCP ネットワークコンテナにレコード newp を追加します。newp に対応するシグニチャは、基盤となるパブリックモジュールによって更新されます。更新における衝突が発生する場合は、データ格納は更新されません。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL, DSVC_EXISTS
modify_dn()
目的
DHCP ネットワークコンテナ内のレコードを変更します。
形式
int modify_dn(void *handp, const dn_rec_t *origp, dn_rec_t *newp);
説明
ハンドル handp で参照される DHCP ネットワークコンテナ内のレコード origp をレコード newp に変更します。newp に対応するシグニチャは、基盤となるパブリックモジュールによって更新されます。更新における衝突が発生する場合には、データ格納は更新されません。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_COLLISION, DSVC_INTERNAL, DSVC_NOENT
delete_dn()
目的
DHCP ネットワークコンテナからレコードを削除します。
形式
int delete_dn(void *handp, const dn_rec_t *pnp);
説明
ハンドル handp で参照される DHCP ネットワークコンテナから、pnp の dn_cip および dn_sig 要素で指定されるレコードを削除します。更新における衝突が発生する場合には、マッチするレコードはデータ格納から削除されず、DSVC_COLLISION が返されます。
pnp の dn_sig シグニチャに 0 を指定すると、更新における衝突があるかどうかの検知は行なわず、マッチするレコードが単純に削除されます。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_BUSY, DSVC_INTERNAL, DSVC_COLLISION
close_dn()
目的
ネットワークコンテナをクローズします。
形式
int close_dn(void **handpp);
説明
インスタンスハンドルを解放し、インスタンスごとの状態を消去します。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_INTERNAL.
remove_dn()
目的
データ格納のロケーションから DHCP ネットワークコンテナを削除します。
形式
int remove_dn(const char *location, const struct in_addr *netp);
説明
location 内の DHCP ネットワークコンテナ netp (ホスト順) を削除します。
戻り値
DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL
一般的なエラーコード
フレームワーク構成層とサービスプロバイダ層の API 関数は、エラーとして次の整数値を返します。ファイル /usr/include/dhcp_svc_public.h は、これらのコードの完全なソースとなります。
* Standard interface errors
*/
#define DSVC_SUCCESS 0 /* success */
#define DSVC_EXISTS 1 /* object already exists */
#define DSVC_ACCESS 2 /* access denied */
#define DSVC_NO_CRED 3 /* No underlying credential */
#define DSVC_NOENT 4 /* object doesn't exist */
#define DSVC_BUSY 5 /* object temporarily busy (again) */
#define DSVC_INVAL 6 /* invalid argument(s) */
#define DSVC_INTERNAL 7 /* internal data store error */
#define DSVC_UNAVAILABLE 8 /* underlying service required by */
/* public module unavailable */
#define DSVC_COLLISION 9 /* update collision */
#define DSVC_UNSUPPORTED 10 /* operation not supported */
#define DSVC_NO_MEMORY 11 /* operation ran out of memory */
#define DSVC_NO_RESOURCES 12 /* non-memory resources unavailable */
#define DSVC_BAD_RESOURCE 13 /* malformed/missing RESOURCE setting */
#define DSVC_BAD_PATH 14 /* malformed/missing PATH setting */
#define DSVC_MODULE_VERSION 15 /* public module version mismatch */
#define DSVC_MODULE_ERR 16 /* internal public module error */
#define DSVC_MODULE_LOAD_ERR 17 /* error loading public module */
#define DSVC_MODULE_UNLOAD_ERR 18 /* error unloading public module */
#define DSVC_MODULE_CFG_ERR 19 /* module configuration failure */
#define DSVC_SYNCH_ERR 20 /* error in synchronization protocol */
#define DSVC_NO_LOCKMGR 21 /* cannot contact lock manager */
#define DSVC_NO_LOCATION 22 /* location nonexistent */
#define DSVC_BAD_CONVER 23 /* malformed/missing CONVER setting */
#define DSVC_NO_TABLE 24 /* table does not exist */
#define DSVC_TABLE_EXISTS 25 /* table already exists */
#define DSVC_NERR (DSVC_TABLE_EXISTS + 1)
- © 2010, Oracle Corporation and/or its affiliates