--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-CED041C8-D68D-55D1-957E-1A48EEFFF851.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,115 @@
+<?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 id="GUID-CED041C8-D68D-55D1-957E-1A48EEFFF851" xml:lang="en"><title>Inquiring
+about Remote Devices</title><shortdesc>Describes how to inquire about remote devices.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>Now that you have decided on the best method of selecting a remote device
+you will need to go through the process. For the purposes of this tutorial
+we will assume you are going to allow the program to determine the remote
+device with which to connect. </p>
+<section id="GUID-2AE00E8E-3DC5-4AB3-9B85-5953BDC873BF"><title>How to inquire about remote devices</title> <p>Each Bluetooth
+device has a 48-bit unique address built into its hardware. A basic inquiry
+for devices in range returns zero or more of these addresses. </p> <p>As well
+as an address, a Bluetooth device has a text name suitable for display to
+users. If you want to display a list of available devices to the user, you
+will also need to obtain these names. </p> <p>The address and the name inquiries
+can occur simultaneously, if the underlying hardware supports this. Otherwise,
+the address inquiry must finish before the name request can be issued over
+the air. </p> <p>Address and name inquiries are performed through the generic
+Symbian platform sockets class <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref>.
+A specialist Bluetooth sockets address class, <xref href="GUID-0ECE42E1-5E04-3BFB-BA17-F8036510798D.dita"><apiname>TInquirySockAddr</apiname></xref>,
+which encapsulates Bluetooth address, Inquiry Access Code, and service and
+device classes, is provided for use with such inquiries. </p> <p><b> Basic
+Procedure</b> </p> <p>To inquire for the addresses of remote devices, take
+the following steps: </p> <ol id="GUID-B794CB43-DF26-5C9E-BABC-95E614B8225F">
+<li id="GUID-20EDA9A2-9C57-55E2-B36D-117CFF923D49"><p>Connect to the Sockets
+Server (<xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RSocketServ</apiname></xref>), and then select the protocol to be
+used using <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita#GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449/GUID-95B5BAA3-5A01-37F3-9C81-C5E71530B3B7"><apiname>RSocketServ::FindProtocol()</apiname></xref>. Address and name
+queries are supplied by the stack's BTLinkManager protocol layer, so select
+this. </p> </li>
+<li id="GUID-30F19EEC-CB83-53D4-99E6-84C68A2DED9C"><p>Create and initialise
+an <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref> object. </p> </li>
+<li id="GUID-B2FD4AE2-A5DE-5EB4-A135-CDA502364550"><p>Set the <codeph>TInquirySockAddr</codeph> parameter
+for the inquiry: for address inquiries, the <xref href="GUID-75438E00-D211-3C94-A47D-61C5644A667D.dita"><apiname>KHostResInquiry</apiname></xref> flag
+must be set through <xref href="GUID-0ECE42E1-5E04-3BFB-BA17-F8036510798D.dita#GUID-0ECE42E1-5E04-3BFB-BA17-F8036510798D/GUID-E4E83FA5-3102-3CE8-8796-A70C017D4FC7"><apiname>TInquirySockAddr::SetAction()</apiname></xref>. </p> <p>The
+query can then be started with <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>. </p> </li>
+<li id="GUID-85980345-3E1A-5E10-A9F0-547DECBE52BB"><p>When <codeph>GetByAddress()</codeph> completes,
+it fills in a <xref href="GUID-C625E339-6726-3FB9-8F8A-F4DB0CAC15FF.dita"><apiname>TNameEntry</apiname></xref> object with the address and class
+of the first device found (or is undefined if no device was found). </p> </li>
+<li id="GUID-B2FE92B6-989A-5A9F-92CB-9759587C31F8"><p>To get all the devices
+discovered, call <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita#GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD/GUID-B64AB6BA-6D1D-30EB-88EF-381B52939F3D"><apiname>RHostResolver::Next()</apiname></xref> repeatedly until <codeph>KErrHostResNoMoreResults</codeph> is
+returned. </p> </li>
+</ol> <p><b>Getting
+the addresses of remote devices</b> </p> <p>The following example shows how
+to start a remote device address inquiry. </p> <ol id="GUID-A31D5876-7EE5-56B6-8F5A-7B8986C55349">
+<li id="GUID-B6BCA711-BBC7-52C0-9B7A-F128031346ED"><p>Connect to the socket
+server </p> <codeblock id="GUID-9E81DC37-FFC5-5427-BC01-54DFD82ED929" xml:space="preserve">RSocketServ socketServ;
+socketServ.Connect();
+TProtocolDesc pInfo;
+_LIT(KL2Cap, "BTLinkManager");
+User::LeaveIfError(socketServ.FindProtocol(KL2Cap,pInfo));</codeblock> </li>
+<li id="GUID-48A0FDB1-BB15-5759-8AC1-F837513B423A"><p>Create and initialise
+an <codeph>RHostResolver</codeph>  </p> <codeblock id="GUID-221037A8-6A39-5C27-A0DD-2A2BD14E5A7F" xml:space="preserve">RHostResolver hr;
+User::LeaveIfError(hr.Open(socketServ,pInfo.iAddrFamily,pInfo.iProtocol));</codeblock> </li>
+<li id="GUID-4A5D7DFC-FDFE-5D87-8DAB-A1BE59EFF806"><p>Set up a discovery query
+and start it </p> <codeblock id="GUID-DA8F9430-CDE6-5663-9DED-D897B134DEEF" xml:space="preserve">TInquirySockAddr addr;
+TNameEntry entry;
+addr.SetIAC(KGIAC);
+addr.SetAction(KHostResInquiry);
+TRequestStatus status;
+hr.GetByAddress(addr, entry, status);
+User::WaitForRequest(status);</codeblock> </li>
+<li id="GUID-9835B54E-E6D2-5FD5-8E7C-1374177F2D8A"><p>Process the information
+returned in <codeph>entry</codeph>  </p> <codeblock id="GUID-766A738A-2F2F-5570-964B-196FA45BA601" xml:space="preserve">...</codeblock> </li>
+</ol> <p><b>Notes:</b> </p> <ul>
+<li id="GUID-71BF7F7E-AD6E-5715-B9A5-BAE7488B9B80"><p> <xref href="GUID-0ECE42E1-5E04-3BFB-BA17-F8036510798D.dita#GUID-0ECE42E1-5E04-3BFB-BA17-F8036510798D/GUID-B8F50B34-789B-3ADE-8D1E-04B59394BC2A"><apiname>TInquirySockAddr::SetIAC()</apiname></xref> sets
+the Bluetooth Inquiry Access Code. For more information, see <xref href="http://www.bluetooth.org/assigned-numbers/" scope="external">Bluetooth Assigned Numbers</xref>. </p> </li>
+<li id="GUID-B55A03AB-3F37-5377-80E6-5F94045A4C5F"><p>The host resolver caches
+the results of inquiries so that devices that are no longer present may appear
+in the list of results. This does not cause any additional complications,
+as it is always possible for a device to go out of range between when it is
+discovered and when a connection to it is made. </p> </li>
+<li id="GUID-51CA2D0D-6A75-537F-A040-EA47D00DFEE0"><p>Communications API calls
+are typically asynchronous (indicated by a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> parameter
+in the call). It is recommended that such calls are encapsulated in active
+objects, as explained in <xref href="GUID-B507490F-6BD3-5DF5-97E4-EFDFEA2B4EDD.dita">Using
+Asynchronous Programming</xref>. </p> </li>
+</ul> <p><b>Getting
+the name of a remote device</b> </p> <p>The name of a remote device can be
+queried for by taking the same steps as for an address query, but setting
+the action flag of a <codeph>TInquirySockAddr</codeph> to <xref href="GUID-8B748089-6177-3C64-8F54-C2F6E1C364F4.dita"><apiname>KHostResName</apiname></xref>.
+The name is returned in the <codeph>iName</codeph> member accessed through
+the <codeph>TNameEntry</codeph>. </p> <p><b>Example </b> </p> <codeblock id="GUID-F670B724-E96C-5077-9317-4A6F27CBFF67" xml:space="preserve">// Now do name inquiry
+addr.SetAction(KHostResName);
+hr.GetByAddress(addr, entry, stat);
+User::WaitForRequest(stat);
+TPtrC deviceName;
+if (stat == KErrNone)
+     deviceName.Set(entry().iName);</codeblock> <p><b>Notes </b> </p> <ul>
+<li id="GUID-DB873994-76A6-5FE2-8B8D-00E0FD815DF2"><p>To do a simultaneous
+address and name inquiry, use <codeph>SetAction(KHostResName|KHostResInquiry)</codeph>. </p> </li>
+<li id="GUID-5823E26F-BFE7-5745-A208-C51DECF21D14"><p> <codeph>RHostResolver::GetByName()</codeph> is
+not supported </p> </li>
+</ul> </section>
+<section id="GUID-4425B269-2649-4A3C-81A4-17AB3733CF1C"><title>Where Next?</title> <p>This tutorial set takes you through
+all the steps involved in setting up and communicating over a Bluetooth connection. </p> <ul>
+<li id="GUID-78BDF706-7245-5D78-AB1D-8DB1352CFEAF"><p> <xref href="GUID-301488F8-B6D8-569A-B05E-19B740FE4C00.dita">Selecting
+a Remote Device</xref>  </p> </li>
+<li id="GUID-65BD97CF-9CD6-5050-9B96-4B22124C7E0F"><p> <b>Inquiring About
+Remote Devices</b> - This document </p> </li>
+<li id="GUID-2418982B-074A-561F-AF89-C0A233F7C593"><p> <xref href="GUID-A13494B9-C1E4-506A-B236-8AE0A6D6D557.dita">Inquiring
+About Services on a Remote Device</xref>  </p> </li>
+<li id="GUID-3E09B7DF-5BD7-5FC7-9C09-245421BCA730"><p> <xref href="GUID-A24D2CEF-88C9-5C63-A14D-85EFFBEF3C92.dita">Connecting
+and Transferring Data to a Remote Device</xref>  </p> </li>
+<li id="GUID-9AF0CBD6-3762-5724-82EF-88348D246CA1"><p> <xref href="GUID-4F0C4B9D-AA42-59C4-900A-7045FEAAF2F4.dita">Using
+security on outgoing sockets</xref>  </p> </li>
+</ul> </section>
+</conbody></concept>
\ No newline at end of file