1LDAP_SYNC(3)               Library Functions Manual               LDAP_SYNC(3)
2
3
4

NAME

6       ldap_sync_init,                            ldap_sync_init_refresh_only,
7       ldap_sync_init_refresh_and_persist, ldap_sync_poll - LDAP sync routines
8

LIBRARY

10       OpenLDAP LDAP (libldap, -lldap)
11

SYNOPSIS

13       #include <ldap.h>
14
15       int ldap_sync_init(ldap_sync_t *ls, int mode);
16
17       int ldap_sync_init_refresh_only(ldap_sync_t *ls);
18
19       int ldap_sync_init_refresh_and_persist(ldap_sync_t *ls);
20
21       int ldap_sync_poll(ldap_sync_t *ls);
22
23       ldap_sync_t * ldap_sync_initialize(ldap_sync_t *ls);
24
25       int ldap_sync_destroy(ldap_sync_t *ls, int freeit);
26
27       typedef int (*ldap_sync_search_entry_f)(ldap_sync_t *ls,
28              LDAPMessage *msg, struct berval *entryUUID,
29              ldap_sync_refresh_t phase);
30
31       typedef int (*ldap_sync_search_reference_f)(ldap_sync_t *ls,
32              LDAPMessage *msg);
33
34       typedef int (*ldap_sync_intermediate_f)(ldap_sync_t *ls,
35              LDAPMessage *msg, BerVarray syncUUIDs,
36              ldap_sync_refresh_t phase);
37
38       typedef int (*ldap_sync_search_result_f)(ldap_sync_t *ls,
39              LDAPMessage *msg, int refreshDeletes);
40

DESCRIPTION

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
50       The members of the ldap_sync_t structure are:
51
52       char *ls_base
53              The search base; by default, the BASE option in ldap.conf(5).
54
55       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
58              details).
59
60       char *ls_filter
61              The filter (RFC 4515); by default, (objectClass=*).
62
63       char **ls_attrs
64              The requested attributes; by default NULL, indicating  all  user
65              attributes.
66
67       int ls_timelimit
68              The requested time limit (in seconds); by default 0, to indicate
69              no limit.
70
71       int ls_sizelimit
72              The requested size limit (in entries); by default 0, to indicate
73              no limit.
74
75       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
85       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
100       ldap_sync_search_reference_f ls_search_reference
101              A function  that  is  called  whenever  a  search  reference  is
102              returned.  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
106       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
119              results 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
126              returned 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
131       ldap_sync_search_result_f ls_search_result
132              A  function  that  is  called  whenever  a  searchResultDone  is
133              returned.  In refreshAndPersist this can  only  occur  when  the
134              server  decides  that  the  search must be interrupted.  The msg
135              argument is the LDAPMessage that contains the response;  it  can
136              be   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
140       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
144       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
148              security in place.
149
150

GENERAL USE

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
160       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*(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
167

REFRESH ONLY

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
176

REFRESH AND PERSIST

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
181       ldap_sync_init_refresh_and_persist(3) and, after a  successful  return,
182       by  repeatedly  polling with ldap_sync_poll(3) according to the desired
183       pattern.
184
185       A client may insert a call to ldap_sync_poll(3) into an  external  loop
186       to  check  if  any modification was returned; in this case, it might be
187       appropriate to set ls_timeout to 0, or to set it  to  a  finite,  small
188       value.  Otherwise, if the client's main purpose consists in waiting for
189       responses, a timeout of -1 is most suitable, so that the function  only
190       returns after some data has been received and handled.
191
192

ERRORS

194       All  routines  return any LDAP error resulting from a lower-level error
195       in the API calls they are based on, or LDAP_SUCCESS in case of success.
196       ldap_sync_poll(3)  may  return  LDAP_SYNC_REFRESH_REQUIRED  if  a  full
197       refresh is requested by the server.  In this case, it is appropriate to
198       call ldap_sync_init(3) again, passing the same ldap_sync_t structure as
199       resulted from any previous call.
200

NOTES

SEE ALSO

203       ldap(3), ldap_search_ext(3), ldap_result(3); RFC 4533  (http://www.rfc-
204       editor.org),
205

AUTHOR

207       Designed  and implemented by Pierangelo Masarati, based on RFC 4533 and
208       loosely inspired by syncrepl code in slapd(8).
209

ACKNOWLEDGEMENTS

211       Initially developed by SysNet s.n.c.  OpenLDAP is developed  and  main‐
212       tained by The OpenLDAP Project (http://www.openldap.org/).  OpenLDAP is
213       derived from University of Michigan LDAP 3.3 Release.
214
215
216
217OpenLDAP 2.4.23                   2010/06/30                      LDAP_SYNC(3)
Impressum