ldapapi.docx
《ldapapi.docx》由会员分享，可在线阅读，更多相关《ldapapi.docx（18页珍藏版）》请在冰豆网上搜索。
ldapapi
ldapapi
1简介
本文定义了C语言应用程序编程接口。
LDAPAPI设计成既强大又简单易用。
定义了LDAP的兼容的同步和同步接口，以适应大量不同应用。
此文档给出简要LDAP模型概要，可以引导用户如何通过这些API编程取得LDAP信息。
2LDAP模型预览
LDAP是轻量级目录访问协议，提供了轻量级的X.500访问前端，或者作为一个独立服务。
在两种模式下，LDAP基于C/S模式客户通过TCP连接到Server，通过此连接发送请求和接收响应。
LDAP模型基于条目，条目包含一些对象信息。
条目由属性组成，属性拥有一个类型和一个或多个值，每个属性有决定那种值允许出现在属性中的语法（例如:
ASCII字符，jepg图片„），并且决定这些值在目录操作中怎样表现其行为。
条目组织为树形结构，通常按政治，地理，组织划分。
每个条目相对于它的相邻条目的命名是唯一的，由一个或多个相区别的属性值（RDN）组成。
每个属性中至多一个有一个值可以在RDN中使用，例如条目PersonBabsJensen可能将名为“BarbaraJensen”的值作为commonName属性，一个全局条目的唯一名称称为DN,由连接从树的根到条目的一系列RDN构造的。
例如，如果Babs在UniversityofMichigan工作，他的DNU-M条目可能是“cn=BarbarsJensen，o=UniversityofMichigan,c=US”。
DN的格式参照RFC1779。
操作提供了身份认证，查询并取得信息，修改信息，添加和删除条目。
下一节将介绍API概要，包括如何使用这些API并且详细描述这些API的调用实现。
3LDAPAPI使用概要
应用程序通常按以下四个步骤使用LDAPAPI
打开一个到LDAPServer的连接，ldap_open（）返回连接句柄，允许多个连接同时
打开。
同LDAPServer验证且/或同X.500DSA认证。
Ldap_bind（）及其他相关函数支持不
同的认证方法。
执行ldap操作获取结果。
Ldap_search（）及相关函数返回的结果可以由
ldap_result2error（）,ldap_first_entry（）,ldap_next_entry（）解析。
关闭连接。
由Ldap_next_entry（）调用实现。
操作能够同步或异步地执行。
同步调用以_s结尾，所以同步搜索的函数为ldap_search_s（）。
所有同步程序返回一个代表操作结果的指示符。
（例如:
常量LDAP_SUCCESS或其他错误码）。
异步程序返回操作初始化的消息ID。
此ID可以被随后的ldap_result（）调用取得操作结果（结果集）。
一个异步操作可以被ldap_abandon（）函数取消。
结果和错误返回到一个非透明的结构LDAPMessage中。
程序提供解析此结构，进入条目和返回的属性，等等功能。
程序同样提供错误解释工作。
下一节详细描述这些程序例程。
4调用LDAP操作
本节描述每一LDAP操作调用细节。
所有调用使用一个“连接句柄”—一个指向LDAP结构的指针，此结构包含了每一个连接的信息。
许多程序返回LDAPMessage结构。
这些结构和其他相关结构将在下面需要时详细描述。
4.1打开一个连接
ldap_open（）打开一个连到LDAPServer的连接。
typedefstructldap{
/*...opaqueparameters...*/
intld_deref;
intld_timelimit;
intld_sizelimit;
intld_errno;
char*ld_matched;
char*ld_error;
/*...opaqueparameters...*/
}LDAP;
LDAP*ldap_open（char*hostname,intprotno）;参数:
hostname:
要连接的运行LDAPServer的服务器的以空格分隔的主机名或点分十进制
表示的IP地址列表。
这些主机名开始被顺序地尝试连接，并且在第一个
连接成功时停止。
Portno:
包含要连接的TCP端口号，缺省的LDAP端口由常量LDAP_PORT提供。
Ldap_open（）返回一个“连接句柄”，——指向LDAP结构的指针，它是应该在后继
调用保留这个连接。
如果连结不能打开将返回NULL。
Ldap_bind的一个调用应该在
连接之前执行完成其他操作。
调用程序应对LDAP结构的各个字段赋空值。
有许多结构中的其它字段为内部库使
用的。
上面的对这些字段的描述也显示在其他调用描述中。
4.2目录验证
ldap_bind（）和相关函数用来进行目录验证
intldap_bind（LDAP*ld,char*dn,char*cred,intmethod）;
intldap_bind_s（LDAP*ld,char*dn,char*cred,intmethod）;
intldap_simple_bind（LDAP*ld,char*dn,char*passwd）;
intldap_simple_bind_s（LDAP*ld,char*dn,char*passwd）;
intldap_kerberos_bind（LDAP*ld,char*dn）;intldap_kerberos_bind_s（LDAP*ld,char*dn）;Parametersare:
Ld:
连接句柄
Dn:
绑定的条目名称
cred:
验证的信任方式LDAP_AUTH_SIMPLE，LDAP_AUTH_KRBV41，
LDAP_AUTH_KRBV42中的一个，指明验证方法。
Passwd:
Ldap_simple_bind（）的密码，它将会和是条目的userPassword属性比较。
有三种类型的绑定调用，提供简单认证，kerberos认证，和两者都使用
的通用例程。
在kerberos第四版，验证使用通用ldap_bind（）例程，cred将
被忽略，例程将会赋予一个合法票证以授权可被取得正确的服务票证的票证已
经存在。
同步版本的例程以_s结尾。
这些例程返回绑定操作的结果，如果操作成
功返回LDAP_SUCCESS,失败了返回错误码。
在下面的错误捕获一节将给出关于
可能的错误和如何捕获的更多信息。
异步版本调用返回绑定初始化消息ID，随后调用ldap_result（）取得绑定
结果。
当出现错误时，程序返回-1，并相应设置LDAP结构的ld_error字段。
需注意的是在绑定调用成功完成以前，不应有其他的试图跨越除了连接的
操作。
随后的绑定调用可以用来进行在同一连接上的重新验证。
4.3关闭连接
ldap_unbind（）用来与一个目录解绑定并关闭连接。
Intldap_unbind（LDAP*ld）;
参数:
ld:
连接句柄
ldap_unbind（）同步状态工作，同目录解绑定，关闭连接，在返回前释放ld结构空间。
Ldap_unbing（）返回LDAP_SUCCESS（或其他请求不能送到LDAPServer的LDAP错误码）。
调用ldap_unbind（）后，ld连接句柄将不可用。
4.4查询
ldap_search（）及其相关函数用来对LDAP目录查询，返回请求的每一个匹配条目的属性集。
下面是三个相关函数:
structtimeval{
longtv_sec;
longtv_usec;
};
intldap_search（
LDAP*ld,
char*base,
intscope,
char*filter,
char*attrs[],
intattrsonly
）;
intldap_search_s（
LDAP*ld,
char*base,
intscope,
char*filter,
char*attrs[],
intattrsonly,
LDAPMessage**res
）;
intldap_search_st（
LDAP*ld,
char*base,
intscope,
char*filter,
char*attrs[],
intattrsonly,
structtimeval*timeout,
LDAPMessage**res
）;
参数:
ld:
连接句柄
base:
开始搜索的dn条目
scope:
常量LDAP_SCOPE_BASE，LDAP_SCOPE_ONELEVEL，LDAP_SCOPE_SUBTREE之
一，表示搜寻范围。
filter:
RFC1558定义的字符串，表示搜索条件。
attr:
指明匹配条目的哪些属性将要返回的NULL结尾的字符串，传NULL串将返
回所有可用的属性。
attronly:
boolean值，为0时指明返回属性的类型和属性值，非0值只返回所需类
型。
timeout:
在调用ldap_search_st（）时，定义本地查询的超时时间。
res:
在同步调用时使用，作为返回结果参数，包含查询调用完成的结果。
Ld连接句柄的三个字段控制查询如何执行。
它们是:
Ld_sizelimit:
限制查询返回的条目数量，0代表无限制。
Ld_timelimit:
限制查询时间，以秒为单位，0代表无限制。
Ld_deref:
常量LDAP_DERF_NEVER，LDAP_DEREF_SEARCHING，LDAP_DEREF_FINDING，
LDAP_DEREF_ALWAYS之一。
描述了在查询过程中如何处理别名。
LDAP_DEREF_SEARCHING值意为在查询中别名被解除，但不会在定位于查
询的基对象时解除引用。
LDAP_DERED_FINGINFG意为别名在定位基对象但不是在查询过程中解除
引用。
异步查询由ldap_search（）初始化。
函数返回查询初始化消息ID。
查询结果将被随后的ldap_result（）调用取得。
结果由结果解释程序解释，在下面将详细介绍。
如果出错，返回-1，同时ld连接句柄的ld_errno字段将会相应设置。
同步查询通过调用ldap_search_s（）和ldap_search_st（）执行。
这些函数除了ldap_search_st（）多一个附加参数以定义查询超时外，都是相同的。
两个函数返回查询结果的标识，LDAP_SUCCESS或者错误标识（参阅错误捕获一节）。
查询条目返回结果包含在res参数中。
此参数对于调用者是非透明的。
条目，属性，值，等等，应被后面说明的函数解析出来。
包含在res中的结果应调用ldap_msgfree（）释放空间，后面将予以说明。
4.5读一个条目
LDAP不支持直接的读操作，替代以查询来模拟，设置base参数为要读的条目DN，scope设置为LDAP_SCOPE_BASE，filter设置为“（objectclass=*）”。
attrs包含返回的属性列表。
4.6列出一个条目的子条目
LDAP不支持直接列表操作，替代以查询来模拟，设置base为要列表的条目DN，scope设为LDAP_SCOPE_ONELEVEL，filter设为“（objectclass=*）”。
attrs包含返回的每一个子条目的属性列表。
4.7修改条目
ldap_modify（）和ldap_modify_s（）函数用来修改已存在的LDAP条目。
typedefstructldapmod{
intmod_op;
char*mod_type;
union{
char**modv_strvals;
structberval**modv_bvals;
}mod_vals;
}LDAPMod;
#definemod_valuesmod_vals.modv_strvals
#definemod_bvaluesmod_vals.modv_bvalsintldap_modify（LDAP*ld,char*dn,LDAPMod*mods[]）;
intldap_modify_s（LDAP*ld,char*dn,LDAPMod*mods[]）;
参数:
ld:
连接句柄
dn:
要修改的条目名
mods:
设置修改条目的空结尾的数组。
此参数在LDAPMod结构中有如下意义:
mod_op:
执行的修改操作。
为LDAP_MOD_ADD，LDAP_MOD_DELETE，
LDAP_MOD_REPLACE之一。
此字段也指明在mod_vals联合中的值的类
型。
此字段同LDAP_MOD_BVALUES进行或操作，以形成mod_bvalues
形式。
另外，mod_values形式也被使用。
Mod_type:
要修改的类型
mod_vals:
此值（如果有的话）将add，delete，replace。
仅变量mod_values或
mod_bvalues之一可以使用，选择此值同mod_op和LDAP_MOD_BVALUES常
量进行或操作。
Mod_values为以NULL结尾的NULL结尾的字符串数组，
mod_bvalues为NULL结尾的berval结构数组，可以用来传送图像一类的
二进制值。
对于LDAP_MOD_ADD修改操作，给定的值是要添加的条目，根据需要创建属性。
对于LDAP_MOD_DELETE修改操作，给定的值是要从条目中被删除的部分，如果没有保留值删除属性。
如果条目属性被删除，mod_vals字段应设为NULL。
对于LDA_REPLACE修改操作，属性会在修改后有可列表的值，根据需要被创建。
所有的修改操作按列出的顺序执行。
Ldap_modify_s（）根据修改操作结果返回LDAP错误码。
此代码由ldap_perror（）及相关函数解释。
ldap_modify（）返回请求初始化消息ID，或出错时返回-1。
操作结果由ldap_result（）获得。
4.8修改条目的RDN
ldap_modrdn和ldap_modrn_s（）函数用来修改LDAP条目名。
intldap_modrdn（
LDAP*ld,
char*dn,
char*newrdn,
intdeleteoldrdn
）;
intldap_modrdn_s（
LDAP*ld,
char*dn,
char*newrdn,
intdeleteoldrdn
）;
参数:
ld:
连接句柄
dn:
要修改的条目名
newrdn:
条目的新的RDN
deleteoldrdn:
布尔值，非0值指明删除旧的RDN，0值指明旧的RDN应保留为条目的非
区别值。
ldap_modrdn_s（）函数为同步调用，返回指明操作输出的LDAP错误码。
ldap_modrdn（）函数为异步调用，返回初始化操作的消息ID，或者出错返回-1。
由ldap_result（）取得返回结果。
4.9添加条目
ldap_add（）和ldap_add_s（）用来添加LDAP目录条目。
intldap_add（LDAP*ld,char*dn,LDAPMod*attrs[]）;
intldap_add_s（LDAP*ld,char*dn,LDAPMod*attrs[]）;
参数:
ld:
连接句柄
dn:
要添加的条目名
attrs:
条目属性，使用为ldap_modify（）定义的LDAPMod结构。
Mod_type和
mod_vals字段需要填充，mod_op字段会被忽略，除非同LDAP_MOD_BVALUES
位或后，用来选择mod_vals中的mod_bvalues。
注意:
条目的父条目必须存在。
Ldap_add_s（）为同步函数，返回指明操作输出的LDAP错误代码。
Ldap_add（）为异步函数，返回操作初始化消息ID，或出错时返回-1，结果由
ldap_result（）函数取得。
4.10删除条目
ldap_delete（）和ldap_delete_s（）用来从LDAP目录中删除条目。
intldap_delete（LDAP*ld,char*dn）;
intldap_delete_s（LDAP*ld,char*dn）;
参数:
ld:
连接句柄
dn:
要删除的条目名
注意:
要删除的条目必须为终端条目（例如:
它不能有子条目）。
LDAP不支持删除
条目子树的操作。
ldap_delete_s（）为异步函数，返回指明操作输出的LDAP错误代码。
ldap_delete（）为同步函数，返回操作初始化消息ID，或出错时返回-1，结果由
ldap_result（）函数取得。
5操作放弃调用
ldap_abandon（）用来放弃一个操作过程。
intldap_abandon（LDAP*ld,intmsgid）;ldap_abandon（）放弃消息ID为msgid的操作。
如果操作成功返回0，否则返回-1。
成功调用ldap_abandon（）后，给定消息ID的结果不会由ldap_result（）调用返回。
6取得结果的调用
ldap_result（）用来取得先前同步初始化的结果。
Ldap_msgfree（）用来释放先前调用ldap_result（）或同步查询函数取得的结果。
intldap_result（
LDAP*ld,
intmsgid,
intall,
structtimeval*timeout,
LDAPMessage**res
）;
intldap_msgfree（LDAPMessage*res）;参数:
ld:
连接句柄
msgid:
需要返回结果的操作的消息ID，或者如果一些结果需要时使用LDAP_RES_ANY
常量。
all:
布尔值，代表查询结果的含义，非0值指明在所有查询结果都应取得后才能返
回。
如为0，查询结果（条目）将会一次返回查到的一个。
timeout:
表示等待返回结果的超时时间。
NULL值将造成ldap_result（）阻塞等待，直到
结果可用。
Timeout值为0秒表示轮询状态。
res:
对于ldap_result（），是一个包含操作结果集的结果参数。
对于ldap_msgfree（），结果要被释放的结果链，从先前的
ldap_result（）,ldap_search_s或ldap_seatch_st（）调用取得。
在成功完成后，ldap_result（）返回在res参数中返回的结果的类型，这些类型为以下常量:
LDAP_RES_BIND，
LDAP_RES_SEARCH_ENTRY，
LDAP_RES_SEARCH_RESULT，
LdaP_RES_MODIFY，
LDAP_RES_ADD，
LDAP_RES_DELETE，
LDAP_RES_MODRDN，
LDAP_RES_COMPARE
Ldap_result（）在超时后返回0，出错后返回-1。
在这种情况下，ld结构的ld_err字段会相应设置。
Ldap_msgfree（）释放指向res的结果结构并返回释放的消息类型。
7错误处理调用
下面调用用来捕获其他LDAPAPI返回的错误。
intldap_result2error（
LDAP*ld,
LDAPMessage*res,
intfreeit
）;
char*ldap_err2string（interr）;voidldap_perror（LDAP*ld,char*msg）;参数:
ld:
连接句柄
res:
ldap_result（）返回的LDAP操作结果，或一个异步API操作调用的结果。
freeit:
布尔值,指明res参数是否被释放（非0值释放，0值不释放）。
err:
LDAP错误码，ldap_result2error（）返回的结果或一个同步API操作调用的结
果。
msg:
在LDAP错误信息之前显示的信息。
Ldap_result2error（）用来转换从ldap_result（）取得的LDAP结果信息，或由一个异步API操作调用的res参数返回的结果，转换成数字形式的错误码。
同时也将结果信息中的ld_matched和ld_error部分解析出来，并将它们放入连接句柄信息中。
所有的同步操作函数在返回前调用ldap_result2error（），确保这些字段正确设置。
连接结构的相关字段是:
ld_matched:
此参数包含了LDAPServer返回结果的错误信息。
Ld_errno:
指明操作输出LDAP错误码，它是下面常量之一:
LDAP_SUCCESSLDAP_BUSY
LDAP_OPERATIONS_ERRORLDAP_UNAVAILABLE
LDAP_PROTOCOL_ERRORLDAP_UNWILLING_TO_PERFORM
LDAP_TIMELIMIT_EXCEEDEDLDAP_LOOP_DETECT
LDAP_SIZELIMIT_EXCEEDEDLDAP_NAMING_VIOLATION
LDAP_COMPARE_FALSELDAP_OBJECT_CLASS_VIOLATION
LDAP_COMPARE_TRUELDAP_NOT_ALLOWED_ON_NONLEAF
LDAP_STRONG_AUTH_NOT_SUPPORTEDLDAP_NOT_ALLOWED_ON_RDN
LDAP_STRONG_AUTH_REQUIREDLDAP_ALREADY_EXISTS
LDAP_NO_SUCH_ATTRIBUTELDAP_NO_OBJECT_CLASS_MODS
LDAP_UNDEFINED_TYPELDAP_RESULTS_TOO_LARGE
LDAP_INAPPROPRIATE_MATCHINGLDAP_OTHER
LDAP_CONSTRAINT_VIOLATIONLDAP_SERVER_DOWN
LDAP_TYPE_OR_VALUE_EXISTSLDAP_LOCAL_ERROR
LDAP_INVALID_SYNTAXLDAP_ENCODING_ERROR
LDAP_NO_SUCH_OBJECTLDAP_DECODING_ERROR
LDAP_ALIAS_PROBLEMLDAP_TIMEOUT
LDAP_INVALID_DN_SYNTAXLDAP_AUTH_UNKNOWN
LDAP_IS_LEAFLDAP_FILTER_ERROR
LDAP_ALIAS_DEREF_PROBLE
升级会员 