8 C APIリファレンス

Oracle Internet DirectoryのC APIでは、Oracleの拡張機能を使用してSSLをサポートします。

次の各トピックでは、Oracle Internet DirectoryのC APIについて説明し、そのAPIの使用例を示します。

• Oracle Internet DirectoryのC APIの概要

• C APIのファンクションの概要

• C APIの使用例

• C APIを使用するためのヘッダー・ファイルおよびライブラリの実装

• C APIの依存性と制限事項

Oracle Internet DirectoryのC APIの概要

Oracle Internet Directory SDK C APIは、LDAPバージョン3 C API、およびSSLをサポートするOracleの拡張機能をベースにしています。

次の各トピックでは、Oracle Internet DirectoryのC APIについて説明します。

• Oracle Internet Directoryのモードの理解

• Oracle Internet Directory SDK C API SSL拡張機能の理解

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の使用例」を参照してください。

Oracle Internet Directory SDK C API SSL拡張機能の理解

LDAP APIへのOracle SSL拡張機能は、標準的なSSLプロトコルに基づいています。SSL拡張機能は回線を通るデータの暗号化と復号化および認証を行います。

認証には次の3つのモードがあります。

• 認証なし: クライアントとサーバーのどちらも認証せず、SSLによる暗号化のみを使用します。

• 一方向: クライアントによりサーバーのみが認証されます。

• 双方向: サーバーとクライアントが相互に認証します。

認証のタイプは、SSLインタフェース・コールのパラメータで指定します。次の各項で、これを簡単に説明します。

• SSLを使用可能にするインタフェース・コール

• ウォレットのサポートについて

SSLを使用可能にするインタフェース・コール

次のコールを行うのみで、SSLは使用可能になります。

int ldap_init_SSL(Sockbuf *sb, char *sslwallet, char *sslwalletpasswd, int sslauthmode)

ldap_init_SSLコールは、標準的なSSLプロトコルを使用して、クライアントとサーバーの間で必要なハンドシェイクを実行します。コールが成功すると、これ以降のすべての通信は保護された接続で実行されます。

表8-1 SSLインタフェース・コールの引数

引数	説明
sb	LDAPハンドルの一部として、ldap_openコールによって戻されたソケット・バッファ・ハンドル。
sslwallet	ユーザー・ウォレットの位置。
sslwalletpasswd	ウォレットを使用するために必要なパスワード。
sslauthmode	ユーザーが使用できるSSL認証モード。使用できる値は次のとおりです。 GSLC_SSL_NO_AUTH: 認証の必要なし GSLC_SSL_ONEWAY_AUTH: サーバー認証のみ必要。 GSLC_SSL_TWOWAY_AUTH: サーバーとクライアントの両方の認証が必要。 戻り値が0(ゼロ)のときは、処理は成功です。戻り値が0(ゼロ)以外のときは、エラーです。エラー・コードは、ldap_err2stringファンクションを使用してエラー・メッセージに変換できます。

関連項目:

C APIの使用例

ウォレットのサポートについて

使用される認証モードによっては、サーバーおよびクライアントの両方でSSL機能を使用するためのウォレットが必要になる場合があります。このAPIは、Oracle Walletのみサポートしています。Oracle Wallet Managerを使用してウォレットを作成できます。

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で使用可能なすべてのコールを示します。

関連項目:

各コールの詳細は、次のURLを参照してください。

http://www.ietf.org

C APIの使用例

最初の3つの例では、SSLと組み合せてC APIを使用する方法、SSLを使用せずにC APIを使用する方法およびSASL認証にC APIを使用する方法を示します。より完全な例は、RFC 1823を参照してください。また、LDAP検索を実行するコマンドライン・ツールのサンプル・コードも、SSLモードおよび非SSLモードでのAPIの使用方法を示します。

次の各トピックでは、C APIの使用方法について説明します。

• SSLを使用するC APIの使用方法

• SSLを使用しないC APIの使用方法

• SASLベースのDigest-MD5認証でのC APIの使用方法

• 参照の追跡時に資格証明を得るためのコールバック・ファンクションの設定と使用

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 );
}

.
.
.

}

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 );
}
.
.
.

}

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 */

参照の追跡時に資格証明を得るためのコールバック・ファンクションの設定と使用

コールバック・ファンクションを設定するには、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);
}

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オペレーティング・システムの場合)

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プログラマーズ・ガイド』を参照してください。

LDAPセッションの初期化と使用方法

コールによって、LDAPサーバーとのセッションが初期化されます。

次の各項では、LDAPセッションと使用方法について説明します。

• ldap_initおよびldap_open

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アドレスは、大カッコ([])で囲む必要があります。次に、有効なhostnameの値の例を示します。 host1.example.com 192.168.1.10 [2002:ae5:4000:1::8c57:352] host1.example.com:3060 192.168.1.10:3060 [2002:ae5:4000:1::8c57:352]:3060
portno	接続先のTCPポート番号が入ります。デフォルトのLDAPポート3060は、定数LDAP_PORTを指定することで取得できます。hostnameにポート番号が含まれている場合、portnoは無視されます。

使用方法

