|
这一部分详细描述了LDAP API的调用。所有调用依赖一个连接句柄，即指向一个包含所有连接信息的LDAP结构的指针。通常结果将返回到一个LDAPMessage结构中。部分结构将在下面说明。
4.1. 打开一个联接
ldap_open() 函数打开一个到LDAP服务器的联接。
typedef struct ldap {
/* ... 隐含参数 ... */
int ld_deref;
int ld_timelimit;
int ld_sizelimit;
int ld_errno;
char *ld_matched;
char *ld_error;
/* ...隐含参数... */
} LDAP;
LDAP *ldap_open( char *hostname, int portno );
参数:
host： 需要联接的LDAP服务器的一个分离空间的主机名列表或者是代表服务器IP地址的分离的字符串。有序列表中的主机都处于准备被联接状态，直到其中有一个被成功联接上为止。
port： 含用于联接的TCP端口号。缺省的LDAP端口能够从常量LDAP_PORT中获得。
ldap_open() 返回一个联结句柄,
即一个指向LDAP结构的指针。为随后的绑定到目录服务器提供参数值。如果打开操作失败，返回NULL。
在其它操作执行之前，必须完成ldap_bind操作（即绑定到目录服务器），关于ldap_bind的说明在后面会提到。
调用程序将不考虑LDAP结构域的顺序。可能结构中的某些域在国内图书馆会被采用。
以上的域在下面其它函数调用的描述中会有所提及。
4.2. 绑定到目录
ldap_bind()及同类函数用于绑定到目录。
int ldap_bind( LDAP *ld, char *dn, char *cred, int method );
int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );
int ldap_simple_bind( LDAP *ld, char *dn, char *passwd );
int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd );
int ldap_kerberos_bind( LDAP *ld, char *dn );
int ldap_kerberos_bind_s( LDAP *ld, char *dn );
参数：
ld 连接句柄；
dn 进行绑定操作的用户dn；
cred 认证的证件；
method LDAP_AUTH_SIMPLE，LDAP_AUTH_KRBV41，或LDAP_AUTH_ LDAPKRBV42中的一种，包含用于认证的方式。
passwd 为ldap_simple_bind()系列专有，用于与目录项中的userPassword属性值作比较。
这里有关于bind调用的三种类型，提供简单的认证，kerberos 认证，以及普通事务。由于第四版本的Kerberos认证使用了通用的ldap_bind() ，忽略了证书部分，因此系统假定存在有效的认证依据，并且能被用于恢复特定的服务依据。
与该事务一致的版本的名字以_s结尾。这些事务返回bind操作的结果。如果操作成功，返回LDAP_SUCCESS，否则返回错误代码。下一节将列出可能出现的错误句柄的更多信息并且对这些信息加以解释。
与以上事务一致的版本将返回初始化bind操作的信息id。随后调用ldap_result(),用于获取bind操作的结果。如果出错，返回-1，并在LDAP结构中设置ld_errno域。
注意，在bind操作成功之前，其它的所有操作都不能成功，其后的bind调用可用于同一联接之上的重复认证。
4.3. 关闭连接
ldap_unbind() 用于解除与目录的绑定并关闭连接。
int ldap_unbind( LDAP *ld );
参数：
ld 连接句柄。
ldap_unbind()
工作在同步模式，解除与目录的绑定，关掉连接，并在返回前释放ld结构。ldap_unbind()返回LDAP_SUCCESS
(如果请求未被送往LDAP服务器，则返回一个LDAP错误代码)。在调用完ldap_unbind()之后，ld连接句柄失效。
4.4. 查询
ldap_search() 及同类函数用于查询LDAP目录，返回匹配的目录项的请求值。
这里有三种形式：
struct timeval {
long tv_sec;
long tv_usec;
};
int ldap_search(
LDAP *ld,
char *base,
int scope,
char *filter,
char *attrs[],
int attrsonly
);
int ldap_search_s(
LDAP *ld,
char *base,
int scope,
char *filter,
char *attrs[],
int attrsonly,
LDAPMessage **res
);
int ldap_search_st(
LDAP *ld,
char *base,
int scope,
char *filter,
char *attrs[],
int attrsonly,
struct timeval *timeout,
LDAPMessage **res
);
参数：
ld 连接句柄；
base 最基本的 dn 条件值；
scope 为LDAP_SCOPE_BASE， LDAP_SCOPE_ONELEVEL，或LDAP_SCOPE_SUBTREE，表示查询的范围。
filter 匹配的字符串，在RFC 1558 [3]中有详细的描述。
attrs 为NULL时表示返回所有匹配的条目。非空导致所有可用属性将被恢复。
attrsonly 布尔值。如果为0则返回属性类型以及属性值；非0则只返回属性类型。
timeout 当调用ldap_search_st()时，它将指出本地查询的时延值。
res 当同步调用时，该参数将包含函数调用结束时的一个返回值。
有三个域决定了查询操作的执行。它们分别是：
ld_sizelimit 限制查询结果的数目。为0时表示没有限制。
ld_timelimit 限制查询的时间。为0表示没有限制。
ld_deref 其值为以下任意一个LDAP_DEREF_NEVER,
LDAP_DEREF_SEARCHING,LDAP_DEREF_FINDING,
或LDAP_DEREF_ALWAYS，指明查询时别名将怎样被绑定。
值为LDAP_DEREF_SEARCHING表示在查询时将不允许别名，但对base指定的条目将不受此限制；值为
LDAP_DEREF_FINDING时情况刚好与LDAP_DEREF_SEARCHING相反。
ldap_search()进行的是异步查询。它返回初始化查询的id值。该值被随后调用的ldap_result()函数获得，对其进行语法分析，并进行相应的描述。如果操作失败，返回-1；并且，LDAP结构中的ld_errno域将被重设。
通过调用ldap_search_s()或ldap_search_st()进行同步查询。进程将保持一致，除了ldap_search_st()函
数的额外参数将指定查询的时延。两个函数都将直接返回查询的结果：LDAP_SUCCESS或者错误代码。查询到的条目的返回值将保存在res参数里。该
参数对于调用者来说是不透明的。条目、属性、值等将通过下面介绍的函数获得。保存在参数res中的结果当不再被使用时，将通过调用
ldap_msgfree()函数进行释放，这在后面会有详细介绍。
4.5. 读取条目
LDAP 不支持直接的读操作。实际上，查询操作中的操作范围：LDAP_SCOPE_BASE，匹配条件："(objectclass=*)"都利用到了读操作。参数attrs包含了返回的属性列表。
4.6. 子条目列表
LDAP 不直接支持列表操作。实际上，查询操作中的操作范围：LDAP_SCOPE_ ONELEVEL，匹配条件："(objectclass=*)"也利用到了列表操作。参数attrs包含了返回的所有子条目的属性列表。
4.7. 修改条目
函数ldap_modify() and ldap_modify_s()用于修改存在的LDAP条目。
typedef struct ldapmod {
int mod_op;
char *mod_type;
union {
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( LDAP *ld, char *dn, LDAPMod *mods[] );
int ldap_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不能共用。只有在mods_op中指定为
LDAP_MOD_BVALUES时才能在这里设为mod_bvalues值。
mod_values为包含字符串的非空数组，字符串可为NULL。mod_bvalues为包含berval结构的非空数组，用于包含二进制类型的值，
例如图片。
LDAP_MOD_ADD模式用于在条目中创建新的属性。LDAP_MOD_DELETE模式用于删除条目中不再需要的属性。如果是删除操作，那么
mod_vals域的值将设为NULL。
LDAP_MOD_REPLACE模式中，属性值将设置为列表中定义的值。所有模式的运行顺序都遵循它们排列的先后顺序。
ldap_modify_s()返回修改操作的LDAP出错代码。该代码能被ldap_perror()及其友元函数解析。
ldap_modify() 返回初始化信息的id，出错时返回-1。操作结果通过调用ldap_result()获得。
4.8. 修改条目的RDN
ldap_modrdn()和ldap_modrdn_s()用于改变条目的名称。
int ldap_modrdn(
LDAP *ld,
char *dn,
char *newrdn,
int deleteoldrdn
);
int ldap_modrdn_s(
LDAP *ld,
char *dn,
char *newrdn,
int deleteoldrdn
);
参数：
ld 连接句柄；
dn RDN将改变的条目名称；
newrdn 给条目的新RDN；
deleteoldrdn 布尔值，非0表示旧的RDN 值将被删除，为0表示将继续保留旧的RDN值。
ldap_modrdn_s()是同步操作，返回操作结果的LDAP错误代码。
ldap_modrdn() 为异步函数，返回操作初始化的信息id。如果有误返回-1。通过调用dap_result()可以获得操作的结果。
4.9. 增加条目
ldap_add()和ldap_add_s()用于增加LDAP目录中的条目。
int ldap_add( LDAP *ld, char *dn, LDAPMod *attrs[] );
int ldap_add_s( LDAP *ld, char *dn, LDAPMod *attrs[] );
参数：
ld 连接句柄；
dn 新添加条目的名称；
attrs
条目的属性，采用ldap_modify()中定义的LDAPMod结构。要求输入mod_type与mod_vals域的值，mod_op域缺省。除非
遇到常量LDAP_MOD_BVALUES时, 需要用到相应的mod_bvalues替代mod_vals。
注意，新添加条目的父条目必须已经存在。
ldap_add_s()是同步操作，返回操作结果的LDAP错误代码。
ldap_add()为异步操作，返回操作初始化的信息id。如果有误返回-1。通过调用dap_result()可以获得操作的结果。
4.10. 删除条目
ldap_delete()和ldap_delete_s()用于删除LDAP目录中的条目。
int ldap_delete( LDAP *ld, char *dn );
int ldap_delete_s( LDAP *ld, char *dn );
参数：
ld 连接句柄；
dn 需要删除的条目名称。
注意，被删除的条目必须是“叶”条目（即，不含有子条目）。LDAP不支持删除带有子条目的结点。
ldap_delete_s() 是同步操作，返回操作结果的LDAP错误代码。
ldap_delete() 是异步操作，返回操作初始化的信息id。如果有误返回-1。通过调用dap_result()可以获得操作的结果。
|
网络协议手册
