1.20.11 処理結果の受取り/解析インタフェース

処理結果の受取り/判定

関数名	関数の説明
ldap_result()	非同期関数の処理結果や検索結果のエントリを受け取ります。
ldap_msgid()	指定されたメッセージのメッセージIDを参照します。
ldap_msgtype()	指定されたメッセージのタイプを参照します。

エラー情報の取得

関数名	関数の説明
ldap_parse_result()	指定されたresult情報のLDAPエラー情報を読み込みます。
ldap_err2string()	LDAPエラーコードを文字列に変換します。
ldapssl_error()	SSLライブラリのエラーコードを読み込みます。

メッセージリスト処理

関数名	関数の説明
ldap_first_message()	最初のメッセージのアドレスを返します。
ldap_next_message()	次のメッセージのアドレスを返します。（前回読み込んだものに続くメッセージ）
ldap_count_messages()	メッセージリストに含まれるメッセージの個数をカウントします。

1.20.11.1 ldap_result()

名前

ldap_result

形式

  #include "idldap.h"
  int  ldap_result(
          LDAP  *ld,
          int  msgid,
          int  all,
          struct timeval  *timeout,
          LDAPMessage  **resp );

機能説明

この関数は、非同期関数の処理結果や検索結果のエントリを受け取ります。

取得したresult情報がどの非同期要求に対するものか判定する場合、ldap_msgid()でresult情報のメッセージIDを参照します。result情報には、対応する非同期要求のメッセージIDが付加されています。

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

パラメタ

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

msgid: 非同期関数で通知されたメッセージIDを指定します。また、受け取る処理結果を特定しない場合には、LDAP_RES_ANYを指定します。LDAP_RES_ANYを指定した場合は、最初に受信したメッセージが通知されます。

all

処理結果のメッセージが複数ある場合の処理として、以下のどれか1つを指定します。

LDAP_MSG_ALL ：要求したmsgidパラメタに対応する処理結果メッセージをすべて受信した後で、呼出し元に復帰します。
LDAP_MSG_ONE ：要求したmsgidパラメタに対応する処理結果メッセージを1個受信するごとに、呼出し元へ復帰します。
LDAP_MSG_RECEIVED ：現在受信済の処理結果メッセージの中から、msgidパラメタで指定された条件に合うものを読み込んで呼出し元へ復帰します。

timeout

受信待ち時間を設定した領域のアドレスを指定します。timeval構造体のメンバには、以下の値を設定します。

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

timeoutパラメタにNULLポインタを指定すると、結果を受け取るまで呼出し元に復帰しません。また、timeval構造体のtv_secパラメタ、およびtv_usecパラメタに0を設定した場合は、指定されたメッセージが到着しているかどうかを判定して、メッセージが到着していなかった場合には、すぐにタイムアウトで復帰します。

resp: LDAPMessage構造体のポインタ変数のアドレスを指定します。

復帰値

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

正常終了：メッセージのタイプ（メッセージリストの先頭）
タイムアウト： 0

異常終了： -1

異常終了の場合のエラー原因は、ldap_get_option()のLDAP_OPT_RESULT_CODEオプションで参照してください。

正常終了の場合に通知されるメッセージのタイプを、以下に示します。

メッセージタイプ	値	説明
LDAP_RES_BIND	0x61	リポジトリサーバとのユーザ認証(BIND)に対するresult情報です。
LDAP_RES_SEARCH_ENTRY	0x64	エントリの検索(SEARCH)で検索条件に合致したエントリを表しています。
LDAP_RES_SEARCH_RESULT	0x65	エントリの検索結果の通知を示します。
LDAP_RES_MODIFY	0x67	エントリの変更(MODIFY)に対するresult情報です。
LDAP_RES_ADD	0x69	エントリの追加(ADD)に対するresult情報です。
LDAP_RES_DELETE	0x6B	エントリの削除(DELETE)に対するresult情報です。
LDAP_RES_MODDN	0x6D	エントリ名の変更(MODDN)に対するresult情報です。
LDAP_RES_COMPARE	0x6F	属性値の比較(COMPARE)に対するresult情報です。

