Interstage Application Server Smart Repository運用ガイド

5.2.3 エントリの検索

関数名	関数の説明
ldap_search()	指定された条件のエントリを検索します。 （非同期型）
ldap_search_s()	指定された条件のエントリを検索します。 （同期型）
ldap_search_st()	指定された条件のエントリを検索します。 （同期型、時間制限付き）
ldap_search_ext()	指定された条件のエントリを検索します。 （非同期型、LDAP V3拡張関数）
ldap_search_ext_s()	指定された条件のエントリを検索します。 （同期型、LDAP V3拡張関数）

 

ldap_search

　この関数は、非同期型のエントリ検索処理を行います。

　非同期型検索の処理結果を受け取る場合、ldap_result()を使用します。この時、ldap_search()の復帰値として返されたメッセージIDを指定します。
　詳細は、“処理結果の受取り/判定”を参照してください。

　検索がどのように行われるかは、以下に示すセションハンドルオプションによって制御されます。

• LDAP_OPT_DEREF ： 別名の参照方法
• LDAP_OPT_SIZELIMIT ： 受信可能な最大エントリ数
• LDAP_OPT_TIMELIMIT ： 最大検索時間（秒単位）

　セションハンドルオプションについては、“セションハンドルオプションの設定/参照”を参照してください。

　ldapssl_init()で獲得したセションハンドルを使用している場合、SSLライブラリで発生したエラーをldapssl_error()で参照することができます。

【指定形式】

#include "idldap.h"
int  ldap_search(
        LDAP  *ld,
        char  *base,
        int  scope,
        char  *filter,
        char  **attrs,
        int  attrsonly );

【パラメタの説明】

• ld

  　ldap_init()、またはldapssl_init()で通知された、セションハンドルを指定します。

• base

  　サーチベースのDNのアドレスを指定します。サーチベースとは、検索開始位置のエントリです。

• scope

  　以下のどれか1つの値を指定します。

  • LDAP_SCOPE_BASE：サーチベースで指定されたエントリを検索します。
  • LDAP_SCOPE_ONELEVEL：サーチベースで指定されたエントリの1階層下のエントリを検索します。
  • LDAP_SCOPE_SUBTREE：サーチベースで指定されたエントリと、その配下の全エントリの中から検索します。
    　
• filter

  　検索フィルタのアドレスを指定します。検索フィルタの文法については、“検索フィルタ”を参照してください。

  例

  (cn=User1)
  (o=Fujitsu*)
  (&(objectClass=person)(|(uid=0001)(cn=User*)))

   

• attrs

  　通知してほしい属性名のアドレスを設定した、ポインタ配列のアドレスを指定します。リポジトリサーバは、ポインタ配列で指定された属性だけをクライアントに通知します。以下の例では、“objectClass”と“commonName”だけが通知されます。

  例

  char  *attrs[3] = {
              "objectClass",
              "commonName",
              NULL
              };

  　このパラメタにNULLを指定すると、検索でヒットしたエントリの利用可能な属性がすべて通知されます。また、ポインタ配列の最後には、NULLを設定しておく必要があります。

• attrsonly

  　以下のどちらかの値を指定します。

  • 属性名と属性値の両方を通知してほしい場合 ： 0
  • 属性名だけを通知してほしい場合 ： 0以外の値

【復帰値】

　この関数は、復帰値として以下の値を返します。

• 正常完了の場合 ： メッセージID
• 異常完了の場合 ： -1

  　異常完了の場合、以下の原因が考えられます。

  • パラメタの指定に誤りがあります。
  • 使用可能なメモリが不足しました。

 

ldap_search_s

　この関数は、時間制限なしで同期型のエントリ検索処理を行います。

　検索がどのように行われるかは、以下に示すセションハンドルオプションによって制御されます。

• LDAP_OPT_DEREF ： 別名の参照方法
• LDAP_OPT_SIZELIMIT ： 受信可能な最大エントリ数
• LDAP_OPT_TIMELIMIT ： 最大検索時間（秒単位）

