NAME

       ldap_sync_init,  ldap_sync_init_refresh_only,  ldap_sync_init_refresh_and_persist,  ldap_sync_poll - LDAP
       sync routines

LIBRARY

       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS

       #include <ldap.h>

       int ldap_sync_init(ldap_sync_t *ls, int mode);

       int ldap_sync_init_refresh_only(ldap_sync_t *ls);

       int ldap_sync_init_refresh_and_persist(ldap_sync_t *ls);

       int ldap_sync_poll(ldap_sync_t *ls);

       ldap_sync_t * ldap_sync_initialize(ldap_sync_t *ls);

       void ldap_sync_destroy(ldap_sync_t *ls, int freeit);

       typedef int (*ldap_sync_search_entry_f)(ldap_sync_t *ls,
              LDAPMessage *msg, struct berval *entryUUID,
              ldap_sync_refresh_t phase);

       typedef int (*ldap_sync_search_reference_f)(ldap_sync_t *ls,
              LDAPMessage *msg);

       typedef int (*ldap_sync_intermediate_f)(ldap_sync_t *ls,
              LDAPMessage *msg, BerVarray syncUUIDs,
              ldap_sync_refresh_t phase);

       typedef int (*ldap_sync_search_result_f)(ldap_sync_t *ls,
              LDAPMessage *msg, int refreshDeletes);

DESCRIPTION

       These routines provide an interface to the LDAP  Content  Synchronization  operation  (RFC  4533).   They
       require  an  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
       ldap_sync_t  structure as the first argument, and a pointer to the LDAPMessage structure as received from
       the server by the client library, plus, occasionally, other specific arguments.

       The members of the ldap_sync_t structure are:

       char *ls_base
              The search base; by default, the BASE option in ldap.conf(5).

       int ls_scope
              The  search  scope  (one  of  LDAP_SCOPE_BASE,  LDAP_SCOPE_ONELEVEL,   LDAP_SCOPE_SUBORDINATE   or
              LDAP_SCOPE_SUBTREE; see ldap.h for details).

       char *ls_filter
              The filter (RFC 4515); by default, (objectClass=*).

       char **ls_attrs
              The requested attributes; by default NULL, indicating all user attributes.

       int ls_timelimit
              The requested time limit (in seconds); by default 0, to indicate no limit.

       int ls_sizelimit
              The requested size limit (in entries); by default 0, to indicate no limit.

       int ls_timeout
              The  desired  timeout  during polling with ldap_sync_poll(3).  A value of -1 means that polling is
              blocking, so ldap_sync_poll(3) will not return until a message is received; a  value  of  0  means
              that  polling returns immediately, no matter if any response is available or not; a positive value
              represents the timeout the ldap_sync_poll(3) function will wait  for  response  before  returning,
              unless  a  message  is received; in that case, ldap_sync_poll(3) returns as soon as the message is
              available.

       ldap_sync_search_entry_f ls_search_entry
              A function that is called whenever an entry is returned.  The msg argument is the LDAPMessage that
              contains  the  searchResultEntry;  it  can  be  parsed using the regular client API routines, like
              ldap_get_dn(3), ldap_first_attribute(3), and so on.  The entryUUID argument contains the entryUUID
              of  the entry.  The phase argument indicates the type of operation: one of LDAP_SYNC_CAPI_PRESENT,
              LDAP_SYNC_CAPI_ADD,     LDAP_SYNC_CAPI_MODIFY,     LDAP_SYNC_CAPI_DELETE;     in      case      of
              LDAP_SYNC_CAPI_PRESENT  or  LDAP_SYNC_CAPI_DELETE, only the DN is contained in the LDAPMessage; in
              case of  LDAP_SYNC_CAPI_MODIFY,  the  whole  entry  is  contained  in  the  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.

       ldap_sync_search_reference_f ls_search_reference
              A function that is called whenever a search reference  is  returned.   The  msg  argument  is  the
              LDAPMessage that contains the searchResultReference; it can be parsed using the regular client API
              routines, like ldap_parse_reference(3).

       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  intermediateResponse  message  type.   The msg argument is the
              LDAPMessage that contains the intermediate response; it can be parsed using the regular client API
              routines,  like  ldap_parse_intermediate(3).  The syncUUIDs argument contains an array of UUIDs of
              the entries that depends on the value of the phase argument.  In case of  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  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 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
              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 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
              LDAP_SYNC_CAPI_PRESENTS_IDSET and LDAP_SYNC_CAPI_DELETES_IDSET cases, syncUUIDs is NULL.

       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 msg argument is the
              LDAPMessage that contains the response; it can be parsed using the regular  client  API  routines,
              like  ldap_parse_result(3).   The  refreshDeletes argument is not relevant in this case; it should
              always be -1.

       void *ls_private
              A pointer to private data.  The client may register here a pointer to data the handlers above  may
              need.

       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.

GENERAL USE

       A  ldap_sync_t  structure  is initialized by calling ldap_sync_initialize(3).  This simply clears out the
       contents of an already existing ldap_sync_t structure, and sets  appropriate  values  for  some  members.
       After that, the caller is responsible for setting up the connection (member ls_ld), eventually setting up
       transport security (TLS), for binding and any other initialization.  The caller must also  fill  all  the
       documented search-related fields of the ldap_sync_t structure.

       At  the  end  of  a session, the structure can be cleaned up by calling ldap_sync_destroy(3), which takes
       care of freeing all data assuming it was allocated  by  ldap_mem*(3)  routines.   Otherwise,  the  caller
       should  take  care  of  destroying  and  zeroing  out  the  documented  search-related  fields,  and call
       ldap_sync_destroy(3) to free undocumented members set by the API.

REFRESH ONLY

       The refreshOnly functionality is obtained by periodically calling  ldap_sync_init(3)  with  mode  set  to
       LDAP_SYNC_REFRESH_ONLY, or, which is equivalent, by directly calling 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 ldap_sync_t structure as left by the previous call.

REFRESH AND PERSIST

       The   refreshAndPersist  functionality  is  obtained  by  calling  ldap_sync_init(3)  with  mode  set  to
       LDAP_SYNC_REFRESH_AND_PERSIST,     or,     which     is     equivalent,     by      directly      calling
       ldap_sync_init_refresh_and_persist(3)  and,  after  a  successful  return,  by  repeatedly  polling  with
       ldap_sync_poll(3) according to the desired pattern.

       A client may insert a call to ldap_sync_poll(3) into an external loop to check if  any  modification  was
       returned;  in  this case, it might be appropriate to set 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.

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.  ldap_sync_poll(3) may return LDAP_SYNC_REFRESH_REQUIRED  if  a  full
       refresh  is  requested  by  the server.  In this case, it is appropriate to call ldap_sync_init(3) again,
       passing the same ldap_sync_t structure as resulted from any previous call.

NOTES

SEE ALSO

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

AUTHOR

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

ACKNOWLEDGEMENTS

       Initially  developed  by  SysNet  s.n.c.   OpenLDAP  is  developed and maintained by The OpenLDAP Project
       (http://www.openldap.org/).  OpenLDAP is derived from University of Michigan LDAP 3.3 Release.