ldap_init()およびldap_open()の戻り値はセッション・ハンドルです。これは、そのセッションに関連する後続のコールに渡す必要がある不透明な構造体へのポインタです。これらのルーチンは、セッションが初期化できない場合にNULLを戻します。セッションが初期化できない場合、オペレーティング・システムのエラー・レポート・メカニズムをチェックし、コールに失敗した理由を確認してください。

LDAP v2サーバーに接続する場合は、後述するLDAPバインド・コールの1つをセッションで完了してから、他の操作を実行する必要があることに注意してください。LDAP v3では、他の操作を実行する前にバインド操作を完了する必要はありません。

コール元プログラムでは、次の項で説明するルーチンを呼び出して、セッションの様々な属性を設定できます。

LDAPセッション・ハンドル・オプション

ldap_init()で戻されたLDAPセッション・ハンドルは、LDAPセッションを表す不透明なデータ型へのポインタです。RFC 1823では、このデータ型はコール元に公開されていた構造体で、構造体のフィールドを設定すると、検索時のサイズや時間の制限などセッションの様々な側面を制御できました。

現在は、コール元でこの構造体に対する重要な変更を行わないように、この項で説明する1組のアクセッサ・ファンクションによってセッションの様々な側面を制御できます。

• ldap_get_optionおよびldap_set_option

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	セッション・ハンドルです。これがNULLの場合は、一連のグローバル・デフォルト値にアクセスします。ldap_init()またはldap_open()を使用して作成された新規のLDAPセッション・ハンドルは、これらのグローバル・デフォルト値の特性を継承します。
option	アクセスまたは設定するオプションの名前です。このパラメータは、表8-5に示す定数のいずれかであることが必要です。定数の後に、その定数の16進値をカッコで囲んで記述します。
outvalue	オプションの値を配置する位置のアドレスです。このパラメータの実際の型は、optionパラメータの設定値によって異なります。outvalueパラメータがchar **型およびLDAPControl **型の場合は、LDAPセッションldに対応付けられているデータのコピーが戻されます。コール元では、戻されたデータの型に従ってldap_memfree()またはldap_controls_free()をコールし、メモリーを解放する必要があります。
invalue	optionパラメータに指定する値へのポインタです。このパラメータの実際の型は、optionパラメータの設定値によって異なります。invalueパラメータに関連付けられたデータはAPI実装によってコピーされるため、APIのコール元はデータを解放するか、ldap_set_option()のコールが正常終了した後にそのデータのコピーを変更できます。invalueパラメータに渡された値が無効な場合、または実装で受け入れることができない場合、ldap_set_option()は-1を戻してエラーの発生を示す必要があります。

定数

表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 *	このオプションは参照キャッシュが有効か無効かを示します。このオプションがLDAP_OPT_ONに設定されている場合、キャッシュは有効です。それ以外の場合、キャッシュは無効です。
ORA_LDAP_OPT_RFRL_CACHE_SZ	int *	int *	このオプションは、参照キャッシュのサイズを指定します。サイズは、キャッシュを大きくできるバイト数の最大サイズです。デフォルトで1MBが設定されます。
LDAP_OPT_DEREF(0x02)	int *	int *	検索時の別名の処理方法を判断します。LDAP_DEREF_NEVER (0x00)、LDAP_DEREF SEARCHING (0x01)、LDAP_DEREF_FINDING (0x02)またはLDAP_DEREF_ALWAYS (0x03)のいずれかの値を持ちます。LDAP_DEREF_SEARCHING値の場合、別名は検索時に参照解除されますが、検索のベース・オブジェクトの検索時は参照解除されません。LDAP_DEREF_FINDING値の場合、別名はベース・オブジェクトの検索時に参照解除されますが、検索時は参照解除されません。このオプションのデフォルト値はLDAP_DEREF_NEVERです。
LDAP_OPT_SIZELIMIT(0x03)	int *	int *	検索で戻されるエントリの最大数です。LDAP_NO_LIMIT (0)値は上限がないことを意味します。このオプションのデフォルト値はLDAP_NO_LIMITです。
LDAP_OPT_TIMELIMIT(0x04)	int *	int *	検索を実行する最大秒数です。LDAP_NO_LIMIT (0)値は上限がないことを意味します。この値は検索リクエスト時のみサーバーに渡され、C LDAP API実装がローカルで検索結果を待機する時間には影響を与えません。ldap_search_ext_s()またはldap_result()(このマニュアルで後述)に渡されたtimeoutパラメータを使用すると、ローカル側とサーバー側の制限時間を指定できます。このオプションのデフォルト値はLDAP_NO_LIMITです。
LDAP_OPT_REFERRALS(0x08)	void *(LDAP_OPT_ON) void *(LDAP_OPT_OFF)	int *	LDAPライブラリが、LDAPサーバーで戻された参照に自動的に従うかどうかを判断します。定数のLDAP_OPT_ONまたはLDAP_OPT_OFFに設定できます。このオプションは、ldap_set_option()に渡されるNULL以外のポインタ値によって有効になります。ldap_get_option()を使用して現在の設定値を読み込むとき、0(ゼロ)値はオフ、0(ゼロ)以外の値はオンを意味します。このオプションはデフォルトでオンになっています。
LDAP_OPT_RESTART(0X09)	void * (LDAP_OPT_ON) void * (LDAP_OPT_OFF)	int *	LDAPの入出力操作が未完了のまま停止したとき、自動的に再起動するかどうかを判断します。LDAP_OPT_ONまたはLDAP_OPT_OFFに設定できます。このオプションは、ldap_set_option()に渡されるNULL以外のポインタ値によって有効になります。ldap_get_option()を使用して現在の設定値を読み込むとき、0(ゼロ)値はオフ、0(ゼロ)以外の値はオンを意味します。このオプションは、タイマーの停止などによって、入出力操作が未完了のまま中断する可能性がある場合に便利です。このオプションはデフォルトでオフになっています。
LDAP_OPT_PROTOCOL_VERSION(0x11)	int *	int *	このオプションは、プライマリLDAPサーバーとの通信時に使用するLDAPプロトコルのバージョンを示します。LDAP_VERSION2 (2)またはLDAP_VERSION3 (3)に設定します。バージョンが設定されていない場合のデフォルトは、LDAP_VERSION2 (2)です。
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_init()に対するhostnameパラメータの定義を参照してください。
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_openをコールする前に設定する必要があります。有効な値は、0から300秒です。値が0(ゼロ)に設定されている場合、タイムアウトはデフォルトのTCPタイムアウトです。このオプションが設定されていない場合、ホストにアクセスできないとldap_open()コールは15秒でタイムアウトになります。

