manpagez: man pages & more
man ldap_sync_init_refresh_and_persist(3)
Home | html | info | man
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_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 return-
              ing,   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  searchResul-
              tEntry;  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_MOD-
              IFY, LDAP_SYNC_CAPI_DELETE; in case of LDAP_SYNC_CAPI_PRESENT or
              LDAP_SYNC_CAPI_DELETE,  only the DN is contained in the LDAPMes-
              sage; in case of LDAP_SYNC_CAPI_MODIFY, the whole entry is  con-
              tained 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 rele-
              vant 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_initial-
       ize(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 main-
       tained 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)

openldap 2.4.40 - Generated Fri Oct 14 15:33:54 CDT 2016
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.