<?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>