repo_zf1/documentation/manual/pt-br/module_specs/Zend_XmlRpc_Client.xml

<sect1 id="zend.xmlrpc.client">
  <title>Zend_XmlRpc_Client</title>

  <sect2 id="zend.xmlrpc.client.introduction">
    <title>Introdução</title>

    <para>A forma de utilização do <code>Zend_XmlRpc_Client</code> é muito
    similar a dos objetos <code>SoapClient</code> (<ulink
    url="http://www.php.net/soap">extensão SOAP web service</ulink>). Você
    pode simplesmente chamar os procedimentos de serviço do XML-RPC como
    métodos de <code>Zend_XmlRpc_Client</code> . Especifique o endereço
    completo do serviço para o construtor do
    <code>Zend_XmlRpc_Client</code>.</para>

    <example>
      <title>Uma requisição XML-RPC básica</title>

      <programlisting role="php">&lt;?php
/**
 * Connect to framework.zend.com server and an array describing
 * the methods available.
 */
require_once 'Zend/XmlRpc/Client.php';

$server = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');

print_r( $server-&gt;system-&gt;listMethods() );

?&gt;
            </programlisting>
    </example>

    <note><para>


        <code>Zend_XmlRpc_Client</code>

         tenta, na medida do possível, utilizar métodos remotos como se fossem nativos. Se um método remoto contiver namespaces, como por exemplo

        <code>system.listMethods()</code>

         , a chamada é feita usando encadeamento de objetos em PHP:

        <code>$server-&gt;system-&gt;listMethods()</code>

         .
     </para></note>
  </sect2>

  <sect2 id="zend.xmlrpc.client.parameters">
    <title>Usando parâmetros</title>

    <para>Alguns procedimentos de serviço XML-RPC requerem parâmetros, os
    parâmetros necessários são passados, como parâmetros, para o método
    <code>Zend_XmlRpc_Client</code>. Os parâmetros do procedimento XML-RPC
    devem ser de tipos de dados específicos ao XML-RPC. Os parâmetros podem
    ser passsados de duas maneiras: tipos nativos do PHP e objetos
    <code>Zend_XmlRpc_Value</code> que representam os tipos XML-RPC.</para>

    <sect3 id="zend.xmlrpc.client.parameters.php_native">
      <title>Passando variáveis nativas como parâmetros em PHP</title>

      <para>Um parâmetro passado como variável nativa do PHP, pode ser uma
      string, um inteiro, um flutuante, um boleano, um array ou um objeto.
      Neste caso, cada tipo PHP nativo irá ser automaticamente detectado e
      convertido em um tipo XML-RPC, de acordo com a tabela abaixo:</para>

      <table>
        <title>Conversão de valores nativos do PHP para tipos XML-RPC</title>

        <tgroup cols="2">
          <thead>
            <row>
              <entry>Tipos nativos do PHP</entry>

              <entry>Tipos XML-RPC</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>inteiro</entry>

              <entry>int</entry>
            </row>

            <row>
              <entry>double</entry>

              <entry>double</entry>
            </row>

            <row>
              <entry>boleano</entry>

              <entry>boolean</entry>
            </row>

            <row>
              <entry>string</entry>

              <entry>string</entry>
            </row>

            <row>
              <entry>array</entry>

              <entry>array</entry>
            </row>

            <row>
              <entry>array associativo</entry>

              <entry>struct</entry>
            </row>

            <row>
              <entry>objeto</entry>

              <entry>array</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <programlisting role="php">...
/** 2 parameters are passed in this procedure
 *  The first parameter is a string that will be auto-converted into an XML-RPC string type
 *  The second parameter is an assosiative array that will be converted into an XML-RPC struct
 */

$p1 = 'parameter 1';
$p2 = array('name' =&gt; 'Joe', 'age' =&gt; 30);

