description-psearch-info.xml revision 73adb2e3dbaa8a9f6448cefccb7933f68c3c7348
<?xml version="1.0" encoding="UTF-8"?>
<!--
! CDDL HEADER START
!
! The contents of this file are subject to the terms of the
! Common Development and Distribution License, Version 1.0 only
! (the "License"). You may not use this file except in compliance
! with the License.
!
! You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
! See the License for the specific language governing permissions
! and limitations under the License.
!
! When distributing Covered Code, include this CDDL HEADER in each
! file and include the License file at legal-notices/CDDLv1_0.txt.
! If applicable, add the following below this CDDL HEADER, with the
! fields enclosed by brackets "[]" replaced with your own identifying
! information:
! Portions Copyright [yyyy] [name of copyright owner]
!
! CDDL HEADER END
!
! Copyright 2015 ForgeRock AS.
!
-->
<!--
This use of <informalexample> is mild tag abuse.
It serves as a single container element for all the elements here.
-->
<informalexample
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://docbook.org/ns/docbook
<para>
A persistent search allows the client to continue receiving new results
whenever changes are made to data that is in the scope of the search,
thus using the search as a form of change notification.
</para>
<variablelist>
<para>
The optional <literal>changetype</literal> setting defines
the kinds of updates that result in notification.
If you do not set the <literal>changetype</literal>,
the default behavior is to send notifications for all updates.
</para>
<varlistentry>
<term><literal>add</literal></term>
<listitem>
<para>
Send notifications for LDAP add operations.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>del</literal></term>
<term><literal>delete</literal></term>
<listitem>
<para>
Send notifications for LDAP delete operations.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>mod</literal></term>
<term><literal>modify</literal></term>
<listitem>
<para>
Send notifications for LDAP modify operations.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>moddn</literal></term>
<term><literal>modrdn</literal></term>
<term><literal>modifydn</literal></term>
<listitem>
<para>
Send notifications for LDAP modify DN (rename and move) operations.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>all</literal></term>
<term><literal>any</literal></term>
<listitem>
<para>
Send notifications for all LDAP update operations.
</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<para>
The optional <literal>changesonly</literal> setting defines
whether the server returns existing entries as well as changes.
</para>
<varlistentry>
<term><literal>true</literal></term>
<listitem>
<para>
Do not return existing entries,
but instead only notifications about changes.
</para>
<para>
This is the default setting.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>false</literal></term>
<listitem>
<para>
Also return existing entries.
</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<para>
The optional <literal>entrychgcontrols</literal> setting defines
whether the server returns an Entry Change Notification control
with each entry notification.
The Entry Change Notification control provides additional information
about the change that caused the entry to be returned by the search.
In particular, it indicates the change type,
the change number if available,
and the previous DN if the change type was a modify DN operation.
</para>
<varlistentry>
<term><literal>true</literal></term>
<listitem>
<para>
Do request the Entry Change Notification control.
</para>
<para>
This is the default setting.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>false</literal></term>
<listitem>
<para>
Do not request the Entry Change Notification control.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>