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

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-95C166C3-2A25-55FB-88BD-62B7EFED2F8E"><title> Using the Domain Name Resolution Tutorial</title><shortdesc>This topic describes how to use the domain name resolution. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-7532AA62-7F2E-5366-870F-19679078A49D"><title>Required background</title> <p>You must be familiar with <codeph>RHostResolver()</codeph> to understand this tutorial. The <codeph>RHostResolver()</codeph> function is defined in <filepath>es_sock.h</filepath>. Types and constants specific to TCP/IP are used in <codeph>RHostResolver()</codeph> arguments are defined in <filepath>in_sock.h</filepath>. </p> </section> <section><title>Introduction</title> <p>The TCP/IP stack contains a Domain Name Service (DNS). The client programs conducts DNS queries through the generic host name resolution interface <codeph>RHostResolver</codeph>, specifying protocol-specific behaviour through the argument values. This tutorial describes how the <codeph>RHostResolver()</codeph> functions are used for DNS. </p> </section> <section><title>Procedure</title> <ol id="GUID-9B54766B-150D-5C97-A8CE-DDD3FE6905DD"><li id="GUID-F8AA8622-612A-5E54-A1ED-42148F42CC10"><p>The <codeph>RHostResolver::Open()</codeph> function starts the DNS access. </p> <p>The parameter values are as follows: </p> <p><table id="GUID-103482B4-11F7-5F14-9408-194BDA258A75"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><tbody><row><entry><p> <b>Parameter</b> </p> </entry> <entry><p> <b>Description</b> </p> </entry> </row> <row><entry><p> <codeph>addrFamily</codeph>  </p> </entry> <entry><p>Always <codeph>KAfInet</codeph>  </p> </entry> </row> <row><entry><p> <codeph>aProtocol</codeph>  </p> </entry> <entry><p>Always <codeph>KProtocolInetUdp</codeph>  </p> </entry> </row> </tbody> </tgroup> </table> </p> </li> <li id="GUID-97330842-8FAE-50FA-8CDA-2B51C29E2309"><p>The <codeph>RHostResolver::Close()</codeph> function closes the DNS access. </p> </li> </ol>  </section> <example><title>DNS Query example</title> <p>When a query is made, the protocol takes the following sequence of actions: </p> <ul><li id="GUID-E9AF9E05-3F92-535E-B855-C122CEA67F8B"><p>Searches the local HOSTS file, if it exists. The <filepath>hosts</filepath> file is stored in the <filepath>\private\10000882\</filepath> directory. </p> </li> <li id="GUID-086E42EC-E68B-56D7-98C0-9DFDF743FD51"><p>If an answer is not found, it checks the DNS cache. The protocol queries the DNS server using a UDP socket. If there is no current connection, a dial-up connection is called. </p> </li> <li id="GUID-1822F3AD-53ED-5CA2-A2CE-6E8BB9CFBECC"><p>If an answer is found, the answer is added to the cache. </p> </li> </ul> <p> <b>Note:</b> The cache entries are held continuously while the client <codeph>RHostResolver</codeph> object is open, for TTL 0 records. The client queries the <codeph>RHostResolver</codeph> object to get the latest records. </p> <p> <b>Note:</b> The DNS server used is managed by PPP to establish a dial-up connection, or configured by the user in ISP settings. </p> <p>The <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita#GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD/GUID-37A2B030-8FDE-372C-938D-FD3D26370BDC"><apiname>RHostResolver::GetByName()</apiname></xref> or <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita#GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD/GUID-B210BAF2-1D26-3F5A-8EBE-EF5B460A69E1"><apiname>RHostResolver::GetByAddress()</apiname></xref> can be called asynchronously, so that the application can select the program and the data when it is required. For more information see Next Result. </p> <p><b>Resolve name</b> </p> <p>Use <codeph>RHostResolver::GetByName()</codeph> to resolve a symbolic name to an IP address. The parameters are as follows: </p> <table id="GUID-4541EEBA-39CB-58BB-98BF-86B8BD885DA1"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><tbody><row><entry><p> <b>Parameter</b> </p> </entry> <entry><p> <b>Description</b> </p> </entry> </row> <row><entry><p> <codeph>aName</codeph>  </p> </entry> <entry><p>The symbolic name to resolve. </p> <p> <b>Note:</b> If you pass the local host name or a null descriptor the result is the address of the network interface. The <codeph>RHostResolver::GetHostName()</codeph> returns the local host name. </p> </entry> </row> <row><entry><p> <codeph>aResult</codeph>  </p> </entry> <entry><p>Returns the result of the name resolution. Unpack the <codeph>TNameEntry</codeph> to get a <codeph>TNameRecord</codeph> with the following members: </p> <p> <codeph>iName</codeph>: the value of the passed <codeph>aName</codeph>  </p> <p> <codeph>iAddr</codeph>: the address information. Assign the <codeph>iAddr</codeph> to <codeph>TInetAddr</codeph> to get the IP address. </p> <p> <codeph>iFlags</codeph>: a bitmask of <codeph>TNameRecordFlags</codeph> flags. </p> </entry> </row> </tbody> </tgroup> </table> <p><b>Get name</b> </p> <p>Use <codeph>RHostResolver::GetByAddress()</codeph> to get an IP address from a symbolic name. The parameters are as follows: </p> <table id="GUID-DED037D9-5BB7-595C-907B-144FF98FC8B9"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><tbody><row><entry><p> <b>Parameter</b> </p> </entry> <entry><p> <b>Description</b> </p> </entry> </row> <row><entry><p> <codeph>anAddr</codeph>  </p> </entry> <entry><p>A <codeph>TInetAddr</codeph> specifies the IP address to use. </p> <p> <b>Note:</b> If you pass a null address or an address that matches the primary network interface, the local host name is returned. </p> </entry> </row> <row><entry><p> <codeph>aResult</codeph>  </p> </entry> <entry><p>Returns the result of the name resolution. Unpack the <codeph>TNameEntry</codeph> to get a <codeph>TNameRecord</codeph> with the following members: </p> <p> <codeph>iName</codeph>: the symbolic name </p> <p> <codeph>iAddr</codeph>: the value of the passed <codeph>anAddr</codeph> </p> <p> <codeph>iFlags</codeph>: a bitmask of <codeph>TNameRecordFlags</codeph> flags. </p> </entry> </row> </tbody> </tgroup> </table> <p><b>Next result</b> </p> <p>The <codeph>Next()</codeph> function finds more answers after an initial <codeph>GetByName()</codeph> or <codeph>GetByAddress()</codeph> query. </p> <p>For <codeph>GetByName()</codeph>, the matching A record (IP address) is returned first. Calls to <codeph>Next()</codeph> return any further CNAME (alias) or A records. CNAME records have the IP address set to 0 and the <codeph>EDnsAlias</codeph> flag set. </p> <p>For <codeph>GetByAddress()</codeph>, the first matching PTR record (domain name) is returned first. Calls to <codeph>Next()</codeph> return any further PTR records. </p> <p> <b> Note:</b>  <codeph>The Next()</codeph> can be called synchronously, because all information is retrieved from a local buffer that was written by the initial query. </p> <p><b>Local host</b> </p> <p> <codeph>RHostResolver::GetHostName()</codeph> and <codeph>RHostResolver::SetHostName()</codeph> get and set the name of the local host. </p> </example> </conbody></concept>