　セションハンドルオプションについては、“セションハンドルオプションの設定/参照”を参照してください。

　通知された検索結果の解析は、構文解析関数を使用して行います。詳細は、“検索結果の解析処理”を参照してください。

　ldapssl_init()で獲得したセションハンドルを使用している場合、SSLライブラリで発生したエラーをldapssl_error()で参照することができます。

【指定形式】

#include "idldap.h"
int  ldap_search_s(
        LDAP  *ld,
        char  *base,
        int  scope,
        char  *filter,
        char  **attrs,
        int  attrsonly,
        LDAPMessage  **res );

【パラメタの説明】

• ld

  　ldap_init()、またはldapssl_init()で通知された、セションハンドルを指定します。

• base

  　サーチベースのDNのアドレスを指定します。サーチベースとは、検索開始位置のエントリです。

• scope

  　以下のどれか1つの値を指定します。

  • LDAP_SCOPE_BASE ： サーチベースで指定されたエントリを検索します。
  • LDAP_SCOPE_ONELEVEL ： サーチベースで指定されたエントリの1階層下のエントリを検索します。
  • LDAP_SCOPE_SUBTREE ： サーチベースで指定されたエントリと、その配下の全エントリの中から検索します。
    　
• filter

  　検索フィルタのアドレスを指定します。検索フィルタの文法については、“検索フィルタ”を参照してください。

  例

  (cn=User1)
  (o=Fujitsu*)
  (&(objectClass=person)(|(uid=0001)(cn=User*)))

   

• attrs

  　通知してほしい属性名のアドレスを設定した、ポインタ配列のアドレスを指定します。リポジトリサーバは、ポインタ配列で指定された属性だけをクライアントに通知します。以下の例では、“objectClass”と“commonName”だけが通知されます。

  例

  char  *attrs[3] = {
              "objectClass",
              "commonName",
              NULL
              };

  　このパラメタにNULLを指定すると、検索でヒットしたエントリの利用可能な属性がすべて通知されます。また、ポインタ配列の最後には、NULLを設定しておく必要があります。

• attrsonly

  　以下のどちらかの値を指定します。

  • 属性名と属性値の両方を通知してほしい場合 ： 0
  • 属性名だけを通知してほしい場合 ： 0以外の値
    　
• res

  　result情報のアドレスを格納するための、“LDAPMessage *”型のポインタ変数のアドレスを指定します。このポインタ変数は、関数を呼び出す前に初期値としてNULLを設定しておく必要があります。

【復帰値】

　この関数では、復帰値としてLDAPエラーコードを返します。LDAPエラーコードの値については、“LDAPエラーコード”を参照してください。

• 正常完了の場合 ： LDAP_SUCCESS
• 異常完了の場合 ： LDAP_SUCCESS 以外のLDAPエラーコード

　サーバから通知されたresult情報がある場合には、resパラメタで指定されたポインタ変数にresult情報のアドレスが設定されています。

• 通知された領域の解放

  　resパラメタで通知されたresult情報と検索結果は、不要になった時点でldap_msgfree()を使用して解放しなければなりません。詳細は、“動的メモリの解放”を参照してください。

 

ldap_search_st

　この関数は、時間制限付きで同期型のエントリ検索処理を行います。

　検索がどのように行われるかは、以下に示すセションハンドルオプションによって制御されます。

• LDAP_OPT_DEREF ： 別名の参照方法
• LDAP_OPT_SIZELIMIT ： 受信可能な最大エントリ数
• LDAP_OPT_TIMELIMIT ： 最大検索時間（秒）

　セションハンドルオプションについては、“セションハンドルオプションの設定/参照”を参照してください。

　通知された検索結果の解析は、構文解析関数を使用して行います。詳細は、“検索結果の解析処理”を参照してください。

　ldapssl_init()で獲得したセションハンドルを使用している場合、SSLライブラリで発生したエラーをldapssl_error()で参照することができます。

【指定形式】