受信したメッセージが存在する場合は、respパラメタが示すポインタ変数に、メッセージリストの先頭アドレスが設定されます。
LDAPMessageの通知形式を以下に示します。

ldap_result()で通知されたメッセージリストは、メッセージリスト処理においてパラメタとして指定します。

注意事項

動的メモリの解放
ldap_result()で通知されたメッセージリストは、不要になった時点でldap_msgfree()を使用して解放しなければなりません。詳細は、“1.20.13 動的メモリの解放インタフェース”を参照してください。

1.20.11.2 ldap_msgid()

名前

ldap_msgid

形式

  #include "idldap.h"
  int  ldap_msgid(
          LDAPMessage  *lm );

機能説明

この関数は、指定されたメッセージのメッセージIDを通知します。

パラメタ

lm: メッセージのアドレスを指定します。

復帰値

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

正常終了：指定されたメッセージのメッセージID
異常終了： -1
異常終了の場合、以下の原因が考えられます。
- パラメタの指定に誤りがあります。

1.20.11.3 ldap_msgtype()

名前

ldap_msgtype

形式

  #include "idldap.h"
  int  ldap_msgtype(
          LDAPMessage  *lm );

機能説明

この関数は、指定されたメッセージのタイプを通知します。メッセージタイプの値については、ldap_result()の復帰値を参照してください。

パラメタ

lm: メッセージのアドレスを指定します。

復帰値

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

正常終了：指定されたメッセージのメッセージタイプ
異常終了： -1
異常終了の場合、以下の原因が考えられます。
- パラメタの指定に誤りがあります。

1.20.11.4 ldap_parse_result()

名前

ldap_parse_result

形式

  #include "idldap.h"
  int  ldap_parse_result(
          LDAP  *ld,
          LDAPMessage  *res,
          int  *errcodep,
          char  **matcheddnp,
          char  **errmsgp,
          char  ***referralsp,
          LDAPControl  ***serverctrlsp,
          int  freeit );

機能説明

この関数は、受信したresult情報内の各種情報を読み込みます。この関数は、LDAP_RES_SEARCH_ENTRY以外のresult情報に対して使用します。

パラメタ

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

res: result情報のアドレスを指定します。

errcodep: result情報に含まれるLDAPエラーコードを格納する、変数のアドレスを指定します。LDAPエラーコードを読み込まない場合は、このパラメタにNULLを指定します。

matcheddnp: 一致した範囲を示すDNのアドレスを格納する、ポインタ変数のアドレスを指定します。一致した範囲を示すDNを読み込まない場合は、このパラメタにNULLを指定します。

errmsgp: 詳細エラーメッセージのアドレスを格納する、変数のアドレスを指定します。詳細エラーメッセージを読み込まない場合は、このパラメタにNULLを指定します。

referralsp: Interstage ディレクトリサービスではリフェラルをサポートしないため、このパラメタにはNULLを指定します。

serverctrlsp: Interstage ディレクトリサービスではサーバコントロールをサポートしていないため、このパラメタにはNULLを指定します。

freeit

呼出し元に復帰する際に、resパラメタで指定したresult情報を解放するかどうかを指定します。

result情報を解放する場合： 0以外を指定
result情報を解放しない場合： 0を指定

復帰値

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

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

正常終了の場合は、パラメタで指定した変数に、以下の情報が設定されます。

errcodepパラメタで指定された変数
LDAPエラーコードが設定されます。
matcheddnpパラメタで指定された変数
適合したDNの範囲を示す文字列のアドレスが設定されます。この領域は不要になった時点でldap_memfree()を使用し解放しなければなりません。
errmsgpパラメタで指定された変数
指定されたresult情報内の、詳細エラーメッセージのアドレスが設定されます。この領域は不要になった時点でldap_memfree()を使用し解放しなければなりません。

注意事項

