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);
int 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.
ERRORS
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.
NOTES
SEE ALSO
ldap(3), ldap_search_ext(3), ldap_result(3); RFC 4533 (http://www.rfc-
editor.org),
AUTHOR
Designed and implemented by Pierangelo Masarati, based on RFC 4533 and
loosely inspired by syncrepl code in slapd(8).
ACKNOWLEDGEMENTS
Initially developed by SysNet s.n.c. OpenLDAP is developed and
maintained by The OpenLDAP Project (http://www.openldap.org/).
OpenLDAP is derived from University of Michigan LDAP 3.3 Release.