1LDAP_SYNC(3) Library Functions Manual LDAP_SYNC(3)
2
6 ldap_sync_init, ldap_sync_init_refresh_only, ldap_sync_init_re‐
7 fresh_and_persist, ldap_sync_poll - LDAP sync routines
8
10 OpenLDAP LDAP (libldap, -lldap)
11
13 #include <ldap.h>
14 int ldap_sync_init(ldap_sync_t *ls, int mode);
16 int ldap_sync_init_refresh_only(ldap_sync_t *ls);
18 int ldap_sync_init_refresh_and_persist(ldap_sync_t *ls);
20 int ldap_sync_poll(ldap_sync_t *ls);
22 ldap_sync_t * ldap_sync_initialize(ldap_sync_t *ls);
24 void ldap_sync_destroy(ldap_sync_t *ls, int freeit);
26 typedef int (*ldap_sync_search_entry_f)(ldap_sync_t *ls,
28 LDAPMessage *msg, struct berval *entryUUID,
29 ldap_sync_refresh_t phase);
30 typedef int (*ldap_sync_search_reference_f)(ldap_sync_t *ls,
32 LDAPMessage *msg);
33 typedef int (*ldap_sync_intermediate_f)(ldap_sync_t *ls,
35 LDAPMessage *msg, BerVarray syncUUIDs,
36 ldap_sync_refresh_t phase);
37 typedef int (*ldap_sync_search_result_f)(ldap_sync_t *ls,
39 LDAPMessage *msg, int refreshDeletes);
40
42 These routines provide an interface to the LDAP Content Synchronization
43 operation (RFC 4533). They require an ldap_sync_t structure to be set
44 up with parameters required for various phases of the operation; this
45 includes setting some handlers for special events. All handlers take a
46 pointer to the ldap_sync_t structure as the first argument, and a
47 pointer to the LDAPMessage structure as received from the server by the
48 client library, plus, occasionally, other specific arguments.
49 The members of the ldap_sync_t structure are:
51 char *ls_base
53 The search base; by default, the BASE option in ldap.conf(5).
54 int ls_scope
56 The search scope (one of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL,
57 LDAP_SCOPE_SUBORDINATE or LDAP_SCOPE_SUBTREE; see ldap.h for de‐
58 tails).
59 char *ls_filter
61 The filter (RFC 4515); by default, (objectClass=*).
62 char **ls_attrs
64 The requested attributes; by default NULL, indicating all user
65 attributes.
66 int ls_timelimit
68 The requested time limit (in seconds); by default 0, to indicate
69 no limit.
70 int ls_sizelimit
72 The requested size limit (in entries); by default 0, to indicate
73 no limit.
74 int ls_timeout
76 The desired timeout during polling with ldap_sync_poll(3). A
77 value of -1 means that polling is blocking, so ldap_sync_poll(3)
78 will not return until a message is received; a value of 0 means
79 that polling returns immediately, no matter if any response is
80 available or not; a positive value represents the timeout the
81 ldap_sync_poll(3) function will wait for response before return‐
82 ing, unless a message is received; in that case,
83 ldap_sync_poll(3) returns as soon as the message is available.
84 ldap_sync_search_entry_f ls_search_entry
86 A function that is called whenever an entry is returned. The
87 msg argument is the LDAPMessage that contains the searchResul‐
88 tEntry; it can be parsed using the regular client API routines,
89 like ldap_get_dn(3), ldap_first_attribute(3), and so on. The
90 entryUUID argument contains the entryUUID of the entry. The
91 phase argument indicates the type of operation: one of
92 LDAP_SYNC_CAPI_PRESENT, LDAP_SYNC_CAPI_ADD, LDAP_SYNC_CAPI_MOD‐
93 IFY, LDAP_SYNC_CAPI_DELETE; in case of LDAP_SYNC_CAPI_PRESENT or
94 LDAP_SYNC_CAPI_DELETE, only the DN is contained in the LDAPMes‐
95 sage; in case of LDAP_SYNC_CAPI_MODIFY, the whole entry is con‐
96 tained in the LDAPMessage, and the application is responsible of
97 determining the differences between the new view of the entry
98 provided by the caller and the data already known.
99 ldap_sync_search_reference_f ls_search_reference
101 A function that is called whenever a search reference is re‐
102 turned. The msg argument is the LDAPMessage that contains the
103 searchResultReference; it can be parsed using the regular client
104 API routines, like ldap_parse_reference(3).
105 ldap_sync_intermediate_f ls_intermediate
107 A function that is called whenever something relevant occurs
108 during the refresh phase of the search, which is marked by an
109 intermediateResponse message type. The msg argument is the
110 LDAPMessage that contains the intermediate response; it can be
111 parsed using the regular client API routines, like
112 ldap_parse_intermediate(3). The syncUUIDs argument contains an
113 array of UUIDs of the entries that depends on the value of the
114 phase argument. In case of LDAP_SYNC_CAPI_PRESENTS, the
115 "present" phase is being entered; this means that the following
116 sequence of results will consist in entries in "present" sync
117 state. In case of LDAP_SYNC_CAPI_DELETES, the "deletes" phase
118 is being entered; this means that the following sequence of re‐
119 sults will consist in entries in "delete" sync state. In case
120 of LDAP_SYNC_CAPI_PRESENTS_IDSET, the message contains a set of
121 UUIDs of entries that are present; it replaces a "presents"
122 phase. In case of LDAP_SYNC_CAPI_DELETES_IDSET, the message
123 contains a set of UUIDs of entries that have been deleted; it
124 replaces a "deletes" phase. In case of LDAP_SYNC_CAPI_DONE, a
125 "presents" phase with "refreshDone" set to "TRUE" has been re‐
126 turned to indicate that the refresh phase of refreshAndPersist
127 is over, and the client should start polling. Except for the
128 LDAP_SYNC_CAPI_PRESENTS_IDSET and LDAP_SYNC_CAPI_DELETES_IDSET
129 cases, syncUUIDs is NULL.
130 ldap_sync_search_result_f ls_search_result
132 A function that is called whenever a searchResultDone is re‐
133 turned. In refreshAndPersist this can only occur when the
134 server decides that the search must be interrupted. The msg ar‐
135 gument is the LDAPMessage that contains the response; it can be
136 parsed using the regular client API routines, like
137 ldap_parse_result(3). The refreshDeletes argument is not rele‐
138 vant in this case; it should always be -1.
139 void *ls_private
141 A pointer to private data. The client may register here a
142 pointer to data the handlers above may need.
143 LDAP *ls_ld
145 A pointer to a LDAP structure that is used to connect to the
146 server. It is the responsibility of the client to initialize
147 the structure and to provide appropriate authentication and se‐
148 curity in place.
149
152 A ldap_sync_t structure is initialized by calling ldap_sync_initial‐
153 ize(3). This simply clears out the contents of an already existing
154 ldap_sync_t structure, and sets appropriate values for some members.
155 After that, the caller is responsible for setting up the connection
156 (member ls_ld), eventually setting up transport security (TLS), for
157 binding and any other initialization. The caller must also fill all
158 the documented search-related fields of the ldap_sync_t structure.
159 At the end of a session, the structure can be cleaned up by calling
161 ldap_sync_destroy(3), which takes care of freeing all data assuming it
162 was allocated by ldap_mem*[22m(3) routines. Otherwise, the caller should
163 take care of destroying and zeroing out the documented search-related
164 fields, and call ldap_sync_destroy(3) to free undocumented members set
165 by the API.
166
169 The refreshOnly functionality is obtained by periodically calling
170 ldap_sync_init(3) with mode set to LDAP_SYNC_REFRESH_ONLY, or, which is
171 equivalent, by directly calling ldap_sync_init_refresh_only(3). The
172 state of the search, and the consistency of the search parameters, is
173 preserved across calls by passing the ldap_sync_t structure as left by
174 the previous call.
175
178 The refreshAndPersist functionality is obtained by calling
179 ldap_sync_init(3) with mode set to LDAP_SYNC_REFRESH_AND_PERSIST, or,
180 which is equivalent, by directly calling ldap_sync_init_re‐
181 fresh_and_persist(3) and, after a successful return, by repeatedly
182 polling with ldap_sync_poll(3) according to the desired pattern.
183 A client may insert a call to ldap_sync_poll(3) into an external loop
185 to check if any modification was returned; in this case, it might be
186 appropriate to set ls_timeout to 0, or to set it to a finite, small
187 value. Otherwise, if the client's main purpose consists in waiting for
188 responses, a timeout of -1 is most suitable, so that the function only
189 returns after some data has been received and handled.
190
193 All routines return any LDAP error resulting from a lower-level error
194 in the API calls they are based on, or LDAP_SUCCESS in case of success.
195 ldap_sync_poll(3) may return LDAP_SYNC_REFRESH_REQUIRED if a full re‐
196 fresh is requested by the server. In this case, it is appropriate to
197 call ldap_sync_init(3) again, passing the same ldap_sync_t structure as
198 resulted from any previous call.
199
202 ldap(3), ldap_search_ext(3), ldap_result(3); RFC 4533 (http://www.rfc-
203 editor.org),
204
206 Designed and implemented by Pierangelo Masarati, based on RFC 4533 and
207 loosely inspired by syncrepl code in slapd(8).
208
210 Initially developed by SysNet s.n.c. OpenLDAP is developed and main‐
211 tained by The OpenLDAP Project (http://www.openldap.org/). OpenLDAP is
212 derived from University of Michigan LDAP 3.3 Release.
213OpenLDAP 2021/06/03 LDAP_SYNC(3)