#include "idldap.h"
int  ldap_search_st(
        LDAP  *ld,
        char  *base,
        int  scope,
        char  *filter,
        char  **attrs,
        int  attrsonly,
        struct timeval  *timeout,
        LDAPMessage  **res );

【パラメタの説明】

• ld

  　ldap_init()、またはldapssl_init()で通知された、セションハンドルを指定します。

• base

  　サーチベースのDNのアドレスを指定します。サーチベースとは、検索開始位置のエントリです。

• scope

  　以下のどれか1つの値を指定します。

  • LDAP_SCOPE_BASE：サーチベースで指定されたエントリを検索します。
  • LDAP_SCOPE_ONELEVEL：サーチベースで指定されたエントリの1階層下のエントリを検索します。
  • LDAP_SCOPE_SUBTREE：サーチベースで指定されたエントリと、その配下の全エントリの中から検索します。
    　
• filter

  　検索フィルタのアドレスを指定します。検索フィルタの文法については、“検索フィルタ”を参照してください。

  例

  (cn=User1)
  (o=Fujitsu*)
  (&(objectClass=person)(|(uid=0001)(cn=User*)))

   

• attrs

  　通知してほしい属性名のアドレスを設定した、ポインタ配列のアドレスを指定します。リポジトリサーバは、ポインタ配列で指定された属性だけをクライアントに通知します。以下の例では、“objectClass”と“commonName”だけが通知されます。

  例

  char  *attrs[3] = {
              "objectClass",
              "commonName",
              NULL
              };

  　このパラメタにNULLを指定すると、検索でヒットしたエントリの利用可能な属性がすべて通知されます。また、ポインタ配列の最後には、NULLを設定しておく必要があります。

• attrsonly

  　以下のどちらかの値を指定します。

  • 属性名と属性値の両方を通知してほしい場合 ： 0
  • 属性名だけを通知してほしい場合 ： 0以外の値
    　
• timeout

  　検索のローカルタイムアウト値を設定した、timeval構造体のアドレスを指定します。
  　timeval構造体のメンバには、以下の値を設定します。

  • tv_sec ： タイマー値（秒単位）
  • tv_usec ： タイマー値（マイクロ秒単位）

  　timeoutパラメタにNULLポインタを指定すると、結果を受け取るまで呼出し元に復帰しません。この値は、クライアントでリポジトリサーバからの検索結果を受信するための最大待ち時間として使用されます。

• res

  　result情報のアドレスを格納するための、“LDAPMessage *”型のポインタ変数のアドレスを指定します。このポインタ変数は、関数を呼び出す前に初期値としてNULLを設定しておく必要があります。

【復帰値】

　この関数では、復帰値としてLDAPエラーコードを返します。LDAPエラーコードの値については、“LDAPエラーコード”を参照してください。

• 正常完了の場合 ： LDAP_SUCCESS
• 異常完了の場合 ： LDAP_SUCCESS 以外のLDAPエラーコード

　サーバから通知されたresult情報がある場合には、resパラメタで指定されたポインタ変数にresult情報のアドレスが設定されています。

• 通知された領域の解放

  　resパラメタで通知されたresult情報と検索結果は、不要になった時点でldap_msgfree()を使用して解放しなければなりません。詳細は、“動的メモリの解放”を参照してください。

 

ldap_search_ext

　この関数は、非同期型のエントリ検索処理を行います。

　非同期型検索の処理結果を受け取る場合、ldap_result()を使用します。この時、ldap_search_ext()の復帰値として返されたメッセージIDを指定します。詳細は、“処理結果の受取り/判定”を参照してください。

　検索がどのように行われるかは、以下に示すセションハンドルオプションによって制御されます。

• DAP_OPT_DEREF ： 別名の参照方法
• LDAP_OPT_SIZELIMIT ： 受信可能な最大エントリ数
• LDAP_OPT_TIMELIMIT ： 最大検索時間（秒単位）

　セションハンドルオプションについては、“セションハンドルオプションの設定/参照”を参照してください。

　ldapssl_init()で獲得したセションハンドルを使用している場合、SSLライブラリで発生したエラーをldapssl_error()で参照することができます。