$service-&gt;serviceProcedure($p1, $p2);
...
            </programlisting>
    </sect3>

    <sect3 id="zend.xmlrpc.client.parameters.xmlrpc_value">
      <title>Passando objetos <code>Zend_XmlRpc_Value</code> como
      parâmetros</title>

      <para>Parameters passados como objetos <code>Zend_XmlRpc_Value</code>.
      Você pode criar uma das instâncias de <code>Zend_XmlRpc_Value</code>
      para especificar o tipo XML-RPC exato dos seus parâmetros. As razões
      principais para especificar explicitamente os tipos XML-RPC são:
      <itemizedlist>
        <listitem>
            <para>
                 Quando você quer assegurar que o tipo correto do parâmetro seja passado ao procedimento (ex: o procedimento exige um inteiro e você pode receber o parâmetro do array $_GET como string)
            </para>
          </listitem>
          <listitem>
            <para>
                 Quando o procedimento exige um tipo datetime ou um base64 (que não são tipos nativos do PHP).
            </para>
          </listitem>
          <listitem>
            <para>
                 Quando a existe a possibilidade da conversão automática falhar (ex: você quer passar uma estrutura XML-RPC vazia como parâmetro. Estruturas vazias são representadas como arrays vazios em PHP, mas, se você fornecer um array vazio como parãmetro ele irá ser automaticamente convertido para um array XML-RPC, desde que não seja um array associativo)
            </para>
          </listitem>
        </itemizedlist></para>

      <para>Existem duas maneiras de criar um objeto
      <code>Zend_XmlRpc_Value</code> object: a maneira explícita (chamando o
      construtor do objeto) ou usando a função estática
      <code>Zend_XmlRpc_Value::getXmlRpcValue()</code> que irá requerer uma
      constante XML-RPC.</para>

      <table>
        <title><code>Objeto Zend_XmlRpc_Value</code> representando os tipos
        XML-RPC</title>

        <tgroup cols="3">
          <thead>
            <row>
              <entry>Tipo XML-RPC</entry>

              <entry>Constante de comparação
              <code>Zend_XmlRpc_Value</code></entry>

              <entry>Objeto <code>Zend_XmlRpc_Value</code></entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>int</entry>

              <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_INTEGER</code></entry>

              <entry><code>Zend_XmlRpc_Value_Integer</code></entry>
            </row>

            <row>
              <entry>double</entry>

              <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_DOUBLE</code></entry>

              <entry><code>Zend_XmlRpc_Value_Double</code></entry>
            </row>

            <row>
              <entry>boolean</entry>

              <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_BOOLEAN</code></entry>

              <entry><code>Zend_XmlRpc_Value_Boolean</code></entry>
            </row>

            <row>
              <entry>string</entry>

              <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_STRING</code></entry>

              <entry><code>Zend_XmlRpc_Value_String</code></entry>
            </row>

            <row>
              <entry>base64</entry>

              <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64</code></entry>

              <entry><code>Zend_XmlRpc_Value_Base64</code></entry>
            </row>

            <row>
              <entry>dateTime.iso8601</entry>

              <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_DATETIME</code></entry>

              <entry><code>Zend_XmlRpc_Value_DateTime</code></entry>
            </row>

            <row>
              <entry>array</entry>

              <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_ARRAY</code></entry>

              <entry><code>Zend_XmlRpc_Value_Array</code></entry>
            </row>

            <row>
              <entry>struct</entry>

              <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_STRUCT</code></entry>

              <entry><code>Zend_XmlRpc_Value_Struct</code></entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <programlisting role="php">...
/** 2 parameters are passed to this procedure
 *  The first parameter is an XML-RPC base64 type that is created using the static Zend_XmlRpc_Value::getXmlRpcValue() function
 *  The second parameter is an XML-RPC strcture that is created explictly
 */

$p1 = ZXmlRpcValue::getXmlRpcValue('encoded string', Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64);
$p2 = new Zend_XmlRpc_Value_Struct(array('name' =&gt; 'Joe', 'age' =&gt; 30));

$service-&gt;serviceProcedure($p1, $p2);
...
            </programlisting>

       <note><para>
           O valor do parâmetro é cedido por uma variável PHP mas irá ser convertido para o tipo específico usando as técnicas de conversão do PHP (ex: se uma string é informada como um valor para o objeto

          <code>Zend_XmlRpc_Value_Integer</code>

          , ele irá ser convertido usando

          <code>(int)$value</code>

          ).
      </para></note>
    </sect3>

    <sect3 id="zend.xmlrpc.client.parameters.as_xml">
      <title>Analisando uma string XML contida em um parâmetro XML-RPC</title>

      <para>Este método de passagem por parâmetros é usado internamente no
      pacote <code>Zend_XmlRpc</code> e seu uso não é recomendado.</para>

      <para>Se você tiver necessidade de usar este método, você deve usar a
      função estática <code>Zend_XmlRpc_Value::getXmlRpcValue()</code> para
      analisar uma string XML em um objeto <code>Zend_XmlRpc_Value</code> que
      representa o tipo XML-RPC correspondente. A função
      <code>Zend_XmlRpc_Value::getXmlRpcValue()</code> deve receber dois
      parâmetros: a string XML e a constante
      <code>Zend_XmlRpc_Value::XML_STRING</code>.</para>
    </sect3>
  </sect2>

  <sect2 id="zend.xmlrpc.client.wsdl">
    <title>Indicando o tipo dos parâmetros</title>

    <para>A principal diferença entre XML-RPC e web services SOAP é o arquivo
    WSDL. O protocolo SOAP usualmente possui um arquivo WSDL que descreve a
    interface para o web service. De acordo com esta interface, o cliente SOAP
    conhece os tipos de parâmetros que devem ser enviados ao servidor e quais
    são os tipos dos valores de retorno. Sem o arquivo WSDL, o usuário pode
    enfrentar problemas para descobrir quais são os tipos.</para>

    <para>O solução do protocolo XML-RPC usa um procedimento de serviço
    especial chamado <code>system.methodSignature</code>. Este procedimento
    toma o nome do procedimento como um parâmetro e retorna a assinatura de um
    dado procedimento. A assinatura contém os respectivos tipos do parâmetro
    requerido e do valor de retorno do procedimento.</para>

    <note>
      <para>Nem todos os servidores XML-RPC suportam o procedimento especial

      <code>system.methodSignature</code>

      , e consequentemente, não suportam também a indicação de tipo. </para>
    </note>

    <para>O <code>Zend_XmlRpc_Client</code> implementa uma gama de tipos de
    arquivos WSDL para servidores XML-RPC usando o procedimento
    <code>system.methodSignature</code>. Se solicitado,
    <code>Zend_XmlRpc_Client</code> irá requisitar uma lista de todos os
    procedimentos de um servidor XML-RPC, incluindo todas as assinaturas
    destes procedimentos. Todos esses dados serão gravados em um arquivo XML
    (similar ao arquivo SOAP WSDL). Quando o mesmo servidor XML-RPC for
    utilizado novamente, o usuário pode fornecer o arquivo XML e o
    <code>Zend_XmlRpc_Client</code> irá indicar o tipo de todos os parâmetros
    para os procedimentos requisitados, de acordo com suas assinaturas.</para>

    <para>O arquivo XML contendo as assinaturas dos procedimentos é criado
    chamando-se a função<code> Zend_XmlRpc_Client::__getMethodsXml()</code> (a
    função retorna uma string XML contendo todos os dados das assinaturas).
    Para selecionar um arquivo XML de assinaturas, o usuário pode passar os
    dados XML como um parâmetro para o construtor
    <code>Zend_XmlRpc_Client</code> ou chamar a função
    <code>Zend_XmlRpc_Client::__setMethodsXml()</code>.</para>

    <example>
      <title>Chamando um serviço XML-RPC com indicação de tipo</title>

      <programlisting role="php">&lt;?php
