dns-get-record.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 525aa5f198d482c0d03be54ddee5af13b376ab99 Maintainer: lacatoire Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.dns-get-record" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>dns_get_record</refname>
  <refpurpose>Lit les données DNS associées à un hôte</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>dns_get_record</methodname>
   <methodparam><type>string</type><parameter>hostname</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>type</parameter><initializer><constant>DNS_ANY</constant></initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">authoritative_name_servers</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">additional_records</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>raw</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Lit les données DNS associées à l'hôte
   <parameter>hostname</parameter>.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>hostname</parameter></term>
     <listitem>
      <para>
       <parameter>hostname</parameter> doit être un nom d'hôte DNS valide, comme
       <literal>www.example.com</literal>. Des résolutions inversées peuvent
       être faites avec la notation <literal>in-addr.arpa</literal>, mais la fonction 
       <function>gethostbyaddr</function> est plus efficace pour faire des
       résolutions inverses.
      </para>
      <note>
       <para>
        En termes de standards DNS, les adresses email sont données au format
        <literal>utilisateur.hote</literal> (par exemple : 
        <literal>webmestre.example.com</literal> au contraire du 
        format <literal>webmestre@example.com</literal>). Il faut vérifier
        cette adresse et la modifier si nécessaire avant
        de la passer à la fonction <function>mail</function>.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>type</parameter></term>
     <listitem>
      <para>
       Par défaut, <function>dns_get_record</function> va rechercher toutes les
       ressources associées à <parameter>hostname</parameter>.
       Pour limiter la requête, utiliser l'une des constantes
       <constant>DNS_<replaceable>*</replaceable></constant>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>authoritative_name_servers</parameter></term>
     <listitem>
      <para>
       Passé par référence, et, s'il est fourni, recevra les
       enregistrements de ressources pour les
       <emphasis>Authoritative Name Servers</emphasis>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_records</parameter></term>
     <listitem>
      <para>
       Passé par référence, et, s'il est fourni, recevra tous les
       <emphasis>enregistrements supplémentaires</emphasis>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>raw</parameter></term>
     <listitem>
      <para>
       Le <parameter>type</parameter> sera interprété comme un ID de type DNS brut
       (les constantes <literal>DNS_<replaceable>*</replaceable></literal> ne peuvent pas être utilisées).
       La valeur de retour contiendra une clé <literal>data</literal>,
       qui doit être manuellement analysée.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <methodname>dns_get_record</methodname> retourne un tableau de tableaux
   associatifs, &return.falseforfailure;.
   Chaque tableau contient <emphasis>au minimum</emphasis> les index suivants :
   <table>
    <title>Attributs de base DNS</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Attribut</entry>
       <entry>Signification</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>host</entry>
       <entry>
        L'enregistrement de l'espace de noms DNS qui est décrit par les autres
        données.
       </entry>
      </row>
      <row>
       <entry>class</entry>
       <entry>
        <function>dns_get_record</function> ne retourne que la classe d'enregistrement
        Internet et, en tant que tel, cet index vaudra toujours <literal>IN</literal>.
       </entry>
      </row>
      <row>
       <entry>type</entry>
       <entry>
        Chaîne de caractères contenant le type d'enregistrement. Des attributs
        supplémentaires seront aussi disponibles dans le tableau suivant la
        valeur de ce type. Se reporter à la table ci-dessous.
       </entry>
      </row>
      <row>
       <entry>ttl</entry>
       <entry>
        <literal>"Time To Live"</literal> : durée avant expiration de l'enregistrement. 
        Cette valeur est <emphasis>différente</emphasis> de la durée avant expiration originale,
        mais plutôt cette valeur moins la durée depuis la dernière interrogation
        du serveur DNS responsable.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para>
   <table>
    <title>Autres index disponibles suivant le type DNS</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Type</entry>
       <entry>Valeur supplémentaire</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>A</literal></entry>
       <entry>
        <literal>ip</literal>: une adresse IPv4, au format numérique.
       </entry>
      </row>
      <row>
       <entry><literal>MX</literal></entry>
       <entry>
        <literal>pri</literal> : priorité du serveur de mail.
        Les nombres faibles indiquent une priorité importante.
        <literal>target</literal> : FQDN du serveur de mail.
        Voir aussi <function>dns_get_mx</function>.
       </entry>
      </row>
      <row>
       <entry><literal>CNAME</literal></entry>
       <entry>
        <literal>target</literal> : FQDN du nom de l'espace DNS qui sert
        d'alias à cet enregistrement.
       </entry>
      </row>
      <row>
       <entry><literal>NS</literal></entry>
       <entry>
        <literal>target</literal> : FQDN du nom de serveur qui est responsable
        de ce nom de domaine.
       </entry>
      </row>
      <row>
       <entry><literal>PTR</literal></entry>
       <entry>
        <literal>target</literal> : nom de domaine vers lequel cet enregistrement pointe.
       </entry>
      </row>
      <row>
       <entry><literal>TXT</literal></entry>
       <entry>
        <literal>txt</literal> : chaîne de caractères arbitrairement associée
        à cet enregistrement.
       </entry>
      </row>
      <row>
       <entry><literal>HINFO</literal></entry>
       <entry>
        <literal>cpu</literal> : numéro IANA désignant le processeur de la machine
        référencée par cet enregistrement.
        <literal>os</literal> : numéro IANA désignant le système d'exploitation
        de la machine référencée par cet enregistrement.
        Voir <link xlink:href="&url.iana.system-names;"><literal>Operating System Names</literal></link>
        pour connaître la signification de ces valeurs.
       </entry>
      </row>
      <row>
       <entry><literal>CAA</literal></entry>
       <entry>
        <literal>flags</literal> : Un champ-bit d'un octet : actuellement seul le bit 0 est défini,
        signifiant 'critical' (critique) ; les autres bits sont réservés et devraient être ignorés.
        <literal>tag</literal>: Le nom du tag CAA (chaîne alphanumérique ASCII).
        <literal>value</literal> : La valeur du tag CAA (chaîne binaire, peut utiliser des sous-formats).
        Pour plus d'informations voir : <link xlink:href="&url.rfc;6844">RFC 6844</link>
       </entry>
      </row>
      <row>
       <entry><literal>SOA</literal></entry>
       <entry>
        <literal>mname</literal> : FQDN de la source de cet enregistrement.
        <literal>rname</literal> : adresse email du contact administratif de
        ce domaine.
        <literal>serial</literal> : numéro de série du nom de domaine.
        <literal>refresh</literal> : intervalle de rafraîchissement (en secondes)
        que les serveurs de noms secondaires doivent utiliser pour mettre
        en cache ce nom de domaine.
        <literal>retry</literal> : durée (en secondes) d'attente après un rafraîchissement
        échoué, avant de faire une seconde tentative.
        <literal>expire</literal> : durée maximale (en secondes) de conservation
        d'une copie des données de zone sans pouvoir faire de rafraîchissement.
        <literal>minimum-ttl</literal> : durée minimale (en secondes) pendant laquelle un
        client conserve des données de zone avant qu'il ne soumette une nouvelle
        requête. Cette configuration peut être annulée par d'autres enregistrements.
       </entry>
      </row>
      <row>
       <entry><literal>AAAA</literal></entry>
       <entry>
        <literal>ipv6</literal>: adresse IPv6
       </entry>
      </row>
      <row>
       <entry><literal>A6</literal></entry>
       <entry>
        <literal>masklen</literal> : longueur (en bits) à hériter depuis
        la cible spécifiée par <parameter>chain</parameter>.
        <literal>ipv6</literal> : adresse pour que cet enregistrement spécifique fusionne
        avec <parameter>chain</parameter>.
        <literal>chain</literal> : l'enregistrement parent à fusionner avec les données
        <parameter>ipv6</parameter>.
       </entry>
      </row>
      <row>
       <entry><literal>SRV</literal></entry>
       <entry>
        <literal>pri</literal> : (priorité) les priorités les plus basses doivent
        être utilisées en premier.
        <literal>weight</literal> : classement pour choisir aléatoirement parmi les
        serveurs <parameter>targets</parameter>.
        <literal>target</literal> et <literal>port</literal> : nom d'hôte et
        port où le service est disponible.
        Pour plus d'informations, voir : <link xlink:href="&url.rfc;2782">RFC 2782</link>
       </entry>
      </row>
      <row>
       <entry><literal>NAPTR</literal></entry>
       <entry>
        <literal>order</literal> et <literal>pref</literal> : équivalent à
        <parameter>pri</parameter> et <parameter>weight</parameter> ci-dessus.
        <literal>flags</literal>, <literal>services</literal>, <literal>regex</literal>,
        et <literal>replacement</literal> : paramètres tels que définis
        dans la <link xlink:href="&url.rfc;2915">RFC 2915</link>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.0.16, 7.1.2</entry>
       <entry>
        Ajout du support des enregistrements de type CAA.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>dns_get_record</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$result = dns_get_record("php.net");