【指定形式】

#include "idldap.h"
int  ldap_search_ext(
        LDAP  *ld,
        char  *base,
        int  scope,
        char  *filter,
        char  **attrs,
        int  attrsonly,
        LDAPControl  **serverctrls,
        LDAPControl  **clientctrls,
        struct timeval  *timeout,
        int  sizelimit,
        int  *msgidp );

【パラメタの説明】

• ld

  　ldap_init()、またはldapssl_init()で通知された、セションハンドルを指定します。

• base

  　サーチベースのDNのアドレスを指定します。サーチベースとは、検索開始位置のエントリです。

• scope

  　以下のどれか1つの値を指定します。

  • LDAP_SCOPE_BASE ： サーチベースで指定されたエントリを検索します。
  • LDAP_SCOPE_ONELEVEL ： サーチベースで指定されたエントリの1階層下のエントリを検索します。
  • LDAP_SCOPE_SUBTREE ： サーチベースで指定されたエントリと、その配下の全エントリの中から検索します。
    　
• filter

  　検索フィルタのアドレスを指定します。検索フィルタの文法については、“検索フィルタ”を参照してください。

  例

  (cn=User1)
  (o=Fujitsu*)
  (&(objectClass=person)(|(uid=0001)(cn=User*)))

   

• attrs

  　通知してほしい属性名のアドレスを設定した、ポインタ配列のアドレスを指定します。リポジトリサーバは、ポインタ配列で指定された属性だけをクライアントに通知します。以下の例では、“objectClass”と“commonName”だけが通知されます。

  例

  char  *attrs[3] = {
              "objectClass",
              "commonName",
              NULL
              };

  　このパラメタにNULLを指定すると、検索でヒットしたエントリの利用可能な属性がすべて通知されます。また、ポインタ配列の最後には、NULLを設定しておく必要があります。

• attrsonly

  　以下のどちらかの値を指定します。

  • 属性名と属性値の両方を通知してほしい場合 ： 0
  • 属性名だけを通知してほしい場合 ： 0以外の値
    　
• serverctrls

  　Smart Repositoryではサーバコントロールをサポートしていないため、このパラメタにはNULLを指定します。

• clientctrls

  　本ライブラリではクライアントコントロールをサポートしていないため、このパラメタにはNULLを指定します。

• timeout

  　サーバにおける検索のタイムアウト値を設定したtimeval構造体のアドレスを指定します。
  　timeval構造体のメンバには、以下の値を設定します。

  • tv_sec ： タイマー値（秒単位）
  • tv_usec ： タイマー値（マイクロ秒単位）

  　timeoutパラメタにNULLポインタを指定すると、LDAP_OPT_TIMELIMITで設定された制限時間を使用します。この値は、リポジトリサーバでの最大検索時間として使用されます。

• sizelimit

  　受信可能な最大エントリ数を指定します。sizelimitパラメタに0を指定すると、LDAP_OPT_SIZELIMITで設定された最大エントリ数を使用します。

• msgidp

  　メッセージIDを格納するための変数のアドレスを指定します。

【復帰値】

　この関数では、復帰値としてLDAPエラーコードを返します。LDAPエラーコードの値については、“LDAPエラーコード”を参照してください。

• 正常完了の場合 ： LDAP_SUCCESS
• 異常完了の場合 ： LDAP_SUCCESS以外のLDAPエラーコード

　正常完了の場合、msgidpが示す変数にメッセージIDが設定されます。

 

ldap_search_ext_s

　この関数は、同期型のエントリ検索処理をします。

　検索がどのように行われるかは、以下に示すセションハンドルオプションによって制御されます。

• LDAP_OPT_DEREF ： 別名の参照方法
• LDAP_OPT_SIZELIMIT ： 受信可能な最大エントリ数
• LDAP_OPT_TIMELIMIT ： 最大検索時間（秒単位）

　セションハンドルオプションについては、“セションハンドルオプションの設定/参照”を参照してください。

　通知された検索結果の解析は、構文解析関数を使用して行います。詳細は、“処理結果の受取り/判定”を参照してください。