使用方法

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 */

参照を追跡するためのバインド資格証明の取得

ldap_set_rebind_proc()ファンクションは、参照の追跡時、新しいサーバーのバインド資格証明の取得に使用されます。

ldap_set_rebind_proc()ファンクションは、LDAP参照の追跡時に新しいサーバーに接続するためのバインド資格証明をライブラリで取得するために使用するコールバック・ファンクションの設定に使用されます。ライブラリでは、ldap_set_option()を使用してLDAP_OPT_REFERRALSが設定されている場合にのみコールバック・ファンクションを使用します。ldap_set_rebind_proc()がコールされていない場合、LDAP参照の追跡時、ライブラリでは新しいサーバーへの接続に匿名バインドを使用します。

関連項目:

LDAPセッション・ハンドル・オプション

ldap_set_rebind_proc()

ldap_set_rebind_proc()ファンクションは、参照の追跡時、新しいサーバーのバインド資格証明の取得に使用されます。

ldap_set_rebind_proc()ファンクションは、LDAP参照の追跡時に新しいサーバーに接続するためのバインド資格証明をライブラリで取得するために使用するコールバック・ファンクションの設定に使用されます。ライブラリでは、ldap_set_option()を使用してLDAP_OPT_REFERRALSが設定されている場合にのみコールバック・ファンクションを使用します。ldap_set_rebind_proc()がコールされていない場合、LDAP参照の追跡時、ライブラリでは新しいサーバーへの接続に匿名バインドを使用します。

関連項目:

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	0 - 新しいサーバーに対するバインド識別名ポインタ、バインド・パスワード・ポインタおよびバインド認証方法ポインタを戻します。 1 - 以前のコールで割り当てられたメモリーを解放します

使用方法

freeitパラメータの値が0の場合、rebindprocは必ずバインド識別名ポインタ、バインド・パスワード・ポインタおよびバインド認証方法ポインタを戻します。freeitパラメータの値が1の場合、rebindprocは前回のコールで割り当てられたすべてのメモリーを解放します。LDAPライブラリはこのファンクションを2回コールします。1回目で資格証明をバインドし、2回目でメモリーを解放します。

関連項目:

参照の追跡時に資格証明を得るためのコールバック・ファンクションの設定と使用

ディレクトリに対する認証

LDAPバインド・ファンクションを使用して、LDAPディレクトリ・サーバーに対してLDAPクライアントを認証できます。

この項のファンクションを使用して、次の各項で説明するLDAPディレクトリ・サーバーに対するLDAPクライアントの認証を行います。

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	LDAP_SASL_SIMPLE (NULL)を指定して簡易認証を取得するか、SASLメソッドを識別するテキスト文字列を指定します。
cred	認証に使用する資格証明です。このパラメータを使用すると、任意の資格証明を渡すことができます。資格証明の書式と内容は、mechanismパラメータの設定内容によって異なります。
passwd	ldap_simple_bind()の場合に、エントリのuserPassword属性と比較するパスワードです。
serverctrls	LDAPサーバー・コントロールのリストです。
clientctrls	クライアント・コントロールのリストです。
msgidp	ldap_sasl_bind()コールが正常終了した場合は、この結果パラメータがリクエストのメッセージIDに設定されます。

使用方法

非推奨のルーチンに関するその他のパラメータは説明していません。詳細は、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処理を実行できます。

関連項目:

エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。

Oracleの拡張機能を使用したSASL認証

SASL認証を実行するには、ora_ldap_init_SASLファンクションを使用します。

この項では、次の項目について説明します。

• ora_ldap_init_SASL

• ora_ldap_create_cred_hdl、ora_ldap_set_cred_props、ora_ldap_get_cred_propsおよびora_ldap_free_cred_hdl

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のクライアント・コンテキストです。これは、ora_ldap_init_clientctx()およびora_ldap_free_clientctx()ファンクションを使用して管理できます。
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接続のユーザー資格証明に基づいてユーザーを認証します。

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のクライアント・コンテキストです。これは、ora_ldap_init_clientctx()およびora_ldap_free_clientctx()ファンクションを使用して管理できます。
credType	SASLメカニズム固有の資格証明ハンドルのタイプです。
cred	SASL認証のための固有のSASLメカニズムに必要なSASL資格証明を含む資格証明ハンドルです。
String[]	資格証明ハンドルに追加する必要がある資格証明のタイプです。
inProperty	資格証明ハンドルに格納されるSASL資格証明の1つです。
outProperty	資格証明ハンドルに格納されたSASL資格証明の1つです。