print_r($result);
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => MX
            [pri] => 5
            [target] => pair2.php.net
            [class] => IN
            [ttl] => 6765
        )

    [1] => Array
        (
            [host] => php.net
            [type] => A
            [ip] => 64.246.30.37
            [class] => IN
            [ttl] => 8125
        )

)
]]>
    </screen>
   </example>
   <example>
    <title>Exemple avec <function>dns_get_record</function> et DNS_ANY</title>
    <para>
     Comme il est très courant de rechercher l'IP d'un serveur,
     une fois que l'enregistrement MX a été résolu, <function>dns_get_record</function>
     retourne aussi un tableau dans le paramètre <parameter>additional_records</parameter>
     qui contiendra les enregistrements associés. <parameter>authoritative_name_servers</parameter>
     est aussi retourné en contenant une liste des serveurs autorité.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
/* Demande tous ("ANY") les enregistrements pour php.net, 
   puis crée les tableaux $authns et $addtl
   contenant une liste des noms de serveurs, et tous
   les enregistrements qui vont avec
   */
$result = dns_get_record("php.net", DNS_ANY, $authns, $addtl);
echo "Result = ";
print_r($result);
echo "Auth NS = ";
print_r($authns);
echo "Additional = ";
print_r($addtl);
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Result = Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => MX
            [pri] => 5
            [target] => pair2.php.net
            [class] => IN
            [ttl] => 6765
        )

    [1] => Array
        (
            [host] => php.net
            [type] => A
            [ip] => 64.246.30.37
            [class] => IN
            [ttl] => 8125
        )

)
Auth NS = Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => remote1.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [1] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => remote2.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [2] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => ns1.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [3] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => ns2.easydns.com
            [class] => IN
            [ttl] => 10722
        )

)
Additional = Array
(
    [0] => Array
        (
            [host] => pair2.php.net
            [type] => A
            [ip] => 216.92.131.5
            [class] => IN
            [ttl] => 6766
        )

    [1] => Array
        (
            [host] => remote1.easydns.com
            [type] => A
            [ip] => 64.39.29.212
            [class] => IN
            [ttl] => 100384
        )

    [2] => Array
        (
            [host] => remote2.easydns.com
            [type] => A
            [ip] => 212.100.224.80
            [class] => IN
            [ttl] => 81241
        )

    [3] => Array
        (
            [host] => ns1.easydns.com
            [type] => A
            [ip] => 216.220.40.243
            [class] => IN
            [ttl] => 81241
        )

    [4] => Array
        (
            [host] => ns2.easydns.com
            [type] => A
            [ip] => 216.220.40.244
            [class] => IN
            [ttl] => 81241
        )

)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>dns_get_mx</function></member>
    <member><function>dns_check_record</function></member>
   </simplelist>
  </para>
 </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
-->