Symbian3/SDK/Source/GUID-95C166C3-2A25-55FB-88BD-62B7EFED2F8E.dita
author Dominic Pinkman <Dominic.Pinkman@Nokia.com>
Thu, 21 Jan 2010 18:18:20 +0000
changeset 0 89d6a7a84779
permissions -rw-r--r--
Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     1
<?xml version="1.0" encoding="utf-8"?>
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     2
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     3
<!-- This component and the accompanying materials are made available under the terms of the License 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     4
"Eclipse Public License v1.0" which accompanies this distribution, 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     5
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     6
<!-- Initial Contributors:
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     7
    Nokia Corporation - initial contribution.
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     8
Contributors: 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     9
-->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    10
<!DOCTYPE concept
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    11
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    12
<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>