　ldapssl_init()で獲得したセションハンドルを使用している場合、SSLライブラリで発生したエラーをldapssl_error()で参照することができます。

【指定形式】

#include "idldap.h"
int  ldap_search_ext_s(
        LDAP  *ld,
        char  *base,
        int  scope,
        char  *filter,
        char  **attrs,
        int  attrsonly,
        LDAPControl  **serverctrls,
        LDAPControl  **clientctrls, 
        struct timeval  *timeout,
        int  sizelimit,
        LDAPMessage  **res );

【パラメタの説明】

• ld

  　ldap_init()、またはldapssl_init()で通知された、セションハンドルを指定します。

• base

  　サーチベースのDNのアドレスを指定します。サーチベースとは、検索開始位置のエントリです。

• scope

  　以下のどれか1つの値を指定します。

  • LDAP_SCOPE_BASE：サーチベースで指定されたエントリを検索します。
  • LDAP_SCOPE_ONELEVEL：サーチベースで指定されたエントリの1階層下のエントリを検索します。
  • LDAP_SCOPE_SUBTREE：サーチベースで指定されたエントリと、その配下の全エントリの中から検索します。
    　
• filter

  　検索フィルタのアドレスを指定します。検索フィルタの文法については、“検索フィルタ”を参照してください。

  例

  (cn=User1)
  (o=Fujitsu*)
  (&(objectClass=person)(|(uid=0001)(cn=User*)))

   

• attrs

  　通知してほしい属性名のアドレスを設定した、ポインタ配列のアドレスを指定します。リポジトリサーバは、ポインタ配列で指定された属性だけをクライアントに通知します。以下の例では、“objectClass”と“commonName”だけが通知されます。

  例

  char  *attrs[3] = {
              "objectClass",
              "commonName",
              NULL
              };

  　このパラメタにNULLを指定すると、検索でヒットしたエントリの利用可能な属性がすべて通知されます。また、ポインタ配列の最後には、NULLを設定しておく必要があります。

• attrsonly

  　以下のどちらかの値を指定します。

  • 属性名と属性値の両方を通知してほしい場合 ： 0
  • 属性名だけを通知してほしい場合 ： 0以外の値
    　
• serverctrls

  　Smart Repositoryではサーバコントロールをサポートしていないため、このパラメタにはNULLを指定します。

• clientctrls

  　本ライブラリではクライアントコントロールをサポートしていないため、このパラメタにはNULLを指定します。

• timeout

  　サーバにおける検索のタイムアウト値を設定した、timeval構造体のアドレスを指定します。
  　timeval構造体のメンバには、以下の値を設定します。

  • tv_sec ： タイマー値（秒単位）
  • tv_usec ： タイマー値（マイクロ秒単位）

  　timeoutパラメタにNULLポインタを指定すると、LDAP_OPT_TIMELIMITで設定された制限時間を使用します。この値は、リポジトリサーバでの最大検索時間として使用されます。

• sizelimit

  　受信可能な最大エントリ数を指定します。sizelimitパラメタに0を指定すると、LDAP_OPT_SIZELIMITで設定された最大エントリ数を使用します。

• res

  　result情報のアドレスを格納するための “LDAPMessage *”型のポインタ変数のアドレスを指定します。このポインタ変数は、関数を呼び出す前に初期値としてNULLを設定しておく必要があります。

【復帰値】

　この関数では、復帰値としてLDAPエラーコードを返します。LDAPエラーコードの値については、“LDAPエラーコード”を参照してください。

• 正常完了の場合 ： LDAP_SUCCESS
• 異常完了の場合 ： LDAP_SUCCESS 以外のLDAPエラーコード

　サーバから通知されたresult情報がある場合には、resパラメタで指定されたポインタ変数にresult情報のアドレスが設定されています。

• 通知された領域の解放

  　resパラメタで通知されたresult情報と検索結果は、不要になった時点でldap_msgfree()を使用して解放しなければなりません。詳細は、“動的メモリの解放”を参照してください。