rfc4533.txt

samba最新软件

3.1.  Synchronization Session

   A sequence of Sync Operations where the last cookie returned by the
   server for one operation is provided by the client in the next
   operation is said to belong to the same Synchronization Session.

   The client MUST specify the same content-controlling parameters (see
   Section 3.5) in each Search Request of the session.  The client
   SHOULD also issue each Sync request of a session under the same
   authentication and authorization associations with equivalent
   integrity and protections.  If the server does not recognize the
   request cookie or the request is made under different associations or
   non-equivalent protections, the server SHALL return the initial
   content as if no cookie had been provided or return an empty content
   with the e-syncRefreshRequired LDAP result code.  The decision
   between the return of the initial content and the return of the empty
   content with the e-syncRefreshRequired result code MAY be based on
   reloadHint in the Sync Request Control from the client.  If the
   server recognizes the request cookie as representing empty or initial
   synchronization state of the client copy, the server SHALL return the
   initial content.

   A Synchronization Session may span multiple LDAP sessions between the
   client and the server.  The client SHOULD issue each Sync request of
   a session to the same server.  (Note: Shadowing considerations are
   discussed in Section 6.)

3.2.  Content Determination

   The content to be provided is determined by parameters of the Search
   Request, as described in [RFC4511], and possibly other controls.  The
   same content parameters SHOULD be used in each Sync request of a
   session.  If different content is requested and the server is
   unwilling or unable to process the request, the server SHALL return
   the initial content as if no cookie had been provided or return an
   empty content with the e-syncRefreshRequired LDAP result code.  The
   decision between the return of the initial content and the return of
   the empty content with the e-syncRefreshRequired result code MAY be
   based on reloadHint in the Sync Request Control from the client.

   The content may not necessarily include all entries or references
   that would be returned by a normal search operation, nor, for those
   entries included, all attributes returned by a normal search.  When
   the server is unwilling or unable to provide synchronization for any
   attribute for a set of entries, the server MUST treat all filter
   components matching against these attributes as Undefined and MUST
   NOT return these attributes in SearchResultEntry responses.




Zeilenga & Choi               Experimental                     [Page 12]

RFC 4533         LDAP Content Synchronization Operation        June 2006


   Servers SHOULD support synchronization for all non-collective user-
   application attributes for all entries.

   The server may also return continuation references to other servers
   or to itself.  The latter is allowed as the server may partition the
   entries it holds into separate synchronization contexts.

   The client may chase all or some of these continuations, each as a
   separate content synchronization session.

3.3.  refreshOnly Mode

   A Sync request with mode refreshOnly and with no cookie is a poll for
   initial content.  A Sync request with mode refreshOnly and with a
   cookie representing a synchronization state is a poll for content
   update.

3.3.1.  Initial Content Poll

   Upon receipt of the request, the server provides the initial content
   using a set of zero or more SearchResultEntry and
   SearchResultReference Messages followed by a SearchResultDone
   Message.

   Each SearchResultEntry Message SHALL include a Sync State Control of
   state add, an entryUUID containing the entry's UUID, and no cookie.
   Each SearchResultReference Message SHALL include a Sync State Control
   of state add, an entryUUID containing the UUID associated with the
   reference (normally the UUID of the associated named referral
   [RFC3296] object), and no cookie.  The SearchResultDone Message SHALL
   include a Sync Done Control having refreshDeletes set to FALSE.

   A resultCode value of success indicates that the operation
   successfully completed.  Otherwise, the result code indicates the
   nature of the failure.  The server may return e-syncRefreshRequired
   result code on the initial content poll if it is safe to do so when
   it is unable to perform the operation due to various reasons.
   reloadHint is set to FALSE in the SearchRequest Message requesting
   the initial content poll.

   If the operation is successful, a cookie representing the
   synchronization state of the current client copy SHOULD be returned
   for use in subsequent Sync Operations.

3.3.2.  Content Update Poll

   Upon receipt of the request, the server provides the content refresh
   using a set of zero or more SearchResultEntry and