使用方法

なし

コントロールの使用

コントロールを使用すると、LDAP v3操作を拡張できます。コントロールは、サーバーに送信したり、LDAPメッセージとともにクライアントに戻すことができます。このようなコントロールは、サーバー・コントロールと呼ばれます。

LDAP APIは、クライアント・コントロールを使用してクライアント側の拡張メカニズムもサポートします。このコントロールは、LDAP APIの動作にのみ影響し、サーバーに送信されることはありません。

両方のタイプのコントロールを表現するため、次の共通のデータ構造が使用されます。

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_value.bv_lenを0(ゼロ)に設定し、ldctl_value.bv_valを長さ0(ゼロ)の文字列に設定します。コントロールに対応付けられたデータがないことを示すには、ldctl_value.bv_valをNULLに設定します。
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管理者ガイドのディレクトリ・スキーマの管理の項を参照してださい。

セッションのクローズ

LDAPファンクションを使用して、接続をバインド解除、クローズおよびオープンできます。

次のファンクションを使用して、ディレクトリからバインドを解除し、オープンしている接続をクローズして、セッション・ハンドルを解放します。

• ldap_unbind

• ldap_unbind_ext

• ldap_unbind_s

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	クライアント・コントロールのリストです。

使用方法

なし

LDAP操作の実行

LDAP操作を使用して、LDAPディレクトリの検索、比較および変更を実行します。

この項のファンクションを使用してLDAPディレクトリを検索し、一致した各エントリについてリクエストされた属性セットを戻します。

• ldap_search_ext、ldap_search_ext_s、ldap_searchおよびldap_search_s

• ldap_compare_ext、ldap_compare_ext_s、ldap_compareおよびldap_compare_s

• ldap_modify_ext、ldap_modify_ext_s、ldap_modifyおよびldap_modify_s

• ldap_renameおよびldap_rename_s

• ldap_add_ext、ldap_add_ext_s、ldap_addおよびldap_add_s

• ldap_delete_ext、ldap_delete_ext_s、ldap_deleteおよびldap_delete_s

• ldap_extended_operationおよびldap_extended_operation_s

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	LDAP_SCOPE_BASE (0x00)、LDAP_SCOPE_ONELEVEL (0x01)またはLDAP_SCOPE_SUBTREE (0x02)のいずれかで、検索範囲を指定します。
filter	検索フィルタを表す文字列です。この値をNULLにすると、すべてのエントリに一致するフィルタ"(objectclass=*)"を使用するように指定できます。APIのコール元でLDAP v2を使用している場合、正常に使用できるのはフィルタ機能のサブセットのみであることに注意してください。
attrs	一致した各エントリのどの属性を戻すかを指定する文字列のNULL終了配列です。このパラメータをNULLにすると、取得可能なユーザー属性がすべて取り出されます。文字列LDAP_NO_ATTRS ("1.1")を配列内の唯一の文字列として使用すると、サーバーから属性の型を戻さないように指定できます。attrs配列の中で、文字列LDAP_ALL_USER_ATTRS ("*")をなんらかの操作属性名とともに使用すると、すべてのユーザー属性に加えて、リストした操作属性を戻すように指定できます。
attrsonly	属性の型と値の両方を戻す場合には0(ゼロ)、属性の型のみを要求する場合には0(ゼロ)以外を指定する必要があるブール値です。
timeout	ldap_search_st()ファンクションの場合は、このパラメータによって、ローカルの検索タイムアウト値を指定します(値がNULLの場合、タイムアウトは無限です)。タイムアウト値0(ゼロ)が渡されると(tv_secおよびtv_usecの両方が0(ゼロ))、API実装はLDAP_PARAM_ERRORを戻す必要があります。ldap_search_ext()ファンクションとldap_search_ext_s()ファンクションの場合は、timeoutパラメータによって、ローカルの検索タイムアウト値と検索リクエストでサーバーに送信される操作制限時間を指定します。timeoutパラメータにNULL値を渡すと、ローカルの無限検索タイムアウト値は使用されずに、LDAPセッション・ハンドルに格納されているグローバルなデフォルト・タイムアウト値(ldap_set_option()のLDAP_OPT_TIMELIMITパラメータで設定)がリクエストとともに送信されます。タイムアウト値0(ゼロ)が渡されると(tv_secおよびtv_usecの両方が0(ゼロ))、API実装はLDAP_PARAM_ERRORを戻す必要があります。tv_secの値は0(ゼロ)だが、tv_usecの値は0(ゼロ)以外の場合は、操作制限時間として1をLDAPサーバーに渡す必要があります。tv_secの値が0(ゼロ)以外の場合は、tv_secの値自体をLDAPサーバーに渡す必要があります。
sizelimit	ldap_search_ext()コールとldap_search_ext_s()コールの場合は、検索によって戻されるエントリの数をこのパラメータで制限します。LDAP_NO_LIMIT (0)値は上限がないことを意味します。
res	同期コールを行うとき、コールの終了時に検索結果が入る結果パラメータです。戻される結果がない場合、*resはNULLに設定されます。
serverctrls	LDAPサーバー・コントロールのリストです。
clientctrls	クライアント・コントロールのリストです。
msgidp	ldap_search_ext()コールが成功した場合、この結果パラメータはリクエストのメッセージIDに設定されます。セッション・ハンドルldには検索の実行方法に影響を与える可能性がある3つのオプションがあります。これには、次のようなものがあります。 LDAP_OPT_SIZELIMIT: 検索で戻されるエントリの最大数です。LDAP_NO_LIMIT (0)値は上限がないことを意味します。ldap_search_ext()ファンクションまたはldap_search_ext_s()ファンクションを使用する場合、セッション・ハンドルの値は無視されることに注意してください。 LDAP_OPT_TIMELIMIT;: 検索を実行する最大秒数です。LDAP_NO_LIMIT (0)値は上限がないことを意味します。ldap_search_ext()ファンクションまたはldap_search_ext_s()ファンクションを使用する場合、セッション・ハンドルの値は無視されることに注意してください。 LDAP_OPT_DEREF: LDAP_DEREF_NEVER (0x00)、LDAP_DEREF_SEARCHING (0x01)、LDAP_DEREF_FINDING (0x02)またはLDAP_DEREF_ALWAYS (0x03)のいずれかで、検索時の別名の処理方法を指定します。The LDAP_DEREF_SEARCHING値の場合、別名は検索時に参照解除されますが、検索のベース・オブジェクトの検索時は参照解除されません。LDAP_DEREF_FINDING値の場合、別名はベース・オブジェクトの検索時に参照解除されますが、検索時は参照解除されません。

