|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-CED041C8-D68D-55D1-957E-1A48EEFFF851" xml:lang="en"><title>Inquiring |
|
13 about Remote Devices</title><shortdesc>Describes how to inquire about remote devices.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Now that you have decided on the best method of selecting a remote device |
|
15 you will need to go through the process. For the purposes of this tutorial |
|
16 we will assume you are going to allow the program to determine the remote |
|
17 device with which to connect. </p> |
|
18 <section id="GUID-2AE00E8E-3DC5-4AB3-9B85-5953BDC873BF"><title>How to inquire about remote devices</title> <p>Each Bluetooth |
|
19 device has a 48-bit unique address built into its hardware. A basic inquiry |
|
20 for devices in range returns zero or more of these addresses. </p> <p>As well |
|
21 as an address, a Bluetooth device has a text name suitable for display to |
|
22 users. If you want to display a list of available devices to the user, you |
|
23 will also need to obtain these names. </p> <p>The address and the name inquiries |
|
24 can occur simultaneously, if the underlying hardware supports this. Otherwise, |
|
25 the address inquiry must finish before the name request can be issued over |
|
26 the air. </p> <p>Address and name inquiries are performed through the generic |
|
27 Symbian platform sockets class <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref>. |
|
28 A specialist Bluetooth sockets address class, <xref href="GUID-0ECE42E1-5E04-3BFB-BA17-F8036510798D.dita"><apiname>TInquirySockAddr</apiname></xref>, |
|
29 which encapsulates Bluetooth address, Inquiry Access Code, and service and |
|
30 device classes, is provided for use with such inquiries. </p> <p><b> Basic |
|
31 Procedure</b> </p> <p>To inquire for the addresses of remote devices, take |
|
32 the following steps: </p> <ol id="GUID-B794CB43-DF26-5C9E-BABC-95E614B8225F"> |
|
33 <li id="GUID-20EDA9A2-9C57-55E2-B36D-117CFF923D49"><p>Connect to the Sockets |
|
34 Server (<xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RSocketServ</apiname></xref>), and then select the protocol to be |
|
35 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 |
|
36 queries are supplied by the stack's BTLinkManager protocol layer, so select |
|
37 this. </p> </li> |
|
38 <li id="GUID-30F19EEC-CB83-53D4-99E6-84C68A2DED9C"><p>Create and initialise |
|
39 an <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref> object. </p> </li> |
|
40 <li id="GUID-B2FD4AE2-A5DE-5EB4-A135-CDA502364550"><p>Set the <codeph>TInquirySockAddr</codeph> parameter |
|
41 for the inquiry: for address inquiries, the <xref href="GUID-75438E00-D211-3C94-A47D-61C5644A667D.dita"><apiname>KHostResInquiry</apiname></xref> flag |
|
42 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 |
|
43 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> |
|
44 <li id="GUID-85980345-3E1A-5E10-A9F0-547DECBE52BB"><p>When <codeph>GetByAddress()</codeph> completes, |
|
45 it fills in a <xref href="GUID-C625E339-6726-3FB9-8F8A-F4DB0CAC15FF.dita"><apiname>TNameEntry</apiname></xref> object with the address and class |
|
46 of the first device found (or is undefined if no device was found). </p> </li> |
|
47 <li id="GUID-B2FE92B6-989A-5A9F-92CB-9759587C31F8"><p>To get all the devices |
|
48 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 |
|
49 returned. </p> </li> |
|
50 </ol> <p><b>Getting |
|
51 the addresses of remote devices</b> </p> <p>The following example shows how |
|
52 to start a remote device address inquiry. </p> <ol id="GUID-A31D5876-7EE5-56B6-8F5A-7B8986C55349"> |
|
53 <li id="GUID-B6BCA711-BBC7-52C0-9B7A-F128031346ED"><p>Connect to the socket |
|
54 server </p> <codeblock id="GUID-9E81DC37-FFC5-5427-BC01-54DFD82ED929" xml:space="preserve">RSocketServ socketServ; |
|
55 socketServ.Connect(); |
|
56 TProtocolDesc pInfo; |
|
57 _LIT(KL2Cap, "BTLinkManager"); |
|
58 User::LeaveIfError(socketServ.FindProtocol(KL2Cap,pInfo));</codeblock> </li> |
|
59 <li id="GUID-48A0FDB1-BB15-5759-8AC1-F837513B423A"><p>Create and initialise |
|
60 an <codeph>RHostResolver</codeph> </p> <codeblock id="GUID-221037A8-6A39-5C27-A0DD-2A2BD14E5A7F" xml:space="preserve">RHostResolver hr; |
|
61 User::LeaveIfError(hr.Open(socketServ,pInfo.iAddrFamily,pInfo.iProtocol));</codeblock> </li> |
|
62 <li id="GUID-4A5D7DFC-FDFE-5D87-8DAB-A1BE59EFF806"><p>Set up a discovery query |
|
63 and start it </p> <codeblock id="GUID-DA8F9430-CDE6-5663-9DED-D897B134DEEF" xml:space="preserve">TInquirySockAddr addr; |
|
64 TNameEntry entry; |
|
65 addr.SetIAC(KGIAC); |
|
66 addr.SetAction(KHostResInquiry); |
|
67 TRequestStatus status; |
|
68 hr.GetByAddress(addr, entry, status); |
|
69 User::WaitForRequest(status);</codeblock> </li> |
|
70 <li id="GUID-9835B54E-E6D2-5FD5-8E7C-1374177F2D8A"><p>Process the information |
|
71 returned in <codeph>entry</codeph> </p> <codeblock id="GUID-766A738A-2F2F-5570-964B-196FA45BA601" xml:space="preserve">...</codeblock> </li> |
|
72 </ol> <p><b>Notes:</b> </p> <ul> |
|
73 <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 |
|
74 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> |
|
75 <li id="GUID-B55A03AB-3F37-5377-80E6-5F94045A4C5F"><p>The host resolver caches |
|
76 the results of inquiries so that devices that are no longer present may appear |
|
77 in the list of results. This does not cause any additional complications, |
|
78 as it is always possible for a device to go out of range between when it is |
|
79 discovered and when a connection to it is made. </p> </li> |
|
80 <li id="GUID-51CA2D0D-6A75-537F-A040-EA47D00DFEE0"><p>Communications API calls |
|
81 are typically asynchronous (indicated by a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> parameter |
|
82 in the call). It is recommended that such calls are encapsulated in active |
|
83 objects, as explained in <xref href="GUID-B507490F-6BD3-5DF5-97E4-EFDFEA2B4EDD.dita">Using |
|
84 Asynchronous Programming</xref>. </p> </li> |
|
85 </ul> <p><b>Getting |
|
86 the name of a remote device</b> </p> <p>The name of a remote device can be |
|
87 queried for by taking the same steps as for an address query, but setting |
|
88 the action flag of a <codeph>TInquirySockAddr</codeph> to <xref href="GUID-8B748089-6177-3C64-8F54-C2F6E1C364F4.dita"><apiname>KHostResName</apiname></xref>. |
|
89 The name is returned in the <codeph>iName</codeph> member accessed through |
|
90 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 |
|
91 addr.SetAction(KHostResName); |
|
92 hr.GetByAddress(addr, entry, stat); |
|
93 User::WaitForRequest(stat); |
|
94 TPtrC deviceName; |
|
95 if (stat == KErrNone) |
|
96 deviceName.Set(entry().iName);</codeblock> <p><b>Notes </b> </p> <ul> |
|
97 <li id="GUID-DB873994-76A6-5FE2-8B8D-00E0FD815DF2"><p>To do a simultaneous |
|
98 address and name inquiry, use <codeph>SetAction(KHostResName|KHostResInquiry)</codeph>. </p> </li> |
|
99 <li id="GUID-5823E26F-BFE7-5745-A208-C51DECF21D14"><p> <codeph>RHostResolver::GetByName()</codeph> is |
|
100 not supported </p> </li> |
|
101 </ul> </section> |
|
102 <section id="GUID-4425B269-2649-4A3C-81A4-17AB3733CF1C"><title>Where Next?</title> <p>This tutorial set takes you through |
|
103 all the steps involved in setting up and communicating over a Bluetooth connection. </p> <ul> |
|
104 <li id="GUID-78BDF706-7245-5D78-AB1D-8DB1352CFEAF"><p> <xref href="GUID-301488F8-B6D8-569A-B05E-19B740FE4C00.dita">Selecting |
|
105 a Remote Device</xref> </p> </li> |
|
106 <li id="GUID-65BD97CF-9CD6-5050-9B96-4B22124C7E0F"><p> <b>Inquiring About |
|
107 Remote Devices</b> - This document </p> </li> |
|
108 <li id="GUID-2418982B-074A-561F-AF89-C0A233F7C593"><p> <xref href="GUID-A13494B9-C1E4-506A-B236-8AE0A6D6D557.dita">Inquiring |
|
109 About Services on a Remote Device</xref> </p> </li> |
|
110 <li id="GUID-3E09B7DF-5BD7-5FC7-9C09-245421BCA730"><p> <xref href="GUID-A24D2CEF-88C9-5C63-A14D-85EFFBEF3C92.dita">Connecting |
|
111 and Transferring Data to a Remote Device</xref> </p> </li> |
|
112 <li id="GUID-9AF0CBD6-3762-5724-82EF-88348D246CA1"><p> <xref href="GUID-4F0C4B9D-AA42-59C4-900A-7045FEAAF2F4.dita">Using |
|
113 security on outgoing sockets</xref> </p> </li> |
|
114 </ul> </section> |
|
115 </conbody></concept> |