Man Pages

ldap_sync(3) - phpMan ldap_sync(3) - phpMan

Command: man perldoc info search(apropos)  


LDAP_SYNC(3)                                                      LDAP_SYNC(3)



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_SUB-
              TREE; 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 block-
              ing, 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 con-
              tains  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 con-
              tains 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 undocu-
       mented 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_per-
       sist(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.



OpenLDAP 2.4.40                   2014/09/20                      LDAP_SYNC(3)