En esta página

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.

ConstanteValorDescripción
QBluetoothSocket::SocketError::UnknownSocketError1Se ha producido un error desconocido.
QBluetoothSocket::SocketError::NoSocketError0No hay error. Se utiliza para realizar pruebas.
QBluetoothSocket::SocketError::HostNotFoundError3No se ha podido encontrar el host remoto.
QBluetoothSocket::SocketError::ServiceNotFoundError4No se ha podido encontrar el UUID del servicio en el host remoto.
QBluetoothSocket::SocketError::NetworkError5El intento de leer o escribir desde el socket ha devuelto un error
QBluetoothSocket::SocketError::UnsupportedProtocolError6El « Protocol » no es compatible con esta plataforma.
QBluetoothSocket::SocketError::OperationError7Se 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)2El host remoto ha cerrado la conexión.
QBluetoothSocket::SocketError::MissingPermissionsError (since Qt 6.4)8El sistema operativo solicita permisos que el usuario no ha concedido.

enum class QBluetoothSocket::SocketState

Esta enumeración describe el estado del socket Bluetooth.

ConstanteValorDescripción
QBluetoothSocket::SocketState::UnconnectedState0El socket no está conectado.
QBluetoothSocket::SocketState::ServiceLookupState1El socket está consultando los parámetros de conexión.
QBluetoothSocket::SocketState::ConnectingState2El socket está intentando conectarse a un dispositivo.
QBluetoothSocket::SocketState::ConnectedState3El socket está conectado a un dispositivo.
QBluetoothSocket::SocketState::BoundState4El socket está vinculado a una dirección y un puerto locales.
QBluetoothSocket::SocketState::ClosingState5El socket está conectado y se cerrará una vez que se hayan escrito todos los datos pendientes en el socket.
QBluetoothSocket::SocketState::ListeningState6El 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:

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.