Zeilenga & Choi               Experimental                     [Page 13]

RFC 4533         LDAP Content Synchronization Operation        June 2006


   SearchResultReference Messages followed by a SearchResultDone
   Message.

   The server is REQUIRED to:

      a) provide the sequence of messages necessary for eventual
         convergence of the client's copy of the content to the server's
         copy,

      b) treat the request as an initial content request (e.g., ignore
         the cookie or the synchronization state represented in the
         cookie),

      c) indicate that the incremental convergence is not possible by
         returning e-syncRefreshRequired,

      d) return a resultCode other than success or e-
         syncRefreshRequired.

   A Sync Operation may consist of a single present phase, a single
   delete phase, or a present phase followed by a delete phase.

   In each phase, for each entry or reference that has been added to the
   content or been changed since the previous Sync Operation indicated
   by the cookie, the server returns a SearchResultEntry or
   SearchResultReference Message, respectively, each with a Sync State
   Control consisting of state add, an entryUUID containing the UUID of
   the entry or reference, and no cookie.  Each SearchResultEntry
   Message represents the current state of a changed entry.  Each
   SearchResultReference Message represents the current state of a
   changed reference.

   In the present phase, for each entry that has not been changed since
   the previous Sync Operation, an empty SearchResultEntry is returned
   whose objectName reflects the entry's current DN, whose attributes
   field is empty, and whose Sync State Control consists of state
   present, an entryUUID containing the UUID of the entry, and no
   cookie.  For each reference that has not been changed since the
   previous Sync Operation, an empty SearchResultReference containing an
   empty SEQUENCE OF LDAPURL is returned with a Sync State Control
   consisting of state present, an entryUUID containing the UUID of the
   entry, and no cookie.  No messages are sent for entries or references
   that are no longer in the content.

   Multiple empty entries with a Sync State Control of state present
   SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
   value with refreshDeletes set to FALSE.  syncUUIDs contain a set of
   UUIDs of the entries and references unchanged since the last Sync



Zeilenga & Choi               Experimental                     [Page 14]

RFC 4533         LDAP Content Synchronization Operation        June 2006


   Operation.  syncUUIDs may be empty.  The Sync Info Message of
   syncIdSet may contain a cookie to represent the state of the content
   after performing the synchronization of the entries in the set.

   In the delete phase, for each entry no longer in the content, the
   server returns a SearchResultEntry whose objectName reflects a past
   DN of the entry or is empty, whose attributes field is empty, and
   whose Sync State Control consists of state delete, an entryUUID
   containing the UUID of the deleted entry, and no cookie.  For each
   reference no longer in the content, a SearchResultReference
   containing an empty SEQUENCE OF LDAPURL is returned with a Sync State
   Control consisting of state delete, an entryUUID containing the UUID
   of the deleted reference, and no cookie.

   Multiple empty entries with a Sync State Control of state delete
   SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
   value with refreshDeletes set to TRUE.  syncUUIDs contain a set of
   UUIDs of the entries and references that have been deleted from the
   content since the last Sync Operation.  syncUUIDs may be empty.  The
   Sync Info Message of syncIdSet may contain a cookie to represent the
   state of the content after performing the synchronization of the
   entries in the set.

   When a present phase is followed by a delete phase, the two phases
   are delimited by a Sync Info Message containing syncInfoValue of
   refreshPresent, which may contain a cookie representing the state
   after completing the present phase.  The refreshPresent contains
   refreshDone, which is always FALSE in the refreshOnly mode of Sync
   Operation because it is followed by a delete phase.

   If a Sync Operation consists of a single phase, each phase and hence
   the Sync Operation are marked as ended by a SearchResultDone Message
   with Sync Done Control, which SHOULD contain a cookie representing
   the state of the content after completing the Sync Operation.  The
   Sync Done Control contains refreshDeletes, which is set to FALSE for
   the present phase and set to TRUE for the delete phase.

   If a Sync Operation consists of a present phase followed by a delete
   phase, the Sync Operation is marked as ended at the end of the delete
   phase by a SearchResultDone Message with Sync Done Control, which
   SHOULD contain a cookie representing the state of the content after
   completing the Sync Operation.  The Sync Done Control contains
   refreshDeletes, which is set to TRUE.

   The client can specify whether it prefers to receive an initial
   content by supplying reloadHint of TRUE or to receive a e-
   syncRefreshRequired resultCode by supplying reloadHint of FALSE
   (hence absent), in the case that the server determines that it is



