QBluetoothSocket 类

The QBluetoothSocket class enables connection to a Bluetooth device running a bluetooth server. 更多...

头: #include <QBluetoothSocket>
qmake: QT += bluetooth
Since: Qt 5.2
继承: QIODevice

该类在 Qt 5.2 引入。

公共类型

enum SocketError { UnknownSocketError, NoSocketError, HostNotFoundError, ServiceNotFoundError, NetworkError, …, RemoteHostClosedError }
enum SocketState { UnconnectedState, ServiceLookupState, ConnectingState, ConnectedState, BoundState, …, ListeningState }

公共函数

QBluetoothSocket (QObject * parent = nullptr)
QBluetoothSocket (QBluetoothServiceInfo::Protocol socketType , 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 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

重实现公共函数

virtual qint64 bytesAvailable () const override
virtual qint64 bytesToWrite () const override
virtual bool canReadLine () const override
virtual void close () override
virtual bool isSequential () const override

信号

void connected ()
void disconnected ()
void error (QBluetoothSocket::SocketError error )
void stateChanged (QBluetoothSocket::SocketState state )

保护函数

void doDeviceDiscovery (const QBluetoothServiceInfo & service , QIODevice::OpenMode openMode )
void setSocketError (QBluetoothSocket::SocketError error_ )
void setSocketState (QBluetoothSocket::SocketState state )

重实现保护函数

virtual qint64 readData (char * data , qint64 maxSize ) override
virtual qint64 writeData (const char * data , qint64 maxSize ) override

详细描述

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.

Protocol 在平台中不被支持,调用 connectToService () 将发射 UnsupportedProtocolError 错误。

注意: QBluetoothSocket does not support synchronous read and write operations. Functions such as waitForReadyRead () 和 waitForBytesWritten () are not implemented. I/O operations should be performed using readyRead (), read () 和 write ().

On iOS, this class cannot be used because the platform does not expose an API which may permit access to QBluetoothSocket related features.

注意: On macOS Monterey (12) the socket data flow is paused when a modal dialogue is executing, or an event tracking mode is entered (for example by long-pressing a Window close button). This may change in the future releases of macOS.

成员类型文档编制

enum QBluetoothSocket:: SocketError

此枚举描述 Bluetooth 套接字错误类型。

常量 描述
QBluetoothSocket::UnknownSocketError QAbstractSocket::UnknownSocketError 出现未知错误。
QBluetoothSocket::NoSocketError -2 没有错误。用于测试。
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 试图操作当套接字处于不准许状态时。
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.

常量 描述
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.

成员函数文档编制

QBluetoothSocket:: QBluetoothSocket ( QObject * parent = nullptr)

Constructs a Bluetooth socket with parent .

QBluetoothSocket:: QBluetoothSocket ( QBluetoothServiceInfo::Protocol socketType , QObject * parent = nullptr)

Constructs a Bluetooth socket of socketType type, with parent .

[signal] void QBluetoothSocket:: connected ()

This signal is emitted when a connection is established.

另请参阅 QBluetoothSocket::ConnectedState and stateChanged ().

[signal] void QBluetoothSocket:: disconnected ()

This signal is emitted when the socket is disconnected.

另请参阅 QBluetoothSocket::UnconnectedState and stateChanged ().

[signal] void QBluetoothSocket:: error ( QBluetoothSocket::SocketError error )

此信号发射当 error 出现。

注意: 信号 error 在此类中被重载。通过使用函数指针句法连接到此信号,Qt 提供用于获得如此范例展示的函数指针的方便帮助程序:

connect(bluetoothSocket, QOverload<QBluetoothSocket::SocketError>::of(&QBluetoothSocket::error),
    [=](QBluetoothSocket::SocketError error){ /* ... */ });
					

另请参阅 error ().

[signal] void QBluetoothSocket:: stateChanged ( QBluetoothSocket::SocketState state )

This signal is emitted when the socket state changes to state .

另请参阅 connected (), disconnected (), state (),和 QBluetoothSocket::SocketState .

[虚拟] QBluetoothSocket:: ~QBluetoothSocket ()

Destroys the Bluetooth socket.

void QBluetoothSocket:: abort ()

中止当前连接并重置套接字。不像 disconnectFromService (),此函数立即关闭套接字,丢弃写缓冲中任何待决数据。

注意: On Android, aborting the socket requires asynchronous interaction with Android threads. Therefore the associated disconnected () 和 stateChanged () signals are delayed until the threads have finished the closure.

另请参阅 disconnectFromService () 和 close ().

[override virtual] qint64 QBluetoothSocket:: bytesAvailable () const

重实现: QIODevice::bytesAvailable () const.

返回等待读取的传入字节数。

另请参阅 bytesToWrite () 和 read ().

[override virtual] qint64 QBluetoothSocket:: bytesToWrite () const

重实现: QIODevice::bytesToWrite () const.

Returns the number of bytes that are waiting to be written. The bytes are written when control goes back to the event loop.

[override virtual] bool QBluetoothSocket:: canReadLine () const

重实现: QIODevice::canReadLine () const.

Returns true if you can read at least one line from the device

[override virtual] void QBluetoothSocket:: close ()

重实现: QIODevice::close ().

Disconnects the socket's connection with the device.

注意: On Android, closing the socket requires asynchronous interaction with Android threads. Therefore the associated disconnected () 和 stateChanged () signals are delayed until the threads have finished the closure.

void QBluetoothSocket:: connectToService (const QBluetoothServiceInfo & service , QIODevice::OpenMode openMode = ReadWrite)

Attempts to connect to the service described by service .

套接字被打开采用给定 openMode socketType () is ignored if service specifies a differing QBluetoothServiceInfo::socketProtocol ().

The socket first enters ConnectingState and attempts to connect to the device providing service 。若建立连接, QBluetoothSocket 进入 ConnectedState 并发射 connected ().

在任何时候,套接字可以发射 error () 给 (发出错误的) 信号。

Note that most platforms require a pairing prior to connecting to the remote device. Otherwise the connection process may fail.

On Android, only RFCOMM connections are possible. This function ignores any socket protocol indicator and assumes RFCOMM.

另请参阅 state () 和 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 .

套接字被打开采用给定 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 。若建立连接, QBluetoothSocket 进入 ConnectedState 并发射 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 .

在任何时候,套接字可以发射 error () 给 (发出错误的) 信号。

Note that most platforms require a pairing prior to connecting to the remote device. Otherwise the connection process may fail.

另请参阅 state () 和 disconnectFromService ().

void QBluetoothSocket:: connectToService (const QBluetoothAddress & address , quint16 port , QIODevice::OpenMode openMode = ReadWrite)

Attempts to make a connection with address 在给定 port .

套接字被打开采用给定 openMode .

The socket first enters ConnectingState , and attempts to connect to address 。若建立连接, QBluetoothSocket 进入 ConnectedState 并发射 connected ().

在任何时候,套接字可以发射 error () 给 (发出错误的) 信号。

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.

另请参阅 state () 和 disconnectFromService ().

void QBluetoothSocket:: disconnectFromService ()

Attempts to close the socket. If there is pending data waiting to be written QBluetoothSocket 将进入 ClosingState 并等待直到所有数据被写入。最终,它将进入 UnconnectedState 和发射 disconnected () 信号。

另请参阅 connectToService ().

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

QString QBluetoothSocket:: errorString () const

Returns a user displayable text string for the error.

[override virtual] bool QBluetoothSocket:: isSequential () const

重实现: QIODevice::isSequential () const.

QBluetoothAddress QBluetoothSocket:: localAddress () const

Returns the address of the local device.

Although some platforms may differ the socket must generally be connected to guarantee the return of a valid address. In particular, this is true when dealing with platforms that support multiple local Bluetooth adapters.

QString QBluetoothSocket:: localName () const

Returns the name of the local device.

Although some platforms may differ the socket must generally be connected to guarantee the return of a valid name. In particular, this is true when dealing with platforms that support multiple local Bluetooth adapters.

quint16 QBluetoothSocket:: localPort () const

Returns the port number of the local socket if available, otherwise returns 0. Although some platforms may differ the socket must generally be connected to guarantee the return of a valid port number.

On Android and macOS, this feature is not supported and returns 0.

QBluetoothAddress QBluetoothSocket:: peerAddress () const

Returns the address of the peer device.

QString QBluetoothSocket:: peerName () const

Returns the name of the peer device.

quint16 QBluetoothSocket:: peerPort () const

Return the port number of the peer socket if available, otherwise returns 0. On Android, this feature is not supported.

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 .

该函数在 Qt 5.6 引入。

另请参阅 setPreferredSecurityFlags ().

[override virtual protected] qint64 QBluetoothSocket:: readData ( char * data , qint64 maxSize )

重实现: QIODevice::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 在默认情况下。

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 在默认情况下。

注意: 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.

该函数在 Qt 5.6 引入。

另请参阅 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 .

The set socket descriptor is considered owned by the QBluetoothSocket and may be e.g. closed once finished.

返回 true 当成功时

另请参阅 socketDescriptor ().

[protected] void QBluetoothSocket:: setSocketError ( QBluetoothSocket::SocketError error_ )

将最后出现的错误类型设为 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.

另请参阅 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

返回套接字的当前状态。

[override virtual protected] qint64 QBluetoothSocket:: writeData (const char * data , qint64 maxSize )

重实现: QIODevice::writeData (const char *data, qint64 maxSize).