diff options
Diffstat (limited to 'examples/bluetooth/btchat/doc/src/btchat.qdoc')
| -rw-r--r-- | examples/bluetooth/btchat/doc/src/btchat.qdoc | 175 |
1 files changed, 97 insertions, 78 deletions
diff --git a/examples/bluetooth/btchat/doc/src/btchat.qdoc b/examples/bluetooth/btchat/doc/src/btchat.qdoc index 42a82bc6..5ad11502 100644 --- a/examples/bluetooth/btchat/doc/src/btchat.qdoc +++ b/examples/bluetooth/btchat/doc/src/btchat.qdoc @@ -1,37 +1,14 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt local connectivty modules. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \example btchat - \title Bluetooth Chat Example - \brief An example showing communication through Bluetooth. + \title Bluetooth Chat + \examplecategory {Connectivity} + \brief Shows communication through Bluetooth using RFCOMM protocol. The Bluetooth Chat example shows how to use the \l{Qt Bluetooth} API to communicate - with another application on a remote device using Bluetooth. + with another application on a remote device using Bluetooth RFCOMM protocol. \image btchat-example.png @@ -43,26 +20,28 @@ \section1 Chat Server - The chat server is implemented by the ChatServer class. The ChatServer class is declared as: + The chat server is implemented by the \c ChatServer class. + The \c ChatServer class is declared as: \snippet btchat/chatserver.h declaration - The first thing the chat server needs to do is create an instance of QRfcommServer to listen - for incoming Bluetooth connections. Our clientConnected() slot will be called whenever a new - connection is created. + The first thing the chat server needs to do is create an instance of + QBluetoothServer to listen for incoming Bluetooth connections. The + \c {clientConnected()} slot will be called whenever a new connection is + created. \snippet btchat/chatserver.cpp Create the server The chat server is only useful if others know that it is there. To enable other devices to - discover it, a record describing the service needs to be published in the systems SDP (Service + discover it, a record describing the service needs to be published in the system's SDP (Service Discovery Protocol) database. The QBluetoothServiceInfo class encapsulates a service record. - We will publish a service record that contains some textural descriptions of the services, a + We will publish a service record that contains some textual descriptions of the services, a UUID that uniquely identifies the service, the discoverability attribute, and connection parameters. - The textural description of the service is stored in the ServiceName, ServiceDescription, and - ServiceProvider attributes. + The textual description of the service is stored in the \c {ServiceName}, + \c {ServiceDescription}, and \c {ServiceProvider} attributes. \snippet btchat/chatserver.cpp Service name, description and provider @@ -72,13 +51,14 @@ \snippet btchat/chatserver.cpp Service UUID \snippet btchat/chatserver.cpp Service UUID set - A Bluetooth service is only discoverable if it is in the PublicBrowseGroup. + A Bluetooth service is only discoverable if it is in the + \l {QBluetoothUuid::}{PublicBrowseGroup}. \snippet btchat/chatserver.cpp Service Discoverability - The ProtocolDescriptorList attribute is used to publish the connection parameters that the - remote device requires to connect to our service. Here we specify that the Rfcomm protocol is - used and set the port number to the port that our rfcommServer instance is listening to. + The \c ProtocolDescriptorList attribute is used to publish the connection parameters that the + remote device requires to connect to our service. Here we specify that the \c Rfcomm protocol + is used and set the port number to the port that our \c rfcommServer instance is listening to. \snippet btchat/chatserver.cpp Protocol descriptor list @@ -86,58 +66,92 @@ \snippet btchat/chatserver.cpp Register service - - As mentioned earlier, incoming connections are handled in the clientConnected() slot where - pending connections are connected to the readyRead() and disconnected() signals. The signals - notify others that a new client has connected. + As mentioned earlier, incoming connections are handled in the + \c {clientConnected()} slot where pending connections are connected to the + \l {QBluetoothSocket::}{readyRead()} and + \l {QBluetoothSocket::}{disconnected()} signals. The signals notify others + that a new client has connected. \snippet btchat/chatserver.cpp clientConnected - The readSocket() slot is called whenever data is ready to be read from a client socket. The - slot reads individual lines from the socket, converts them from UTF-8, and emits the - messageReceived() signal. + The \c {readSocket()} slot is called whenever data is ready to be read from + a client socket. The slot reads individual lines from the socket, converts + them from UTF-8, and emits the \c {messageReceived()} signal. \snippet btchat/chatserver.cpp readSocket - The clientDisconnected() slot is called whenever a client disconnects from the service. The - slot emits a signal to notify others that a client has disconnected, and deletes the socket. + The \c {clientDisconnected()} slot is called whenever a client disconnects + from the service. The slot emits a signal to notify others that a client + has disconnected, and deletes the socket. \snippet btchat/chatserver.cpp clientDisconnected - The sendMessage() slot is used to send a message to all connected clients. The message is + The \c {sendMessage()} slot is used to send a message to all connected clients. The message is converted into UTF-8 and appended with a newline before being sent to all clients. \snippet btchat/chatserver.cpp sendMessage - When the chat server is stopped the service record is removed from the system SDP database, all - connected client sockets are deleted, and the QRfcommServer instance is deleted. + When the chat server is stopped, the service record is removed from the + system SDP database, all connected client sockets are deleted, and the + \c rfcommServer instance is deleted. \snippet btchat/chatserver.cpp stopServer + \section1 Service Discovery + + Before connecting to the server, the client needs to scan the nearby + devices and search for the device that is advertising the chat service. + This is done by the \c RemoteSelector class. + + To start service lookup, the \c RemoteSelector creates an instance of + \l QBluetoothServiceDiscoveryAgent and connects to its signals. + + \snippet btchat/remoteselector.cpp createDiscoveryAgent + + An UUID filter is set, so that the service discovery only shows the devices + that advertise the needed service. After that a + \l {QBluetoothServiceDiscoveryAgent::}{FullDiscovery} is started: + + \snippet btchat/remoteselector.cpp startDiscovery + + When a matching service is discovered, a + \l {QBluetoothServiceDiscoveryAgent::}{serviceDiscovered()} signal is + emitted with an instance of \l QBluetoothServiceInfo as a parameter. This + service info is used to extract the device name and the service name, + and add a new entry to the list of discovered remote devices: + + \snippet btchat/remoteselector.cpp serviceDiscovered + + Later the user can select one of the devices from the list and try to + connect to it. + \section1 Chat Client - The chat client is implemented by the ChatClient class. The ChatClient class is declared as: + The chat client is implemented by the \c ChatClient class. + The \c ChatClient class is declared as: \snippet btchat/chatclient.h declaration - The client creates a new QBluetoothSocket and connects to the remote service described by the - \e remoteService parameter. Slots are connected to the sockets readyRead(), connected() and - disconnected() signals. + The client creates a new QBluetoothSocket and connects to the remote + service described by the \c remoteService parameter. Slots are connected + to the socket's \l {QBluetoothSocket::}{readyRead()}, + \l {QBluetoothSocket::}{connected()}, and + \l {QBluetoothSocket::}{disconnected()} signals. \snippet btchat/chatclient.cpp startClient - On successful socket connection we emit a signal to notify others. + On successful socket connection we emit a signal to notify other users. \snippet btchat/chatclient.cpp connected - Similarly to the chat server, the readSocket() slot is called when data is available from the - socket. Lines are read individually and converted from UTF-8. The messageReceived() signal - is emitted. + Similarly to the chat server, the \c readSocket() slot is called when data + is available from the socket. Lines are read individually and converted + from UTF-8. The \c {messageReceived()} signal is emitted. \snippet btchat/chatclient.cpp readSocket - The sendMessage() slot is used to send a message to the remote device. The message is - converted to UTF-8 and a newline is appended. + The \c {sendMessage()} slot is used to send a message to the remote device. + The message is converted to UTF-8 and a newline is appended. \snippet btchat/chatclient.cpp sendMessage @@ -147,9 +161,10 @@ \section1 Chat Dialog - The main window of this example is the chat dialog, implemented in the Chat class. This class - displays a chat session between a single ChatServer and zero or more ChatClients. The Chat - class is declared as: + The main window of this example is the chat dialog, implemented in the + \c Chat class. This class displays a chat session between a single + \c ChatServer and zero or more \c {ChatClient}s. The \c Chat class is + declared as: \snippet btchat/chat.h declaration @@ -157,38 +172,42 @@ \snippet btchat/chat.cpp Construct UI - We create an instance of the ChatServer and respond to its clientConnected(), - clientDiconnected(), and messageReceived() signals. + We create an instance of the \c ChatServer and respond to its + \c {clientConnected()}, \c {clientDiconnected()}, and + \c {messageReceived()} signals. \snippet btchat/chat.cpp Create Chat Server - In response to the clientConnected() and clientDisconnected() signals of the ChatServer, we - display the typical "X has joined chat." and "Y has left." messages in the chat session. + In response to the \c {clientConnected()} and \c {clientDisconnected()} + signals of the \c ChatServer, we display the typical "X has joined chat." + and "Y has left." messages in the chat session. \snippet btchat/chat.cpp clientConnected clientDisconnected - Incoming messages from clients connected to the ChatServer are handled in the showMessage() - slot. The message text tagged with the remote device name is displayed in the chat session. + Incoming messages from clients connected to the \c ChatServer are handled + in the \c {showMessage()} slot. The message text tagged with the remote + device name is displayed in the chat session. \snippet btchat/chat.cpp showMessage In response to the connect button being clicked, the application starts service discovery and - presents a list of discovered chat services on remote devices. A ChatClient for the service + presents a list of discovered chat services on remote devices. A \c ChatClient for the service is selected by the user. \snippet btchat/chat.cpp Connect to remote service - In reponse to the connected() signals from ChatClient, we display the a "Joined chat with X." - message in the chat session. + In reponse to the \c {connected()} signals from \c ChatClient, we display + the "Joined chat with X." message in the chat session. \snippet btchat/chat.cpp connected - Messages are sent to all remote devices via the ChatServer and ChatClient instances by emitting - the sendMessage() signal. + Messages are sent to all remote devices via the \c ChatServer and + \c ChatClient instances by emitting the \c {sendMessage()} signal. \snippet btchat/chat.cpp sendClicked - We need to clean up ChatClient instances when the remote device forces a disconnect. + We need to clean up \c ChatClient instances when the remote device forces + a disconnect. \snippet btchat/chat.cpp clientDisconnected */ |