rfc4533.txt

samba最新软件

   Message having a FALSE refreshDone value.  In the case that both the
   phases are used, the present phase is used to bring the client copy
   up to the state at which the subsequent delete phase can begin.

   In the present phase, the server sends an empty entry (i.e., no
   attributes) with a Sync State Control indicating state present for
   each unchanged entry.

   The delete phase may be used when the server can reliably determine
   which entries in the prior client copy are no longer present in the
   content and the number of such entries is less than or equal to the
   number of unchanged entries.  In the delete mode, the server sends an
   empty entry with a Sync State Control indicating state delete for
   each entry that is no longer in the content, instead of returning an
   empty entry with state present for each present entry.

   The server may send syncIdSet Sync Info Messages containing the set
   of UUIDs of either unchanged present entries or deleted entries,
   instead of sending multiple individual messages.  If refreshDeletes
   of syncIdSet is set to FALSE, the UUIDs of unchanged present entries
   are contained in the syncUUIDs set; if refreshDeletes of syncIdSet is
   set to TRUE, the UUIDs of the entries no longer present in the
   content are contained in the syncUUIDs set.  An optional cookie can



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


   be included in the syncIdSet to represent the state of the content
   after synchronizing the presence or the absence of the entries
   contained in the syncUUIDs set.

   The synchronized copy of the DIT fragment is constructed by the
   client.

   If refreshDeletes of syncDoneValue is FALSE, the new copy includes
   all changed entries returned by the reissued Sync Operation, as well
   as all unchanged entries identified as being present by the reissued
   Sync Operation, but whose content is provided by the previous Sync
   Operation.  The unchanged entries not identified as being present are
   deleted from the client content.  They had been either deleted,
   moved, or otherwise scoped-out from the content.

   If refreshDeletes of syncDoneValue is TRUE, the new copy includes all
   changed entries returned by the reissued Sync Operation, as well as
   all other entries of the previous copy except for those that are
   identified as having been deleted from the content.

   The client can, at some later time, re-poll for changes to this
   synchronized client copy.

1.3.2.  Listening for Changes (refreshAndPersist)

   Polling for changes can be expensive in terms of server, client, and
   network resources.  The refreshAndPersist mode allows for active
   updates of changed entries in the content.

   By selecting the refreshAndPersist mode, the client requests that the
   server send updates of entries that are changed after the initial
   refresh content is determined.  Instead of sending a SearchResultDone
   Message as in polling, the server sends a Sync Info Message to the
   client indicating that the refresh stage is complete and then enters
   the persist stage.  After receipt of this Sync Info Message, the
   client will construct a synchronized copy as described in Section
   1.3.1.

   The server may then send change notifications as the result of the
   original Sync search request, which now remains persistent in the
   server.  For entries to be added to the returned content, the server
   sends a SearchResultEntry (with attributes) with a Sync State Control
   indicating state add.  For entries to be deleted from the content,
   the server sends a SearchResultEntry containing no attributes and a
   Sync State Control indicating state delete.  For entries to be
   modified in the return content, the server sends a SearchResultEntry
   (with attributes) with a Sync State Control indicating state modify.




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


   Upon modification of an entry, all (modified or unmodified)
   attributes belonging to the content are sent.

   Note that renaming an entry of the DIT may cause an add state change
   where the entry is renamed into the content, a delete state change
   where the entry is renamed out of the content, and a modify state
   change where the entry remains in the content.  Also note that a
   modification of an entry of the DIT may cause an add, delete, or
   modify state change to the content.

   Upon receipt of a change notification, the client updates its copy of
   the content.

   If the server desires to update the syncCookie during the persist
   stage, it may include the syncCookie in any Sync State Control or
   Sync Info Message returned.

   The operation persists until canceled [RFC3909] by the client or
   terminated by the server.  A Sync Done Control shall be attached to
   SearchResultDone Message to provide a new syncCookie.

1.4.  Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in BCP 14 [RFC2119].

   Protocol elements are described using ASN.1 [X.680] with implicit
   tags.  The term "BER-encoded" means the element is to be encoded
   using the Basic Encoding Rules [X.690] under the restrictions
   detailed in Section 5.1 of [RFC4511].

2.  Elements of the Sync Operation

   The Sync Operation is defined as an extension to the LDAP Search
   Operation [RFC4511] where the directory user agent (DUA or client)
   submits a SearchRequest Message with a Sync Request Control and the
   directory system agent (DSA or server) responds with zero or more
   SearchResultEntry Messages, each with a Sync State Control; zero or
   more SearchResultReference Messages, each with a Sync State Control;
   zero or more Sync Info Intermediate Response Messages; and a
   SearchResultDone Message with a Sync Done Control.

   To allow clients to discover support for this operation, servers
   implementing this operation SHOULD publish 1.3.6.1.4.1.4203.1.9.1.1
   as a value of the 'supportedControl' attribute [RFC4512] of the root
   DSA-specific entry (DSE).  A server MAY choose to advertise this
   extension only when the client is authorized to use it.



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