使用方法

エントリの読取り

LDAPでは、読取り操作を直接サポートしていません。かわりに、この操作は、ベースを読み込むエントリの識別名に設定し、有効範囲をLDAP_SCOPE_BASEに設定し、さらにフィルタを"(objectclass=*)"またはNULLに設定した検索によってエミュレーションを行います。attrsパラメータには、戻される属性のリストが格納されます。

エントリの子のリスト表示

LDAPでは、リスト操作を直接サポートしていません。かわりに、この操作は、ベースをリスト表示するエントリの識別名に設定し、有効範囲をLDAP_SCOPE_ONELEVELに設定し、さらにフィルタを"(objectclass=*)"またはNULLに設定した検索によってエミュレーションを行います。パラメータattrsには、子エントリごとに戻される属性のリストが格納されます。

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	指定のエントリで検索された属性と照合して比較される属性値です。このパラメータは拡張ルーチンで使用され、struct bervalへのポインタとなるため、バイナリ値と比較できます。
value	比較の対象となる文字列の属性値で、ldap_compare()ファンクションとldap_compare_s()ファンクションで使用します。バイナリ値と比較する必要がある場合は、ldap_compare_ext()またはldap_compare_ext_s()を使用します。
serverctrls	LDAPサーバー・コントロールのリストです。
clientctrls	クライアント・コントロールのリストです。
msgidp	ldap_compare_ext()コールが正常終了した場合は、この結果パラメータがリクエストのメッセージIDに設定されます。

使用方法

なし

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	エントリに対する変更のNULL終了配列です。
serverctrls	LDAPサーバー・コントロールのリストです。
clientctrls	クライアント・コントロールのリストです。
msgidp	ldap_modify_ext()コールが正常終了した場合は、この結果パラメータがリクエストのメッセージIDに設定されます。

表8-15に、LDAPMod構造体のフィールドを示します。

表8-15 LDAPMod構造体のフィールド

フィールド	説明
mod_op	実行する変更操作です。LDAP_MOD_ADD (0x00)、LDAP_MOD_DELETE (0x01)またはLDAP_MOD_REPLACE (0x02)のいずれかになります。このフィールドは、mod_vals共用体に格納されている値のタイプも示します。mod_bvalues形式を選択するには、LDAP_MOD_BVALUES (0x80)との論理和をとります。それ以外の場合は、mod_values形式が使用されます。
mod_type	変更する属性の型です。
mod_vals	追加、削除または置換する値(存在する場合)。mod_valuesまたはmod_bvalues変数はいずれか1つのみ使用できます。これは、mod_opフィールドと定数LDAP_MOD_BVALUESのORを取ることによって選択されます。mod_valuesは、ゼロ終了文字列のNULL終了配列で、mod_bvaluesはイメージなどのバイナリ値を渡すのに使用されるberval構造体のNULL終了配列です。

使用方法

LDAP_MOD_ADD変更の場合は、指定の値がエントリに追加され、必要に応じて属性が作成されます。

LDAP_MOD_DELETE変更の場合は、指定の値がエントリから削除され、値がない場合は属性が削除されます。すべての属性を削除する場合は、mod_valsフィールドをNULLに設定できます。

