Common Test: Editorial changes 3

Reference Manual files from Pär Wennstad added

1 files changed, 1037 insertions, 0 deletions

diff --git a/lib/common_test/doc/src/ct_netconfc.xml b/lib/common_test/doc/src/ct_netconfc.xml
new file mode 100644
index 0000000000..8139d8afdb
--- /dev/null
+++ b/lib/common_test/doc/src/ct_netconfc.xml
@@ -0,0 +1,1037 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2010</year><year>2012</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+
+    </legalnotice>
+
+    <title>ct_netconfc</title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev>A</rev>
+    <file>ct_netconfc.xml</file>
+  </header>
+  <module>ct_netconfc</module>
+  <modulesummary>NETCONF client module.</modulesummary>
+
+<description>
+
+    <p>NETCONF client module.</p>
+
+    <p>The NETCONF client is compliant with RFC 4741 NETCONF Configuration
+      Protocol and RFC 4742 Using the NETCONF Configuration Protocol over
+      Secure SHell (SSH)..</p>
+
+    <p>For each server to test against, the following entry can be added to a
+      configuration file:</p>
+
+    <pre>
+ {server_id(),options()}.</pre>
+
+    <p>The <c>server_id()</c> or an associated <c>target_name()</c> (see
+      module <seealso marker="ct"><c>ct</c></seealso>) must then be used
+      in calls to
+      <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>.</p>
+
+    <p>If no configuration exists for a server, a session can still be
+      opened by calling
+      <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso> with
+      all necessary options specified in the call. The first argument to
+      <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso> can
+      then be any atom.</p>
+
+  </description>
+
+  <section>
+  <marker id="Logging"/>
+    <title>Logging</title> 
+    <p>The NETCONF server uses <c>error_logger</c> for logging of NETCONF
+      traffic. A special purpose error handler is implemented in
+      <c>ct_conn_log_h</c>. To use this error handler, add the
+      <c>cth_conn_log</c> hook in the test suite, for example:</p>
+
+    <pre>
+ suite() -&gt;
+    [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].</pre>
+
+    <p><c>conn_mod()</c> is the name of the <c>Common Test</c> module
+      implementing the connection protocol, for example, <c>ct_netconfc</c>.</p>
+
+    <p>Hook option <c>log_type</c> specifies the type of logging:</p>
+
+    <taglist>
+      <tag><c>raw</c></tag>
+      <item><p>The sent and received NETCONF data is logged to a separate
+        text file "as is" without any formatting. A link to the file is
+        added to the test case HTML log.</p>.</item>
+
+      <tag><c>pretty</c></tag>
+      <item><p>The sent and received NETCONF data is logged to a separate
+        text file with XML data nicely indented. A link to the file is
+        added to the test case HTML log.</p></item>
+
+      <tag><c>html (default)</c></tag>
+      <item><p>The sent and received NETCONF traffic is pretty printed
+        directly in the test case HTML log.</p></item>
+
+      <tag><c>silent</c></tag>
+      <item><p>NETCONF traffic is not logged.</p></item>
+    </taglist>
+
+    <p>By default, all NETCONF traffic is logged in one single log file.
+      However, different connections can be logged in separate files.
+      To do this, use hook option <c>hosts</c> and list the names of the
+      servers/connections to be used in the suite. The connections
+      must be named for this to work, that is, they must be opened with
+      <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>.</p>
+
+    <p>Option <c>hosts</c> has no effect if <c>log_type</c> is set to
+      <c>html</c> or <c>silent</c>.</p>
+
+    <p>The hook options can also be specified in a configuration file with
+      configuration variable <c>ct_conn_log</c>:</p>
+
+    <pre>
+ {ct_conn_log,[{conn_mod(),hook_options()}]}.</pre>
+
+    <p>For example:</p>
+
+    <pre>
+ {ct_conn_log,[{ct_netconfc,[{log_type,pretty},
+                             {hosts,[key_or_name()]}]}]}</pre>
+
+    <note>
+      <p>Hook options specified in a configuration file overwrite the
+        hard-coded hook options in the test suite.</p>
+    </note>
+
+    <p><em>Logging Example 1:</em></p>
+    <marker id="Logging_example_1"/>
+
+    <p>The following <c>ct_hooks</c> statement causes pretty printing of
+      NETCONF traffic to separate logs for the connections named
+      <c>nc_server1</c> and <c>nc_server2</c>. Any other connections are
+      logged to default NETCONF log.</p>
+
+    <pre>
+ suite() -&gt;
+    [{ct_hooks, [{cth_conn_log, [{ct_netconfc,[{log_type,pretty}},
+                                               {hosts,[nc_server1,nc_server2]}]}
+                                ]}]}].</pre>
+
+    <p>Connections must be opened as follows:</p>
+
+    <pre>
+ open(nc_server1,[...]),
+ open(nc_server2,[...]).</pre>
+
+    <p><em>Logging Example 2:</em></p>
+    <marker id="Logging_example_2"/>
+
+    <p>The following configuration file causes raw logging of all NETCONF 
+      traffic in to one single text file:</p>
+
+    <pre>
+ {ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.</pre>
+
+    <p>The <c>ct_hooks</c> statement must look as follows:</p>
+
+    <pre>
+ suite() -&gt;
+    [{ct_hooks, [{cth_conn_log, []}]}].</pre>
+
+    <p>The same <c>ct_hooks</c> statement without the configuration file
+      would cause HTML logging of all NETCONF connections in to the test
+      case HTML log.</p>
+  </section>
+
+  <section>
+  <marker id="Notifications"/>
+    <title>Notifications</title>
+
+    <p>The NETCONF client is also compliant with RFC 5277 NETCONF Event
+      Notifications, which defines a mechanism for an asynchronous message 
+      notification delivery service for the NETCONF protocol.</p>
+
+    <p>Specific functions to support this are
+      <seealso marker="#create_subscription-6"><c>ct_netconfc:create_subscription/6</c></seealso>
+      and
+      <seealso marker="#get_event_streams-3"><c>ct_netconfc:get_event_streams/3</c></seealso>.
+      (The functions also exist with other arities.)</p>
+  </section>
+
+  <section>
+    <title>Data Types</title>
+    <marker id="types"/>
+    <taglist>
+      <tag><c>client() = handle() | key_or_name()</c></tag>
+      <item><marker id="type-client"/>
+        <p>For <c>handle()</c>, see module
+          <seealso marker="ct"><c>ct</c></seealso>.</p></item>
+
+      <tag><c>error_reason() = term()</c></tag>
+      <item><marker id="type-error_reason"/> </item>
+      <tag><c>event_time() = {eventTime, xml_attributes(), [xs_datetime()]}</c></tag>
+      <item><marker id="type-event_time"/> </item>
+
+      <tag><c>handle() = term()</c></tag>
+      <item><marker id="type-handle"/>
+        <p>Opaque reference for a connection (NETCONF session). For more
+          information, see module <seealso marker="ct"><c>ct</c></seealso>.</p>
+      </item>
+
+      <tag><c>host() = hostname() | ip_address()</c></tag>
+      <item><marker id="type-host"/>
+        <p>For <c>hostname()</c> and <c>ip_address()</c>, see module
+          <seealso marker="kernel:inet"><c>kernel:inet</c></seealso></p></item>
+
+      <tag><c>key_or_name() = server_id() | target_name()</c></tag>
+      <item><marker id="type-key_or_name"/>
+        <p>For <c>target_name</c>, see module
+          <seealso marker="ct"><c>ct</c></seealso>.</p></item>
+
+      <tag><c>netconf_db() = running | startup | candidate</c></tag>
+      <item><marker id="type-netconf_db"/> </item>
+
+      <tag><c>notification() = {notification, xml_attributes(), notification_content()}</c></tag>
+      <item><marker id="type-notification"/> </item>
+
+      <tag><c>notification_content() = [event_time() | simple_xml()]</c></tag> 
+      <item><marker id="type-notification_content"/> </item>
+
+      <tag><c>option() = {ssh, host()} | {port, port_number()} | {user, string()} | {password, string()} | {user_dir, string()} | {timeout, timeout()}</c></tag>
+      <item><marker id="type-option"/>
+        <p>For <c>port_number()</c>, see module
+          <seealso marker="kernel:inet"><c>kernel:inet</c></seealso></p></item>
+
+      <tag><c>options() = [option()]</c></tag>
+      <item><marker id="type-options"/>
+        <p>Options used for setting up an SSH connection to a NETCONF
+          server.</p></item>
+
+      <tag><c>server_id() = atom()</c></tag>
+      <item><marker id="type-server_id"/>
+        <p>The identity of a server, specified in a configuration
+          file.</p></item>
+
+      <tag><c>simple_xml() = {xml_tag(), xml_attributes(), xml_content()} | {xml_tag(), xml_content()} | xml_tag()</c></tag>
+      <item><marker id="type-simple_xml"/>
+        <p>This type is further described in application
+          <seealso marker="xmerl"><c>xmerl</c></seealso>.</p></item>
+
+      <tag><c>stream_data() = {description, string()} | {replaySupport, string()} | {replayLogCreationTime, string()} | {replayLogAgedTime, string()}</c></tag>
+      <item><marker id="type-stream_data"/>
+        <p>For details about the data format for the string values, see
+          "XML Schema for Event Notifications" in RFC 5277.</p></item>
+
+      <tag><c>stream_name() = string()</c></tag>
+      <item><marker id="type-stream_name"/> </item>
+
+      <tag><c>streams() = [{stream_name(), [stream_data()]}]</c></tag>
+      <item><marker id="type-streams"/> </item>
+
+      <tag><c>xml_attribute_tag() = atom()</c></tag>
+      <item><marker id="type-xml_attribute_tag"/> </item>
+
+      <tag><c>xml_attribute_value() = string()</c></tag>
+      <item><marker id="type-xml_attribute_value"/> </item>
+
+      <tag><c>xml_attributes() = [{xml_attribute_tag(), xml_attribute_value()}]</c></tag>
+      <item><marker id="type-xml_attributes"/> </item>
+
+      <tag><c>xml_content() = [simple_xml() | iolist()]</c></tag>
+      <item><marker id="type-xml_content"/> </item>
+
+      <tag><c>xml_tag() = atom()</c></tag>
+      <item><marker id="type-xml_tag"/> </item>
+
+      <tag><c>xpath() = {xpath, string()}</c></tag>
+      <item><marker id="type-xpath"/> </item>
+
+      <tag><c>xs_datetime() = string()</c></tag>
+      <item><marker id="type-xs_datetime"/>
+        <p>This date and time identifier has the same format as the XML type
+          <c>dateTime</c> and is compliant with RFC 3339 Date and Time on
+          the Internet Timestamps. The format is as follows:</p>
+      <pre>
+ [-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]</pre>
+      </item>
+    </taglist>
+  </section>
+
+  <funcs>
+    <func>
+      <name>action(Client, Action) -&gt; Result</name>
+      <fsummary>Equivalent to action(Client, Action, infinity).</fsummary>
+      <desc><marker id="action-2"/>
+        <p>Equivalent to
+          <seealso marker="#action-3"><c>ct_netconfc:action(Client, Action,
+          infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>action(Client, Action, Timeout) -&gt; Result</name>
+      <fsummary>Executes an action.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Action = simple_xml()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = ok | {ok, [simple_xml()]} | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="action-3"/>
+        <p>Executes an action. If the return type is void, <c>ok</c> is
+          returned instead of <c>{ok,[simple_xml()]}</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>close_session(Client) -&gt; Result</name>
+      <fsummary>Equivalent to close_session(Client, infinity).</fsummary>
+      <desc><marker id="close_session-1"/>
+        <p>Equivalent to
+          <seealso marker="#close_session-2"><c>ct_netconfc:close_session(Client,
+            infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>close_session(Client, Timeout) -&gt; Result</name>
+      <fsummary>Requests graceful termination of the session associated with
+        the client.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = ok | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="close_session-2"/>
+        <p>Requests graceful termination of the session associated with the
+          client.</p>
+
+        <p>When a NETCONF server receives a <c>close-session</c> request, it
+          gracefully closes the session.  The server releases any locks and
+          resources associated with the session and gracefully closes any
+          associated connections. Any NETCONF requests received after a
+          <c>close-session</c> request are ignored.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>copy_config(Client, Source, Target) -&gt; Result</name>
+      <fsummary>Equivalent to copy_config(Client, Source, Target,
+        infinity).</fsummary>
+      <desc><marker id="copy_config-3"/>
+        <p>Equivalent to
+          <seealso marker="#copy_config-4"><c>ct_netconfc:copy_config(Client,
+            Source, Target, infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>copy_config(Client, Target, Source, Timeout) -&gt; Result</name>
+      <fsummary>Copies configuration data.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Target = netconf_db()</v>
+        <v>Source = netconf_db()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = ok | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="copy_config-4"/>
+        <p>Copies configuration data.</p>
+
+        <p>Which source and target options that can be issued depends on the
+          capabilities supported by the server. That is, <c>:candidate</c>
+          and/or <c>:startup</c> are required.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>create_subscription(Client) -&gt; term()</name>
+      <fsummary>Creates a subscription for event notifications.</fsummary>
+      <desc><marker id="create_subscription-1"/></desc>
+    </func>
+
+    <func>
+      <name>create_subscription(Client, Timeout) -&gt; term()</name>
+      <fsummary>Creates a subscription for event notifications.</fsummary>
+      <desc><marker id="create_subscription-2"/></desc>
+    </func>
+
+    <func>
+      <name>create_subscription(Client, Stream, Timeout) -&gt; term()</name>
+      <fsummary>Creates a subscription for event notifications.</fsummary>
+      <desc><marker id="create_subscription-3"/></desc>
+    </func>
+
+    <func>
+      <name>create_subscription(Client, StartTime, StopTime, Timeout) -&gt; term()</name>
+      <fsummary>Creates a subscription for event notifications.</fsummary>
+      <desc><marker id="create_subscription-4"/></desc>
+    </func>
+
+    <func>
+      <name>create_subscription(Client, Stream, StartTime, StopTime, Timeout) -&gt; term()</name>
+      <fsummary>Creates a subscription for event notifications.</fsummary>
+      <desc><marker id="create_subscription-5"/></desc>
+    </func>
+
+    <func>
+      <name>create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout) -&gt; Result</name>
+      <fsummary>Creates a subscription for event notifications.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Stream = stream_name()</v>
+        <v>Filter = simple_xml() | [simple_xml()]</v>
+        <v>StartTime = xs_datetime()</v>
+        <v>StopTime = xs_datetime()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = ok | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="create_subscription-6"/>
+        <p>Creates a subscription for event notifications.</p>
+
+        <p>This function sets up a subscription for NETCONF event
+          notifications of the specified stream type, matching the specified
+          filter. The calling process receives notifications as messages of
+          type <c>notification()</c>.</p>
+
+        <taglist>
+          <tag><c>Stream</c></tag>
+          <item><p>Optional parameter that indicates which stream of event
+            is of interest. If not present, events in the default NETCONF
+            stream are sent.</p></item>
+          <tag><c>Filter</c></tag>
+          <item><p>Optional parameter that indicates which subset of all
+            possible events is of interest. The parameter format is the
+            same as that of the filter parameter in the NETCONF protocol
+            operations. If not present, all events not precluded by other
+            parameters are sent.</p></item>
+          <tag><c>StartTime</c></tag>
+          <item><p>Optional parameter used to trigger the replay feature and
+              indicate that the replay is to start at the time specified.
+              If <c>StartTime</c> is not present, this is not a replay
+              subscription.</p>
+            <p>It is not valid to specify start times that are later than
+              the current time. If <c>StartTime</c> is specified earlier
+              than the log can support, the replay begins with the earliest
+              available notification.</p>
+            <p>This parameter is of type <c>dateTime</c> and compliant to
+              RFC 3339. Implementations must support time zones.</p></item>
+          <tag><c>StopTime</c></tag>
+          <item><p>Optional parameter used with the optional replay feature
+              to indicate the newest notifications of interest. If
+              <c>StopTime</c> is not present, the notifications continues
+              until the subscription is terminated.</p>
+            <p>Must be used with and be later than <c>StartTime</c>. Values
+              of <c>StopTime</c> in the future are valid. This parameter is
+              of type <c>dateTime</c> and compliant to RFC 3339.
+              Implementations must support time zones.</p></item>
+        </taglist>
+
+        <p>For more details about the event notification mechanism, see
+          RFC 5277.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>delete_config(Client, Target) -&gt; Result</name>
+      <fsummary>Equivalent to delete_config(Client, Target,
+        infinity).</fsummary>
+      <desc><marker id="delete_config-2"/>
+        <p>Equivalent to
+          <seealso marker="#delete_config-3"><c>ct_netconfc:delete_config(Client, Target, infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>delete_config(Client, Target, Timeout) -&gt; Result</name>
+      <fsummary>Deletes configuration data.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Target = startup | candidate</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = ok | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="delete_config-3"/>
+        <p>Deletes configuration data.</p>
+
+        <p>The running configuration cannot be deleted and <c>:candidate</c>
+          or <c>:startup</c> must be advertised by the server.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>edit_config(Client, Target, Config) -&gt; Result</name>
+        <fsummary>Equivalent to edit_config(Client, Target, Config, [],
+          infinity).</fsummary>
+      <desc><marker id="edit_config-3"/>
+        <p>Equivalent to
+          <seealso marker="#edit_config-5"><c>ct_netconfc:edit_config(Client,
+          Target, Config, [], infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>edit_config(Client, Target, Config, OptParamsOrTimeout) -&gt; Result</name>
+      <fsummary>If OptParamsOrTimeout is a time-out value, this function is
+        equivalent to ct_netconfc:edit_config(Client, Target, Config, [],
+        Timeout).</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Target = netconf_db()</v>
+        <v>Config = simple_xml()</v>
+        <v>OptParamsOrTimeout = [simple_xml()] | timeout()</v>
+        <v>Result = ok | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="edit_config-4"/>
+        <p>If <c>OptParamsOrTimeout</c> is a time-out value, this function is
+          equivalent to
+          <seealso marker="#edit_config-5"><c>ct_netconfc:edit_config(Client,
+          Target, Config, [], Timeout)</c></seealso>.</p>
+
+        <p>If <c>OptParamsOrTimeout</c> is a list of simple XML, this
+          function is equivalent to
+          <seealso marker="#edit_config-5"><c>ct_netconfc:edit_config(Client,
+          Target, Config, OptParams, infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>edit_config(Client, Target, Config, OptParams, Timeout) -&gt; Result</name>
+      <fsummary>Edits configuration data.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Target = netconf_db()</v>
+        <v>Config = simple_xml()</v>
+        <v>OptParams = [simple_xml()]</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = ok | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="edit_config-5"/>
+        <p>Edits configuration data.</p>
+
+        <p>By default only the running target is available, unless the server
+          includes <c>:candidate</c> or <c>:startup</c> in its list of
+          capabilities.</p>
+
+        <p><c>OptParams</c> can be used for specifying optional parameters
+          (<c>default-operation</c>, <c>test-option</c>, or
+          <c>error-option</c>) to be added to the <c>edit-config</c>
+          request. The value must be a list containing valid simple XML,
+          for example:</p>
+
+        <pre>
+ [{'default-operation', ["none"]},
+  {'error-option', ["rollback-on-error"]}]</pre>
+      </desc>
+    </func>
+
+    <func>
+      <name>get(Client, Filter) -&gt; Result</name>
+      <fsummary>Equivalent to get(Client, Filter, infinity).</fsummary>
+      <desc><marker id="get-2"/>
+        <p>Equivalent to
+          <seealso marker="#get-3"><c>ct_netconfc:get(Client, Filter,
+            infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get(Client, Filter, Timeout) -&gt; Result</name>
+      <fsummary>Gets data.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Filter = simple_xml() | xpath()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = {ok, [simple_xml()]} | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="get-3"/>
+        <p>Gets data.</p>
+ 
+        <p>This operation returns both configuration and state data from the
+          server.</p>
+
+        <p>Filter type <c>xpath</c> can be used only if the server supports
+          <c>:xpath</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_capabilities(Client) -&gt; Result</name>
+      <fsummary>Equivalent to get_capabilities(Client, infinity).</fsummary>
+      <desc><marker id="get_capabilities-1"/>
+        <p>Equivalent to
+          <seealso marker="#get_capabilities-2"><c>ct_netconfc:get_capabilities(Client,
+          infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_capabilities(Client, Timeout) -&gt; Result</name>
+      <fsummary>Returns the server side capabilities.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = [string()] | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="get_capabilities-2"/>
+        <p>Returns the server side capabilities.</p>
+
+        <p>The following capability identifiers, defined in RFC 4741 NETCONF
+          Configuration Protocol, can be returned:</p>
+
+        <list>
+          <item><p><c>"urn:ietf:params:netconf:base:1.0"</c></p></item>
+          <item><p><c>"urn:ietf:params:netconf:capability:writable-running:1.0"</c></p></item>
+          <item><p><c>"urn:ietf:params:netconf:capability:candidate:1.0"</c></p></item>
+          <item><p><c>"urn:ietf:params:netconf:capability:confirmed-commit:1.0"</c></p></item>
+          <item><p><c>"urn:ietf:params:netconf:capability:rollback-on-error:1.0"</c></p></item>
+          <item><p><c>"urn:ietf:params:netconf:capability:startup:1.0"</c></p></item>
+          <item><p><c>"urn:ietf:params:netconf:capability:url:1.0"</c></p></item>
+          <item><p><c>"urn:ietf:params:netconf:capability:xpath:1.0"</c></p></item>
+        </list>
+ 
+        <p>More identifiers can exist, for example, server-side namespace.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_config(Client, Source, Filter) -&gt; Result</name>
+      <fsummary>Equivalent to get_config(Client, Source, Filter,
+        infinity).</fsummary>
+      <desc><marker id="get_config-3"/>
+        <p>Equivalent to
+          <seealso marker="#get_config-4"><c>ct_netconfc:get_config(Client, Source, Filter, infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_config(Client, Source, Filter, Timeout) -&gt; Result</name>
+      <fsummary>Gets configuration data.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Source = netconf_db()</v>
+        <v>Filter = simple_xml() | xpath()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = {ok, [simple_xml()]} | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="get_config-4"/>
+        <p>Gets configuration data.</p>
+
+        <p>To be able to access another source than <c>running</c>, the
+          server must advertise <c>:candidate</c> and/or <c>:startup</c>.</p>
+
+        <p>Filter type <c>xpath</c> can be used only if the server supports
+          <c>:xpath</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_event_streams(Client, Timeout) -&gt; Result</name>
+      <fsummary>Equivalent to get_event_streams(Client, [], Timeout).</fsummary>
+      <desc><marker id="get_event_streams-2"/>
+        <p>Equivalent to
+          <seealso marker="#get_event_streams-3"><c>ct_netconfc:get_event_streams(Client,
+          [], Timeout)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_event_streams(Client, Streams, Timeout) -&gt; Result</name>
+      <fsummary>Sends a request to get the specified event streams.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Streams = [stream_name()]</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = {ok, streams()} | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="get_event_streams-3"/>
+        <p>Sends a request to get the specified event streams.</p>
+
+        <p><c>Streams</c> is a list of stream names. The following filter is
+          sent to the NETCONF server in a <c>get</c> request:</p>
+
+        <pre>
+ &lt;netconf xmlns="urn:ietf:params:xml:ns:netmod:notification"&gt;
+   &lt;streams&gt;
+     &lt;stream&gt;
+       &lt;name&gt;StreamName1&lt;/name&gt;
+     &lt;/stream&gt;
+     &lt;stream&gt;
+       &lt;name&gt;StreamName2&lt;/name&gt;
+     &lt;/stream&gt;
+     ...
+   &lt;/streams&gt;
+ &lt;/netconf&gt;</pre>
+
+        <p>If <c>Streams</c> is an empty list, <em>all</em> streams are
+          requested by sending the following filter:</p>
+
+        <pre>
+ &lt;netconf xmlns="urn:ietf:params:xml:ns:netmod:notification"&gt;
+   &lt;streams/&gt;
+ &lt;/netconf&gt;</pre>
+
+        <p>If more complex filtering is needed, use
+          <seealso marker="#get-2"><c>ct_netconfc:get/2</c></seealso> or
+          <seealso marker="#get-3"><c>ct_netconfc:get/3</c></seealso> and
+          specify the exact filter according to "XML Schema for Event
+          Notifications" in RFC 5277.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_session_id(Client) -&gt; Result</name>
+      <fsummary>Equivalent to get_session_id(Client, infinity).</fsummary>
+      <desc><marker id="get_session_id-1"/>
+        <p>Equivalent to
+          <seealso marker="#get_session_id-2"><c>ct_netconfc:get_session_id(Client,
+          infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_session_id(Client, Timeout) -&gt; Result</name>
+      <fsummary>Returns the session Id associated with the specified
+        client.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = pos_integer() | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="get_session_id-2"/>
+        <p>Returns the session Id associated with the specified client.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>hello(Client) -&gt; Result</name>
+      <fsummary>Equivalent to hello(Client, [], infinity).</fsummary>
+      <desc><marker id="hello-1"/>
+        <p>Equivalent to
+          <seealso marker="#hello-3"><c>ct_netconfc:hello(Client, [],
+          infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>hello(Client, Timeout) -&gt; Result</name>
+      <fsummary>Equivalent to hello(Client, [], Timeout).</fsummary>
+      <desc><marker id="hello-2"/>
+        <p>Equivalent to
+          <seealso marker="#hello-3"><c>ct_netconfc:hello(Client, [],
+          Timeout)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>hello(Client, Options, Timeout) -&gt; Result</name>
+      <fsummary>Exchanges hello messages with the server.</fsummary>
+      <type>
+        <v>Client = handle()</v>
+        <v>Options = [{capability, [string()]}]</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = ok | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="hello-3"/>
+        <p>Exchanges <c>hello</c> messages with the server.</p>
+
+        <p>Adds optional capabilities and sends a <c>hello</c> message to the
+          server and waits for the return.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>kill_session(Client, SessionId) -&gt; Result</name>
+      <fsummary>Equivalent to kill_session(Client, SessionId,
+        infinity).</fsummary>
+      <desc><marker id="kill_session-2"/>
+        <p>Equivalent to
+          <seealso marker="#kill_session-3"><c>ct_netconfc:kill_session(Client,
+SessionId, infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>kill_session(Client, SessionId, Timeout) -&gt; Result</name>
+      <fsummary>Forces termination of the session associated with the supplied
+        session Id.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>SessionId = pos_integer()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = ok | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="kill_session-3"/>
+        <p>Forces termination of the session associated with the supplied
+          session Id.</p>
+
+        <p>The server side must abort any ongoing operations, release any
+          locks and resources associated with the session, and close any
+          associated connections.</p>
+
+        <p>Only if the server is in the confirmed commit phase, the
+          configuration is restored to its state before entering the confirmed
+          commit phase. Otherwise, no configuration rollback is performed.</p>
+
+         <p>If the specified <c>SessionId</c> is equal to the current session
+           Id, an error is returned.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>lock(Client, Target) -&gt; Result</name>
+      <fsummary>Equivalent to lock(Client, Target, infinity).</fsummary>
+      <desc><marker id="lock-2"/>
+        <p>Equivalent to
+          <seealso marker="#lock-3"><c>ct_netconfc:lock(Client, Target,
+            infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>lock(Client, Target, Timeout) -&gt; Result</name>
+      <fsummary>Unlocks the configuration target.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Target = netconf_db()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = ok | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="lock-3"/>
+        <p>Unlocks the configuration target.</p>
+
+        <p>Which target parameters that can be used depends on if
+          <c>:candidate</c> and/or <c>:startup</c> are supported by the
+          server. If successfull, the configuration system of the device is
+          unavailable to other clients (NETCONF, CORBA, SNMP, and so on).
+          Locks are intended to be short-lived.</p>
+
+         <p>Operation
+           <seealso marker="#kill_session-2"><c>ct_netconfc:kill_session/2</c></seealso>
+           or
+           <seealso marker="#kill_session-3"><c>ct_netconfc:kill_session/3</c></seealso>
+           can be used to force the release of a lock owned by another NETCONF
+           session. How this is achieved by the server side is
+           implementation-specific.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>only_open(Options) -&gt; Result</name>
+      <fsummary>Opens a NETCONF session, but does not send hello.</fsummary>
+      <type>
+        <v>Options = options()</v>
+        <v>Result = {ok, handle()} | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="only_open-1"/>
+        <p>Opens a NETCONF session, but does not send <c>hello</c>.</p>
+
+        <p>As <seealso marker="#open-1"><c>ct_netconfc:open/1</c></seealso>,
+          but does not send a <c>hello</c> message.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>only_open(KeyOrName, ExtraOptions) -&gt; Result</name>
+      <fsummary>Opens a name NETCONF session, but does not send
+        hello.</fsummary>
+      <type>
+        <v>KeyOrName = key_or_name()</v>
+        <v>ExtraOptions = options()</v>
+        <v>Result = {ok, handle()} | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="only_open-2"/>
+        <p>Opens a name NETCONF session, but does not send <c>hello</c>.</p>
+
+        <p>As <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>,
+          but does not send a <c>hello</c> message.</p>
+      </desc>
+    </func>
+
+    <func>
+    <name>open(Options) -&gt; Result</name>
+    <fsummary>Opens a NETCONF session and exchanges hello messages.</fsummary>
+      <type>
+        <v>Options = options()</v>
+        <v>Result = {ok, handle()} | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="open-1"/>
+        <p>Opens a NETCONF session and exchanges <c>hello</c> messages.</p>
+
+        <p>If the server options are specified in a configuration file,
+          or if a named client is needed for logging purposes (see section
+          <seealso marker="#Logging">Logging</seealso> in this module), use
+          <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>
+          instead.</p>
+
+        <p>The opaque <c>handler()</c> reference returned from this
+          function is required as client identifier when calling any other
+          function in this module.</p>
+
+        <p>Option <c>timeout</c> (milliseconds) is used when setting up the
+          SSH connection and when waiting for the <c>hello</c> message from
+          the server. It is not used for any other purposes during the
+          lifetime of the connection.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>open(KeyOrName, ExtraOptions) -&gt; Result</name>
+      <fsummary>Opens a named NETCONF session and exchanges hello
+        messages.</fsummary>
+      <type>
+        <v>KeyOrName = key_or_name()</v>
+        <v>ExtraOptions = options()</v>
+        <v>Result = {ok, handle()} | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="open-2"/>
+        <p>Opens a named NETCONF session and exchanges <c>hello</c>
+          messages.</p>
+
+         <p>If <c>KeyOrName</c> is a configured <c>server_id()</c> or a
+           <c>target_name()</c> associated with such an Id, then the options
+           for this server are fetched from the configuration file.</p>
+
+         <p>Argument <c>ExtraOptions</c> is added to the options found in the
+           configuration file. If the same options are specified, the values
+           from the configuration file overwrite <c>ExtraOptions</c>.</p>
+
+         <p>If the server is not specified in a configuration file, use
+           <seealso marker="#open-1"><c>ct_netconfc:open/1</c></seealso>
+           instead.</p>
+
+         <p>The opaque <c>handle()</c> reference returned from this
+           function can be used as client identifier when calling any other
+           function in this module. However, if <c>KeyOrName</c> is a
+           <c>target_name()</c>, that is, if the server is named through a
+           call to <seealso marker="ct#require-2"><c>ct:require/2</c></seealso>
+           or a <c>require</c> statement in the test suite, then this name can
+           be used instead of <c>handle()</c>.</p>
+
+        <p>Option <c>timeout</c> (milliseconds) is used when setting up the
+          SSH connection and when waiting for the <c>hello</c> message from
+          the server. It is not used for any other purposes during the
+          lifetime of the connection.</p>
+
+         <p>See also
+           <seealso marker="ct#require-2"><c>ct:require/2</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>send(Client, SimpleXml) -&gt; Result</name>
+      <fsummary>Equivalent to send(Client, SimpleXml, infinity).</fsummary>
+      <desc><marker id="send-2"/>
+        <p>Equivalent to
+          <seealso marker="#send-3"><c>ct_netconfc:send(Client, SimpleXml,
+            infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>send(Client, SimpleXml, Timeout) -&gt; Result</name>
+      <fsummary>Sends an XML document to the server.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>SimpleXml = simple_xml()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = simple_xml() | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="send-3"/>
+        <p>Sends an XML document to the server.</p>
+
+        <p>The specified XML document is sent "as is" to the server. This
+          function can be used for sending XML documents that cannot be
+          expressed by other interface functions in this module.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>send_rpc(Client, SimpleXml) -&gt; Result</name>
+      <fsummary>Equivalent to send_rpc(Client, SimpleXml, infinity).</fsummary>
+      <desc><marker id="send_rpc-2"/>
+        <p>Equivalent to
+          <seealso marker="#send_rpc-3"><c>ct_netconfc:send_rpc(Client,
+          SimpleXml, infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>send_rpc(Client, SimpleXml, Timeout) -&gt; Result</name>
+      <fsummary>Sends a NETCONF rpc request to the server.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>SimpleXml = simple_xml()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = [simple_xml()] | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="send_rpc-3"/>
+        <p>Sends a NETCONF <c>rpc</c> request to the server.</p>
+
+        <p>The specified XML document is wrapped in a valid NETCONF <c>rpc</c>
+          request and sent to the server. The <c>message-id</c> and namespace
+          attributes are added to element <c>rpc</c>.</p>
+
+        <p>This function can be used for sending <c>rpc</c> requests that
+          cannot be expressed by other interface functions in this module.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>unlock(Client, Target) -&gt; Result</name>
+      <fsummary>Equivalent to unlock(Client, Target, infinity).</fsummary>
+      <desc><marker id="unlock-2"/>
+        <p>Equivalent to
+          <seealso marker="#unlock-3"><c>ct_netconfc:unlock(Client, Target,
+            infinity)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>unlock(Client, Target, Timeout) -&gt; Result</name>
+      <fsummary>Unlocks the configuration target.</fsummary>
+      <type>
+        <v>Client = client()</v>
+        <v>Target = netconf_db()</v>
+        <v>Timeout = timeout()</v>
+        <v>Result = ok | {error, error_reason()}</v>
+      </type>
+      <desc><marker id="unlock-3"/>
+        <p>Unlocks the configuration target.</p>
+
+        <p>If the client earlier has acquired a lock through
+          <seealso marker="#lock-2"><c>ct_netconfc:lock/2</c></seealso> or
+          <seealso marker="#lock-3"><c>ct_netconfc:lock/3</c></seealso>, this
+          operation releases the associated lock. To access another target
+          than <c>running</c>, the server must support <c>:candidate</c>
+          and/or <c>:startup</c>.</p>
+      </desc>
+    </func>
+  </funcs>
+
+</erlref>
+
+