Provided by: libldap2-dev_2.4.28-1.1ubuntu4_amd64 bug

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.