git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_sync.3

   1 .TH LDAP_SYNC 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 2006 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_sync_init, ldap_sync_init_refresh_only, ldap_sync_init_refresh_and_persist, ldap_sync_poll \- LDAP sync routines
   7 .SH LIBRARY
   8 OpenLDAP LDAP (libldap, -lldap)
   9 .SH SYNOPSIS
  10 .nf
  11 .B #include <ldap_sync.h>
  12 .LP
  13 .BI "int ldap_sync_init(ldap_sync_t *" ls ", int " mode ", int " cancel ");"
  14 .LP
  15 .BI "int ldap_sync_init_refresh_only(ldap_sync_t *" ls ", int " cancel ");"
  16 .LP
  17 .BI "int ldap_sync_init_refresh_and_persist(ldap_sync_t *" ls ", int " cancel ");"
  18 .LP
  19 .BI "int ldap_sync_poll(ldap_sync_t *" ls ");"
  20 .LP
  21 .BI "ldap_sync_t * ldap_sync_initialize(ldap_sync_t *" ls ");"
  22 .LP
  23 .BI "int ldap_sync_destroy(ldap_sync_t *" ls ", int " freeit ");"
  24 .LP
  25 .BI "typedef int (*" ldap_sync_search_entry_f ")(ldap_sync_t *" ls ","
  26 .RS
  27 .BI "LDAPMessage *" msg ", struct berval *" entryUUID ","
  28 .BI "ldap_sync_refresh_t " phase ");"
  29 .RE
  30 .LP
  31 .BI "typedef int (*" ldap_sync_search_reference_f ")(ldap_sync_t *" ls ","
  32 .RS
  33 .BI "LDAPMessage *" msg ");"
  34 .RE
  35 .LP
  36 .BI "typedef int (*" ldap_sync_intermediate_f ")(ldap_sync_t *" ls ","
  37 .RS
  38 .BI "LDAPMessage *" msg ", BerVarray " syncUUIDs ","
  39 .BI "ldap_sync_refresh_t " phase ");"
  40 .RE
  41 .LP
  42 .BI "typedef int (*" ldap_sync_search_result_f ")(ldap_sync_t *" ls ","
  43 .RS
  44 .BI "LDAPMessage *" msg ", int " refreshDeletes ");"
  45 .RE
  46 .SH DESCRIPTION
  47 .LP
  48 These routines provide an interface to the LDAP Content Synchronization
  49 operation (RFC 4533).
  50 They require an
  51 .BR ldap_sync_t
  52 structure to be set up with parameters required for various phases
  53 of the operation; this includes setting some handlers for special events.
  54 All handlers take a pointer to the \fBldap_sync_t\fP structure as the first
  55 argument, and a pointer to the \fBLDAPMessage\fP structure as received
  56 from the server by the client library, plus, occasionally, other specific
  57 arguments.
  58
  59 The members of the \fBldap_sync_t\fP structure are:
  60 .TP
  61 .BI "char *" ls_base
  62 The search base; by default, the
  63 .B BASE
  64 option in
  65 .BR ldap.conf (5).
  66 .TP
  67 .BI "int " ls_scope
  68 The search scope (one of
  69 .BR LDAP_SCOPE_BASE ,
  70 .BR LDAP_SCOPE_ONELEVEL ,
  71 .BR LDAP_SCOPE_SUBORDINATE
  72 or
  73 .BR LDAP_SCOPE_SUBTREE ;
  74 see
  75 .B ldap.h
  76 for details).
  77 .TP
  78 .BI "char *" ls_filter
  79 The filter (RFC 4515); by default,
  80 .BR (objectClass=*) .
  81 .TP
  82 .BI "char **" ls_attrs
  83 The requested attributes; by default
  84 .BR NULL ,
  85 indicating all user attributes.
  86 .TP
  87 .BI "int " ls_timelimit
  88 The requested time limit (in seconds); by default
  89 .BR 0 ,
  90 to indicate no limit.
  91 .TP
  92 .BI "int " ls_sizelimit
  93 The requested size limit (in entries); by default
  94 .BR 0 ,
  95 to indicate no limit.
  96 .TP
  97 .BI "int " ls_timeout
  98 The desired timeout during polling with
  99 .BR ldap_sync_poll (3).
 100 A value of
 101 .BR -1
 102 means that polling is blocking, so
 103 .BR ldap_sync_poll (3)
 104 will not return until a message is received; a value of
 105 .BR 0
 106 means that polling returns immediately, no matter if any response
 107 is available or not; a positive value represents the timeout the
 108 .BR ldap_sync_poll (3)
 109 function will wait for response before returning, unless a message
 110 is received; in that case,
 111 .BR ldap_sync_poll (3)
 112 returns as soon as the message is available.
 113 .TP
 114 .BI "ldap_sync_search_entry_f " ls_search_entry
 115 A function that is called whenever an entry is returned.
 116 The
 117 .BR msg
 118 argument is the
 119 .BR LDAPMessage
 120 that contains the searchResultEntry; it can be parsed using the regular
 121 client API routines, like
 122 .BR ldap_get_dn (3),
 123 .BR ldap_first_attribute (3),
 124 and so on.
 125 The
 126 .BR entryUUID
 127 argument contains the entryUUID of the entry.
 128 The
 129 .BR phase
 130 argument indicates the type of operation: one of
 131 .BR LDAP_SYNC_CAPI_PRESENT ,
 132 .BR LDAP_SYNC_CAPI_ADD ,
 133 .BR LDAP_SYNC_CAPI_MODIFY ,
 134 .BR LDAP_SYNC_CAPI_DELETE ;
 135 in case of
 136 .BR LDAP_SYNC_CAPI_PRESENT
 137 or
 138 .BR LDAP_SYNC_CAPI_DELETE ,
 139 only the DN is contained in the
 140 .IR LDAPMessage ;
 141 in case of
 142 .BR LDAP_SYNC_CAPI_MODIFY ,
 143 the whole entry is contained in the
 144 .IR LDAPMessage ,
 145 and the application is responsible of determining the differences
 146 between the new view of the entry provided by the caller and the data
 147 already known.
 148 .TP
 149 .BI "ldap_sync_search_reference_f " ls_search_reference
 150 A function that is called whenever a search reference is returned.
 151 The
 152 .BR msg
 153 argument is the
 154 .BR LDAPMessage
 155 that contains the searchResultReference; it can be parsed using
 156 the regular client API routines, like
 157 .BR ldap_parse_reference (3).
 158 .TP
 159 .BI "ldap_sync_intermediate_f " ls_intermediate
 160 A function that is called whenever something relevant occurs during
 161 the refresh phase of the search, which is marked by
 162 an \fIintermediateResponse\fP message type.
 163 The
 164 .BR msg
 165 argument is the
 166 .BR LDAPMessage
 167 that contains the intermediate response; it can be parsed using
 168 the regular client API routines, like
 169 .BR ldap_parse_intermediate (3).
 170 The
 171 .BR syncUUIDs
 172 argument contains an array of UUIDs of the entries that depends
 173 on the value of the
 174 .BR phase
 175 argument.
 176 In case of
 177 .BR LDAP_SYNC_CAPI_PRESENTS ,
 178 the "present" phase is being entered;
 179 this means that the following sequence of results will consist
 180 in entries in "present" sync state.
 181 In case of
 182 .BR LDAP_SYNC_CAPI_DELETES ,
 183 the "deletes" phase is being entered;
 184 this means that the following sequence of results will consist
 185 in entries in "delete" sync state.
 186 In case of
 187 .BR LDAP_SYNC_CAPI_PRESENTS_IDSET ,
 188 the message contains a set of UUIDs of entries that are present;
 189 it replaces a "presents" phase.
 190 In case of
 191 .BR LDAP_SYNC_CAPI_DELETES_IDSET ,
 192 the message contains a set of UUIDs of entries that have been deleted;
 193 it replaces a "deletes" phase.
 194 In case of
 195 .BR LDAP_SYNC_CAPI_DONE,
 196 a "presents" phase with "refreshDone" set to "TRUE" has been returned
 197 to indicate that the refresh phase of refreshAndPersist is over, and
 198 the client should start polling.
 199 Except for the
 200 .BR LDAP_SYNC_CAPI_PRESENTS_IDSET
 201 and LDAP_SYNC_CAPI_DELETES_IDSET
 202 cases,
 203 .BR syncUUIDs
 204 is NULL.
 205 .BR
 206 .TP
 207 .BI "ldap_sync_search_result_f " ls_search_result
 208 A function that is called whenever a searchResultDone is returned.
 209 In refreshAndPersist this can only occur when the server decides
 210 that the search must be interrupted.
 211 The
 212 .BR msg
 213 argument is the
 214 .BR LDAPMessage
 215 that contains the response; it can be parsed using
 216 the regular client API routines, like
 217 .BR ldap_parse_result (3).
 218 The
 219 .BR refreshDeletes
 220 argument is not relevant in this case; it should always be -1.
 221 .TP
 222 .BI "void *" ls_private
 223 A pointer to private data.  The client may register here
 224 a pointer to data the handlers above may need.
 225 .TP
 226 .BI "LDAP *" ls_ld
 227 A pointer to a LDAP structure that is used to connect to the server.
 228 It is the responsibility of the client to initialize the structure
 229 and to provide appropriate authentication and security in place.
 230
 231 .SH "GENERAL USE"
 232 A
 233 .B ldap_sync_t
 234 structure is initialized by calling
 235 .BR ldap_sync_initialize(3).
 236 This simply clears out the contents of an already existing
 237 .B ldap_sync_t
 238 structure, and sets appropriate values for some members.
 239 After that, the caller is responsible for setting up the
 240 connection (member
 241 .BR ls_ld ),
 242 evetually setting up transport security (TLS),
 243 for binding and any other initialization.
 244 The caller must also fill all the documented search-related fields
 245 of the
 246 .B ldap_sync_t
 247 structure.
 248
 249 At the end of a session, the structure can be cleaned up by calling
 250 .BR ldap_sync_destroy (3),
 251 which takes care of freeing all data assuming it was allocated by
 252 .BR ldap_mem* (3)
 253 routines.
 254 Otherwise, the caller should take care of destroying and zeroing out
 255 the documented search-related fields, and call
 256 .BR ldap_sync_destroy (3)
 257 to free undocumented members set by the API.
 258
 259 .SH "REFRESH ONLY"
 260 The
 261 .BR refreshOnly
 262 functionality is obtained by periodically calling
 263 .BR ldap_sync_init (3)
 264 with mode set to
 265 .BR LDAP_SYNC_REFRESH_ONLY ,
 266 or, which is equivalent, by directly calling
 267 .BR ldap_sync_init_refresh_only (3).
 268 The state of the search, and the consistency of the search parameters,
 269 is preserved across calls by passing the
 270 .B ldap_sync_t
 271 structure as left by the previous call.
 272
 273 .SH "REFRESH AND PERSIST"
 274 The
 275 .BR refreshAndPersist
 276 functionality is obtained by calling
 277 .BR ldap_sync_init (3)
 278 with mode set to
 279 .BR LDAP_SYNC_REFRESH_AND_PERSIST ,
 280 or, which is equivalent, by directly calling
 281 .BR ldap_sync_init_refresh_and_persist (3)
 282 and, after a successful return, by repeatedly polling with
 283 .BR ldap_sync_poll (3)
 284 according to the desired pattern.
 285
 286 A client may insert a call to
 287 .BR ldap_sync_poll (3)
 288 into an external loop to check if any modification was returned;
 289 in this case, it might be appropriate to set
 290 .BR ls_timeout
 291 to 0, or to set it to a finite, small value.
 292 Otherwise, if the client's main purpose consists in waiting for
 293 responses, a timeout of -1 is most suitable, so that the function
 294 only returns after some data has been received and handled.
 295
 296 .SH ERRORS
 297 All routines return any LDAP error resulting from a lower-level error
 298 in the API calls they are based on, or LDAP_SUCCESS in case of success.
 299 .BR ldap_sync_poll (3)
 300 may return
 301 .BR LDAP_SYNC_REFRESH_REQUIRED
 302 if a full refresh is requested by the server.
 303 In this case, it is appropriate to call
 304 .BR ldap_sync_init (3)
 305 again, passing the same
 306 .B ldap_sync_t
 307 structure as resulted from any previous call.
 308 .SH NOTES
 309 .SH SEE ALSO
 310 .BR ldap (3),
 311 .BR ldap_search_ext (3),
 312 .BR ldap_result (3) ;
 313 .B RFC 4533
 314 (http://www.rfc-editor.org),
 315 .SH AUTHOR
 316 Designed and implemented by Pierangelo Masarati, based on RFC 4533
 317 and loosely inspired by syncrepl code in
 318 .BR slapd (8).
 319 .SH ACKNOWLEDGEMENTS
 320 Initially developed by
 321 .BR "SysNet s.n.c."
 322 .B OpenLDAP
 323 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 324 .B OpenLDAP
 325 is derived from University of Michigan LDAP 3.3 Release.