8 C APIリファレンス
次の各トピックでは、Oracle Internet DirectoryのC APIについて説明し、そのAPIの使用例を示します。
8.1 Oracle Internet DirectoryのC APIの概要
Oracle Internet Directory SDK C APIは、LDAPバージョン3 C API、およびSSLをサポートするOracleの拡張機能をベースにしています。
次の各トピックでは、Oracle Internet DirectoryのC APIについて説明します。
8.1.1 Oracle Internet Directoryのモードの理解
Oracle Internet Directory APIは、SSLモードと非SSLモードで使用できます。
次のモードについて説明します。
-
SSL—SSLを使用してすべての通信を保護します。
-
非SSL—クライアント/サーバー間の通信を保護しません。
APIは、TCP/IPを使用してディレクトリ・サーバーに接続します。接続するとき、デフォルトでは暗号化されていないチャネルを使用します。SSLモードを使用するには、Oracle SSLコール・インタフェースを使用する必要があります。APIを使用する際に、SSLコールの有無によってどちらのモードを使用するかを決定します。SSLモードと非SSLモードは簡単に切り替えることができます。
関連項目:
2つのモードの使用方法については、「C APIの使用例」を参照してください。
8.1.2 Oracle Internet Directory SDK C API SSL拡張機能の理解
LDAP APIへのOracle SSL拡張機能は、標準的なSSLプロトコルに基づいています。SSL拡張機能は回線を通るデータの暗号化と復号化および認証を行います。
認証には次の3つのモードがあります。
-
認証なし—クライアントとサーバーのどちらも認証せず、SSLによる暗号化のみを使用します。
-
一方向—クライアントによりサーバーのみが認証されます。
-
双方向—サーバーとクライアントが相互に認証します。
認証のタイプは、SSLインタフェース・コールのパラメータで指定します。次の各項で、これを簡単に説明します。
8.1.2.1 SSLを使用可能にするインタフェース・コール
次のコールを行うのみで、SSLは使用可能になります。
int ldap_init_SSL(Sockbuf *sb, char *sslwallet, char *sslwalletpasswd, int sslauthmode)
ldap_init_SSL
コールは、標準的なSSLプロトコルを使用して、クライアントとサーバーの間で必要なハンドシェイクを実行します。コールが成功すると、これ以降のすべての通信は保護された接続で実行されます。
表8-1 SSLインタフェース・コールの引数
引数 | 説明 |
---|---|
sb |
LDAPハンドルの一部として、 |
sslwallet |
ユーザー・ウォレットの位置。 |
sslwalletpasswd |
ウォレットを使用するために必要なパスワード。 |
sslauthmode |
ユーザーが使用できるSSL認証モード。使用できる値は次のとおりです。
|
関連項目:
8.2 C APIのファンクションの概要
C APIのファンクションでは、多くのプロシージャを使用して、ディレクトリで様々な操作を実行します。
表8-2に、C APIのファンクションおよびプロシージャをすべて示し、その用途を簡単に説明します。
表8-2 C APIのファンクションおよびプロシージャ
ファンクションまたはプロシージャ | 説明 |
---|---|
ber_free |
BerElement構造体のために割り当てられたメモリーの解放 |
ldap_abandon_ext ldap_abandon |
非同期操作の取消し |
ldap_add_ext ldap_add_ext_s ldap_add ldap_add_s |
ディレクトリに新規エントリを追加 |
ldap_compare_ext ldap_compare_ext_s ldap_compare ldap_compare_s |
ディレクトリ内のエントリの比較 |
ldap_count_entries |
一連の検索結果のエントリ件数をカウント |
ldap_count_values |
属性の文字列値をカウント |
ldap_count_values_len |
属性のバイナリ値をカウント |
ora_ldap_create_clientctx |
クライアントのコンテキストの作成およびハンドルを戻す。 |
ora_ldap_create_cred_hdl |
資格証明ハンドルの作成 |
ldap_delete_ext ldap_delete_ext_s ldap_delete ldap_delete_s |
ディレクトリからのエントリの削除 |
ora_ldap_destroy_clientctx |
クライアントのコンテキストの破棄 |
ora_ldap_free_cred_hdl |
資格証明ハンドルの破棄 |
ldap_dn2ufn |
ユーザーにわかりやすい名前に変換 |
ldap_err2string |
特定のエラー・コードのエラー・メッセージを取得 |
ldap_explode_dn |
識別名を構成要素に分割 |
ldap_explode_rdn |
|
ldap_first_attribute |
エントリ内の最初の属性の名前を取得 |
ldap_first_entry |
一連の検索結果から最初のエントリを取得 |
ora_ldap_get_cred_props |
資格証明ハンドルに関連付けられたプロパティの取得 |
ldap_get_dn |
エントリの識別名の取得 |
ldap_get_option |
セッション全体の様々なパラメータの現在の値にアクセス |
ldap_get_values |
属性の文字列値を取得 |
ldap_get_values_len |
属性のバイナリ値を取得 |
ldap_init ldap_open |
LDAPサーバーへの接続のオープン |
ora_ldap_init_SASL |
SASL認証の実行 |
ldap_memfree |
LDAP APIファンクション・コールによって割り当てられたメモリーの解放 |
ldap_modify_ext ldap_modify_ext_s ldap_modify ldap_modify_s |
ディレクトリ内のエントリの変更 |
ldap_msgfree |
検索結果あるいは他のLDAP操作結果のために割り当てられたメモリーの解放 |
ldap_first_attribute ldap_next_attribute |
エントリ内の次の属性の名前を取得 |
ldap_next_entry |
一連の検索結果から次のエントリを取得 |
ldap_perror (非推奨) |
エラー・メッセージの中から指定したメッセージを出力 |
ldap_rename ldap_rename_s |
ディレクトリ内のエントリの相対識別名を変更 |
ldap_result2error (非推奨) |
結果メッセージからエラー・コードを取得 |
ldap_result ldap_msgfree ldap_msgtype ldap_msgid |
非同期操作の結果のチェック |
ldap_sasl_bind ldap_sasl_bind_s |
LDAPサーバーへの一般認証 |
ldap_search_ext ldap_search_ext_s ldap_search ldap_search_s |
ディレクトリの検索 |
ldap_search_st |
タイムアウト値でのディレクトリの検索 |
ldap_get_option ldap_set_option |
パラメータの値を設定 |
ldap_set_rebind_proc |
参照を追跡する際、新しいサーバーへのバインド資格証明の取得に使用されるコールバック・ファンクションの設定。 |
ora_ldap_set_clientctx |
クライアントのコンテキスト・ハンドルへのプロパティの追加 |
ora_ldap_set_cred_props |
資格証明ハンドルへのプロパティの追加 |
ldap_simple_bind ldap_simple_bind_s ldap_sasl_bind ldap_sasl_bind_s |
LDAPサーバーへの簡易認証 |
ldap_unbind_ext ldap_unbind ldap_unbind_s |
LDAPセッションの終了 |
ldap_value_free |
属性の文字列値のために割り当てられたメモリーの解放 |
ldap_value_free ldap_value_free_len |
属性のバイナリ値のために割り当てられたメモリーの解放 |
この項では、RFC 1823に規定されているLDAP C APIで使用可能なすべてのコールを示します。
8.3 C APIの使用例
最初の3つの例では、SSLと組み合せてC APIを使用する方法、SSLを使用せずにC APIを使用する方法およびSASL認証にC APIを使用する方法を示します。より完全な例は、RFC 1823を参照してください。また、LDAP検索を実行するコマンドライン・ツールのサンプル・コードも、SSLモードおよび非SSLモードでのAPIの使用方法を示します。
次の各トピックでは、C APIの使用方法について説明します。
8.3.1 SSLを使用するC APIの使用方法
ユーザーがldap_init_SSL
をコールすると、クライアントとサーバーの通信は、SSLを使用して保護されます。
次のコードは、SSLを使用するC APIの使用方法を説明しています。
#include <stdio.h> #include <ldap.h> main() {
LDAP *ld; int ret = 0; …. /* open a connection */ if ((ld = ldap_open("MyHost", 3131)) == NULL) exit( 1 ); /* SSL initialization */ ret = ldap_init_SSL(&ld->ld_sb, "file:/sslwallet", "welcome", GSLC_SSL_ONEWAY_AUTH ); if(ret != 0) {
printf(" %s \n", ldap_err2string(ret)); exit(1);
} /* authenticate as nobody */ if ( ldap_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_bind_s" ); exit( 1 ); }
. . .
}
8.3.2 SSLを使用しないC APIの使用方法
ユーザーがldap_init_SSL
をコールしない場合、クライアント/サーバー間の通信は保護されません。
次のコードは、SSLを使用しないC APIの使用方法を説明しています。
#include <stdio.h> #include <ldap.h> main() {
LDAP *ld; int ret = 0; . . . /* open a connection */ if ( (ld = ldap_open( "MyHost", LDAP_PORT )) == NULL ) exit( 1 ); /* authenticate as nobody */ if ( ldap_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_bind_s" ); exit( 1 ); } . . .
}
8.3.3 SASLベースのDigest-MD5認証でのC APIの使用方法
ディレクトリ・サーバーに対するSASLベースのDigest-MD5認証では、LDAP SASL C-APIが使用されます。
このサンプル・プログラムは、LDAP SASL C-APIの使用方法を示しています。
/* EXPORT FUNCTION(S) NONE INTERNAL FUNCTION(S) NONE STATIC FUNCTION(S) NONE NOTES Usage: saslbind -h ldap_host -p ldap_port -D authentication_identity_dn \ -w password options -h LDAP host -p LDAP port -D DN of the identity for authentication -p Password Default SASL authentication parameters used by the demo program SASL Security Property : Currently only "auth" security property is supported by the C-API. This demo program uses this security property. SASL Mechanism : Supported mechanisms by OID "DIGEST-MD5" - This demo program illustrates it's usage. "EXTERNAL" - SSL authentication is used. (This demo program does not illustrate it's usage.) Authorization identity : This demo program does not use any authorization identity. MODIFIED (MM/DD/YY) ****** 06/12/03 - Creation */ /*--------------------------------------------------------------------------- PRIVATE TYPES AND CONSTANTS ---------------------------------------------------------------------------*/ /*--------------------------------------------------------------------------- STATIC FUNCTION DECLARATIONS ---------------------------------------------------------------------------*/ #include <stdio.h> #include <stdlib.h> #include <ldap.h> static int ldap_version = LDAP_VERSION3; main (int argc, char **argv) { LDAP* ld; extern char* optarg; char* ldap_host = NULL; char* ldap_bind_dn = NULL; char* ldap_bind_pw = NULL; int authmethod = 0; char ldap_local_host[256] = "localhost"; int ldap_port = 3060; char* authcid = (char *)NULL; char* mech = "DIGEST-MD5"; /* SASL mechanism */ char* authzid = (char *)NULL; char* sasl_secprops = "auth"; char* realm = (char *)NULL; int status = LDAP_SUCCESS; OraLdapHandle sasl_cred = (OraLdapHandle )NULL; OraLdapClientCtx *cctx = (OraLdapClientCtx *)NULL; int i = 0; while (( i = getopt( argc, argv, "D:h:p:w:E:P:U:V:W:O:R:X:Y:Z" )) != EOF ) { switch( i ) { case 'h': /* ldap host */ ldap_host = (char *)strdup( optarg ); break; case 'D': /* bind DN */ authcid = (char *)strdup( optarg ); break; case 'p': /* ldap port */ ldap_port = atoi( optarg ); break; case 'w': /* Password */ ldap_bind_pw = (char *)strdup( optarg ); break; default: printf("Invalid Arguments passed\n" ); } } /* Get the connection to the LDAP server */ if (ldap_host == NULL) ldap_host = ldap_local_host; if ((ld = ldap_open (ldap_host, ldap_port)) == NULL) { ldap_perror (ld, "ldap_init"); exit (1); } /* Create the client context needed by LDAP C-API Oracle Extension functions*/ status = ora_ldap_init_clientctx(&cctx); if(LDAP_SUCCESS != status) { printf("Failed during creation of client context \n"); exit(1); } /* Create SASL credentials */ sasl_cred = ora_ldap_create_cred_hdl(cctx, ORA_LDAP_CRED_HANDLE_SASL_MD5); ora_ldap_set_cred_props(cctx, sasl_cred, ORA_LDAP_CRED_SASL_REALM, (void *)realm); ora_ldap_set_cred_props(cctx, sasl_cred, ORA_LDAP_CRED_SASL_AUTH_PASSWORD, (void *)ldap_bind_pw); ora_ldap_set_cred_props(cctx, sasl_cred, ORA_LDAP_CRED_SASL_AUTHORIZATION_ID, (void *)authzid); ora_ldap_set_cred_props(cctx, sasl_cred, ORA_LDAP_CRED_SASL_SECURITY_PROPERTIES, (void *)sasl_secprops); /* If connecting to the directory using SASL DIGEST-MD5, the Authentication ID has to be normalized before it's sent to the server, the LDAP C-API does this normalization based on the following flag set in SASL credential properties */ ora_ldap_set_cred_props(cctx, sasl_cred, ORA_LDAP_CRED_SASL_NORM_AUTHDN, (void *)NULL); /* SASL Authetication to LDAP Server */ status = (int)ora_ldap_init_SASL(cctx, ld, (char *)authcid, (char *)ORA_LDAP_SASL_MECH_DIGEST_MD5, sasl_cred, NULL, NULL); if(LDAP_SUCCESS == status) { printf("SASL bind successful \n" ); }else { printf("SASL bind failed with status : %d\n", status); } /* Free SASL Credentials */ ora_ldap_free_cred_hdl(cctx, sasl_cred); status = ora_ldap_free_clientctx(cctx); /* Unbind from LDAP server */ ldap_unbind (ld); return (0); } /* end of file saslbind.c */
8.3.4 参照の追跡時に資格証明を得るためのコールバック・ファンクションの設定と使用
コールバック・ファンクションを設定するには、ldap_set_rebind_proc()を使用します。コールバック・ファンクションは、ldap_set_option()を使用してLDAP_OPT_REFERRALSが設定されている場合にのみ使用されます。ldap_set_rebind_proc()がコールされていない場合、LDAP参照の追跡時、ライブラリでは新しいサーバーへの接続に匿名バインドを使用します。
/* referralsample.c - Sample program to demonstrate the usage of ldap_set_rebind_proc() for referrals */ #include <stdio.h> #include <stdlib.h> #include <ldap.h> /* * Prints the Entry DNs of the search result */ void print_entry_dns( LDAP *ld, LDAPMessage *result ) { LDAPMessage *e; char *dn; for ( e = ldap_first_entry( ld, result ); e != NULL; e = ldap_next_entry(ld, e ) ) { if ( (dn = ldap_get_dn( ld, e )) != NULL ) { printf( "dn: %s\n\n", dn ); ldap_memfree( dn ); } else { ldap_perror( ld, "ldap_get_dn" ); } } } /* * Rebind function for providing the credentials to bind referral servers */ int getbindcredentials(LDAP *ld, char **binddn, char **bindpwd, int *authmethod, int freeit) { if (freeit == 0) { /* In this example bind credentials are static. Typically, Bind credentials are fetched from wallet or some other means for the server information in input session handle */ *binddn = "cn=orcladmin"; *bindpwd = "xyz"; *authmethod = LDAP_AUTH_SIMPLE; } else { /* In this example there is no memory allocation. If the memory is allocated for binddn/bindpwd/authmehod, they should be freed here */ *binddn = NULL; *bindpwd = NULL; *authmethod = 0; } return 0; } main() { char ldaphost[] = "localhost"; char binddn[] = "cn=orcladmin"; char bindpwd[] = "password"; int ldapport = 3060; char searchbase[] = "dc=oracle,dc=com"; char filter[] = "objectclass=*"; int scope = LDAP_SCOPE_SUBTREE; LDAP *ld; LDAPMessage *result; int ret = 0; if ( (ld = ldap_open( ldaphost, ldapport )) == NULL) { printf( "ldap_open: Connection failed\n" ); exit( 1 ); } if ( ldap_simple_bind_s(ld, binddn, bindpwd) != LDAP_SUCCESS ) { ldap_perror(ld, "ldap_simple_bind_s"); exit( 1 ); } /* Set this option to connect to the referrals */ ldap_set_option (ld, LDAP_OPT_REFERRALS, (void *)1); /* set the function pointer which provides the bind credentials for referral server */ ldap_set_rebind_proc(ld, (int (*)(LDAP*, char**, char**, int*, int))getbindcredentials); ret = ldap_search_s( ld, searchbase, scope, filter, NULL, 0, &result ); if(LDAP_SUCCESS != ret) { ldap_perror(ld, "ldap_search_s"); exit( 1 ); } print_entry_dns(ld, result); ldap_unbind(ld); return(0); }
8.4 C APIを使用するためのヘッダー・ファイルおよびライブラリの実装
C APIを使用してアプリケーションを作成するには、これをライブラリにリンクする必要があります。
-
$ORACLE_HOME/ldap/public/ldap.h
にあるヘッダー・ファイルをインクルードします。 -
次の場所にあるライブラリに動的にリンクします。
-
$ORACLE_HOME/lib/libclntsh.so.11.1
(UNIXおよびLinuxオペレーティング・システムの場合) -
%ORACLE_HOME%\bin\oraldapclnt11.lib
(Windowsオペレーティング・システムの場合)
-
8.5 C APIの依存性と制限事項
このAPIは、すべてのリリースのOracle Internet Directoryで機能します。Oracle環境または最低でもグローバリゼーション・サポートなどの主要ライブラリが必要です。
SSLで別の認証モードを使用するには、ディレクトリ・サーバーの構成設定をモードに応じて変更する必要があります。
関連項目:
様々なSSL認証モードでのディレクトリ・サーバーの設定方法の詳細は、『Oracle Fusion Middleware Oracle Internet Directory管理者ガイド』の「Secure Sockets Layer (SSL)の構成」を参照してください。
SSLモードでC APIを使用する場合は、ウォレットを作成するためにOracle Wallet Managerが必要となります。
TCP/IPソケット・ライブラリが必要です。
次のOracleライブラリが必要です。
-
Oracle SSL関連ライブラリ
-
Oracleシステム・ライブラリ
サンプル・コマンドライン・ツールのリリースの中には、サンプル・ライブラリが含まれています。それらのライブラリはユーザー自身のライブラリに置き換える必要があります。
この製品は、LDAP SDKの仕様(RFC 1823)に記述されている認証方式のみをサポートします。
C APIに入力されるすべての文字列はUTF-8形式の必要があります。文字列がUTF-8形式でない場合は、OCIファンクションOCINlsCharSetConvert
を使用して変換できます。http://www.oracle.com/technology/documentation
のOracle Database Libraryで『Oracle Call Interfaceプログラマーズ・ガイド』を参照してください。
8.6 LDAPセッションの初期化と使用上のノート
コールによって、LDAPサーバーとのセッションが初期化されます。
次の各項では、LDAPセッションと使用上のノートについて説明します。
8.6.1 ldap_initおよびldap_open
ldap_init()
はLDAPサーバーとのセッションを初期化しますが、接続のオープンは行いません。サーバーへの接続が必要となる操作が実行されるまで、実際にはサーバーに接続されません。そのため、初期化後に様々なオプションを設定できます。ldap_open()
はセッションを初期化し、接続をオープンします。この2つは同じ目的を達成し、構文も同じですが、前者の使用をお薦めします。
構文
LDAP *ldap_init ( const char *hostname, int portno ) ;
パラメータ
表8-3に、LDAPセッションを初期化するためのパラメータを示します。
表8-3 LDAPセッションを初期化するためのファンクションのパラメータ
パラメータ | 説明 |
---|---|
hostname |
接続先のLDAPサーバーを実行しているホストのIPアドレスを示す、空白で区切られたホスト名またはドット表記の文字列のリストが入ります。リスト内の各ホスト名には、ポート番号を含めることもできます。ホスト名とポート番号はコロンで区切る必要があります。接続に成功するまで、ホストがリストの順序に従って試されます。 IPv6アドレスは、大カッコ(
|
portno |
接続先のTCPポート番号が入ります。デフォルトのLDAPポート |
使用上のノート
ldap_init()
およびldap_open()
の戻り値はセッション・ハンドルです。これは、そのセッションに関連する後続のコールに渡す必要がある不透明な構造体へのポインタです。これらのルーチンは、セッションが初期化できない場合にNULL
を戻します。セッションが初期化できない場合、オペレーティング・システムのエラー・レポート・メカニズムをチェックし、コールに失敗した理由を確認してください。
LDAP v2サーバーに接続する場合は、後述するLDAPバインド・コールの1つをセッションで完了してから、他の操作を実行する必要があることに注意してください。LDAP v3では、他の操作を実行する前にバインド操作を完了する必要はありません。
コール元プログラムでは、次の項で説明するルーチンを呼び出して、セッションの様々な属性を設定できます。
8.7 LDAPセッション・ハンドル・オプション
ldap_init()
で戻されたLDAPセッション・ハンドルは、LDAPセッションを表す不透明なデータ型へのポインタです。RFC 1823では、このデータ型はコール元に公開されていた構造体で、構造体のフィールドを設定すると、検索時のサイズや時間の制限などセッションの様々な側面を制御できました。
現在は、コール元でこの構造体に対する重要な変更を行わないように、この項で説明する1組のアクセッサ・ファンクションによってセッションの様々な側面を制御できます。
8.7.1 ldap_get_optionおよびldap_set_option
セッション全体に及ぶ様々なパラメータの現在の値にアクセスするにはldap_get_option()
を使用します。それらのパラメータに値を設定するにはldap_set_option()
を使用します。オプションの中には読取り専用で値が設定できないものもあります。ldap_set_option()
をコールし、読取り専用のオプションに値を設定しようとした場合はエラーとなります。
自動参照追跡が有効な場合(デフォルト)、参照の追跡時に確立された接続は、参照を戻す原因となった最初のリクエストを送信したセッションに関するオプションを継承することに注意してください。
構文
int ldap_get_option (
LDAP *ld, int option, void *outvalue
) ; int ldap_set_option (
LDAP *ld, int option, const void *invalue
) ;
#define LDAP_OPT_ON ((void *)1) #define LDAP_OPT_OFF ((void *)0)
パラメータ
表8-4に、LDAPセッション・ハンドル・オプションのパラメータをリストし、説明します。
表8-4 LDAPセッション・ハンドル・ファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。これが |
option |
アクセスまたは設定するオプションの名前です。このパラメータは、表8-5に示す定数のいずれかであることが必要です。定数の後に、その定数の16進値をカッコで囲んで記述します。 |
outvalue |
オプションの値を配置する位置のアドレスです。このパラメータの実際の型は、optionパラメータの設定値によって異なります。outvalueパラメータが |
invalue |
optionパラメータに指定する値へのポインタです。このパラメータの実際の型は、optionパラメータの設定値によって異なります。invalueパラメータに関連付けられたデータはAPI実装によってコピーされるため、APIのコール元はデータを解放するか、 |
定数
表8-5に、LDAPセッション・ハンドル・オプションの定数をリストし、説明します。
表8-5 LDAPセッション・ハンドル・オプションの定数
定数 | invalueパラメータの型 | outvalueパラメータの型 | 説明 |
---|---|---|---|
LDAP_OPT_API_INFO(0x00) |
非適用。オプションは読取り専用です。 |
LDAPAPIInfo* |
実行時にLDAP API実装に関する基本的な情報を取得します。アプリケーションでは、コンパイル時および実行時の両方で使用する特定のAPI実装に関する情報を判断できることが必要です。このオプションは読取り専用で、設定はできません。 |
ORA_LDAP_OPT_RFRL_CACHE |
void* (LDAP_OPT_ON) void* (LDAP_OPT_OFF) |
int * |
このオプションは参照キャッシュが有効か無効かを示します。このオプションが |
ORA_LDAP_OPT_RFRL_CACHE_SZ |
int * |
int * |
このオプションは、参照キャッシュのサイズを指定します。サイズは、キャッシュを大きくできるバイト数の最大サイズです。デフォルトで1MBが設定されます。 |
LDAP_OPT_DEREF(0x02) |
int * |
int * |
検索時の別名の処理方法を判断します。 |
LDAP_OPT_SIZELIMIT(0x03) |
int * |
int * |
検索で戻されるエントリの最大数です。 |
LDAP_OPT_TIMELIMIT(0x04) |
int * |
int * |
検索を実行する最大秒数です。 |
LDAP_OPT_REFERRALS(0x08) |
void *(LDAP_OPT_ON) void *(LDAP_OPT_OFF) |
int * |
LDAPライブラリが、LDAPサーバーで戻された参照に自動的に従うかどうかを判断します。定数の |
LDAP_OPT_RESTART(0X09) |
void * (LDAP_OPT_ON) void * (LDAP_OPT_OFF) |
int * |
LDAPの入出力操作が未完了のまま停止したとき、自動的に再起動するかどうかを判断します。 |
LDAP_OPT_PROTOCOL_VERSION(0x11) |
int * |
int * |
このオプションは、プライマリLDAPサーバーとの通信時に使用するLDAPプロトコルのバージョンを示します。 |
LDAP_OPT_SERVER_CONTROLS(0x12) |
LDAPControl** |
LDAPControl*** |
各リクエストとともに送信されるLDAPサーバー・コントロールのデフォルト・リストです。 関連項目: 「コントロールの使用」 |
LDAP_OPT_CLIENT_CONTROLS(0x13) |
LDAPControl** |
LDAPControl*** |
LDAPセッションに影響を与えるクライアント・コントロールのデフォルト・リストです。 関連項目: 「コントロールの使用」 |
LDAP_OPT_API_FEATURE_INFO(0x15) |
非適用。オプションは読取り専用です。 |
LDAPAPIFeatureInfo * |
実行時にLDAP API拡張機能に関するバージョン情報を取得します。アプリケーションでは、コンパイル時および実行時の両方で使用する特定のAPI実装に関する情報を判断できることが必要です。このオプションは読取り専用です。設定はできません。 |
LDAP_OPT_HOST_NAME(0x30) |
char * |
char ** |
プライマリLDAPサーバーのホスト名(またはホストのリスト)です。構文については、 |
LDAP_OPT_ERROR_NUMBER(0x31) |
int * |
int * |
このセッションで発生した最新のLDAPエラーのコードです。 |
LDAP_OPT_ERROR_STRING(0x32) |
char * |
- |
このセッションで発生した最新のLDAPエラーで戻されたメッセージです。 |
LDAP_OPT_MATCHED_DN(0x33) |
char * |
char ** |
このセッションで発生した最新のLDAPエラーで戻された、一致する識別名です。 |
ORA_LDAP_OPT_CONNECT_TIMEOUT (0xD2) |
int * |
int * |
このオプションは、LDAP接続のタイムアウト値を秒数で設定します。接続タイムアウトは、 |
使用上のノート
ldap_get_option()
およびldap_set_option()
は、正常終了した場合は0
(ゼロ)を、エラーが発生した場合は-1
を戻します。いずれかのファンクションで-1
が戻された場合は、オプション値LDAP_OPT_ERROR_NUMBER
を設定してldap_get_option()
をコールすると、特定のエラー・コードを取得できます。オプション値LDAP_OPT_ERROR_NUMBER
を設定したldap_get_option()
コールに失敗すると、特定のエラー・コードを取得する方法は他にないことに注意してください。
ldap_get_option()
コールが正常終了した場合、API実装では、今後のLDAP APIコールの動作に影響を与えるような、LDAPセッション・ハンドルの状態または基礎となる実装の状態の変更は行わないでください。ldap_get_option()
コールに失敗した場合、許容されるセッション・ハンドルの変更はLDAPエラー・コードの設定のみです(LDAP_OPT_ERROR_NUMBER
オプションによって戻されます)。
ldap_set_option()
コールに失敗した場合は、今後のLDAP APIコールの動作に影響を与えるような、LDAPセッション・ハンドルの状態または基礎となる実装の状態の変更は行わないでください。
この仕様を拡張して新規オプションを指定している規格準拠ドキュメントでは、0x1000から0x3FFFの間のオプション・マクロの値を使用する必要があります。プライベートな拡張や経験に基づく拡張では、0x4000から0x7FFFの間のオプション・マクロの値を使用する必要があります。このドキュメントで定義されていない0x1000未満および0x7FFFを超える値は、すべて予約されており使用することはできません。拡張機能の実装を支援するには、次のマクロをC LDAP API実装で定義する必要があります。
#define LDAP_OPT_PRIVATE_EXTENSION_BASE 0x4000 /* to 0x7FFF inclusive */
8.8 参照を追跡するためのバインド資格証明の取得
ldap_set_rebind_proc()
ファンクションは、参照の追跡時、新しいサーバーのバインド資格証明の取得に使用されます。
ldap_set_rebind_proc()
ファンクションは、LDAP参照の追跡時に新しいサーバーに接続するためのバインド資格証明をライブラリで取得するために使用するコールバック・ファンクションの設定に使用されます。ライブラリでは、ldap_set_option
()を使用してLDAP_OPT_REFERRALS
が設定されている場合にのみコールバック・ファンクションを使用します。ldap_set_rebind_proc
()がコールされていない場合、LDAP参照の追跡時、ライブラリでは新しいサーバーへの接続に匿名バインドを使用します。
関連項目:
8.8.1 ldap_set_rebind_proc()
ldap_set_rebind_proc()
ファンクションは、参照の追跡時、新しいサーバーのバインド資格証明の取得に使用されます。
ldap_set_rebind_proc
()ファンクションは、LDAP参照の追跡時に新しいサーバーに接続するためのバインド資格証明をライブラリで取得するために使用するコールバック・ファンクションの設定に使用されます。ライブラリでは、ldap_set_option
()を使用してLDAP_OPT_REFERRALS
が設定されている場合にのみコールバック・ファンクションを使用します。ldap_set_rebind_proc
()がコールされていない場合、LDAP参照の追跡時、ライブラリでは新しいサーバーへの接続に匿名バインドを使用します。
関連項目:
構文
void ldap_set_rebind_proc ( LDAP *ld, int(*rebindproc) (LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit) )
パラメータ
reprocbind
()ファンクションは、新しいサーバーのバインド資格証明を取得するためにコールされるファンクションです。
表8-6 コールバック・ファンクションのパラメータおよびコールバック・ファンクションを設定するためのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです |
rebindproc |
LDAP参照の追跡時に新しいサーバーへ接続するためのバインド資格証明の取得に使用されるコールバック・ファンクション |
ld |
新しいサーバーへのセッション・ハンドル |
dnp |
新しいサーバーに対するバインド識別名のポインタ |
passwdp |
新しいサーバーに対するバインド・パスワードのポインタ |
authmethodp |
新しいサーバーに対する認証方法のポインタ |
freeit |
|
使用上のノート
freeit
パラメータの値が0
の場合、rebindproc
は必ずバインド識別名ポインタ、バインド・パスワード・ポインタおよびバインド認証方法ポインタを戻します。freeit
パラメータの値が1の場合、rebindproc
は前回のコールで割り当てられたすべてのメモリーを解放します。LDAPライブラリはこのファンクションを2回コールします。1回目で資格証明をバインドし、2回目でメモリーを解放します。
8.9 ディレクトリに対する認証
LDAPバインド・ファンクションを使用して、LDAPディレクトリ・サーバーに対してLDAPクライアントを認証できます。
この項のファンクションを使用して、次の各項で説明するLDAPディレクトリ・サーバーに対するLDAPクライアントの認証を行います。
8.9.1 ldap_sasl_bind、ldap_sasl_bind_s、ldap_simple_bindおよびldap_simple_bind_s
ldap_sasl_bind()
ファンクションおよびldap_sasl_bind_s()
ファンクションは、Simple Authentication Security Layerを使用したLDAPでの通常および拡張認証に使用できます。
いずれのルーチンも、メソッドを識別するオブジェクト識別子(OID)のドット区切りの文字列表記として使用するメソッドとして、また資格証明を保持するstruct berval
として、バインドする識別名を使用します。簡易認証のリクエストには特別な定数値LDAP_SASL_SIMPLE (NULL)
を渡すか、簡略化ルーチンldap_simple_bind()
またはldap_simple_bind_s()
が使用できます。
構文
int ldap_sasl_bind (
LDAP *ld, const char *dn, const char *mechanism, const struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );
int ldap_sasl_bind_s(
LDAP *ld, const char *dn, const char *mechanism, const struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls,
);
int ldap_simple_bind(
LDAP *ld, const char *dn, const char *passwd
);
int ldap_simple_bind_s(
LDAP *ld, const char *dn, const char *passwd
);
次のルーチンの使用は非推奨です。詳細は、RFC 1823を参照してください。
-
int ldap_bind( LDAP *ld, const char *dn, const char *cred, int method );
-
int ldap_bind_s( LDAP *ld, const char *dn, const char *cred, int method );
-
int ldap_kerberos_bind( LDAP *ld, const char *dn );
-
int ldap_kerberos_bind_s( LDAP *ld, const char *dn );
パラメータ
表8-7に、ディレクトリに対する認証のパラメータをリストし、説明します。
表8-7 ディレクトリの認証ファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです |
dn |
バインドするエントリの名前です。 |
mechanism |
|
cred |
認証に使用する資格証明です。このパラメータを使用すると、任意の資格証明を渡すことができます。資格証明の書式と内容は、mechanismパラメータの設定内容によって異なります。 |
passwd |
|
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
使用上のノート
非推奨のルーチンに関するその他のパラメータは説明していません。詳細は、RFC 1823を参照してください。
ldap_sasl_bind()
ファンクションは、非同期のバインド操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_sasl_bind()
によってリクエストのメッセージIDが*msgidp
に格納されます。続けてldap_result()
をコールすると、バインドの結果を取得できます。
ldap_simple_bind()
ファンクションは、単純な非同期のバインド操作を開始し、開始した操作のメッセージIDを戻します。続けてldap_result()
をコールすると、バインドの結果を取得できます。エラーが発生した場合、ldap_simple_bind()
は-1
を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_sasl_bind_s()
ファンクションおよびldap_simple_bind_s()
ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
LDAP v2サーバーに接続している場合は、バインド・コールが正常に完了するまで、接続に対する他の操作ができないことに注意してください。
続けてバインド・コールを使用すると、同じ接続に対して再認証を行うことができます。また、ldap_sasl_bind()
またはldap_sasl_bind_s()
を連続してコールすると、複数ステップのSASL処理を実行できます。
関連項目:
エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。
8.10 Oracleの拡張機能を使用したSASL認証
SASL認証を実行するには、ora_ldap_init_SASL
ファンクションを使用します。
8.10.1 ora_ldap_init_SASL
ora_ldap_init_SASL()
ファンクションを使用すると、SASL認証を実行できます。このファンクションは、入力引数の1つに指定したメカニズムに基づいて認証を実行します。
このファンクションは、様々な標準SASLメカニズムのクライアントとディレクトリ・サーバー間のSASLハンドシェイクをカプセル化するため、ディレクトリ・サーバーへのSASLベース接続の確立でのコーディングの負荷が軽減されます。
構文
int ora_ldap_init_SASL ( OraLdapClientCtx * clientCtx, LDAP *ld, char * dn, char * mechanism, OraLdapHandle cred, LDAPControl **serverctrls, LDAPControl **clientctrls );
パラメータ
次の表に、パラメータを示します。
表8-8 ora_ldap_init_sasl()ファンクションのパラメータ
パラメータ | 説明 |
---|---|
clientCtx |
C APIのクライアント・コンテキストです。これは、 |
ld |
LDAPセッション・ハンドルです。 |
dn |
認証されるユーザーDNです。 |
mechanism |
SASLメカニズムです。 |
cred |
SASL認証に必要な資格証明です。 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
使用上のノート
credパラメータは、ユーザー用のSASL証明書ハンドルです。このハンドルは、ora_ldap_create_cred_hdl()
、ora_ldap_set_cred_props()
およびora_ldap_free_cred_hdl()
ファンクションを使用して管理できます。
サポートされるSASLメカニズムは次のとおりです。
-
DIGEST-MD5
Oracle Internet Directory SASL APIは、Digest-MD5の認証のみのモードをサポートします。データ・プライバシおよびデータ整合性に対応したその他2つの認証モードは、まだサポートされていません。
Oracle Internet Directoryに対して認証する際は、ユーザーの識別名はサーバーに送信される前に正規化される必要があります。これは、DNをSASL APIに渡す前に
ora_ldap_normalize_dn()
ファンクションを使用してSASL APIの外部で行うか、またはora_ldap_set_cred_handle()
を使用して、SASL資格証明ハンドルにORA_LDAP_CRED_SASL_NORM_AUTHDN
オプションを設定してSASL APIで行うことができます。 -
EXTERNAL:
Oracle Internet DirectoryでのSASL APIおよびSASLの実装には、外部認証メカニズムの1つとしてSSL認証を使用します。
このメカニズムを使用するには、
ora_ldap_init_SSL()
ファンクションを使用して、ディレクトリ・サーバーに対してSSL接続(相互認証モード)を確立する必要があります。これにより、ora_ldap_init_SASL()
ファンクションは、mechanism
引数にEXTERNAL
を指定して起動できます。ディレクトリ・サーバーは、SSL接続のユーザー資格証明に基づいてユーザーを認証します。
8.10.2 ora_ldap_create_cred_hdl、ora_ldap_set_cred_props、ora_ldap_get_cred_propsおよびora_ldap_free_cred_hdl
次のファンクションを使用して、SASL資格証明ハンドルを作成および管理します。ora_ldap_create_cred_hdl
ファンクションは、SASL認証に使用するメカニズムのタイプをベースにした、特定のタイプのSASL資格証明ハンドルの作成に使用します。ora_ldap_set_cred_props()
ファンクションは、SASL認証に必要なハンドルに関連する資格証明の追加に使用できます。
ora_ldap_get_cred_props()
ファンクションは、資格証明ハンドルに格納されたプロパティの取得に、ora_ldap_free_cred_hdl ()
ファンクションは、使用後のハンドルの破棄に使用できます。
構文
OraLdapHandle ora_ldap_create_cred_hdl ( OraLdapClientCtx * clientCtx, int credType ); OraLdapHandle ora_ldap_set_cred_props ( OraLdapClientCtx * clientCtx, OraLdapHandle cred, int String[], void * inProperty ); OraLdapHandle ora_ldap_get_cred_props ( OraLdapClientCtx * clientCtx, OraLdapHandle cred, int String[], void * outProperty ); OraLdapHandle ora_ldap_free_cred_hdl ( OraLdapClientCtx * clientCtx, OraLdapHandle cred );
パラメータ
次の表に、パラメータを示します。
表8-9 SASL資格証明の管理ファンクションのパラメータ
パラメータ | 説明 |
---|---|
clientCtx |
C APIのクライアント・コンテキストです。これは、 |
credType |
SASLメカニズム固有の資格証明ハンドルのタイプです。 |
cred |
SASL認証のための固有のSASLメカニズムに必要なSASL資格証明を含む資格証明ハンドルです。 |
String[] |
資格証明ハンドルに追加する必要がある資格証明のタイプです。 |
inProperty |
資格証明ハンドルに格納されるSASL資格証明の1つです。 |
outProperty |
資格証明ハンドルに格納されたSASL資格証明の1つです。 |
使用上のノート
なし
8.11 コントロールの使用
コントロールを使用すると、LDAP v3操作を拡張できます。コントロールは、サーバーに送信したり、LDAPメッセージとともにクライアントに戻すことができます。このようなコントロールは、サーバー・コントロールと呼ばれます。
LDAP APIは、クライアント・コントロールを使用してクライアント側の拡張メカニズムもサポートします。このコントロールは、LDAP APIの動作にのみ影響し、サーバーに送信されることはありません。
両方のタイプのコントロールを表現するため、次の共通のデータ構造が使用されます。
8.11.1 ldapcontrol
ldapcontrol
データ構造には、コントロール・タイプ、コントロールに対応付けられたデータおよびコントロールが重要かどうかを示す要素が含まれます。
構文
typedef struct ldapcontrol {
char *ldctl_oid; struct berval ldctl_value; char ldctl_iscritical;
} LDAPControl;
パラメータ
表8-10に、ldapcontrol
構造体のフィールドを示します。
表8-10 ldapcontrol構造体のフィールド
フィールド | 説明 |
---|---|
ldctl_oid |
文字列で表現されたコントロール・タイプです。 |
ldctl_value |
コントロールに対応付けられたデータ(ある場合)です。長さ0(ゼロ)の値を指定するには、 |
ldctl_iscritical |
コントロールが重要かどうかを示します。このフィールドが0(ゼロ)以外の場合は、サーバーまたはクライアント(あるいはその両方)でコントロールが認識されると、その操作のみが実行されます。LDAPのバインド解除操作および中止操作では、サーバーからのレスポンスはありません。これら2つの操作でサーバー・コントロールを使用するときは、クライアントでコントロールを重要(critical)とマークしないでください。 |
関連項目:
コントロールの詳細は、「LDAPプロトコルに対する拡張機能」を参照してください。
使用上のノート
LDAP APIの一部のコールでは、ldapcontrol
構造体、またはldapcontrol
構造体のNULL
終了配列を割り当てます。次のルーチンを使用すると、単一コントロールまたはコントロールの配列を解放できます。
void ldap_control_free( LDAPControl *ctrl ); void ldap_controls_free( LDAPControl **ctrls );
ctrl
パラメータまたはctrls
パラメータがNULL
の場合は、このファンクションをコールしても何も実行されません。
セッション全体に影響を与えるコントロールのセットは、ldap_set_option()
ファンクション(「ldap_get_optionおよびldap_set_option」を参照)を使用して設定できます。コントロールのリストをldap_search_ext()
などの一部のLDAP APIコールに直接渡すこともできます。この場合、ldap_set_option()
を使用して設定したセッションのコントロール・セットは無視されます。コントロール・リストはldapcontrol
構造体へのポインタのNULL
終了配列で表されます。
サーバー・コントロールは、LDAP v3プロトコル拡張ドキュメントで定義されています。たとえば、コントロールは、サーバー側での検索結果のソートをサポートするために計画されています。
この章では、1つのクライアント・コントロールが定義されています(後の項で説明)。
クライアント・コントロールの参照プロセス
「LDAPセッションの初期化と使用上のノート」で説明したように、アプリケーションでは、LDAP_OPT_REFERRALS
オプションを設定したldap_set_option()
ファンクションを使用して、セッション全体で自動参照追跡を有効にしたり無効にすることができます。これは、リクエストごとに自動参照追跡を制御する場合にも役立ちます。この機能を提供するため、1.2.840.113556.1.4.616
のオブジェクト識別子(OID)を持つクライアント・コントロールがあります。
/* OID for referrals client control */ #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616" /* Flags for referrals client control value */ #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020U #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040U
参照先クライアント・コントロールを作成するには、LDAPControl
構造体のldctl_oid
フィールドをLDAP_CONTROL_REFERRALS ("1.2.840.113556.1.4.616")
に設定し、ldctl_value
フィールドを一連のフラグが格納された4オクテット値に設定する必要があります。ldctl_value.bv_len
フィールドは常に4
に設定する必要があります。ldctl_value.bv_val
フィールドは、4オクテットの整数フラグ値を指し示す必要があります。このフラグ値を0(ゼロ)に設定すると、自動参照追跡とLDAP v3リファレンスの両方を無効にできます。これ以外に、このフラグ値を、値LDAP_CHASE_SUBORDINATE_REFERRALS (0x00000020U)
に設定して、LDAP v3の検索継続リファレンスのみがAPI実装によって自動的に追跡されることを示すか、値LDAP_CHASE_EXTERNAL_REFERRALS (0x00000040U)
に設定して、LDAP v3参照のみが自動的に追跡されることを示すか、2つのフラグ値の論理和(0x00000060U)
に設定して、参照先と参照元の両方が自動的に追跡されることを示すことができます。
関連項目:
オブジェクト識別子の詳細は、Oracle Fusion Middleware Oracle Internet Directory管理者ガイドのディレクトリ・スキーマの管理の項を参照してださい。
8.12 セッションのクローズ
LDAPファンクションを使用して、接続をバインド解除、クローズおよびオープンできます。
次のファンクションを使用して、ディレクトリからバインドを解除し、オープンしている接続をクローズして、セッション・ハンドルを解放します。
-
ldap_unbind
-
ldap_unbind_ext
-
ldap_unbind_s
8.12.1 ldap_unbind_ext()、ldap_unbind()およびldap_unbind_s()
ldap_unbind_ext()
、ldap_unbind()
およびldap_unbind_s()
は、サーバーにバインド解除リクエストを送信し、LDAPセッション・ハンドルに関連するオープンな接続をすべてクローズし、セッション・ハンドルに関連するリソースをすべて解放した後に値が戻されるという点で、すべて同期的に動作します。ただし、LDAPバインド解除操作にはサーバー・レスポンスがないことに注意してください。
3つのバインド解除ファンクションはすべて、LDAP_SUCCESS
を戻します(LDAPサーバーにリクエストが送信できない場合は別のLDAPエラー・コードを戻します)。バインド解除ファンクションを1つコールすると、セッション・ハンドルld
は無効となり、ld
を使用した別のLDAP APIのコールはできなくなります。
ldap_unbind()
ファンクションとldap_unbind_s()
ファンクションは同じように動作します。ldap_unbind_ext()
ファンクションを使用すると、サーバー・コントロールとクライアント・コントロールを明示的に含めることができますが、バインド解除リクエストに対するサーバーからのレスポンスがないため、バインド解除リクエストで送信されたサーバー・コントロールに対するレスポンスを受信する方法はないことに注意してください。
構文
int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls, LDAPControl **clientctrls ); int ldap_unbind( LDAP *ld ); int ldap_unbind_s( LDAP *ld );
パラメータ
次の表に、パラメータを示します。
表8-11 セッションをクローズするファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
使用上のノート
なし
8.13 LDAP操作の実行
LDAP操作を使用して、LDAPディレクトリの検索、比較および変更を実行します。
この項のファンクションを使用してLDAPディレクトリを検索し、一致した各エントリについてリクエストされた属性セットを戻します。
8.13.1 ldap_search_ext、ldap_search_ext_s、ldap_searchおよびldap_search_s
ldap_search_ext()
ファンクションは、非同期の検索操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_search_ext()
によってリクエストのメッセージIDが*msgidp
に格納されます。続けてldap_result()
をコールすると、検索の結果を取得できます。検索結果は、後述する結果解析ルーチンを使用して解析できます。
ldap_search_ext()
ファンクションと同様に、ldap_search()
ファンクションは非同期の検索操作を開始し、開始した操作のメッセージIDを戻します。ldap_search_ext()
の場合は、続けてldap_result()
をコールすると、バインドの結果を取得できます。エラーが発生した場合、ldap_search()
は-1
を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_search_ext_s()
、ldap_search_s()
およびldap_search_st()
の各ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。検索によって戻されるエントリがある場合、res
パラメータの中に収められます。このパラメータはコール元に対しては不透明です。エントリ、属性、値などは、この項で説明する解析ルーチンをコールすることで抽出できます。res
に格納された結果が不要になった場合は、後述するldap_msgfree()
をコールして解放する必要があります。
ldap_search_ext()
ファンクションとldap_search_ext_s()
ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートし、各検索操作に対して様々なサイズと制限時間を簡単に指定できます。ldap_search_st()
ファンクションは、検索のローカル・タイムアウトを指定するパラメータがあること以外は、ldap_search_s()
ファンクションと同じです。ローカル検索タイムアウトは、検索完了までAPI実装が待機する時間を制限するために使用します。ローカル検索タイムアウトを経過すると、API実装は中止操作を送信して検索操作を停止します。
関連項目:
エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。
構文
int ldap_search_ext (
LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly, LDAPControl **serverctrls, LDAPControl **clientctrls, struct timeval *timeout, int sizelimit, int *msgidp
); int ldap_search_ext_s (
LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly, LDAPControl **serverctrls, LDAPControl **clientctrls, struct timeval *timeout, int sizelimit, LDAPMessage **res
); int ldap_search (
LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly
); int ldap_search_s (
LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly, LDAPMessage **res
); int ldap_search_st );
LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly, struct timeval *timeout, LDAPMessage **res
);
パラメータ
表8-12に、検索操作のパラメータをリストし、説明します。
表8-12 検索操作ファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
base |
検索の開始点となるエントリの識別名です。 |
scope |
|
filter |
検索フィルタを表す文字列です。この値を |
attrs |
一致した各エントリのどの属性を戻すかを指定する文字列の |
attrsonly |
属性の型と値の両方を戻す場合には0(ゼロ)、属性の型のみを要求する場合には0(ゼロ)以外を指定する必要があるブール値です。 |
timeout |
|
sizelimit |
|
res |
同期コールを行うとき、コールの終了時に検索結果が入る結果パラメータです。戻される結果がない場合、 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
使用上のノート
エントリの読取り
LDAPでは、読取り操作を直接サポートしていません。かわりに、この操作は、ベースを読み込むエントリの識別名に設定し、有効範囲をLDAP_SCOPE_BASE
に設定し、さらにフィルタを"(objectclass=*)"
またはNULL
に設定した検索によってエミュレーションを行います。attrs
パラメータには、戻される属性のリストが格納されます。
エントリの子のリスト表示
LDAPでは、リスト操作を直接サポートしていません。かわりに、この操作は、ベースをリスト表示するエントリの識別名に設定し、有効範囲をLDAP_SCOPE_ONELEVELに設定し、さらにフィルタを"(objectclass=*)"またはNULLに設定した検索によってエミュレーションを行います。パラメータattrsには、子エントリごとに戻される属性のリストが格納されます。
8.13.2 ldap_compare_ext、ldap_compare_ext_s、ldap_compareおよびldap_compare_s
ldap_compare_ext()
ファンクションは、非同期の比較操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_compare_ext()
によってリクエストのメッセージIDが*msgidp
に格納されます。続けてldap_result()
をコールすると、比較の結果を取得できます。
これらのルーチンを使用して、属性値のアサーションをLDAPエントリと照合して比較します。
ldap_compare_ext()
ファンクションと同様に、ldap_compare()
ファンクションは非同期の比較操作を開始し、開始した操作のメッセージIDを戻します。ldap_compare_ext()
の場合は、続けてldap_result()
をコールすると、バインドの結果を取得できます。エラーが発生した場合、ldap_compare()
は-1
を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_compare_ext_s()
ファンクションおよびldap_compare_s()
ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
ldap_compare_ext()
ファンクションとldap_compare_ext_s()
ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
関連項目:
エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。
構文
int ldap_compare_ext (
LDAP *ld, const char *dn, const char *attr, const struct berval *bvalue, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_compare_ext_s (
LDAP *ld, const char *dn, const char *attr, const struct berval *bvalue, LDAPControl **serverctrls, LDAPControl **clientctrls
); int ldap_compare (
LDAP *ld, const char *dn, const char *attr, const char *value
); int ldap_compare_s (
LDAP *ld, const char *dn, const char *attr, const char *value
);
パラメータ
表8-13に、比較操作のパラメータをリストし、説明します。
表8-13 比較操作のパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
dn |
比較の対象となるエントリの名前です。 |
attr |
比較の対象となる属性です。 |
bvalue |
指定のエントリで検索された属性と照合して比較される属性値です。このパラメータは拡張ルーチンで使用され、 |
value |
比較の対象となる文字列の属性値で、 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
使用上のノート
なし
8.13.3 ldap_modify_ext、ldap_modify_ext_s、ldap_modifyおよびldap_modify_s
これらのルーチンを使用して、既存のLDAPエントリを変更します。ldap_modify_ext()
ファンクションは、非同期の変更操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_modify_ext()
によってリクエストのメッセージIDが*msgidp
に格納されます。続けてldap_result()
をコールすると、変更の結果を取得できます。
ldap_modify_ext()
ファンクションと同様に、ldap_modify()
ファンクションは非同期の変更操作を開始し、開始した操作のメッセージIDを戻します。ldap_modify_ext()
の場合は、続けてldap_result()
をコールすると、変更の結果を取得できます。エラーが発生した場合、ldap_modify()
は-1
を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_modify_ext_s()
ファンクションおよびldap_modify_s()
ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
ldap_modify_ext()
ファンクションとldap_modify_ext_s()
ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
関連項目:
エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。
構文
typedef struct ldapmod {
int mod_op; char *mod_type; union mod_vals_u {
char **modv_strvals; struct berval **modv_bvals; } mod_vals;
} LDAPMod;
#define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals
int ldap_modify_ext (
LDAP *ld, const char *dn, LDAPMod **mods, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_modify_ext_s (
LDAP *ld, const char *dn, LDAPMod **mods, LDAPControl **serverctrls, LDAPControl **clientctrls
); int ldap_modify (
LDAP *ld, const char *dn, LDAPMod **mods );
int ldap_modify_s (
LDAP *ld, const char *dn, LDAPMod **mods
);
パラメータ
表8-14に、変更操作のパラメータをリストし、説明します。
表8-14 変更操作ファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです |
dn |
変更するエントリの名前です。 |
mods |
エントリに対する変更の |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
表8-15に、LDAPMod構造体のフィールドを示します。
表8-15 LDAPMod構造体のフィールド
フィールド | 説明 |
---|---|
mod_op |
実行する変更操作です。 |
mod_type |
変更する属性の型です。 |
mod_vals |
追加、削除または置換する値(存在する場合)。 |
使用上のノート
LDAP_MOD_ADD
変更の場合は、指定の値がエントリに追加され、必要に応じて属性が作成されます。
LDAP_MOD_DELETE
変更の場合は、指定の値がエントリから削除され、値がない場合は属性が削除されます。すべての属性を削除する場合は、mod_valsフィールドをNULL
に設定できます。
LDAP_MOD_REPLACE
変更の場合、属性は変更後にリストされた値を保持します。値は必要に応じて作成され、mod_vals
フィールドがNULL
の場合は削除されます。すべての変更はリストされた順序で実行されます。
8.13.4 ldap_renameおよびldap_rename_s
これらのルーチンを使用して、エントリ名を変更します。ldap_rename()
ファンクションは、非同期の識別名変更操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_rename()
によってリクエストのメッセージIDが*msgidp
に格納されます。続けてldap_result()
をコールすると、名前の変更の結果を取得できます。
同期型のldap_rename_s()
ファンクションは、操作が正常終了した場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
ldap_rename()
ファンクションとldap_rename_s()
ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
関連項目:
エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。
構文
int ldap_rename (
LDAP *ld, const char *dn, const char *newrdn, const char *newparent, int deleteoldrdn, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_rename_s (
LDAP *ld, const char *dn, const char *newrdn, const char *newparent, int deleteoldrdn, LDAPControl **serverctrls, LDAPControl **clientctrls
);
次のルーチンの使用は非推奨です。詳細は、RFC 1823を参照してください。
int ldap_modrdn (
LDAP *ld, const char *dn, const char *newrdn
); int ldap_modrdn_s (
LDAP *ld, const char *dn, const char *newrdn
); int ldap_modrdn2 (
LDAP *ld, const char *dn, const char *newrdn, int deleteoldrdn
); int ldap_modrdn2_s (
LDAP *ld, const char *dn, const char *newrdn, int deleteoldrdn
);
パラメータ
表8-16に、名前の変更操作のパラメータをリストし、説明します。
表8-16 名前の変更操作ファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
dn |
識別名を変更するエントリの名前です。 |
newrdn |
エントリに指定する新規の相対識別名です。 |
newparent |
新規の親または上位エントリ。このパラメータが |
deleteoldrdn |
newrdnが古い相対識別名と異なる場合、このパラメータは名前の変更ルーチンでのみ使用されます。このパラメータはブール値で、0(ゼロ)以外の場合は古い相対識別名が削除されたことを示し、0(ゼロ)の場合は、エントリの識別されない値として古い相対識別名が保持されていることを示します。 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
使用上のノート
なし
8.13.5 ldap_add_ext、ldap_add_ext_s、ldap_addおよびldap_add_s
これらのファンクションを使用して、LDAPディレクトリにエントリを追加します。ldap_add_ext()
ファンクションは、非同期の追加操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_add_ext()
によってリクエストのメッセージIDが*msgidp
に格納されます。続けてldap_result()
をコールすると、追加の結果を取得できます。
ldap_add_ext()
ファンクションと同様に、ldap_add()
ファンクションは非同期の追加操作を開始し、開始した操作のメッセージIDを戻します。ldap_add_ext()
の場合は、続けてldap_result()
をコールすると、追加の結果を取得できます。エラーが発生した場合、ldap_add()
は-1
を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_add_ext_s()
ファンクションおよびldap_add_s()
ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
ldap_add_ext()
ファンクションとldap_add_ext_s()
ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
関連項目:
エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。
構文
int ldap_add_ext (
LDAP *ld, const char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_add_ext_s (
LDAP *ld, const char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls
); int ldap_add (
LDAP *ld, const char *dn, LDAPMod **attrs
); int ldap_add_s (
LDAP *ld, const char *dn, LDAPMod **attrs
);
パラメータ
表8-17に、追加操作のパラメータをリストし、説明します。
表8-17 追加操作ファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
dn |
追加するエントリの名前です。 |
attrs |
|
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
使用上のノート
追加操作を正常に行うためには、追加するエントリの親がすでに存在しているか、親が空(つまり、ルートの識別名と同じ)であることが必要です。
8.13.6 ldap_delete_ext、ldap_delete_ext_s、ldap_deleteおよびldap_delete_s
これらのファンクションを使用して、LDAPディレクトリからリーフ・エントリを削除します。ldap_delete_ext()
ファンクションは、非同期の削除操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを戻します。正常終了の場合、ldap_delete_ext()
によってリクエストのメッセージIDが*msgidp
に格納されます。続けてldap_result()
をコールすると、削除の結果を取得できます。
ldap_delete_ext()
ファンクションと同様に、ldap_delete()
ファンクションは非同期の削除操作を開始し、開始した操作のメッセージIDを戻します。ldap_delete_ext()
の場合は、続けてldap_result()
をコールすると、削除の結果を取得できます。エラーが発生した場合、ldap_delete()
は-1
を戻し、LDAP構造体に適切なセッション・エラー・パラメータを設定します。
同期型のldap_delete_ext_s()
ファンクションおよびldap_delete_s()
ファンクションはいずれも、操作が正常終了した場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。
ldap_delete_ext()
ファンクションとldap_delete_ext_s()
ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
関連項目:
エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。
構文
int ldap_delete_ext (
LDAP *ld, const char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_delete_ext_s ( LDAP *ld,
const char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls
);
int ldap_delete
(
LDAP *ld, const char *dn
); int ldap_delete_s (
LDAP *ld, const char *dn
);
パラメータ
表8-18に、削除操作のパラメータをリストし、説明します。
表8-18 削除操作ファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
dn |
削除するエントリの名前です。 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
使用上のノート
削除するエントリは、リーフ・エントリ(つまり、子エントリがないエントリ)であることが必要です。1回の操作でサブツリー全体を削除する操作は、LDAPではサポートされていません。
8.13.7 ldap_extended_operationおよびldap_extended_operation_s
これらのルーチンを使用すると、拡張LDAP操作をサーバーに渡し、一般的なプロトコル拡張メカニズムを提供できます。
ldap_extended_operation()
ファンクションは、非同期の拡張操作を開始し、リクエストが正常に送信された場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを戻します。正常終了した場合、ldap_extended_operation()
はリクエストのメッセージIDを*msgidp
に配置します。ldap_result()
を続けてコールすると拡張操作の結果を取得できます。この結果をldap_parse_extended_result()
に渡すとオブジェクト識別子(OID)とレスポンスに格納されたデータを取得できます。
同期型のldap_extended_operation_s()
ファンクションは、操作が正常終了した場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを操作の結果として戻します。retoid
パラメータとretdata
パラメータには、結果に含まれているOIDとデータが入力されます。戻されるOIDまたはデータがない場合、これらのパラメータはNULL
に設定されます。
ldap_extended_operation()
ファンクションとldap_extended_operation_s()
ファンクションは、LDAP v3のサーバー・コントロールとクライアント・コントロールをサポートします。
関連項目:
エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。
構文
int ldap_extended_operation (
LDAP *ld, const char *requestoid, const struct berval *requestdata, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
); int ldap_extended_operation_s (
LDAP *ld, const char *requestoid, const struct berval *requestdata, LDAPControl **serverctrls, LDAPControl **clientctrls, char **retoidp, struct berval **retdatap
);
パラメータ
表8-19に、拡張操作のパラメータをリストし、説明します。
表8-19 拡張操作ファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです |
requestoid |
リクエストを指定する、ドット表記のOIDテキスト文字列です。 |
requestdata |
操作に必要な任意のデータです( |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
msgidp |
|
retoidp |
サーバーによって戻されたドット区切りの割当て済OIDテキスト文字列に設定された、文字列へのポインタです。この文字列は |
retdatap |
サーバーによって戻されたデータの割当て済コピーに設定される |
使用上のノート
なし
8.14 操作の中止
ldap_abandon_ext()
ファンクションは、msgid
パラメータのメッセージIDを使用して操作を中止し、中止操作が正常終了した場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを戻します。
ldap_abandon()
は、クライアント・コントロールまたはサーバー・コントロールを受け入れないこと以外はldap_abandon_ext()
と同じで、中止操作が正常終了した場合は0(ゼロ)を、失敗した場合は-1
を戻します。
ldap_abandon()
コールまたはldap_abandon_ext()
コールが正常終了した後、指定のメッセージIDを持つ結果は、引き続きldap_result()
をコールしても戻されません。LDAP中止操作に対するサーバーのレスポンスはありません。
8.14.1 ldap_abandon_ext()
ldap_abandon_ext()
ファンクションは、msgidパラメータのメッセージIDを使用して操作を中止し、中止操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。
構文
int ldap_abandon_ext (
LDAP *ld, int msgid, LDAPControl **serverctrls, LDAPControl **clientctrls
); int ldap_abandon (
LDAP *ld, int msgid
);
パラメータ
表8-20に、操作の中止のパラメータをリストし、説明します。
表8-20 操作の中止ファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
msgid |
中止するリクエストのメッセージIDです。 |
serverctrls |
LDAPサーバー・コントロールのリストです。 |
clientctrls |
クライアント・コントロールのリストです。 |
関連項目:
エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。
使用上のノート
なし
8.15 結果の取得とLDAPメッセージの確認
非同期で開始された操作の結果は、ldap_result()
ファンクションで戻されます。
この項のファンクションを使用して、非同期で開始した操作の結果を戻します。これらのファンクションは、メッセージを型およびIDで識別します。
8.15.1 ldap_result、ldap_msgtypeおよびldap_msgid
ldap_result()
を使用して、非同期に開始した前回の操作の結果を取得します。コールの方法によって、ldap_result()
が実際に戻す値が結果メッセージのリストの場合とチェーンの場合があることに注意してください。
ldap_result()
ファンクションは単一リクエストに対するメッセージのみを返します。検索以外のすべてのLDAP操作で想定されている結果メッセージは1つのみです。つまり、結果チェーンが複数のメッセージを格納できるのは、検索操作のからの結果が戻された場合のみです。
コール元に戻された結果セットは、そのセットを生成したLDAPリクエストとの関連をコール元で表示する方法はありません。したがって、ldap_result()
または同期検索ルーチンをコールして戻された結果セットは、後続のLDAP APIコールの影響を受けることはありません(結果セットを解放するldap_msgfree()
は除きます)。
ldap_msgfree()
は、ldap_result()
または同期検索ルーチンをコールして前に取得した結果メッセージ(結果セット全体の場合もあります)を解放します。
ldap_msgtype()
はLDAPメッセージのタイプを戻します。ldap_msgid()
はLDAPメッセージのメッセージIDを戻します。
構文
int ldap_result (
LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **res
); int ldap_msgfree( LDAPMessage *res ); int ldap_msgtype( LDAPMessage *res ); int ldap_msgid( LDAPMessage *res );
パラメータ
表8-21に、結果の取得とLDAPメッセージの確認のためのパラメータをリストし、説明します。
表8-21 結果の取得とLDAPメッセージの確認のファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
msgid |
結果が戻される操作のメッセージID、定数 |
all |
1回の |
timeout |
結果の戻りに対する待機時間を指定するタイムアウトです。 |
res |
|
使用上のノート
正常終了すると、ldap_result()
は戻された最初の結果のタイプをres
パラメータに戻します。次のいずれかの定数が戻されます。
LDAP_RES_BIND (0x61)
LDAP_RES_SEARCH_ENTRY (0x64)
LDAP_RES_SEARCH_REFERENCE (0x73)
- LDAP v3の新規定数
LDAP_RES_SEARCH_RESULT (0x65)
LDAP_RES_MODIFY (0x67)
LDAP_RES_ADD (0x69)
LDAP_RES_DELETE (0x6B)
LDAP_RES_MODDN (0x6D)
LDAP_RES_COMPARE (0x6F)
LDAP_RES_EXTENDED (0x78)
-- LDAP v3の新規定数
ldap_result()
は、タイムアウトを超過した場合は0
(ゼロ)を、エラーが発生した場合は-1
を戻します。エラーの発生に応じて、LDAPセッション・ハンドルのエラー・パラメータが設定されます。
ldap_msgfree()
は、res
パラメータが指し示す結果セット内の各メッセージを解放し、最後のメッセージのタイプを戻します。res
がNULL
の場合は何も処理されず、値0(ゼロ)が戻されます。
ldap_msgtype()
は、パラメータとして渡されるLDAPメッセージのタイプを戻します。タイプは、前述のタイプのいずれかか、エラーの場合は-1
です。
ldap_msgid()
は、パラメータとして渡されたLDAPメッセージに対応付けられているメッセージIDを戻します。エラーの場合は-1
を戻します。
8.16 結果の取得とLDAPメッセージの確認
この項のファンクションを使用して、非同期で開始した操作の結果を戻します。これらのファンクションは、メッセージを型およびIDで識別します。
8.16.1 ldap_result、ldap_msgtypeおよびldap_msgid
ldap_result()
を使用して、非同期に開始した前回の操作の結果を取得します。コールの方法によって、ldap_result()
が実際に戻す値が結果メッセージのリストの場合とチェーンの場合があることに注意してください。ldap_result()
ファンクションは単一リクエストに対するメッセージのみを返します。検索以外のすべてのLDAP操作で想定されている結果メッセージは1つのみです。つまり、結果チェーンが複数のメッセージを格納できるのは、検索操作のからの結果が戻された場合のみです。
コール元に戻された結果セットは、そのセットを生成したLDAPリクエストとの関連をコール元で表示する方法はありません。したがって、ldap_result()
または同期検索ルーチンをコールして戻された結果セットは、後続のLDAP APIコールの影響を受けることはありません(結果セットを解放するldap_msgfree()
は除きます)。
ldap_msgfree()
は、ldap_result()
または同期検索ルーチンをコールして前に取得した結果メッセージ(結果セット全体の場合もあります)を解放します。
ldap_msgtype()
はLDAPメッセージのタイプを戻します。ldap_msgid()
はLDAPメッセージのメッセージIDを戻します。
構文
int ldap_result (
LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **res
); int ldap_msgfree( LDAPMessage *res ); int ldap_msgtype( LDAPMessage *res ); int ldap_msgid( LDAPMessage *res );
パラメータ
表8-22に、結果の取得とLDAPメッセージの確認のためのパラメータをリストし、説明します。
表8-22 LDAPメッセージ・ファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
msgid |
結果が戻される操作のメッセージID、定数 |
all |
1回の |
timeout |
結果の戻りに対する待機時間を指定するタイムアウトです。 |
res |
|
使用上のノート
正常終了すると、ldap_result()
は戻された最初の結果のタイプをres
パラメータに戻します。次のいずれかの定数が戻されます。
LDAP_RES_BIND (0x61)
LDAP_RES_SEARCH_ENTRY (0x64)
LDAP_RES_SEARCH_REFERENCE (0x73)
- LDAP v3の新規定数
LDAP_RES_SEARCH_RESULT (0x65)
LDAP_RES_MODIFY (0x67)
LDAP_RES_ADD (0x69)
LDAP_RES_DELETE (0x6B)
LDAP_RES_MODDN (0x6D)
LDAP_RES_COMPARE (0x6F)
LDAP_RES_EXTENDED (0x78)
-- LDAP v3の新規定数
ldap_result()
は、タイムアウトを超過した場合は0
(ゼロ)を、エラーが発生した場合は-1
を戻します。エラーの発生に応じて、LDAPセッション・ハンドルのエラー・パラメータが設定されます。
ldap_msgfree()
は、res
パラメータが指し示す結果セット内の各メッセージを解放し、最後のメッセージのタイプを戻します。res
がNULL
の場合は何も処理されず、値0(ゼロ)が戻されます。
ldap_msgtype()
は、パラメータとして渡されるLDAPメッセージのタイプを戻します。タイプは、前述のタイプのいずれかか、エラーの場合は-1
です。
ldap_msgid()
は、パラメータとして渡されたLDAPメッセージに対応付けられているメッセージIDを戻します。エラーの場合は-1
を戻します。
8.17 エラーの処理と結果の解析
結果から情報を抽出し、他のLDAP APIルーチンによって戻されたエラーを処理できます。ldap_parse_sasl_bind_result()
およびldap_parse_extended_result()
は、通常、ldap_parse_result()
とともに使用して、SASLバインド操作および拡張操作の結果情報をそれぞれ取得することに注意してください。
ldap_parse_result()
、ldap_parse_sasl_bind_result()
およびldap_parse_extended_result()
の各ファンクションは、解析する結果メッセージの検索時に、メッセージ・タイプのLDAP_RES_SEARCH_ENTRY
およびLDAP_RES_SEARCH_REFERENCE
をスキップします。これらのファンクションは、結果が正常に解析された場合は定数LDAP_SUCCESS
を、失敗した場合は別のLDAPエラー・コードを戻します。サーバーで実行された操作の結果を示すLDAPエラー・コードは、ldap_parse_result()
のerrcodepパラメータに格納されることに注意してください。複数の結果メッセージが含まれた結果セットがこれらのルーチンに渡されている場合、これらのルーチンは、常にその結果セット内の最初の結果から操作を開始します。
ldap_err2string()
は、ldap_parse_result()
、ldap_parse_sasl_bind_result()
、ldap_parse_extended_result()
またはAPI操作の同期コールの1つから戻された数値のLDAPエラー・コードを、エラーを説明するゼロ終了文字列メッセージに変換するために使用されます。このファンクションは、静的データへのポインタを戻します。
8.17.1 ldap_parse_result、ldap_parse_extended_result、ldap_result2error
ファンクションldap_parse_result
、ldap_parse_extended_result
およびldap_result2error
は、エラーの処理に使用されます。
構文
int ldap_parse_result (
); LDAP *ld, LDAPMessage *res, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit
int ldap_parse_sasl_bind_result (
LDAP *ld, LDAPMessage *res, struct berval **servercredp, int freeit
);
int ldap_parse_extended_result (
LDAP *ld, LDAPMessage *res, char **retoidp, struct berval **retdatap, int freeit
); #define LDAP_NOTICE_OF_DISCONNECTION "1.3.6.1.4.1.1466.20036" char *ldap_err2string( int err );
次のルーチンは非推奨です。それらについてさらに学習するには、RFC 1823を参照してください。
int ldap_result2error (
LDAP *ld, LDAPMessage *res, int freeit
); void ldap_perror( LDAP *ld, const char *msg );
パラメータ
表8-23に、エラーの処理と結果の解析を行うためのパラメータをリストし、説明します。
表8-23 エラーの処理と結果の解析のファンクションのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
res |
|
errcodep |
この結果パラメータには、 |
matcheddnp |
|
errmsgp |
この結果パラメータには、 |
referralsp |
この結果パラメータには、 |
serverctrlsp |
この結果パラメータには、 |
freeit |
|
servercredp |
SASLバインド結果に関するこの結果パラメータには、相互認証が指定されている場合、サーバーから戻された資格証明が入力されます。割り当てられた |
retoidp |
拡張操作の結果に関するこの結果パラメータには、拡張操作のレスポンス名のドット区切りのOIDテキスト表現が入力されます。この文字列は |
retdatap |
拡張操作の結果に関するこの結果パラメータには、拡張操作のレスポンス・データが含まれる |
err |
|
使用上のノート
非推奨のルーチンに固有のパラメータについては、RFC 1823を参照してください。
8.18 結果リストの参照
ldap_result()
を使用すると、結果チェーンでメッセージのリストが戻されます。
検索操作の結果セットには、参照メッセージ、エントリ・メッセージおよび結果メッセージを格納できます。
ldap_count_messages()
は、戻されたメッセージの件数をカウントします。前述のldap_msgtype()
ファンクションを使用すると、異なるメッセージ・タイプを区別できます。
8.18.1 ldap_first_message、ldap_next_message、ldap_count_messages
ldap_first_message()
およびldap_next_message()
は、戻される結果セットにこれ以上メッセージが存在しない場合にNULL
を戻します。
構文
LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg ); int ldap_count_messages( LDAP *ld, LDAPMessage *res );
パラメータ
表8-24に、結果リストを参照するためのパラメータをリストし、説明します。
表8-24 結果リストを参照するためのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
res |
同期検索ルーチンのいずれか、または |
msg |
|
使用上のノート
エントリの参照中にエラーが発生した場合はNULL
が戻されます。この場合セッション・ハンドルIDのエラー・パラメータがエラーを示すように設定されます。
正常終了した場合、ldap_count_messages()
は、結果のチェーンに格納されたメッセージ数を戻します。resパラメータが無効などのエラーが発生した場合は-1
が戻されます。ldap_first_message()
, ldap_next_message()
, ldap_first_entry()
, ldap_next_entry()
, ldap_first_reference()
, ldap_next_reference()
によって戻されたメッセージ、エントリまたはリファレンスとともにコールした場合、ldap_count_messages()
コールを使用してチェーンに残っているメッセージ数をカウントすることもできます。
8.19 検索結果の解析
ldap_search()
ファンクションで戻されるエントリやリファレンスを解析できます。
これらの結果は、この項で説明するルーチンをコールしてアクセスできる不透明な構造体に戻されます。これらのルーチンは、戻されたエントリやリファレンスの参照、エントリの属性の参照、エントリ名の取得、およびエントリ内の指定した属性に対応付けられている値の取得を行うために用意されています。これらの関数については、次の各項で説明します。
8.19.1 ldap_first_entry、ldap_next_entry、ldap_first_reference、ldap_next_reference、ldap_count_entriesおよびldap_count_references
ldap_first_entry()
およびldap_next_entry()
ルーチンは、検索結果チェーンからのエントリのリストの参照および取得に使用されます。
ldap_first_reference()
およびldap_next_reference()
ルーチンを使用して、検索結果チェーンからの継続リファレンスのリストの参照および取得を行います。ldap_count_entries()
を使用して戻されたエントリ数をカウントします。ldap_count_references()
を使用して戻されたリファレンス数をカウントします。
構文
LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); int ldap_count_entries( LDAP *ld, LDAPMessage *res ); int ldap_count_references( LDAP *ld, LDAPMessage *res );
パラメータ
表8-25に、エントリと継続リファレンスを検索結果セットから取得したり、戻されたエントリの件数をカウントするためのパラメータをリストし、説明します。
表8-25 エントリと継続リファレンスを検索結果セットから取得したり、戻されたエントリの件数をカウントするためのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
res |
検索結果です。同期検索ルーチンのいずれか、または |
entry |
|
ref |
|
使用上のノート
ldap_first_entry()
、ldap_next_entry()
、ldap_first_reference()
およびldap_next_reference()
はすべて、戻される結果セットにこれ以上エントリまたはリファレンスが存在しない場合にNULL
を戻します。エントリまたはリファレンスの参照中にエラーが発生した場合もNULL
が戻されます。この場合、セッション・ハンドルld
のエラー・パラメータがエラーを示すように設定されます。
ldap_count_entries()
は、エントリのチェーンに含まれるエントリの数を戻します。res
パラメータが無効などのエラーが発生した場合、-1
が戻されます。ldap_first_message()
, ldap_next_message()
, ldap_first_entry()
, ldap_next_entry()
, ldap_first_reference()
, ldap_next_reference()
によって戻されたメッセージ、エントリまたはリファレンスとともにコールした場合、ldap_count_entries()
コールを使用してチェーンに残っているエントリの数をカウントすることもできます。
ldap_count_references()
は検索結果のチェーンに含まれるリファレンスの数を戻します。res
パラメータが無効などのエラーが発生した場合は-1
が戻されます。ldap_count_references()
コールを使用してチェーンに残っているリファレンス数をカウントすることもできます。
8.19.2 ldap_first_attributeおよびldap_next_attribute
ldap_first_attribute()
およびldap_next_attribute()
は、属性の最後に達したり、エラーが発生した場合に、NULLを戻します。後者の場合は、そのエラーを示すためにセッション・ハンドルldのエラー・パラメータが設定されます。
この項のファンクションを使用して、エントリとともに戻される属性の型のリストを参照します。
構文
char *ldap_first_attribute (
LDAP *ld, LDAPMessage *entry, BerElement **ptr
); char *ldap_next_attribute (
LDAP *ld, LDAPMessage *entry, BerElement *ptr
); void ldap_memfree( char *mem );
パラメータ
表8-26に、エントリとともに戻される属性の型を参照するためのパラメータを示します。
表8-26 エントリとともに戻される属性の型を参照するためのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
entry |
属性を参照する対象となるエントリです。 |
ptr |
|
mem |
|
使用上のノート
ldap_first_attribute()
とldap_next_attribute()
のルーチンは、現行の属性名が格納されている割当て済バッファへのポインタを戻します。不要になった場合は、ldap_memfree()
をコールして解放する必要があります。
ldap_first_attribute()
は、現在の位置の追跡に使用されるBerElement
へのポインタをptr
に割り当て、戻します。このポインタを後続のldap_next_attribute()
コールに渡し、エントリの属性を参照できます。ldap_first_attribute()
およびldap_next_attribute()
の一連のコールの後、ptr
がnull以外の場合、ber_free(ptr, 0)
をコールしてこれを解放する必要があります。BerElement
に関連付けられたバッファが別に割り当てられたメモリーを示さないため、このコールで2つ目のパラメータを0
(ゼロ)として渡すことが非常に重要です。
戻された属性の型の名前は、関連する値を取り出すためのldap_get_values()
や関連するファンクションのコールに渡すのに適しています。
8.19.3 ldap_get_values、ldap_get_values_len、ldap_count_values、ldap_count_values_len、ldap_value_freeおよびldap_value_free_len
ldap_get_values()
およびldap_get_values_len()
を使用して、指定した属性の値をエントリから取得します。ldap_count_values()
およびldap_count_values_len()
を使用して、戻された値をカウントします。
ldap_value_free()
およびldap_value_free_len()
は、値を解放します。
構文
char **ldap_get_values (
LDAP *ld, LDAPMessage *entry, const char *attr
); struct berval **ldap_get_values_len (
LDAP *ld, LDAPMessage *entry, const char *attr
); int ldap_count_values( char **vals ); int ldap_count_values_len( struct berval **vals ); void ldap_value_free( char **vals ); void ldap_value_free_len( struct berval **vals );
パラメータ
表8-27に、属性値を取得してその件数をカウントするためのパラメータをリストし、説明します。
表8-27 属性値を取得してその件数をカウントするためのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
entry |
値を取得する元のエントリです。 |
attr |
値を取得する対象となる属性です。 |
vals |
|
使用上のノート
2つの形式のコールが用意されています。最初の形式は、バイナリ以外の文字列データに対してのみ使用できます。_len
が付く2番目の形式は、あらゆる種類のデータで使用できます。
ldap_get_values()
およびldap_get_values_len()
は、attr
に値がない場合またはエラーが発生した場合、NULL
を戻します。
ldap_count_values()
およびldap_count_values_len()
は、vals
パラメータが無効などのエラーが発生した場合、-1
を戻します。
NULL
のvals
パラメータがldap_value_free()
またはldap_value_free_len()
に渡された場合、何も処理されません。
戻された値は動的に割り当てられます。不要になった場合は、ldap_value_free()
またはldap_value_free_len()
をコールして解放する必要があります。
8.19.4 ldap_get_dn、ldap_explode_dn、ldap_explode_rdnおよびldap_dn2ufn
ldap_get_dn()
は、エントリの名前の取得に使用されます。ldap_explode_dn()
およびldap_explode_rdn()
は、名前の構成要素への分割に使用されます。ldap_dn2ufn()
は、名前をわかりやすい形式に変換するために使用されます。
構文
char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); char **ldap_explode_dn( const char *dn, int notypes ); char **ldap_explode_rdn( const char *rdn, int notypes ); char *ldap_dn2ufn( const char *dn );
パラメータ
表8-28に、エントリ名を取得、分割および変換するためのパラメータをリストし、説明します。
表8-28 エントリ名を取得、分割および変換するためのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
entry |
名前を取得する対象となるエントリです。 |
dn |
|
rdn |
|
notypes |
ブール値パラメータです。0(ゼロ)以外の場合は、識別名または相対識別名の構成要素から型情報が削除されることを示します。つまり、 |
使用上のノート
識別名解析エラーが発生した場合、ldap_get_dn()
はNULL
を戻します。ファンクションはセッション・ハンドルld
にエラー・パラメータを設定し、エラーを示します。新規に割り当てられた領域へのポインタを戻します。この領域は不要になった際にコール元がldap_memfree()
をコールして解放する必要があります。
notypes
パラメータで示されたタイプの有無にかかわらず、ldap_explode_dn()
は指定されたDNのRDNコンポーネントを含むNULL
終了char *
配列を戻します。コンポーネントはDNに指定されている順序で戻されます。この戻された配列が不要になった場合は、ldap_value_free()
をコールして解放する必要があります。
notypes
パラメータで示されたタイプの有無にかかわらず、ldap_explode_rdn()
は、指定されたRDNのコンポーネントを含むNULL
終了char *
配列を戻します。コンポーネントはRDNに指定されている順序で戻されます。この戻された配列が不要になった場合は、ldap_value_free()
をコールして解放する必要があります。
ldap_dn2ufn()
はDNをユーザーにわかりやすい形式に変換します。戻されたUFNは新規に割り当てられた領域です。この領域は不要になった際、ldap_memfree()
コールにより解放する必要があります。
8.19.5 ldap_get_entry_controls
ldap_get_entry_controls()
は、LDAPコントロールをエントリから抽出します。
構文
int ldap_get_entry_controls (
LDAP *ld, LDAPMessage *entry, LDAPControl ***serverctrlsp
);
パラメータ
表8-29に、LDAPコントロールをエントリから抽出するためのパラメータを示します。
表8-29 LDAPコントロールをエントリから抽出するためのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
entry |
コントロールを抽出する元のエントリです。 |
serverctrlsp |
この結果パラメータには、エントリからコピーされたコントロールの割当て済配列が入力されます。このコントロール配列は、 |
使用上のノート
ldap_get_entry_controls()
は、リファレンスが正常に解析されたかどうかを示すLDAPエラー・コードを戻します(正常終了の場合はLDAP_SUCCESS
)。
8.19.6 ldap_parse_reference
ldap_parse_reference()
を使用して、参照およびコントロールをSearchResultReference
メッセージから抽出します
構文
int ldap_parse_reference (
LDAP *ld, LDAPMessage *ref, char ***referralsp, LDAPControl ***serverctrlsp, int freeit
);
パラメータ
表8-30に、参照とコントロールをSearchResultReference
メッセージから抽出するためのパラメータをリストし、説明します。
表8-30 参照とコントロールをSearchResultReferenceメッセージから抽出するためのパラメータ
パラメータ | 説明 |
---|---|
ld |
セッション・ハンドルです。 |
ref |
解析するリファレンスです。 |
referralsp |
この結果パラメータには、文字列の割当て済配列が入力されます。配列の要素は、refに格納されている参照(通常はLDAP URL)です。この配列が不要になった場合は、 |
serverctrlsp |
この結果パラメータには、 |
freeit |
|
使用上のノート
ldap_parse_reference()
は、リファレンスが正常に解析されたかどうかを示すLDAPエラー・コードを戻します(正常終了の場合はLDAP_SUCCESS
)。