LDAP_MOD_REPLACE変更の場合、属性は変更後にリストされた値を保持します。値は必要に応じて作成され、mod_valsフィールドがNULLの場合は削除されます。すべての変更はリストされた順序で実行されます。

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	新規の親または上位エントリ。このパラメータがNULLの場合、エントリのRDNのみ変更されます。ルート識別名は長さゼロの文字列""を渡して指定します。LDAPプロトコルのバージョン2を使用した場合、newparentパラメータは常にNULLです。それ以外の場合のサーバー動作は未定義です。
deleteoldrdn	newrdnが古い相対識別名と異なる場合、このパラメータは名前の変更ルーチンでのみ使用されます。このパラメータはブール値で、0(ゼロ)以外の場合は古い相対識別名が削除されたことを示し、0(ゼロ)の場合は、エントリの識別されない値として古い相対識別名が保持されていることを示します。
serverctrls	LDAPサーバー・コントロールのリストです。
clientctrls	クライアント・コントロールのリストです。
msgidp	ldap_rename()コールが正常終了した場合は、この結果パラメータがリクエストのメッセージIDに設定されます。

使用方法

なし

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	ldap_modify()に定義されているLDAPMod構造体を使用して指定されるエントリ属性です。mod_typeおよびmod_valsフィールドには必ず値が必要です。mod_opフィールドは、定数LDAP_MOD_BVALUESとのORが取られ、mod_vals共用体のmod_bvaluesケースの選択に使用されないかぎり、無視されます。
serverctrls	LDAPサーバー・コントロールのリストです。
clientctrls	クライアント・コントロールのリストです。
msgidp	ldap_add_ext()コールが正常終了した場合は、この結果パラメータがリクエストのメッセージIDに設定されます。

使用方法

追加操作を正常に行うためには、追加するエントリの親がすでに存在しているか、親が空(つまり、ルートの識別名と同じ)であることが必要です。

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	ldap_delete_ext()コールが正常終了した場合は、この結果パラメータがリクエストのメッセージIDに設定されます。

使用方法

削除するエントリは、リーフ・エントリ(つまり、子エントリがないエントリ)であることが必要です。1回の操作でサブツリー全体を削除する操作は、LDAPではサポートされていません。

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	操作に必要な任意のデータです(NULLの場合、サーバーにデータは送信されません)。
serverctrls	LDAPサーバー・コントロールのリストです。
clientctrls	クライアント・コントロールのリストです。
msgidp	ldap_extended_operation()コールが正常終了した場合は、この結果パラメータがリクエストのメッセージIDに設定されます。
retoidp	サーバーによって戻されたドット区切りの割当て済OIDテキスト文字列に設定された、文字列へのポインタです。この文字列はldap_memfree()ファンクションを使用して解放する必要があります。OIDが戻されなかった場合、*retoidpにはNULLが設定されます。
retdatap	サーバーによって戻されたデータの割当て済コピーに設定されるberval構造体ポインタへのポインタです。このstruct bervalはber_bvfree()を使用して解放する必要があります。データが戻されなかった場合、*retdatapにはNULLが設定されます。

使用方法

なし

操作の中止

ldap_abandon_ext()ファンクションは、msgidパラメータのメッセージIDを使用して操作を中止し、中止操作が正常終了した場合は定数LDAP_SUCCESSを、失敗した場合は別のLDAPエラー・コードを戻します。

ldap_abandon()は、クライアント・コントロールまたはサーバー・コントロールを受け入れないこと以外はldap_abandon_ext()と同じで、中止操作が正常終了した場合は0(ゼロ)を、失敗した場合は-1を戻します。

ldap_abandon()コールまたはldap_abandon_ext()コールが正常終了した後、指定のメッセージIDを持つ結果は、引き続きldap_result()をコールしても戻されません。LDAP中止操作に対するサーバーのレスポンスはありません。

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	クライアント・コントロールのリストです。

関連項目:

エラーとその解析方法の詳細は、「エラーの処理と結果の解析」を参照してください。

使用方法

なし

結果の取得とLDAPメッセージの確認

非同期で開始された操作の結果は、ldap_result()ファンクションで戻されます。

この項のファンクションを使用して、非同期で開始した操作の結果を戻します。これらのファンクションは、メッセージを型およびIDで識別します。

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、定数LDAP_RES_UNSOLICITED (0)(要求に基づかない結果を取得する場合)、または定数LDAP_RES_ANY (-1)(任意の結果を取得する場合)です。
all	1回のldap_result()コールで取得するメッセージの数を指定します。このパラメータは、検索結果を取得する場合にのみ使用されます。定数LDAP_MSG_ONE (0x00)を渡して、一度に1つのメッセージを取得します。すべての結果が1つの結果セットとして戻される前に、すべての検索結果を取得するには、LDAP_MSG_ALL (0x01)を渡します。すでに取得したすべてのメッセージを結果セットに戻すには、LDAP_MSG_RECEIVED (0x02)を渡します。
timeout	結果の戻りに対する待機時間を指定するタイムアウトです。NULL値を指定すると、ldap_result()は結果が戻るまでブロックされます。タイムアウト値に0(ゼロ)秒を指定すると、ポーリング動作になります。
res	ldap_result()の場合は、操作の結果が含まれる結果パラメータです。戻される結果がない場合、*resはNULLに設定されます。ldap_msgfree()の場合は、ldap_result()、ldap_search_s()またはldap_search_st()をコールして前に取得し、解放する結果セットです。resをNULLに設定すると何も処理されず、ldap_msgfree()は0 (ゼロ)を戻します。

使用方法

