подпрограммы синхронизации LDAP (LDAP sync routines)
Имя (Name)
ldap_sync_init, ldap_sync_init_refresh_only,
ldap_sync_init_refresh_and_persist, ldap_sync_poll - LDAP sync
routines
Библиотека (Library)
OpenLDAP LDAP (libldap, -lldap)
Синопсис (Synopsis)
#include <ldap.h>
int ldap_sync_init(ldap_sync_t *ls, int mode);
int ldap_sync_init_refresh_only(ldap_sync_t *ls);
int ldap_sync_init_refresh_and_persist(ldap_sync_t *ls);
int ldap_sync_poll(ldap_sync_t *ls);
ldap_sync_t * ldap_sync_initialize(ldap_sync_t *ls);
void ldap_sync_destroy(ldap_sync_t *ls, int freeit);
typedef int (*ldap_sync_search_entry_f)(ldap_sync_t *ls,
LDAPMessage *msg, struct berval *entryUUID,
ldap_sync_refresh_t phase);
typedef int (*ldap_sync_search_reference_f)(ldap_sync_t *ls,
LDAPMessage *msg);
typedef int (*ldap_sync_intermediate_f)(ldap_sync_t *ls,
LDAPMessage *msg, BerVarray syncUUIDs,
ldap_sync_refresh_t phase);
typedef int (*ldap_sync_search_result_f)(ldap_sync_t *ls,
LDAPMessage *msg, int refreshDeletes);
Описание (Description)
These routines provide an interface to the LDAP Content
Synchronization operation (RFC 4533). They require an
ldap_sync_t structure to be set up with parameters required for
various phases of the operation; this includes setting some
handlers for special events. All handlers take a pointer to the
ldap_sync_t structure as the first argument, and a pointer to the
LDAPMessage structure as received from the server by the client
library, plus, occasionally, other specific arguments.
The members of the ldap_sync_t structure are:
char *ls_base
The search base; by default, the BASE option in
ldap.conf(5).
int ls_scope
The search scope (one of LDAP_SCOPE_BASE,
LDAP_SCOPE_ONELEVEL, LDAP_SCOPE_SUBORDINATE or
LDAP_SCOPE_SUBTREE; see ldap.h for details).
char *ls_filter
The filter (RFC 4515); by default, (objectClass=*).
char **ls_attrs
The requested attributes; by default NULL, indicating all
user attributes.
int ls_timelimit
The requested time limit (in seconds); by default 0, to
indicate no limit.
int ls_sizelimit
The requested size limit (in entries); by default 0, to
indicate no limit.
int ls_timeout
The desired timeout during polling with ldap_sync_poll(3).
A value of -1 means that polling is blocking, so
ldap_sync_poll(3) will not return until a message is
received; a value of 0 means that polling returns
immediately, no matter if any response is available or
not; a positive value represents the timeout the
ldap_sync_poll(3) function will wait for response before
returning, unless a message is received; in that case,
ldap_sync_poll(3) returns as soon as the message is
available.
ldap_sync_search_entry_f ls_search_entry
A function that is called whenever an entry is returned.
The msg argument is the LDAPMessage that contains the
searchResultEntry; it can be parsed using the regular
client API routines, like ldap_get_dn(3),
ldap_first_attribute(3), and so on. The entryUUID
argument contains the entryUUID of the entry. The phase
argument indicates the type of operation: one of
LDAP_SYNC_CAPI_PRESENT, LDAP_SYNC_CAPI_ADD,
LDAP_SYNC_CAPI_MODIFY, LDAP_SYNC_CAPI_DELETE; in case of
LDAP_SYNC_CAPI_PRESENT or LDAP_SYNC_CAPI_DELETE, only the
DN is contained in the LDAPMessage; in case of
LDAP_SYNC_CAPI_MODIFY, the whole entry is contained in the
LDAPMessage, and the application is responsible of
determining the differences between the new view of the
entry provided by the caller and the data already known.
ldap_sync_search_reference_f ls_search_reference
A function that is called whenever a search reference is
returned. The msg argument is the LDAPMessage that
contains the searchResultReference; it can be parsed using
the regular client API routines, like
ldap_parse_reference(3).
ldap_sync_intermediate_f ls_intermediate
A function that is called whenever something relevant
occurs during the refresh phase of the search, which is
marked by an intermediateResponse message type. The msg
argument is the LDAPMessage that contains the intermediate
response; it can be parsed using the regular client API
routines, like ldap_parse_intermediate(3). The syncUUIDs
argument contains an array of UUIDs of the entries that
depends on the value of the phase argument. In case of
LDAP_SYNC_CAPI_PRESENTS, the "present" phase is being
entered; this means that the following sequence of results
will consist in entries in "present" sync state. In case
of LDAP_SYNC_CAPI_DELETES, the "deletes" phase is being
entered; this means that the following sequence of results
will consist in entries in "delete" sync state. In case
of LDAP_SYNC_CAPI_PRESENTS_IDSET, the message contains a
set of UUIDs of entries that are present; it replaces a
"presents" phase. In case of
LDAP_SYNC_CAPI_DELETES_IDSET, the message contains a set
of UUIDs of entries that have been deleted; it replaces a
"deletes" phase. In case of LDAP_SYNC_CAPI_DONE, a
"presents" phase with "refreshDone" set to "TRUE" has been
returned to indicate that the refresh phase of
refreshAndPersist is over, and the client should start
polling. Except for the LDAP_SYNC_CAPI_PRESENTS_IDSET and
LDAP_SYNC_CAPI_DELETES_IDSET cases, syncUUIDs is NULL.
ldap_sync_search_result_f ls_search_result
A function that is called whenever a searchResultDone is
returned. In refreshAndPersist this can only occur when
the server decides that the search must be interrupted.
The msg argument is the LDAPMessage that contains the
response; it can be parsed using the regular client API
routines, like ldap_parse_result(3). The refreshDeletes
argument is not relevant in this case; it should always be
-1.
void *ls_private
A pointer to private data. The client may register here a
pointer to data the handlers above may need.
LDAP *ls_ld
A pointer to a LDAP structure that is used to connect to
the server. It is the responsibility of the client to
initialize the structure and to provide appropriate
authentication and security in place.
Общее использование (General use)
A ldap_sync_t structure is initialized by calling
ldap_sync_initialize(3). This simply clears out the contents of
an already existing ldap_sync_t structure, and sets appropriate
values for some members. After that, the caller is responsible
for setting up the connection (member ls_ld), eventually setting
up transport security (TLS), for binding and any other
initialization. The caller must also fill all the documented
search-related fields of the ldap_sync_t structure.
At the end of a session, the structure can be cleaned up by
calling ldap_sync_destroy(3), which takes care of freeing all
data assuming it was allocated by ldap_mem*(3) routines.
Otherwise, the caller should take care of destroying and zeroing
out the documented search-related fields, and call
ldap_sync_destroy(3) to free undocumented members set by the API.
Только обновление (Refresh only)
The refreshOnly functionality is obtained by periodically calling
ldap_sync_init(3) with mode set to LDAP_SYNC_REFRESH_ONLY, or,
which is equivalent, by directly calling
ldap_sync_init_refresh_only(3). The state of the search, and the
consistency of the search parameters, is preserved across calls
by passing the ldap_sync_t structure as left by the previous
call.
Обновление и устойчивость (Refresh and persist)
The refreshAndPersist functionality is obtained by calling
ldap_sync_init(3) with mode set to LDAP_SYNC_REFRESH_AND_PERSIST,
or, which is equivalent, by directly calling
ldap_sync_init_refresh_and_persist(3) and, after a successful
return, by repeatedly polling with ldap_sync_poll(3) according to
the desired pattern.
A client may insert a call to ldap_sync_poll(3) into an external
loop to check if any modification was returned; in this case, it
might be appropriate to set ls_timeout to 0, or to set it to a
finite, small value. Otherwise, if the client's main purpose
consists in waiting for responses, a timeout of -1 is most
suitable, so that the function only returns after some data has
been received and handled.
Ошибки (Error)
All routines return any LDAP error resulting from a lower-level
error in the API calls they are based on, or LDAP_SUCCESS in case
of success. ldap_sync_poll(3) may return
LDAP_SYNC_REFRESH_REQUIRED if a full refresh is requested by the
server. In this case, it is appropriate to call
ldap_sync_init(3) again, passing the same ldap_sync_t structure
as resulted from any previous call.
Смотри также (See also)
ldap(3), ldap_search_ext(3), ldap_result(3); RFC 4533
(http://www.rfc-editor.org),
