QBluetoothSocket Class
La clase QBluetoothSocket permite conectarse a un dispositivo Bluetooth en el que se esté ejecutando un servidor Bluetooth. Más información...
| Encabezado: | #include <QBluetoothSocket> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Bluetooth) target_link_libraries(mytarget PRIVATE Qt6::Bluetooth) |
| qmake: | QT += bluetooth |
| Heredado de: | QIODevice |
Tipos públicos
| enum class | SocketError { UnknownSocketError, NoSocketError, HostNotFoundError, ServiceNotFoundError, NetworkError, …, MissingPermissionsError } |
| enum class | SocketState { UnconnectedState, ServiceLookupState, ConnectingState, ConnectedState, BoundState, …, ListeningState } |
Funciones públicas
| QBluetoothSocket(QObject *parent = nullptr) | |
| QBluetoothSocket(QBluetoothServiceInfo::Protocol socketType, QObject *parent = nullptr) | |
| virtual | ~QBluetoothSocket() |
| void | abort() |
| void | connectToService(const QBluetoothServiceInfo &service, QIODeviceBase::OpenMode openMode = ReadWrite) |
| void | connectToService(const QBluetoothAddress &address, const QBluetoothUuid &uuid, QIODeviceBase::OpenMode openMode = ReadWrite) |
| void | connectToService(const QBluetoothAddress &address, quint16 port, QIODeviceBase::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 = SocketState::ConnectedState, QIODeviceBase::OpenMode openMode = ReadWrite) |
| int | socketDescriptor() const |
| QBluetoothServiceInfo::Protocol | socketType() const |
| QBluetoothSocket::SocketState | state() const |
Funciones públicas reimplementadas
| virtual qint64 | bytesAvailable() const override |
| virtual qint64 | bytesToWrite() const override |
| virtual bool | canReadLine() const override |
| virtual void | close() override |
| virtual bool | isSequential() const override |
Señales
| void | connected() |
| void | disconnected() |
(since 6.2) void | errorOccurred(QBluetoothSocket::SocketError error) |
| void | stateChanged(QBluetoothSocket::SocketState state) |
Funciones protegidas
| void | doDeviceDiscovery(const QBluetoothServiceInfo &service, QIODeviceBase::OpenMode openMode) |
| void | setSocketError(QBluetoothSocket::SocketError error_) |
| void | setSocketState(QBluetoothSocket::SocketState state) |
Funciones protegidas reimplementadas
| virtual qint64 | readData(char *data, qint64 maxSize) override |
| virtual qint64 | writeData(const char *data, qint64 maxSize) override |
Descripción detallada
QBluetoothSocket admite dos tipos de sockets: L2CAP y RFCOMM.
L2CAP es un socket Bluetooth de bajo nivel orientado a datagramas. Android no admite L2CAP para conexiones de socket.
RFCOMM es un socket fiable, orientado a flujos. Los sockets RFCOMM emulan un puerto serie RS-232.
Para establecer una conexión con un servicio Bluetooth, crea un socket del tipo adecuado y llama a ` connectToService()` pasando la dirección Bluetooth y el número de puerto. QBluetoothSocket emitirá la señal ` connected()` cuando se establezca la conexión.
Si la función ` Protocol ` no es compatible con una plataforma, al llamar a ` connectToService()` se generará un error de tipo ` UnsupportedProtocolError `.
Nota: QBluetoothSocket no admite operaciones síncronas de lectura y escritura. Funciones como waitForReadyRead() y waitForBytesWritten() no están implementadas. Las operaciones de E/S deben realizarse utilizando readyRead(), read() y write().
En iOS, esta clase no se puede utilizar porque la plataforma no expone una API que permita el acceso a las funciones relacionadas con QBluetoothSocket.
Nota: En macOS Monterey (12), el flujo de datos del socket se detiene cuando se ejecuta un cuadro de diálogo modal o se entra en un modo de seguimiento de eventos (por ejemplo, al mantener pulsado el botón de cierre de una ventana). Este problema se ha solucionado en macOS Sequoia (15).
Documentación sobre los tipos de miembros
enum class QBluetoothSocket::SocketError
Esta enumeración describe los tipos de error de los sockets Bluetooth.
| Constante | Valor | Descripción |
|---|---|---|
QBluetoothSocket::SocketError::UnknownSocketError | 1 | Se ha producido un error desconocido. |
QBluetoothSocket::SocketError::NoSocketError | 0 | No hay error. Se utiliza para realizar pruebas. |
QBluetoothSocket::SocketError::HostNotFoundError | 3 | No se ha podido encontrar el host remoto. |
QBluetoothSocket::SocketError::ServiceNotFoundError | 4 | No se ha podido encontrar el UUID del servicio en el host remoto. |
QBluetoothSocket::SocketError::NetworkError | 5 | El intento de leer o escribir desde el socket ha devuelto un error |
QBluetoothSocket::SocketError::UnsupportedProtocolError | 6 | El « Protocol » no es compatible con esta plataforma. |
QBluetoothSocket::SocketError::OperationError | 7 | Se intentó realizar una operación mientras el socket se encontraba en un estado que no lo permitía. |
QBluetoothSocket::SocketError::RemoteHostClosedError (since Qt 5.10) | 2 | El host remoto ha cerrado la conexión. |
QBluetoothSocket::SocketError::MissingPermissionsError (since Qt 6.4) | 8 | El sistema operativo solicita permisos que el usuario no ha concedido. |
enum class QBluetoothSocket::SocketState
Esta enumeración describe el estado del socket Bluetooth.
| Constante | Valor | Descripción |
|---|---|---|
QBluetoothSocket::SocketState::UnconnectedState | 0 | El socket no está conectado. |
QBluetoothSocket::SocketState::ServiceLookupState | 1 | El socket está consultando los parámetros de conexión. |
QBluetoothSocket::SocketState::ConnectingState | 2 | El socket está intentando conectarse a un dispositivo. |
QBluetoothSocket::SocketState::ConnectedState | 3 | El socket está conectado a un dispositivo. |
QBluetoothSocket::SocketState::BoundState | 4 | El socket está vinculado a una dirección y un puerto locales. |
QBluetoothSocket::SocketState::ClosingState | 5 | El socket está conectado y se cerrará una vez que se hayan escrito todos los datos pendientes en el socket. |
QBluetoothSocket::SocketState::ListeningState | 6 | El socket está a la escucha de conexiones entrantes. |
Documentación de funciones miembro
[explicit] QBluetoothSocket::QBluetoothSocket(QObject *parent = nullptr)
Crea un socket Bluetooth con ` parent`.
[explicit] QBluetoothSocket::QBluetoothSocket(QBluetoothServiceInfo::Protocol socketType, QObject *parent = nullptr)
Crea un socket Bluetooth de tipo « socketType », con « parent ».
[virtual noexcept] QBluetoothSocket::~QBluetoothSocket()
Destruye el conector Bluetooth.
void QBluetoothSocket::abort()
Cancela la conexión actual y restablece el socket. A diferencia de ` disconnectFromService()`, esta función cierra inmediatamente el socket, descartando cualquier dato pendiente en el búfer de escritura.
Nota: En Android, la interrupción del socket requiere una interacción asíncrona con los hilos de Android. Por lo tanto, las señales asociadas disconnected() y stateChanged() se retrasan hasta que los hilos hayan finalizado el cierre.
Véase también disconnectFromService() y close().
[override virtual] qint64 QBluetoothSocket::bytesAvailable() const
Reimplementa: ` QIODevice::bytesAvailable()` const.
Devuelve el número de bytes entrantes que están a la espera de ser leídos.
Véase también bytesToWrite() y read().
[override virtual] qint64 QBluetoothSocket::bytesToWrite() const
Reimplementa: ` QIODevice::bytesToWrite()` const.
Devuelve el número de bytes que están a la espera de ser escritos. Los bytes se escriben cuando el control vuelve al bucle de eventos.
[override virtual] bool QBluetoothSocket::canReadLine() const
Reimplementa: ` QIODevice::canReadLine()` const.
Devuelve «true» si se puede leer al menos una línea del dispositivo.
[override virtual] void QBluetoothSocket::close()
Reimplementa: QIODevice::close().
Desconecta la conexión del socket con el dispositivo.
Nota: En Android, el cierre del socket requiere una interacción asíncrona con los subprocesos de Android. Por lo tanto, las señales asociadas disconnected() y stateChanged() se retrasan hasta que los subprocesos hayan finalizado el cierre.
void QBluetoothSocket::connectToService(const QBluetoothServiceInfo &service, QIODeviceBase::OpenMode openMode = ReadWrite)
Intenta conectarse al servicio descrito en service.
El socket se abre en la dirección indicada openMode. La función socketType() se ignora si service especifica un QBluetoothServiceInfo::socketProtocol() diferente.
El socket entra primero en ConnectingState e intenta conectarse al dispositivo que proporciona service. Si se establece una conexión, QBluetoothSocket entra en ConnectedState y emite connected().
En cualquier momento, el socket puede emitir errorOccurred() para indicar que se ha producido un error.
Ten en cuenta que la mayoría de las plataformas requieren un emparejamiento antes de conectarse al dispositivo remoto. De lo contrario, el proceso de conexión podría fallar.
En Android, solo son posibles las conexiones RFCOMM. Esta función ignora cualquier indicador de protocolo del socket y asume que se trata de RFCOMM.
Véanse también state() y disconnectFromService().
void QBluetoothSocket::connectToService(const QBluetoothAddress &address, const QBluetoothUuid &uuid, QIODeviceBase::OpenMode openMode = ReadWrite)
Intenta establecer una conexión con el servicio identificado por uuid en el dispositivo con la dirección address.
Se abre el socket en la dirección openMode indicada.
En el caso de BlueZ, el socket accede primero a ServiceLookupState y consulta los parámetros de conexión para uuid. Si se recuperan correctamente los parámetros del servicio, el socket accede a ConnectingState e intenta conectarse a address. Si se establece la conexión, QBluetoothSocket accede a ConnectedState y emite connected().
En Android, la conexión al servicio se puede establecer directamente utilizando el UUID del servicio remoto. Por lo tanto, la plataforma no requiere el ServiceLookupState y socketType() siempre se establece en QBluetoothServiceInfo::RfcommProtocol.
En cualquier momento, el socket puede emitir errorOccurred() para indicar que se ha producido un error.
Ten en cuenta que la mayoría de las plataformas requieren un emparejamiento antes de conectarse al dispositivo remoto. De lo contrario, el proceso de conexión podría fallar.
Véanse también state() y disconnectFromService().
void QBluetoothSocket::connectToService(const QBluetoothAddress &address, quint16 port, QIODeviceBase::OpenMode openMode = ReadWrite)
Se intenta establecer una conexión con address en el puerto port indicado.
Se abre el socket en la dirección indicada openMode.
El socket entra primero en ConnectingState e intenta conectarse a address. Si se establece una conexión, QBluetoothSocket entra en ConnectedState y emite connected().
En cualquier momento, el socket puede emitir errorOccurred() para indicar que se ha producido un error.
En Android y BlueZ (versión 5.46 o superior), no se puede establecer una conexión con un servicio utilizando un puerto. Al llamar a esta función se emitirá un ServiceNotFoundError.
Ten en cuenta que la mayoría de las plataformas requieren un emparejamiento antes de conectarse al dispositivo remoto. De lo contrario, el proceso de conexión podría fallar.
Véanse también state() y disconnectFromService().
[signal] void QBluetoothSocket::connected()
Esta señal se emite cuando se establece una conexión.
Véase también QBluetoothSocket::SocketState::ConnectedState y stateChanged().
void QBluetoothSocket::disconnectFromService()
Intenta cerrar el socket. Si hay datos pendientes de escribir, ` QBluetoothSocket ` entrará en ` ClosingState ` y esperará hasta que se hayan escrito todos los datos. Finalmente, entrará en ` UnconnectedState ` y emitirá la señal ` disconnected()`.
Véase también connectToService().
[signal] void QBluetoothSocket::disconnected()
Esta señal se emite cuando se desconecta el conector.
Véase también QBluetoothSocket::SocketState::UnconnectedState y stateChanged().
[protected] void QBluetoothSocket::doDeviceDiscovery(const QBluetoothServiceInfo &service, QIODeviceBase::OpenMode openMode)
Inicia la detección de dispositivos en service y abre el socket con openMode. Si el socket se crea con una dirección de dispositivo UUID de servicio, utiliza la detección de servicios para encontrar el número de puerto al que conectarte.
QBluetoothSocket::SocketError QBluetoothSocket::error() const
Devuelve el último error.
[signal, since 6.2] void QBluetoothSocket::errorOccurred(QBluetoothSocket::SocketError error)
Esta señal se emite cuando se produce un error de « error ».
Esta función se introdujo en Qt 6.2.
Véase también error().
QString QBluetoothSocket::errorString() const
Devuelve una cadena de texto que el usuario puede visualizar correspondiente al error.
[override virtual] bool QBluetoothSocket::isSequential() const
Reimplementa: QIODevice::isSequential() const.
QBluetoothAddress QBluetoothSocket::localAddress() const
Devuelve la dirección del dispositivo local.
Aunque puede haber diferencias entre algunas plataformas, por lo general es necesario que el socket esté conectado para garantizar que se devuelva una dirección válida. Esto es especialmente cierto en el caso de plataformas que admiten varios adaptadores Bluetooth locales.
QString QBluetoothSocket::localName() const
Devuelve el nombre del dispositivo local.
Aunque puede haber diferencias entre algunas plataformas, por lo general es necesario que el socket esté conectado para garantizar que se devuelva un nombre válido. Esto es especialmente cierto en el caso de plataformas que admiten varios adaptadores Bluetooth locales.
quint16 QBluetoothSocket::localPort() const
Devuelve el número de puerto del socket local si está disponible; en caso contrario, devuelve 0. Aunque puede variar en función de la plataforma, por lo general el socket debe estar conectado para garantizar que se devuelva un número de puerto válido.
En Android y macOS, esta función no está disponible y devuelve 0.
QBluetoothAddress QBluetoothSocket::peerAddress() const
Devuelve la dirección del dispositivo homólogo.
QString QBluetoothSocket::peerName() const
Devuelve el nombre del dispositivo homólogo.
quint16 QBluetoothSocket::peerPort() const
Devuelve el número de puerto del socket del interlocutor, si está disponible; de lo contrario, devuelve 0. En Android, esta función no es compatible.
QBluetooth::SecurityFlags QBluetoothSocket::preferredSecurityFlags() const
Devuelve los parámetros de seguridad utilizados para el intento inicial de conexión.
Los parámetros de seguridad pueden renegociarse entre ambas partes durante o después de que se haya establecido la conexión. Si se produce dicho cambio, este no se refleja en el valor de este indicador.
En macOS, este indicador siempre está establecido en « QBluetooth::Security::Secure ».
Véase también ` setPreferredSecurityFlags()`.
[override virtual protected] qint64 QBluetoothSocket::readData(char *data, qint64 maxSize)
Reimplementa: QIODevice::readData(char *data, qint64 maxSize).
void QBluetoothSocket::setPreferredSecurityFlags(QBluetooth::SecurityFlags flags)
Establece el parámetro de seguridad preferido para el intento de conexión a flags. Este valor se aplica al llamar a la función connectToService(). Por lo tanto, es necesario volver a conectarse para cambiar este parámetro en una conexión ya existente.
En el backend BlueZ de Linux, los indicadores se asignan a los niveles de seguridad del kernel:
- QBluetooth::Security::Authorization se asigna a
BT_SECURITY_LOW; - QBluetooth::Security::Encryption se asigna a
BT_SECURITY_MEDIUM; - QBluetooth::Security::Secure se asigna a «
BT_SECURITY_HIGH»; - QBluetooth::Security::Authentication no es utilizado por el núcleo y se ignora.
El valor por defecto es « QBluetooth::Security::Authorization ».
En Linux con el backend D-Bus de BlueZ y en Windows, este indicador no es compatible y se ignora.
En macOS, este valor se ignora, ya que la plataforma no permite el acceso al parámetro de seguridad del socket. Sin embargo, por defecto, la plataforma da prioridad a las conexiones seguras/cifradas y, por lo tanto, esta función siempre devuelve « QBluetooth::Security::Secure ».
Android solo admite dos niveles de seguridad (seguro y no seguro). Si este indicador se establece en « QBluetooth::Security::NoSecurity », el objeto socket no empleará ninguna autenticación ni cifrado. Cualquier otra combinación de indicadores de seguridad activará una conexión Bluetooth segura. Este indicador está establecido en « QBluetooth::Security::Secure » de forma predeterminada.
Nota: Una conexión segura requiere un emparejamiento entre los dos dispositivos. En algunas plataformas, el emparejamiento se inicia automáticamente durante el establecimiento de la conexión. Otras plataformas requieren que la aplicación inicie manualmente el emparejamiento antes de intentar conectarse.
Véase también preferredSecurityFlags().
bool QBluetoothSocket::setSocketDescriptor(int socketDescriptor, QBluetoothServiceInfo::Protocol socketType, QBluetoothSocket::SocketState socketState = SocketState::ConnectedState, QIODeviceBase::OpenMode openMode = ReadWrite)
Configura el socket para que utilice socketDescriptor con un tipo de socketType, que se encuentra en el estado socketState y en el modo openMode.
El descriptor de socket es propiedad de la instancia de ` QBluetoothSocket ` y puede cerrarse una vez finalizada la operación.
Devuelve true si la operación se realiza correctamente.
Véase también socketDescriptor().
[protected] void QBluetoothSocket::setSocketError(QBluetoothSocket::SocketError error_)
Establece el tipo del último error que se ha producido en ` error_`.
[protected] void QBluetoothSocket::setSocketState(QBluetoothSocket::SocketState state)
Establece el estado del socket en « state ».
int QBluetoothSocket::socketDescriptor() const
Devuelve el descriptor de socket específico de la plataforma, si está disponible. Esta función devuelve -1 si el descriptor no está disponible o si se ha producido un error.
Véase también ` setSocketDescriptor()`.
QBluetoothServiceInfo::Protocol QBluetoothSocket::socketType() const
Devuelve el tipo de socket. El socket se adapta automáticamente al protocolo que ofrece el servicio remoto.
Android solo admite sockets basados en RFCOMM.
QBluetoothSocket::SocketState QBluetoothSocket::state() const
Devuelve el estado actual del socket.
[signal] void QBluetoothSocket::stateChanged(QBluetoothSocket::SocketState state)
Esta señal se emite cuando el estado del socket cambia a « state ».
Véase también connected(), disconnected(), state() y QBluetoothSocket::SocketState.
[override virtual protected] qint64 QBluetoothSocket::writeData(const char *data, qint64 maxSize)
Reimplementa: ` QIODevice::writeData` (`const char *data`, `qint64 maxSize`).
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.