正常終了すると、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を戻します。

結果の取得とLDAPメッセージの確認

この項のファンクションを使用して、非同期で開始した操作の結果を戻します。これらのファンクションは、メッセージを型およびIDで識別します。

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、定数LDAP_RES_UNSOLICITED (0)(要求に基づかない結果を取得する場合)、または定数LDAP_RES_ANY (-1)(任意の結果を取得する場合)です。
all	1回のldap_result()コールで取得するメッセージの数を指定します。このパラメータは、検索結果を取得する場合にのみ使用されます。定数LDAP_MSG_ONE (0x00)を渡して、一度に1つのメッセージを取得します。すべての結果が1つの結果セットとして戻される前に、すべての検索結果を取得するには、LDAP_MSG_ALL (0x01)を渡します。すでに取得したすべてのメッセージを結果セットに戻すには、LDAP_MSG_RECEIVED (0x02)を渡します。
timeout	結果の戻りに対する待機時間を指定するタイムアウトです。NULL値を指定すると、ldap_result()は結果が戻るまでブロックされます。タイムアウト値に0(ゼロ)秒を指定すると、ポーリング動作になります。
res	ldap_result()の場合は、操作の結果が含まれる結果パラメータです。戻される結果がない場合、*resはNULLに設定されます。ldap_msgfree()の場合は、ldap_result()、ldap_search_s()またはldap_search_st()をコールして前に取得し、解放する結果セットです。resをNULLに設定すると何も処理されず、ldap_msgfree()は0 (ゼロ)を戻します。

使用方法

正常終了すると、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を戻します。

エラーの処理と結果の解析

結果から情報を抽出し、他の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エラー・コードを、エラーを説明するゼロ終了文字列メッセージに変換するために使用されます。このファンクションは、静的データへのポインタを戻します。

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	ldap_result()またはAPI操作の同期コールの1つから戻されたLDAP操作の結果です。
errcodep	この結果パラメータには、LDAPMessageメッセージのLDAPエラー・コード・フィールドの値が入力されます。これは、サーバーでの操作の結果を示します。このフィールドを無視する場合は、NULLを渡す必要があります。
matcheddnp	LDAP_NO_SUCH_OBJECTが戻された場合、この結果パラメータには、リクエスト内の名前が認識された程度を示す識別名が入力されます。このフィールドを無視する場合は、NULLを渡す必要があります。一致した識別名の文字列は、このマニュアルで後述するldap_memfree()をコールして解放する必要があります。
errmsgp	この結果パラメータには、LDAPMessageメッセージのエラー・メッセージ・フィールドの内容が入力されます。エラー・メッセージ文字列は、このマニュアルで後述するldap_memfree()をコールして解放する必要があります。このフィールドを無視する場合は、NULLを渡す必要があります。
referralsp	この結果パラメータには、LDAPMessageメッセージの参照フィールドの内容が入力され、リクエストを再試行するための代替LDAPサーバーの有無が示されます。この参照配列は、このマニュアルで後述するldap_value_free()をコールして解放する必要があります。このフィールドを無視する場合は、NULLを渡す必要があります。
serverctrlsp	この結果パラメータには、LDAPMessageメッセージからコピーされたコントロールの割当て済配列が入力されます。このコントロール配列は、前に説明したldap_controls_free()をコールして解放する必要があります。
freeit	resパラメータを解放するかどうかを判断するブール値です。0(ゼロ)以外の値を渡すと、これらのルーチンはリクエストされた情報を抽出した後にresパラメータを解放します。これは便宜的に提供されており、結果の解放はldap_msgfree()を使用して後で行うこともできます。freeitが0 (ゼロ)以外の場合、resで表されるメッセージのチェーン全体が解放の対象となります。
servercredp	SASLバインド結果に関するこの結果パラメータには、相互認証が指定されている場合、サーバーから戻された資格証明が入力されます。割り当てられたberval構造体が戻されるため、ber_bvfree()をコールして解放する必要があります。このフィールドを無視する場合は、NULLを渡す必要があります。
retoidp	拡張操作の結果に関するこの結果パラメータには、拡張操作のレスポンス名のドット区切りのOIDテキスト表現が入力されます。この文字列はldap_memfree()をコールして解放する必要があります。このフィールドを無視する場合は、NULLを渡す必要があります。LDAP_NOTICE_OF_DISCONNECTIONマクロはクライアントに対して便宜的に定義されています。これにより、クライアントは、OIDが要求に基づかない切断通知(RFC 2251[2]のセクション4.4.1に定義)に使用されるOIDと一致しているかどうかをチェックします。
retdatap	拡張操作の結果に関するこの結果パラメータには、拡張操作のレスポンス・データが含まれるstruct bervalへのポインタが入力されます。このパラメータは、ber_bvfree()をコールして解放する必要があります。このフィールドを無視する場合は、NULLを渡す必要があります。
err	ldap_err2string()に関するLDAPエラー・コードで、ldap_parse_result()または他のLDAP APIコールによって戻されます。

使用方法

非推奨のルーチンに固有のパラメータについては、RFC 1823を参照してください。

結果リストの参照

ldap_result()を使用すると、結果チェーンでメッセージのリストが戻されます。

検索操作の結果セットには、参照メッセージ、エントリ・メッセージおよび結果メッセージを格納できます。

