--- /dev/null
+.TH LDAP_SYNC 3 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 2006 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
+.SH NAME
+ldap_sync_init, ldap_sync_init_refresh_only, ldap_sync_init_refresh_and_persist, ldap_sync_poll \- LDAP sync routines
+.SH LIBRARY
+OpenLDAP LDAP (libldap, -lldap)
+.SH SYNOPSIS
+.nf
+.B #include <ldap_sync.h>
+.LP
+.BI "int ldap_sync_init(ldap_sync_t *" ls ", int " mode ", int " cancel ");"
+.LP
+.BI "int ldap_sync_init_refresh_only(ldap_sync_t *" ls ", int " cancel ");"
+.LP
+.BI "int ldap_sync_init_refresh_and_persist(ldap_sync_t *" ls ", int " cancel ");"
+.LP
+.BI "int ldap_sync_poll(ldap_sync_t *" ls ");"
+.LP
+.BI "ldap_sync_t * ldap_sync_initialize(ldap_sync_t *" ls ");"
+.LP
+.BI "int ldap_sync_destroy(ldap_sync_t *" ls ", int " freeit ");"
+.LP
+.BI "typedef int (*" ldap_sync_search_entry_f ")(ldap_sync_t *" ls ","
+.RS
+.BI "LDAPMessage *" msg ", struct berval *" entryUUID ","
+.BI "ldap_sync_refresh_t " phase ");"
+.RE
+.LP
+.BI "typedef int (*" ldap_sync_search_reference_f ")(ldap_sync_t *" ls ","
+.RS
+.BI "LDAPMessage *" msg ");"
+.RE
+.LP
+.BI "typedef int (*" ldap_sync_intermediate_f ")(ldap_sync_t *" ls ","
+.RS
+.BI "LDAPMessage *" msg ", BerVarray " syncUUIDs ","
+.BI "ldap_sync_refresh_t " phase ");"
+.RE
+.LP
+.BI "typedef int (*" ldap_sync_search_result_f ")(ldap_sync_t *" ls ","
+.RS
+.BI "LDAPMessage *" msg ", int " refreshDeletes ");"
+.RE
+.SH DESCRIPTION
+.LP
+These routines provide an interface to the LDAP Content Synchronization
+operation (RFC 4533).
+They require an
+.BR 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 \fBldap_sync_t\fP structure as the first
+argument, and a pointer to the \fBLDAPMessage\fP structure as received
+from the server by the client library, plus, occasionally, other specific
+arguments.
+
+The members of the \fBldap_sync_t\fP structure are:
+.TP
+.BI "char *" ls_base
+The search base; by default, the
+.B BASE
+option in
+.BR ldap.conf (5).
+.TP
+.BI "int " ls_scope
+The search scope (one of
+.BR LDAP_SCOPE_BASE ,
+.BR LDAP_SCOPE_ONELEVEL ,
+.BR LDAP_SCOPE_SUBORDINATE
+or
+.BR LDAP_SCOPE_SUBTREE ;
+see
+.B ldap.h
+for details).
+.TP
+.BI "char *" ls_filter
+The filter (RFC 4515); by default,
+.BR (objectClass=*) .
+.TP
+.BI "char **" ls_attrs
+The requested attributes; by default
+.BR NULL ,
+indicating all user attributes.
+.TP
+.BI "int " ls_timelimit
+The requested time limit (in seconds); by default
+.BR 0 ,
+to indicate no limit.
+.TP
+.BI "int " ls_sizelimit
+The requested size limit (in entries); by default
+.BR 0 ,
+to indicate no limit.
+.TP
+.BI "int " ls_timeout
+The desired timeout during polling with
+.BR ldap_sync_poll (3).
+A value of
+.BR -1
+means that polling is blocking, so
+.BR ldap_sync_poll (3)
+will not return until a message is received; a value of
+.BR 0
+means that polling returns immediately, no matter if any response
+is available or not; a positive value represents the timeout the
+.BR ldap_sync_poll (3)
+function will wait for response before returning, unless a message
+is received; in that case,
+.BR ldap_sync_poll (3)
+returns as soon as the message is available.
+.TP
+.BI "ldap_sync_search_entry_f " ls_search_entry
+A function that is called whenever an entry is returned.
+The
+.BR msg
+argument is the
+.BR LDAPMessage
+that contains the searchResultEntry; it can be parsed using the regular
+client API routines, like
+.BR ldap_get_dn (3),
+.BR ldap_first_attribute (3),
+and so on.
+The
+.BR entryUUID
+argument contains the entryUUID of the entry.
+The
+.BR phase
+argument indicates the type of operation: one of
+.BR LDAP_SYNC_CAPI_PRESENT ,
+.BR LDAP_SYNC_CAPI_ADD ,
+.BR LDAP_SYNC_CAPI_MODIFY ,
+.BR LDAP_SYNC_CAPI_DELETE ;
+in case of
+.BR LDAP_SYNC_CAPI_PRESENT
+or
+.BR LDAP_SYNC_CAPI_DELETE ,
+only the DN is contained in the
+.IR LDAPMessage ;
+in case of
+.BR LDAP_SYNC_CAPI_MODIFY ,
+the whole entry is contained in the
+.IR 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.
+.TP
+.BI "ldap_sync_search_reference_f " ls_search_reference
+A function that is called whenever a search reference is returned.
+The
+.BR msg
+argument is the
+.BR LDAPMessage
+that contains the searchResultReference; it can be parsed using
+the regular client API routines, like
+.BR ldap_parse_reference (3).
+.TP
+.BI "ldap_sync_intermediate_f " ls_intermediate
+A function that is called whenever something relevant occurs during
+the refresh phase of the search, which is marked by
+an \fIintermediateResponse\fP message type.
+The
+.BR msg
+argument is the
+.BR LDAPMessage
+that contains the intermediate response; it can be parsed using
+the regular client API routines, like
+.BR ldap_parse_intermediate (3).
+The
+.BR syncUUIDs
+argument contains an array of UUIDs of the entries that depends
+on the value of the
+.BR phase
+argument.
+In case of
+.BR 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
+.BR 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
+.BR 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
+.BR 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
+.BR 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
+.BR LDAP_SYNC_CAPI_PRESENTS_IDSET
+and LDAP_SYNC_CAPI_DELETES_IDSET
+cases,
+.BR syncUUIDs
+is NULL.
+.BR
+.TP
+.BI "ldap_sync_search_result_f " ls_search_result
+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
+.BR msg
+argument is the
+.BR LDAPMessage
+that contains the response; it can be parsed using
+the regular client API routines, like
+.BR ldap_parse_result (3).
+The
+.BR refreshDeletes
+argument is not relevant in this case; it should always be -1.
+.TP
+.BI "void *" ls_private
+A pointer to private data. The client may register here
+a pointer to data the handlers above may need.
+.TP
+.BI "LDAP *" ls_ld
+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.
+
+.SH "GENERAL USE"
+A
+.B ldap_sync_t
+structure is initialized by calling
+.BR ldap_sync_initialize(3).
+This simply clears out the contents of an already existing
+.B ldap_sync_t
+structure, and sets appropriate values for some members.
+After that, the caller is responsible for setting up the
+connection (member
+.BR ls_ld ),
+evetually setting up transport security (TLS),
+for binding and any other initialization.
+The caller must also fill all the documented search-related fields
+of the
+.B ldap_sync_t
+structure.
+
+At the end of a session, the structure can be cleaned up by calling
+.BR ldap_sync_destroy (3),
+which takes care of freeing all data assuming it was allocated by
+.BR ldap_mem* (3)
+routines.
+Otherwise, the caller should take care of destroying and zeroing out
+the documented search-related fields, and call
+.BR ldap_sync_destroy (3)
+to free undocumented members set by the API.
+
+.SH "REFRESH ONLY"
+The
+.BR refreshOnly
+functionality is obtained by periodically calling
+.BR ldap_sync_init (3)
+with mode set to
+.BR LDAP_SYNC_REFRESH_ONLY ,
+or, which is equivalent, by directly calling
+.BR 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
+.B ldap_sync_t
+structure as left by the previous call.
+
+.SH "REFRESH AND PERSIST"
+The
+.BR refreshAndPersist
+functionality is obtained by calling
+.BR ldap_sync_init (3)
+with mode set to
+.BR LDAP_SYNC_REFRESH_AND_PERSIST ,
+or, which is equivalent, by directly calling
+.BR ldap_sync_init_refresh_and_persist (3)
+and, after a successful return, by repeatedly polling with
+.BR ldap_sync_poll (3)
+according to the desired pattern.
+
+A client may insert a call to
+.BR ldap_sync_poll (3)
+into an external loop to check if any modification was returned;
+in this case, it might be appropriate to set
+.BR ls_timeout
+to 0, or to set it to a finite, small value.
+Otherwise, if the client'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.
+
+.SH ERRORS
+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.
+.BR ldap_sync_poll (3)
+may return
+.BR LDAP_SYNC_REFRESH_REQUIRED
+if a full refresh is requested by the server.
+In this case, it is appropriate to call
+.BR ldap_sync_init (3)
+again, passing the same
+.B ldap_sync_t
+structure as resulted from any previous call.
+.SH NOTES
+.SH SEE ALSO
+.BR ldap (3),
+.BR ldap_search_ext (3),
+.BR ldap_result (3) ;
+.B RFC 4533
+(http://www.rfc-editor.org),
+.SH AUTHOR
+Designed and implemented by Pierangelo Masarati, based on RFC 4533
+and loosely inspired by syncrepl code in
+.BR slapd (8).
+.SH ACKNOWLEDGEMENTS
+Initially developed by
+.BR "SysNet s.n.c."
+.B OpenLDAP
+is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
+.B OpenLDAP
+is derived from University of Michigan LDAP 3.3 Release.
projects / openldap / commitdiff