QBluetoothSocket#
The QBluetoothSocket
class enables connection to a Bluetooth device running a bluetooth server. More…
Synopsis#
Functions#
def
abort
()def
connectToService
(address, uuid[, mode=QIODeviceBase.OpenModeFlag.ReadWrite])def
connectToService
(address, uuid[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite])def
connectToService
(address, port[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite])def
connectToService
(service[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite])def
disconnectFromService
()def
doDeviceDiscovery
(service, openMode)def
error
()def
localAddress
()def
localName
()def
localPort
()def
peerAddress
()def
peerName
()def
peerPort
()def
preferredSecurityFlags
()def
setPreferredSecurityFlags
(flags)def
setSocketDescriptor
(socketDescriptor, socketType[, socketState=QBluetoothSocket.SocketState.ConnectedState[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite]])def
setSocketError
(error)def
setSocketState
(state)def
socketDescriptor
()def
socketType
()def
state
()
Signals#
def
connected
()def
disconnected
()def
errorOccurred
(error)def
stateChanged
(state)
Note
This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE
Detailed Description#
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.
Note
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.
- class PySide6.QtBluetooth.QBluetoothSocket(socketType[, parent=None])#
PySide6.QtBluetooth.QBluetoothSocket([parent=None])
- Parameters:
socketType –
Protocol
parent –
PySide6.QtCore.QObject
Constructs a Bluetooth socket of socketType
type, with parent
.
Constructs a Bluetooth socket with parent
.
- PySide6.QtBluetooth.QBluetoothSocket.SocketState#
This enum describes the state of the Bluetooth socket.
Constant
Description
QBluetoothSocket.SocketState.UnconnectedState
Socket is not connected.
QBluetoothSocket.SocketState.ServiceLookupState
Socket is querying connection parameters.
QBluetoothSocket.SocketState.ConnectingState
Socket is attempting to connect to a device.
QBluetoothSocket.SocketState.ConnectedState
Socket is connected to a device.
QBluetoothSocket.SocketState.BoundState
Socket is bound to a local address and port.
QBluetoothSocket.SocketState.ClosingState
Socket is connected and will be closed once all pending data is written to the socket.
QBluetoothSocket.SocketState.ListeningState
Socket is listening for incoming connections.
- PySide6.QtBluetooth.QBluetoothSocket.SocketError#
This enum describes Bluetooth socket error types.
Constant
Description
QBluetoothSocket.SocketError.UnknownSocketError
An unknown error has occurred.
QBluetoothSocket.SocketError.NoSocketError
No error. Used for testing.
QBluetoothSocket.SocketError.HostNotFoundError
Could not find the remote host.
QBluetoothSocket.SocketError.ServiceNotFoundError
Could not find the service UUID on remote host.
QBluetoothSocket.SocketError.NetworkError
Attempt to read or write from socket returned an error
QBluetoothSocket.SocketError.UnsupportedProtocolError
The
Protocol
is not supported on this platform.QBluetoothSocket.SocketError.OperationError
An operation was attempted while the socket was in a state that did not permit it.
QBluetoothSocket.SocketError.RemoteHostClosedError
The remote host closed the connection.
QBluetoothSocket.SocketError.MissingPermissionsError
The operating system requests permissions which were not granted by the user.
- PySide6.QtBluetooth.QBluetoothSocket.abort()#
Aborts the current connection and resets the socket. Unlike disconnectFromService()
, this function immediately closes the socket, discarding any pending data in the write buffer.
Note
On Android, aborting the socket requires asynchronous interaction with Android threads. Therefore the associated disconnected()
and stateChanged()
signals are delayed until the threads have finished the closure.
See also
disconnectFromService()
close()
- PySide6.QtBluetooth.QBluetoothSocket.connectToService(address, uuid[, mode=QIODeviceBase.OpenModeFlag.ReadWrite])#
- Parameters:
address –
PySide6.QtBluetooth.QBluetoothAddress
uuid –
ServiceClassUuid
mode – Combination of
QIODeviceBase.OpenModeFlag
- PySide6.QtBluetooth.QBluetoothSocket.connectToService(address, uuid[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite])
- Parameters:
address –
PySide6.QtBluetooth.QBluetoothAddress
openMode – Combination of
QIODeviceBase.OpenModeFlag
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 RfcommProtocol
.
At any point, the socket can emit errorOccurred()
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
- PySide6.QtBluetooth.QBluetoothSocket.connectToService(address, port[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite])
- Parameters:
address –
PySide6.QtBluetooth.QBluetoothAddress
port – int
openMode – Combination of
QIODeviceBase.OpenModeFlag
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 errorOccurred()
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
- PySide6.QtBluetooth.QBluetoothSocket.connectToService(service[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite])
- Parameters:
openMode – Combination of
QIODeviceBase.OpenModeFlag
Attempts to connect to the service described by service
.
The socket is opened in the given openMode
. The socketType()
is ignored if service
specifies a differing socketProtocol()
.
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 errorOccurred()
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.
On Android, only RFCOMM connections are possible. This function ignores any socket protocol indicator and assumes RFCOMM.
See also
- PySide6.QtBluetooth.QBluetoothSocket.connected()#
This signal is emitted when a connection is established.
See also
ConnectedState
stateChanged()
- PySide6.QtBluetooth.QBluetoothSocket.disconnectFromService()#
Attempts to close the socket. If there is pending data waiting to be written QBluetoothSocket
will enter ClosingState
and wait until all data has been written. Eventually, it will enter UnconnectedState
and emit the disconnected()
signal.
See also
- PySide6.QtBluetooth.QBluetoothSocket.disconnected()#
This signal is emitted when the socket is disconnected.
See also
UnconnectedState
stateChanged()
- PySide6.QtBluetooth.QBluetoothSocket.doDeviceDiscovery(service, openMode)#
- Parameters:
openMode – Combination of
QIODeviceBase.OpenModeFlag
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.
- PySide6.QtBluetooth.QBluetoothSocket.error()#
- Return type:
Returns the last error.
- PySide6.QtBluetooth.QBluetoothSocket.errorOccurred(error)#
- Parameters:
error –
SocketError
This signal is emitted when an error
occurs.
See also
- PySide6.QtBluetooth.QBluetoothSocket.localAddress()#
- Return type:
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.
- PySide6.QtBluetooth.QBluetoothSocket.localName()#
- Return type:
str
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.
- PySide6.QtBluetooth.QBluetoothSocket.localPort()#
- Return type:
int
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.
- PySide6.QtBluetooth.QBluetoothSocket.peerAddress()#
- Return type:
Returns the address of the peer device.
- PySide6.QtBluetooth.QBluetoothSocket.peerName()#
- Return type:
str
Returns the name of the peer device.
- PySide6.QtBluetooth.QBluetoothSocket.peerPort()#
- Return type:
int
Return the port number of the peer socket if available, otherwise returns 0. On Android, this feature is not supported.
- PySide6.QtBluetooth.QBluetoothSocket.preferredSecurityFlags()#
- Return type:
Combination of
QBluetooth.Security
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 Secure
.
See also
- PySide6.QtBluetooth.QBluetoothSocket.setPreferredSecurityFlags(flags)#
- Parameters:
flags – Combination of
QBluetooth.Security
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 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 Secure
.
Android only supports two levels of security (secure and non-secure). If this flag is set to 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 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.
See also
- PySide6.QtBluetooth.QBluetoothSocket.setSocketDescriptor(socketDescriptor, socketType[, socketState=QBluetoothSocket.SocketState.ConnectedState[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite]])#
- Parameters:
socketDescriptor – int
socketType –
Protocol
socketState –
SocketState
openMode – Combination of
QIODeviceBase.OpenModeFlag
- Return type:
bool
Sets the socket to use socketDescriptor
with a type of socketType
, which is in state socketState
, and mode openMode
.
The socket descriptor is owned by the QBluetoothSocket
instance and may be closed once finished.
Returns true
on success.
See also
- PySide6.QtBluetooth.QBluetoothSocket.setSocketError(error)#
- Parameters:
error –
SocketError
Sets the type of error that last occurred to error_
.
- PySide6.QtBluetooth.QBluetoothSocket.setSocketState(state)#
- Parameters:
state –
SocketState
Sets the socket state to state
.
- PySide6.QtBluetooth.QBluetoothSocket.socketDescriptor()#
- Return type:
int
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
Returns the socket type. The socket automatically adjusts to the protocol offered by the remote service.
Android only support RFCOMM
based sockets.
- PySide6.QtBluetooth.QBluetoothSocket.state()#
- Return type:
Returns the current state of the socket.
- PySide6.QtBluetooth.QBluetoothSocket.stateChanged(state)#
- Parameters:
state –
SocketState
This signal is emitted when the socket state changes to state
.
See also
connected()
disconnected()
state()
SocketState