ldap_count_messages()は、戻されたメッセージの件数をカウントします。前述のldap_msgtype()ファンクションを使用すると、異なるメッセージ・タイプを区別できます。

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	同期検索ルーチンのいずれか、またはldap_result()をコールして取得する結果セットです。
msg	ldap_first_message()またはldap_next_message()のコールで前に戻されたメッセージです。

使用方法

エントリの参照中にエラーが発生した場合は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()コールを使用してチェーンに残っているメッセージ数をカウントすることもできます。

検索結果の解析

ldap_search()ファンクションで戻されるエントリやリファレンスを解析できます。

これらの結果は、この項で説明するルーチンをコールしてアクセスできる不透明な構造体に戻されます。これらのルーチンは、戻されたエントリやリファレンスの参照、エントリの属性の参照、エントリ名の取得、およびエントリ内の指定した属性に対応付けられている値の取得を行うために用意されています。これらの関数については、次の各項で説明します。

• ldap_first_entry、ldap_next_entry、ldap_first_reference、ldap_next_reference、ldap_count_entriesおよびldap_count_references

• ldap_first_attributeおよびldap_next_attribute

• ldap_get_values、ldap_get_values_len、ldap_count_values、ldap_count_values_len、ldap_value_freeおよびldap_value_free_len

• ldap_get_dn、ldap_explode_dn、ldap_explode_rdnおよびldap_dn2ufn

• ldap_get_entry_controls

• ldap_parse_reference

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	検索結果です。同期検索ルーチンのいずれか、またはldap_result()をコールして取得されるものと同一です。
entry	ldap_first_entry()またはldap_next_entry()のコールで前に戻されたエントリです。
ref	ldap_first_reference()またはldap_next_reference()のコールで前に戻されたリファレンスです。

使用方法

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()コールを使用してチェーンに残っているリファレンス数をカウントすることもできます。

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	属性を参照する対象となるエントリです。ldap_first_entry()またはldap_next_entry()の戻り値と同一です。
ptr	ldap_first_attribute()では、エントリ内の現在の位置を追跡管理するために内部で使用されるポインタのアドレスです。ldap_next_attribute()では、ldap_first_attribute()のコールで前に戻されたポインタです。BerElementタイプ自体は、不透明な構造体です。
mem	ldap_first_attribute()およびldap_next_attributeで戻される属性の型の名前やldap_get_dn()で戻される識別名など、LDAPライブラリによって割り当てられたメモリーへのポインタです。memがNULLの場合は、ldap_memfree()をコールしても何も処理されません。

使用方法

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()や関連するファンクションのコールに渡すのに適しています。

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	値を取得する元のエントリです。ldap_first_entry()またはldap_next_entry()の戻り値と同一です。
attr	値を取得する対象となる属性です。ldap_first_attribute()またはldap_next_attribute()の戻り値、またはコール元が提供する文字列(たとえば、mail)と同一です。
vals	ldap_get_values()またはldap_get_values_len()のコールで前に戻された値です。

使用方法

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()をコールして解放する必要があります。

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	名前を取得する対象となるエントリです。ldap_first_entry()またはldap_next_entry()の戻り値と同一です。
dn	ldap_get_dn()で戻された識別名など、分割する識別名です。
rdn	ldap_explode_dn()によって配列の構成要素に戻された相対識別名など、分割する相対識別名です。
notypes	ブール値パラメータです。0(ゼロ)以外の場合は、識別名または相対識別名の構成要素から型情報が削除されることを示します。つまり、cn=BabsはBabsになります。

使用方法

識別名解析エラーが発生した場合、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()コールにより解放する必要があります。

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	コントロールを抽出する元のエントリです。ldap_first_entry()またはldap_next_entry()の戻り値と同一です。
serverctrlsp	この結果パラメータには、エントリからコピーされたコントロールの割当て済配列が入力されます。このコントロール配列は、ldap_controls_free()をコールして解放する必要があります。serverctrlspがNULLの場合、コントロールは戻されません。

使用方法

ldap_get_entry_controls()は、リファレンスが正常に解析されたかどうかを示すLDAPエラー・コードを戻します(正常終了の場合はLDAP_SUCCESS)。

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	解析するリファレンスです。ldap_result()、ldap_first_reference()またはldap_next_reference()の戻り値と同一です。
referralsp	この結果パラメータには、文字列の割当て済配列が入力されます。配列の要素は、refに格納されている参照(通常はLDAP URL)です。この配列が不要になった場合は、ldap_value_free()をコールして解放する必要があります。referralspがNULLの場合、参照URLは戻されません。
serverctrlsp	この結果パラメータには、refからコピーされたコントロールの割当て済配列が入力されます。このコントロール配列は、ldap_controls_free()をコールして解放する必要があります。serverctrlspがNULLの場合、コントロールは戻されません。
freeit	refパラメータを解放するかどうかを判断するブール値です。0(ゼロ)以外の値を渡すと、このルーチンはリクエストされた情報を抽出した後にrefパラメータを解放します。このパラメータは便宜的に用意されたものです。結果は、後でldap_msgfree()を使用して解放することもできます。

使用方法

ldap_parse_reference()は、リファレンスが正常に解析されたかどうかを示すLDAPエラー・コードを戻します(正常終了の場合はLDAP_SUCCESS)。