2.1.  Common ASN.1 Elements

2.1.1.  syncUUID

   The syncUUID data type is an OCTET STRING holding a 128-bit
   (16-octet) Universally Unique Identifier (UUID) [UUID].

      syncUUID ::= OCTET STRING (SIZE(16))
           -- constrained to UUID

2.1.2.  syncCookie

   The syncCookie is a notational convenience to indicate that, while
   the syncCookie type is encoded as an OCTET STRING, its value is an
   opaque value containing information about the synchronization session
   and its state.  Generally, the session information would include a
   hash of the operation parameters that the server requires not be
   changed and the synchronization state information would include a
   commit (log) sequence number, a change sequence number, or a time
   stamp.  For convenience of description, the term "no cookie" refers
   either to a null cookie or to a cookie with pre-initialized
   synchronization state.

      syncCookie ::= OCTET STRING

2.2.  Sync Request Control

   The Sync Request Control is an LDAP Control [RFC4511] where the
   controlType is the object identifier 1.3.6.1.4.1.4203.1.9.1.1 and the
   controlValue, an OCTET STRING, contains a BER-encoded
   syncRequestValue.  The criticality field is either TRUE or FALSE.

      syncRequestValue ::= SEQUENCE {
          mode ENUMERATED {
              -- 0 unused
              refreshOnly       (1),
              -- 2 reserved
              refreshAndPersist (3)
          },
          cookie     syncCookie OPTIONAL,
          reloadHint BOOLEAN DEFAULT FALSE
      }

   The Sync Request Control is only applicable to the SearchRequest
   Message.






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


2.3.  Sync State Control

   The Sync State Control is an LDAP Control [RFC4511] where the
   controlType is the object identifier 1.3.6.1.4.1.4203.1.9.1.2 and the
   controlValue, an OCTET STRING, contains a BER-encoded syncStateValue.
   The criticality is FALSE.

      syncStateValue ::= SEQUENCE {
          state ENUMERATED {
              present (0),
              add (1),
              modify (2),
              delete (3)
          },
          entryUUID syncUUID,
          cookie    syncCookie OPTIONAL
      }

   The Sync State Control is only applicable to SearchResultEntry and
   SearchResultReference Messages.

2.4.  Sync Done Control

   The Sync Done Control is an LDAP Control [RFC4511] where the
   controlType is the object identifier 1.3.6.1.4.1.4203.1.9.1.3 and the
   controlValue contains a BER-encoded syncDoneValue.  The criticality
   is FALSE (and hence absent).

      syncDoneValue ::= SEQUENCE {
          cookie          syncCookie OPTIONAL,
          refreshDeletes  BOOLEAN DEFAULT FALSE
      }

   The Sync Done Control is only applicable to the SearchResultDone
   Message.
















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


2.5.  Sync Info Message

   The Sync Info Message is an LDAP Intermediate Response Message
   [RFC4511] where responseName is the object identifier
   1.3.6.1.4.1.4203.1.9.1.4 and responseValue contains a BER-encoded
   syncInfoValue.  The criticality is FALSE (and hence absent).

      syncInfoValue ::= CHOICE {
          newcookie      [0] syncCookie,
          refreshDelete  [1] SEQUENCE {
              cookie         syncCookie OPTIONAL,
              refreshDone    BOOLEAN DEFAULT TRUE
          },
          refreshPresent [2] SEQUENCE {
              cookie         syncCookie OPTIONAL,
              refreshDone    BOOLEAN DEFAULT TRUE
          },
          syncIdSet      [3] SEQUENCE {
              cookie         syncCookie OPTIONAL,
              refreshDeletes BOOLEAN DEFAULT FALSE,
              syncUUIDs      SET OF syncUUID
          }
      }

2.6.  Sync Result Codes

   The following LDAP resultCode [RFC4511] is defined:

      e-syncRefreshRequired (4096)

3.  Content Synchronization

   The Sync Operation is invoked when the client sends a SearchRequest
   Message with a Sync Request Control.

   The absence of a cookie or an initialized synchronization state in a
   cookie indicates a request for initial content, while the presence of
   a cookie representing a state of a client copy indicates a request
   for a content update.  Synchronization Sessions are discussed in
   Section 3.1.  Content Determination is discussed in Section 3.2.

   The mode is either refreshOnly or refreshAndPersist.  The refreshOnly
   and refreshAndPersist modes are discussed in Sections 3.3 and 3.4,
   respectively.  The refreshOnly mode consists only of a refresh stage,
   while the refreshAndPersist mode consists of a refresh stage and a
   subsequent persist stage.





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