ldap_sync_init, ldap_sync_init_refresh_only, ldap_sync_init_refresh_and_persist,
ldap_sync_poll - LDAP sync routines
OpenLDAP LDAP (libldap, -lldap)
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,
typedef int (*ldap_sync_search_reference_f)(ldap_sync_t *ls,
typedef int (*ldap_sync_intermediate_f)(ldap_sync_t *ls,
LDAPMessage *msg, BerVarray syncUUIDs,
typedef int (*ldap_sync_search_result_f)(ldap_sync_t *ls,
LDAPMessage *msg, int refreshDeletes);
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:
The search base; by default, the BASE option in ldap.conf(5).
The search scope (one of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, LDAP_SCOPE_SUBORDI-
NATE or LDAP_SCOPE_SUBTREE; see ldap.h for details).
The filter (RFC 4515); by default, (objectClass=*).
The requested attributes; by default NULL, indicating all user attributes.
The requested time limit (in seconds); by default 0, to indicate no limit.
The requested size limit (in entries); by default 0, to indicate no limit.
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 mes-
sage is received; in that case, ldap_sync_poll(3) returns as soon as the message is
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 indi-
cates 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.
A function that is called whenever a search reference is returned. The msg argu-
ment is the LDAPMessage that contains the searchResultReference; it can be parsed
using the regular client API routines, like ldap_parse_reference(3).
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 con-
sist 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.
A function that is called whenever a searchResultDone is returned. In refreshAnd-
Persist this can only occur when the server decides that the search must be inter-
rupted. 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.
A pointer to private data. The client may register here a pointer to data the han-
dlers above may need.
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.
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 connec-
tion (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 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 mod-
ification 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.
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.
ldap(3), ldap_search_ext(3), ldap_result(3); RFC 4533 (http://www.rfc-editor.org),
Designed and implemented by Pierangelo Masarati, based on RFC 4533 and loosely inspired by
syncrepl code in slapd(8).
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
OpenLDAP 2.4.25 2011/03/26 LDAP_SYNC(3)