Section (3) ldap_sync
ldap_sync_init, ldap_sync_init_refresh_only, ldap_sync_init_refresh_and_persist, ldap_sync_poll — LDAP sync routines
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);
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
BASEoption in ldap.conf(5).
The search scope (one of
The filter (RFC 4515); by default,
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
0means 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.
A function that is called whenever an entry is returned. The
msgargument 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
entryUUIDargument contains the entryUUID of the entry. The
phaseargument indicates the type of operation: one of
LDAP_SYNC_CAPI_DELETE; in case of
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
msgargument 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
msgargument is the LDAPMessage that contains the intermediate response; it can be parsed using the regular client API routines, like ldap_parse_intermediate(3). The
syncUUIDsargument contains an array of UUIDs of the entries that depends on the value of the
phaseargument. 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
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
msgargument is the LDAPMessage that contains the response; it can be parsed using the regular client API routines, like ldap_parse_result(3). The
refreshDeletesargument 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 handlers 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 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.
functionality is obtained by periodically calling ldap_sync_init(3) with mode
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
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
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_zsingle_quotesz_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
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.
Designed and implemented by Pierangelo Masarati, based on RFC 4533 and loosely inspired by syncrepl code in slapd(8).