/**
 * Connect to an XML-RPC server, and save it's signatures file (the XML-RPC eqvivilant to a SOAP WSDL file)
 */
require_once 'Zend/XmlRpc/Client.php';

$service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc');

file_put_contents('/tmp/xmlrpc-signatures/example.xml', $service-&gt;__getMethodsXml());

/* The $service object contains all the signatures of the XML-RPC server,
    when the serviceProcedure is called, its parameter ($param) is converted
    to the necessary type according to the procedure's signature.
 */
$service-&gt;serviceProcedure($param);
?&gt;
            </programlisting>

      <programlisting role="php">&lt;?php
/**
 * Connect to an XML-RPC server, using an existing signature file, we make sure
 * that the type of the parameters passed to the procedures are of the necessary type
 */
require_once 'Zend/XmlRpc/Client.php';

$signature_file_xml = file_get_contents('/tmp/xmlrpc-signatures/example.xml');
$service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc', 'namespace', $signature_file_xml);

/* The $service object contains all the signatures of the XML-RPC server,
    when the serviceProcedure is called, its parameter ($param) is converted
    to the necessary type according to the procedure's signature.
 */
$service-&gt;serviceProcedure($param);
?&gt;
            </programlisting>
    </example>
  </sect2>

  <sect2 id="zend.xmlrpc.client.response">
    <title>Obtendo a resposta</title>

    <para>O procedimento retorna um valor de um tipo XML-RPC. O método
    <code>Zend_XmlRpc_Client</code> que chama o procedimento XML-RPC retorna
    um tipo nativo do PHP que foi convertido a partir de um tipo XML-RPC
    retornado.</para>

    <para>Você pode usar a função
    <code>Zend_XmlRpc_Client::__getResponse()</code> para recuperar o valor de
    retorno do procedimento requisitado. A função <code>__getResponse()</code>
    recebe um parâmetro que indica o tipo do valor de retorno. As opções de
    resposta são: <itemizedlist>
        <listitem>
            <para>
                <code>Zend_XmlRpc_Client::RESPONSE_PHP_NATIVE</code>
                - Devolve o valor de retorno do procedimento convertido para um tipo nativo do PHP (converte o tipo XML-RPC em um tipo PHP).
            </para>
        </listitem>
        <listitem>
            <para>
                <code>Zend_XmlRpc_Client::RESPONSE_XML_STRING</code>
                - Retorna a string XML representando a resposta XML-RPC.
            </para>
        </listitem>
        <listitem>
            <para>
´               <code>Zend_XmlRpc_Client::RESPONSE_ZXMLRPC_OBJECT</code>
                - Retorna um objeto
                <code>Zend_XmlRpc_Value</code>
                object que representa o tipo XML-RPC retornado.
            </para>
        </listitem>
      </itemizedlist></para>

    <programlisting role="php">...
$service-&gt;serviceProcedure();

$response = $service-&gt;__getResponse();
// $response is the PHP variable converted from the XML-RPC type return value

$response = $service-&gt;__getResponse(ZXmlRpcClient::RESPONSE_XML_STRING);
// $response is a string containing the XML representing the procedure return value

$response = $service-&gt;__getResponse(ZXmlRpcClient::RESPONSE_ZXMLRPC_OBJECT);
// $response is a Zend_XmlRpc_Value instance representing the XML-RPC type return value
...
        </programlisting>
  </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->