QBluetoothSocket Class
The QBluetoothSocket class enables connection to a Bluetooth device running a bluetooth server. More...
Header: | #include <QBluetoothSocket> |
qmake: | QT += bluetooth |
Since: | Qt 5.2 |
Inherits: | QIODevice |
Public Types
enum | SocketError { UnknownSocketError, NoSocketError, HostNotFoundError, ServiceNotFoundError, ..., RemoteHostClosedError } |
enum | SocketState { UnconnectedState, ServiceLookupState, ConnectingState, ConnectedState, ..., ListeningState } |
Public Functions
QBluetoothSocket(QBluetoothServiceInfo::Protocol socketType, QObject *parent = nullptr) | |
QBluetoothSocket(QObject *parent = nullptr) | |
virtual | ~QBluetoothSocket() |
void | abort() |
void | connectToService(const QBluetoothServiceInfo &service, QIODevice::OpenMode openMode = ReadWrite) |
void | connectToService(const QBluetoothAddress &address, const QBluetoothUuid &uuid, QIODevice::OpenMode openMode = ReadWrite) |
void | connectToService(const QBluetoothAddress &address, quint16 port, QIODevice::OpenMode openMode = ReadWrite) |
void | connectToService(const QBluetoothAddress &address, QBluetoothUuid::ServiceClassUuid uuid, QIODevice::OpenMode mode = ReadWrite) |
void | disconnectFromService() |
QBluetoothSocket::SocketError | error() const |
QString | errorString() const |
QBluetoothAddress | localAddress() const |
QString | localName() const |
quint16 | localPort() const |
QBluetoothAddress | peerAddress() const |
QString | peerName() const |
quint16 | peerPort() const |
QBluetooth::SecurityFlags | preferredSecurityFlags() const |
void | setPreferredSecurityFlags(QBluetooth::SecurityFlags flags) |
bool | setSocketDescriptor(int socketDescriptor, QBluetoothServiceInfo::Protocol socketType, QBluetoothSocket::SocketState socketState = ConnectedState, QIODevice::OpenMode openMode = ReadWrite) |
int | socketDescriptor() const |
QBluetoothServiceInfo::Protocol | socketType() const |
QBluetoothSocket::SocketState | state() const |
Reimplemented Public Functions
virtual qint64 | bytesAvailable() const |
virtual qint64 | bytesToWrite() const |
virtual bool | canReadLine() const |
virtual void | close() |
virtual bool | isSequential() const |
Signals
void | connected() |
void | disconnected() |
void | error(QBluetoothSocket::SocketError error) |
void | stateChanged(QBluetoothSocket::SocketState state) |
Static Public Members
const QMetaObject | staticMetaObject |
- 9 static public members inherited from QObject
Protected Functions
void | doDeviceDiscovery(const QBluetoothServiceInfo &service, QIODevice::OpenMode openMode) |
void | setSocketError(QBluetoothSocket::SocketError error_) |
void | setSocketState(QBluetoothSocket::SocketState state) |
Reimplemented Protected Functions
virtual qint64 | readData(char *data, qint64 maxSize) |
virtual qint64 | writeData(const char *data, qint64 maxSize) |
Protected Variables
QBluetoothSocketBasePrivate * | d_ptr |
Additional Inherited Members
Detailed Description
The QBluetoothSocket class enables connection to a Bluetooth device running a bluetooth server.
QBluetoothSocket supports two socket types, L2CAP and RFCOMM.
L2CAP is a low level datagram-oriented Bluetooth socket. Android does not support L2CAP for socket connections.
RFCOMM is a reliable, stream-oriented socket. RFCOMM sockets emulate an RS-232 serial port.
To create a connection to a Bluetooth service, create a socket of the appropriate type and call connectToService() passing the Bluetooth address and port number. QBluetoothSocket will emit the connected() signal when the connection is established.
If the Protocol is not supported on a platform, calling connectToService() will emit a UnsupportedProtocolError error.
Note: QBluetoothSocket does not support synchronous read and write operations. Functions such as waitForReadyRead() and waitForBytesWritten() are not implemented. I/O operations should be performed using readyRead(), read() and write().
On iOS, this class cannot be used because the platform does not expose an API which may permit access to QBluetoothSocket related features.
Member Type Documentation
enum QBluetoothSocket::SocketError
This enum describes Bluetooth socket error types.
Constant | Value | Description |
---|---|---|
QBluetoothSocket::UnknownSocketError | QAbstractSocket::UnknownSocketError | An unknown error has occurred. |
QBluetoothSocket::NoSocketError | -2 | No error. Used for testing. |
QBluetoothSocket::HostNotFoundError | QAbstractSocket::HostNotFoundError | Could not find the remote host. |
QBluetoothSocket::ServiceNotFoundError | QAbstractSocket::SocketAddressNotAvailableError | Could not find the service UUID on remote host. |
QBluetoothSocket::NetworkError | QAbstractSocket::NetworkError | Attempt to read or write from socket returned an error |
QBluetoothSocket::UnsupportedProtocolError | 8 | The Protocol is not supported on this platform. |
QBluetoothSocket::OperationError | QAbstractSocket::OperationError | An operation was attempted while the socket was in a state that did not permit it. |
QBluetoothSocket::RemoteHostClosedError | QAbstractSocket::RemoteHostClosedError | The remote host closed the connection. This value was introduced by Qt 5.10. |
enum QBluetoothSocket::SocketState
This enum describes the state of the Bluetooth socket.
Constant | Value | Description |
---|---|---|
QBluetoothSocket::UnconnectedState | QAbstractSocket::UnconnectedState | Socket is not connected. |
QBluetoothSocket::ServiceLookupState | QAbstractSocket::HostLookupState | Socket is querying connection parameters. |
QBluetoothSocket::ConnectingState | QAbstractSocket::ConnectingState | Socket is attempting to connect to a device. |
QBluetoothSocket::ConnectedState | QAbstractSocket::ConnectedState | Socket is connected to a device. |
QBluetoothSocket::BoundState | QAbstractSocket::BoundState | Socket is bound to a local address and port. |
QBluetoothSocket::ClosingState | QAbstractSocket::ClosingState | Socket is connected and will be closed once all pending data is written to the socket. |
QBluetoothSocket::ListeningState | QAbstractSocket::ListeningState | Socket is listening for incoming connections. |
Member Function Documentation
QBluetoothSocket::QBluetoothSocket(QBluetoothServiceInfo::Protocol socketType, QObject *parent = nullptr)
Constructs a Bluetooth socket of socketType type, with parent.
QBluetoothSocket::QBluetoothSocket(QObject *parent = nullptr)
Constructs a Bluetooth socket with parent.
[virtual]
QBluetoothSocket::~QBluetoothSocket()
Destroys the Bluetooth socket.
void QBluetoothSocket::abort()
[virtual]
qint64 QBluetoothSocket::bytesAvailable() const
Reimplemented from QIODevice::bytesAvailable().
Returns the number of incoming bytes that are waiting to be read.
See also bytesToWrite() and read().
[virtual]
qint64 QBluetoothSocket::bytesToWrite() const
Reimplemented from QIODevice::bytesToWrite().
Returns the number of bytes that are waiting to be written. The bytes are written when control goes back to the event loop.
[virtual]
bool QBluetoothSocket::canReadLine() const
Reimplemented from QIODevice::canReadLine().
Returns true if you can read at least one line from the device
[virtual]
void QBluetoothSocket::close()
void QBluetoothSocket::connectToService(const QBluetoothServiceInfo &service, QIODevice::OpenMode openMode = ReadWrite)
Attempts to connect to the service described by service.
The socket is opened in the given openMode. The socketType() may change depending on the protocol required by service.
The socket first enters ConnectingState and attempts to connect to the device providing service. If a connection is established, QBluetoothSocket enters ConnectedState and emits connected().
At any point, the socket can emit error() to signal that an error occurred.
Note that most platforms require a pairing prior to connecting to the remote device. Otherwise the connection process may fail.
See also state() and disconnectFromService().
void QBluetoothSocket::connectToService(const QBluetoothAddress &address, const QBluetoothUuid &uuid, QIODevice::OpenMode openMode = ReadWrite)
Attempts to make a connection to the service identified by uuid on the device with address address.
The socket is opened in the given openMode.
For BlueZ, the socket first enters the ServiceLookupState and queries the connection parameters for uuid. If the service parameters are successfully retrieved the socket enters ConnectingState, and attempts to connect to address. If a connection is established, QBluetoothSocket enters ConnectedState and emits connected().
On Android, the service connection can directly be established using the UUID of the remote service. Therefore the platform does not require the ServiceLookupState and socketType() is always set to QBluetoothServiceInfo::RfcommProtocol.
At any point, the socket can emit error() to signal that an error occurred.
Note that most platforms require a pairing prior to connecting to the remote device. Otherwise the connection process may fail.
See also state() and disconnectFromService().
void QBluetoothSocket::connectToService(const QBluetoothAddress &address, quint16 port, QIODevice::OpenMode openMode = ReadWrite)
Attempts to make a connection with address on the given port.
The socket is opened in the given openMode.
The socket first enters ConnectingState, and attempts to connect to address. If a connection is established, QBluetoothSocket enters ConnectedState and emits connected().
At any point, the socket can emit error() to signal that an error occurred.
On Android and BlueZ (version 5.46 or above), a connection to a service can not be established using a port. Calling this function will emit a ServiceNotFoundError.
Note that most platforms require a pairing prior to connecting to the remote device. Otherwise the connection process may fail.
See also state() and disconnectFromService().
void QBluetoothSocket::connectToService(const QBluetoothAddress &address, QBluetoothUuid::ServiceClassUuid uuid, QIODevice::OpenMode mode = ReadWrite)
[signal]
void QBluetoothSocket::connected()
void QBluetoothSocket::disconnectFromService()
[signal]
void QBluetoothSocket::disconnected()
[protected]
void QBluetoothSocket::doDeviceDiscovery(const QBluetoothServiceInfo &service, QIODevice::OpenMode openMode)
Start device discovery for service and open the socket with openMode. If the socket is created with a service uuid device address, use service discovery to find the port number to connect to.
QBluetoothSocket::SocketError QBluetoothSocket::error() const
Returns the last error.
[signal]
void QBluetoothSocket::error(QBluetoothSocket::SocketError error)
Note: Signal error is overloaded in this class. To connect to this signal by using the function pointer syntax, Qt provides a convenient helper for obtaining the function pointer as shown in this example:
connect(bluetoothSocket, QOverload<QBluetoothSocket::SocketError>::of(&QBluetoothSocket::error), [=](QBluetoothSocket::SocketError error){ /* ... */ });
QString QBluetoothSocket::errorString() const
Returns a user displayable text string for the error.
[virtual]
bool QBluetoothSocket::isSequential() const
Reimplemented from QIODevice::isSequential().
QBluetoothAddress QBluetoothSocket::localAddress() const
QString QBluetoothSocket::localName() const
quint16 QBluetoothSocket::localPort() const
QBluetoothAddress QBluetoothSocket::peerAddress() const
QString QBluetoothSocket::peerName() const
quint16 QBluetoothSocket::peerPort() const
QBluetooth::SecurityFlags QBluetoothSocket::preferredSecurityFlags() const
Returns the security parameters used for the initial connection attempt.
The security parameters may be renegotiated between the two parties during or after the connection has been established. If such a change happens it is not reflected in the value of this flag.
On macOS, this flag is always set to QBluetooth::Secure.
This function was introduced in Qt 5.6.
See also setPreferredSecurityFlags().
[virtual protected]
qint64 QBluetoothSocket::readData(char *data, qint64 maxSize)
void QBluetoothSocket::setPreferredSecurityFlags(QBluetooth::SecurityFlags flags)
Sets the preferred security parameter for the connection attempt to flags. This value is incorporated when calling connectToService(). Therefore it is required to reconnect to change this parameter for an existing connection.
On Bluez this property is set to QBluetooth::Authorization by default.
On macOS, this value is ignored as the platform does not permit access to the security parameter of the socket. By default the platform prefers secure/encrypted connections though and therefore this function always returns QBluetooth::Secure.
Android only supports two levels of security (secure and non-secure). If this flag is set to QBluetooth::NoSecurity the socket object will not employ any authentication or encryption. Any other security flag combination will trigger a secure Bluetooth connection. This flag is set to QBluetooth::Secure by default.
Note: A secure connection requires a pairing between the two devices. On some platforms, the pairing is automatically initiated during the establishment of the connection. Other platforms require the application to manually trigger the pairing before attempting to connect.
This function was introduced in Qt 5.6.
See also preferredSecurityFlags().
bool QBluetoothSocket::setSocketDescriptor(int socketDescriptor, QBluetoothServiceInfo::Protocol socketType, QBluetoothSocket::SocketState socketState = ConnectedState, QIODevice::OpenMode openMode = ReadWrite)
Set the socket to use socketDescriptor with a type of socketType, which is in state, socketState, and mode, openMode.
Returns true on success
See also socketDescriptor().
[protected]
void QBluetoothSocket::setSocketError(QBluetoothSocket::SocketError error_)
Sets the type of error that last occurred to error_.
[protected]
void QBluetoothSocket::setSocketState(QBluetoothSocket::SocketState state)
Sets the socket state to state.
int QBluetoothSocket::socketDescriptor() const
Returns the platform-specific socket descriptor, if available. This function returns -1 if the descriptor is not available or an error has occurred.
See also setSocketDescriptor().
QBluetoothServiceInfo::Protocol QBluetoothSocket::socketType() const
Returns the socket type. The socket automatically adjusts to the protocol offered by the remote service.
Android only support RFCOMM based sockets.
QBluetoothSocket::SocketState QBluetoothSocket::state() const
Returns the current state of the socket.