result情報の解放
ldap_parse_result()を呼び出す際に、freeitパラメタに0以外の値を指定した場合、ライブラリ内部でldap_msgfree()使用してresult情報を解放します。このため、これ以降は、result情報にアクセスできなくなります。ldap_parse_result()を呼び出す際に、freeitパラメタに0を指定した場合には、不要になった時点で、呼出し元がldap_msgfree()使用してresult情報を解放しなければなりません。

1.20.11.5 ldap_err2string()

名前

ldap_err2string

形式

  #include "idldap.h"
  char  *ldap_err2string(
          int  err );

機能説明

この関数は、指定されたLDAPエラーコードに対応するエラーメッセージの文字列を通知します。

パラメタ

err: LDAPエラーコードを指定します。LDAPエラーコードの値については、“メッセージ集”の“LDAPエラーコード”を参照してください。

復帰値

この関数は、指定されたLDAPエラーコードに対応するエラーメッセージのアドレスを、関数の復帰値として返します。未定義のLDAPエラーコードが指定された場合には、“Unknown error”が通知されます。

1.20.11.6 ldapssl_error()

名前

ldapssl_error

形式

  #include "idldap.h"
  char  *ldapssl_error(
        LDAP  *ld,
        int  *ssl_err,
        int  *ssl_err_detail );

機能説明

この関数は、SSL使用時にSSLライブラリで検出したエラーコードを獲得します。SSLエラーコードの値については、“メッセージ集”の“Interstage ディレクトリサービスから通知されるエラーコード”-“SSLエラーコード”を参照してください。

パラメタ

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

ssl_err: SSLエラーコードが設定される変数のアドレスを指定します。

ssl_err_detail: SSLエラー詳細コードが設定される変数のアドレスを指定します。

復帰値

ありません。

1.20.11.7 ldap_first_message()

名前

ldap_first_message

形式

  #include "idldap.h"
  LDAPMessage  *ldap_first_message(
          LDAP  *ld,
          LDAPMessage  *res );

機能説明

この関数は、ldap_result()、または同期型の検索処理で通知されたメッセージリスト内の、先頭のメッセージのアドレスを通知します。

ldap_first_message()で通知されたメッセージのアドレスは、以下の関数においてパラメタとして使用することができます。

メッセージリスト処理
ldap_next_message()
ldap_count_messages()
エラー情報の取得処理（result情報の場合）
ldap_parse_result()
エントリリストの処理
  ldap_first_entry()
  ldap_next_entry()
  ldap_count_entries()

パラメタ

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

res: ldap_result()、または同期型の検索処理で通知された、メッセージリストのアドレスを指定します。

復帰値

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

正常終了の場合：先頭のメッセージアドレス
異常終了の場合： NULL
異常終了の場合のエラー原因は、ldap_get_option()のLDAP_OPT_RESULT_CODEオプションで参照してください。

1.20.11.8 ldap_next_message()

名前

ldap_next_message

形式

  #include "idldap.h"
  LDAPMessage  *ldap_next_message(
          LDAP  *ld,
          LDAPMessage  *msg );

機能説明

この関数は、直前のldap_first_message()、またはldap_next_message()で通知されたメッセージの、次のメッセージのアドレスを通知します。

ldap_next_message()で通知されたメッセージのアドレスは、以下の関数においてパラメタとして使用することができます。

メッセージリスト処理
ldap_next_message()
ldap_count_messages()
エラー情報の取得処理（result情報の場合）
ldap_parse_result()
エントリリストの処理
  ldap_first_entry()
  ldap_next_entry()
  ldap_count_entries()

パラメタ

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

msg: 直前のldap_first_message()、またはldap_next_message()で通知された、メッセージのアドレスを指定します。

復帰値

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

正常終了の場合：次のメッセージのアドレス
異常終了の場合： NULL
異常終了の場合のエラー原因は、ldap_get_option()のLDAP_OPT_RESULT_CODEオプションで参照してください。
なお、次のメッセージがない場合にも、復帰値としてNULLを返します。