external/bsd/openldap/man/ldap_sync.3

   1 .TH LDAP_SYNC 3 "2008/07/16" "OpenLDAP 2.4.11"
   2 .\" $OpenLDAP: pkg/ldap/doc/man/man3/ldap_sync.3,v 1.1.2.3 2008/02/11 23:26:39 kurt Exp $
   3 .\" Copyright 2006-2008 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 ");"
  14 .LP
  15 .BI "int ldap_sync_init_refresh_only(ldap_sync_t *" ls ");"
  16 .LP
  17 .BI "int ldap_sync_init_refresh_and_persist(ldap_sync_t *" ls  ");"
  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
 202 .BR LDAP_SYNC_CAPI_DELETES_IDSET
 203 cases,
 204 .BR syncUUIDs
 205 is NULL.
 206 .BR
 207 .TP
 208 .BI "ldap_sync_search_result_f " ls_search_result
 209 A function that is called whenever a searchResultDone is returned.
 210 In refreshAndPersist this can only occur when the server decides
 211 that the search must be interrupted.
 212 The
 213 .BR msg
 214 argument is the
 215 .BR LDAPMessage
 216 that contains the response; it can be parsed using
 217 the regular client API routines, like
 218 .BR ldap_parse_result (3).
 219 The
 220 .BR refreshDeletes
 221 argument is not relevant in this case; it should always be -1.
 222 .TP
 223 .BI "void *" ls_private
 224 A pointer to private data.  The client may register here
 225 a pointer to data the handlers above may need.
 226 .TP
 227 .BI "LDAP *" ls_ld
 228 A pointer to a LDAP structure that is used to connect to the server.
 229 It is the responsibility of the client to initialize the structure
 230 and to provide appropriate authentication and security in place.
 231
 232 .SH "GENERAL USE"
 233 A
 234 .B ldap_sync_t
 235 structure is initialized by calling
 236 .BR ldap_sync_initialize(3).
 237 This simply clears out the contents of an already existing
 238 .B ldap_sync_t
 239 structure, and sets appropriate values for some members.
 240 After that, the caller is responsible for setting up the
 241 connection (member
 242 .BR ls_ld ),
 243 eventually setting up transport security (TLS),
 244 for binding and any other initialization.
 245 The caller must also fill all the documented search-related fields
 246 of the
 247 .B ldap_sync_t
 248 structure.
 249
 250 At the end of a session, the structure can be cleaned up by calling
 251 .BR ldap_sync_destroy (3),
 252 which takes care of freeing all data assuming it was allocated by
 253 .BR ldap_mem* (3)
 254 routines.
 255 Otherwise, the caller should take care of destroying and zeroing out
 256 the documented search-related fields, and call
 257 .BR ldap_sync_destroy (3)
 258 to free undocumented members set by the API.
 259
 260 .SH "REFRESH ONLY"
 261 The
 262 .BR refreshOnly
 263 functionality is obtained by periodically calling
 264 .BR ldap_sync_init (3)
 265 with mode set to
 266 .BR LDAP_SYNC_REFRESH_ONLY ,
 267 or, which is equivalent, by directly calling
 268 .BR ldap_sync_init_refresh_only (3).
 269 The state of the search, and the consistency of the search parameters,
 270 is preserved across calls by passing the
 271 .B ldap_sync_t
 272 structure as left by the previous call.
 273
 274 .SH "REFRESH AND PERSIST"
 275 The
 276 .BR refreshAndPersist
 277 functionality is obtained by calling
 278 .BR ldap_sync_init (3)
 279 with mode set to
 280 .BR LDAP_SYNC_REFRESH_AND_PERSIST ,
 281 or, which is equivalent, by directly calling
 282 .BR ldap_sync_init_refresh_and_persist (3)
 283 and, after a successful return, by repeatedly polling with
 284 .BR ldap_sync_poll (3)
 285 according to the desired pattern.
 286
 287 A client may insert a call to
 288 .BR ldap_sync_poll (3)
 289 into an external loop to check if any modification was returned;
 290 in this case, it might be appropriate to set
 291 .BR ls_timeout
 292 to 0, or to set it to a finite, small value.
 293 Otherwise, if the client's main purpose consists in waiting for
 294 responses, a timeout of -1 is most suitable, so that the function
 295 only returns after some data has been received and handled.
 296
 297 .SH ERRORS
 298 All routines return any LDAP error resulting from a lower-level error
 299 in the API calls they are based on, or LDAP_SUCCESS in case of success.
 300 .BR ldap_sync_poll (3)
 301 may return
 302 .BR LDAP_SYNC_REFRESH_REQUIRED
 303 if a full refresh is requested by the server.
 304 In this case, it is appropriate to call
 305 .BR ldap_sync_init (3)
 306 again, passing the same
 307 .B ldap_sync_t
 308 structure as resulted from any previous call.
 309 .SH NOTES
 310 .SH SEE ALSO
 311 .BR ldap (3),
 312 .BR ldap_search_ext (3),
 313 .BR ldap_result (3) ;
 314 .B RFC 4533
 315 (http://www.rfc-editor.org),
 316 .SH AUTHOR
 317 Designed and implemented by Pierangelo Masarati, based on RFC 4533
 318 and loosely inspired by syncrepl code in
 319 .BR slapd (8).
 320 .SH ACKNOWLEDGEMENTS
 321 Initially developed by
 322 .BR "SysNet s.n.c."
 323 .B OpenLDAP
 324 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 325 .B OpenLDAP
 326 is derived from University of Michigan LDAP 3.3 Release.