<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<refentry xml:id="zookeeper.addauth" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>Zookeeper::addAuth</refname>
  <refpurpose>Specify application credentials</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis role="oop">
   <modifier>public</modifier>
   <type>bool</type><methodname>Zookeeper::addAuth</methodname>
   <methodparam><type>string</type><parameter>scheme</parameter></methodparam>
   <methodparam><type>string</type><parameter>cert</parameter></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>completion_cb</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   The application calls this function to specify its credentials for purposes of authentication. The server will use the security provider specified by the scheme parameter to authenticate the client connection. If the authentication request has failed:
    - the server connection is dropped.
    - the watcher is called with the ZOO_AUTH_FAILED_STATE value as the state parameter.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>scheme</parameter></term>
    <listitem>
     <para>
      The id of authentication scheme. Natively supported: "digest" password-based authentication
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>cert</parameter></term>
    <listitem>
     <para>
      Application credentials. The actual value depends on the scheme.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>completion_cb</parameter></term>
    <listitem>
     <para>
      The routine to invoke when the request completes. One of the following result codes may be passed into the completion callback:
      - ZOK operation completed successfully
      - ZAUTHFAILED authentication failed
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   This method emits PHP error/warning when parameters count or types are wrong or operation fails.
  </para>
  <caution>
    <para>
      Since version 0.3.0, this method emits <classname>ZookeeperException</classname> and it's derivatives.
    </para>
  </caution>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example xml:id="zookeeper.addauth.example.basic">
   <title><methodname>Zookeeper::addAuth</methodname> example</title>
   <para>
     Add auth before requesting node value.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$value = 'nodevalue';
$zookeeper->set($path, $value);

$zookeeper->addAuth('digest', 'user0:passwd0');
$r = $zookeeper->get($path);
if ($r)
  echo $r;
else
  echo 'ERR';
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
nodevalue
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><methodname>Zookeeper::create</methodname></member>
   <member><methodname>Zookeeper::setAcl</methodname></member>
   <member><methodname>Zookeeper::getAcl</methodname></member>
   <member><link linkend="zookeeper.class.constants.states">ZooKeeper States</link></member>
   <member><classname>ZookeeperException</classname></member>
  </simplelist>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
