# ldap_sync

## 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



    


## 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.
    


* * *