Zeilenga & Choi               Experimental                     [Page 15]

RFC 4533         LDAP Content Synchronization Operation        June 2006


   impossible or inefficient to achieve the eventual convergence by
   continuing the current incremental synchronization thread.

   A resultCode value of success indicates that the operation is
   successfully completed.  A resultCode value of e-syncRefreshRequired
   indicates that a full or partial refresh is needed.  Otherwise, the
   result code indicates the nature of failure.  A cookie is provided in
   the Sync Done Control for use in subsequent Sync Operations for
   incremental synchronization.

3.4.  refreshAndPersist Mode

   A Sync request with mode refreshAndPersist asks for initial content
   or content update (during the refresh stage) followed by change
   notifications (during the persist stage).

3.4.1.  refresh Stage

   The content refresh is provided as described in Section 3.3, except
   that the successful completion of content refresh is indicated by
   sending a Sync Info Message of refreshDelete or refreshPresent with a
   refreshDone value set to TRUE instead of a SearchResultDone Message
   with resultCode success.  A cookie SHOULD be returned in the Sync
   Info Message to represent the state of the content after finishing
   the refresh stage of the Sync Operation.

3.4.2.  persist Stage

   Change notifications are provided during the persist stage.

   As updates are made to the DIT, the server notifies the client of
   changes to the content.  DIT updates may cause entries and references
   to be added to the content, deleted from the content, or modified
   within the content.  DIT updates may also cause references to be
   added, deleted, or modified within the content.

   Where DIT updates cause an entry to be added to the content, the
   server provides a SearchResultEntry Message that represents the entry
   as it appears in the content.  The message SHALL include a Sync State
   Control with state of add, an entryUUID containing the entry's UUID,
   and an optional cookie.

   Where DIT updates cause a reference to be added to the content, the
   server provides a SearchResultReference Message that represents the
   reference in the content.  The message SHALL include a Sync State
   Control with state of add, an entryUUID containing the UUID
   associated with the reference, and an optional cookie.




Zeilenga & Choi               Experimental                     [Page 16]

RFC 4533         LDAP Content Synchronization Operation        June 2006


   Where DIT updates cause an entry to be modified within the content,
   the server provides a SearchResultEntry Message that represents the
   entry as it appears in the content.  The message SHALL include a Sync
   State Control with state of modify, an entryUUID containing the
   entry's UUID, and an optional cookie.

   Where DIT updates cause a reference to be modified within the
   content, the server provides a SearchResultReference Message that
   represents the reference in the content.  The message SHALL include a
   Sync State Control with state of modify, an entryUUID containing the
   UUID associated with the reference, and an optional cookie.

   Where DIT updates cause an entry to be deleted from the content, the
   server provides a SearchResultEntry Message with no attributes.  The
   message SHALL include a Sync State Control with state of delete, an
   entryUUID containing the entry's UUID, and an optional cookie.

   Where DIT updates cause a reference to be deleted from the content,
   the server provides a SearchResultReference Message with an empty
   SEQUENCE OF LDAPURL.  The message SHALL include a Sync State Control
   with state of delete, an entryUUID containing the UUID associated
   with the reference, and an optional cookie.

   Multiple empty entries with a Sync State Control of state delete
   SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
   value with refreshDeletes set to TRUE. syncUUIDs contain a set of
   UUIDs of the entries and references that have been deleted from the
   content.  The Sync Info Message of syncIdSet may contain a cookie to
   represent the state of the content after performing the
   synchronization of the entries in the set.