path: root/lib/common_test/doc/src/ct_netconfc.xml

<?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>