Persistent search

The persistent search control can be included in the Controls portion of an LDAP V3 search request message. The controlType for the persistent search control is "2.16.840.1.113730.3.4.3".

PersistentSearch ::= SEQUENCE {
                       changeTypes INTEGER,
                       changesOnly BOOLEAN,
                       returnECs BOOLEAN
                     }

On receiving this control, the Directory Server processes the request as a standard LDAP V3 search with the following exceptions:

• If changesOnly is TRUE, the server does not return any existing entries that match the search criteria. Entries are only returned when they are changed by an update operation such as add, modify, delete, or modifyDN operation.
• After the changes are made to the server, the affected entries that match the search criteria are returned to the client only if the operation that caused the change is included in the changeTypes field. The changeTypes field is the logical or of one or more of these values: add (1), delete (2), modify (4), and modDN (8).
• After the operation is done, the server does not return a SearchResultDone message. Instead, the search operation is kept active until the client unbinds.
• If the value in the returnECs field is TRUE, the server returns the Entry Change Notification control with each entry returned as the result of changes.

The ldap_create_persistentsearch_control() API can be used to create the persistent search control that can then be passed to the controls section of the ldap_search_ext() or ldap_search_ext_s() API to initiate a persistent search.

If a client sets the returnECs field to TRUE in the persistent search control, then Directory Server includes the entry change notification control in the Controls portion of each SerachResultEntry that is returned due to an entry that is being added, deleted, or modified.

EntryChangeNotification ::= SEQUENCE {
            changeType ENUMERATED {
               add             (1),
               delete          (2),
               modify          (4),
               modDN           (8)
            },
            previousDN   LDAPDN  OPTIONAL,  # modifyDN operations only
            changeNumber INTEGER OPTIONAL  # if supported
}

where,

changeType

This parameter indicates the type of LDAP operation that caused the entry to be returned.

previousDN

The value of this parameter is present only for modifyDN operations. This parameter contains the DN of the entry before it was renamed or moved. The returnECs optional field is included only when you return change notifications as a result of modifyDN operations.

changeNumber

This parameter contains the change number, [CHANGELOG], assigned by the server for a change on an entry.

The ldap_parse_entrychange_control() API goes through a list of controls that are received from a persistent search operation, retrieves the entry change control from it and parses that control for change information.