diff -r 4816d766a08a -r f345bda72bc4 Symbian3/PDK/Source/GUID-CED041C8-D68D-55D1-957E-1A48EEFFF851.dita --- a/Symbian3/PDK/Source/GUID-CED041C8-D68D-55D1-957E-1A48EEFFF851.dita Tue Mar 30 11:42:04 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-CED041C8-D68D-55D1-957E-1A48EEFFF851.dita Tue Mar 30 11:56:28 2010 +0100 @@ -1,29 +1,115 @@ - - - - - -Inquiring about Remote Devices

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.

How to inquire about remote devices

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.

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.

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.

Address and name inquiries are performed through the generic Symbian OS sockets class RHostResolver. A specialist Bluetooth sockets address class, TInquirySockAddr, which encapsulates Bluetooth address, Inquiry Access Code, and service and device classes, is provided for use with such inquiries.

Basic Procedure

To inquire for the addresses of remote devices, take the following steps:

  1. Connect to the Sockets Server (RSocketServ), and then select the protocol to be used using RSocketServ::FindProtocol(). Address and name queries are supplied by the stack's BTLinkManager protocol layer, so select this.

  2. Create and initialise an RHostResolver object.

  3. Set the TInquirySockAddr parameter for the inquiry: for address inquiries, the KHostResInquiry flag must be set through TInquirySockAddr::SetAction().

    The query can then be started with RHostResolver::GetByAddress().

  4. When GetByAddress() completes, it fills in a TNameEntry object with the address and class of the first device found (or is undefined if no device was found).

  5. To get all the devices discovered, call RHostResolver::Next() repeatedly until KErrHostResNoMoreResults is returned.

Getting the addresses of remote devices

The following example shows how to start a remote device address inquiry.

  1. Connect to the socket server

    RSocketServ socketServ; -socketServ.Connect(); -TProtocolDesc pInfo; -_LIT(KL2Cap, "BTLinkManager"); -User::LeaveIfError(socketServ.FindProtocol(KL2Cap,pInfo));

  2. Create and initialise an RHostResolver

    RHostResolver hr; -User::LeaveIfError(hr.Open(socketServ,pInfo.iAddrFamily,pInfo.iProtocol));

  3. Set up a discovery query and start it

    TInquirySockAddr addr; -TNameEntry entry; -addr.SetIAC(KGIAC); -addr.SetAction(KHostResInquiry); -TRequestStatus status; -hr.GetByAddress(addr, entry, status); -User::WaitForRequest(status);

  4. Process the information returned in entry

    ...

Notes:

  • TInquirySockAddr::SetIAC() sets the Bluetooth Inquiry Access Code. For more information, see Bluetooth Assigned Numbers.

  • 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.

  • Communications API calls are typically asynchronous (indicated by a TRequestStatus parameter in the call). It is recommended that such calls are encapsulated in active objects, as explained in Using Asynchronous Programming.

Getting the name of a remote device

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 TInquirySockAddr to KHostResName. The name is returned in the iName member accessed through the TNameEntry.

Example

// Now do name inquiry -addr.SetAction(KHostResName); -hr.GetByAddress(addr, entry, stat); -User::WaitForRequest(stat); -TPtrC deviceName; -if (stat == KErrNone) - deviceName.Set(entry().iName);

Notes

  • To do a simultaneous address and name inquiry, use SetAction(KHostResName|KHostResInquiry).

  • RHostResolver::GetByName() is not supported

Where Next?

This tutorial set takes you through all the steps involved in setting up and communicating over a Bluetooth connection.

  • Selecting a Remote Device

  • Inquiring About Remote Devices - This document

  • Inquiring About Services on a Remote Device

  • Connecting and Transferring Data to a Remote Device

  • Using security on outgoing sockets

\ No newline at end of file + + + + + +Inquiring +about Remote DevicesDescribes how to inquire about remote devices. +

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.

+
How to inquire about remote devices

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.

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.

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.

Address and name inquiries are performed through the generic +Symbian platform sockets class RHostResolver. +A specialist Bluetooth sockets address class, TInquirySockAddr, +which encapsulates Bluetooth address, Inquiry Access Code, and service and +device classes, is provided for use with such inquiries.

Basic +Procedure

To inquire for the addresses of remote devices, take +the following steps:

    +

  1. Connect to the Sockets +Server (RSocketServ), and then select the protocol to be +used using RSocketServ::FindProtocol(). Address and name +queries are supplied by the stack's BTLinkManager protocol layer, so select +this.

    2. +

  2. Create and initialise +an RHostResolver object.

    3. +

  3. Set the TInquirySockAddr parameter +for the inquiry: for address inquiries, the KHostResInquiry flag +must be set through TInquirySockAddr::SetAction().

    The +query can then be started with RHostResolver::GetByAddress().

    4. +

  4. When GetByAddress() completes, +it fills in a TNameEntry object with the address and class +of the first device found (or is undefined if no device was found).

    5. +

  5. To get all the devices +discovered, call RHostResolver::Next() repeatedly until KErrHostResNoMoreResults is +returned.

    6. +

Getting +the addresses of remote devices

The following example shows how +to start a remote device address inquiry.

    +

  1. Connect to the socket +server

    RSocketServ socketServ; +socketServ.Connect(); +TProtocolDesc pInfo; +_LIT(KL2Cap, "BTLinkManager"); +User::LeaveIfError(socketServ.FindProtocol(KL2Cap,pInfo));
    2. +

  2. Create and initialise +an RHostResolver

    RHostResolver hr; +User::LeaveIfError(hr.Open(socketServ,pInfo.iAddrFamily,pInfo.iProtocol));
    3. +

  3. Set up a discovery query +and start it

    TInquirySockAddr addr; +TNameEntry entry; +addr.SetIAC(KGIAC); +addr.SetAction(KHostResInquiry); +TRequestStatus status; +hr.GetByAddress(addr, entry, status); +User::WaitForRequest(status);
    4. +

  4. Process the information +returned in entry

    ...
    5. +

Notes:

    +

  • TInquirySockAddr::SetIAC() sets +the Bluetooth Inquiry Access Code. For more information, see Bluetooth Assigned Numbers.

    • +

  • 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.

    • +

  • Communications API calls +are typically asynchronous (indicated by a TRequestStatus parameter +in the call). It is recommended that such calls are encapsulated in active +objects, as explained in Using +Asynchronous Programming.

    • +

Getting +the name of a remote device

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 TInquirySockAddr to KHostResName. +The name is returned in the iName member accessed through +the TNameEntry.

Example

// Now do name inquiry +addr.SetAction(KHostResName); +hr.GetByAddress(addr, entry, stat); +User::WaitForRequest(stat); +TPtrC deviceName; +if (stat == KErrNone) + deviceName.Set(entry().iName);

Notes

    +

  • To do a simultaneous +address and name inquiry, use SetAction(KHostResName|KHostResInquiry).

    • +

  • RHostResolver::GetByName() is +not supported

    • +
+
Where Next?

This tutorial set takes you through +all the steps involved in setting up and communicating over a Bluetooth connection.

    +

  • Selecting +a Remote Device

    • +

  • Inquiring About +Remote Devices - This document

    • +

  • Inquiring +About Services on a Remote Device

    • +

  • Connecting +and Transferring Data to a Remote Device

    • +

  • Using +security on outgoing sockets

    • +
+ \ No newline at end of file