En esta página

QDBusConnection Class

La clase QDBusConnection representa una conexión con el demonio del bus D-Bus. Más información...

Encabezado: #include <QDBusConnection>
CMake: find_package(Qt6 REQUIRED COMPONENTS DBus)
target_link_libraries(mytarget PRIVATE Qt6::DBus)
qmake: QT += dbus

Tipos públicos

enum BusType { SessionBus, SystemBus, ActivationBus }
flags ConnectionCapabilities
enum ConnectionCapability { UnixFileDescriptorPassing }
enum RegisterOption { ExportAdaptors, ExportScriptableSlots, ExportScriptableSignals, ExportScriptableProperties, ExportScriptableInvokables, …, ExportChildObjects }
flags RegisterOptions
enum UnregisterMode { UnregisterNode, UnregisterTree }

Funciones públicas

QDBusConnection(const QString &name)
QDBusConnection(const QDBusConnection &other)
~QDBusConnection()
QDBusPendingCall asyncCall(const QDBusMessage &message, int timeout = -1) const
QString baseService() const
QDBusMessage call(const QDBusMessage &message, QDBus::CallMode mode = QDBus::Block, int timeout = -1) const
bool callWithCallback(const QDBusMessage &message, QObject *receiver, const char *returnMethod, const char *errorMethod, int timeout = -1) const
bool connect(const QString &service, const QString &path, const QString &interface, const QString &name, QObject *receiver, const char *slot)
bool connect(const QString &service, const QString &path, const QString &interface, const QString &name, const QString &signature, QObject *receiver, const char *slot)
bool connect(const QString &service, const QString &path, const QString &interface, const QString &name, const QStringList &argumentMatch, const QString &signature, QObject *receiver, const char *slot)
QDBusConnection::ConnectionCapabilities connectionCapabilities() const
bool disconnect(const QString &service, const QString &path, const QString &interface, const QString &name, QObject *receiver, const char *slot)
bool disconnect(const QString &service, const QString &path, const QString &interface, const QString &name, const QString &signature, QObject *receiver, const char *slot)
bool disconnect(const QString &service, const QString &path, const QString &interface, const QString &name, const QStringList &argumentMatch, const QString &signature, QObject *receiver, const char *slot)
QDBusConnectionInterface *interface() const
bool isConnected() const
QDBusError lastError() const
QString name() const
QObject *objectRegisteredAt(const QString &path) const
bool registerObject(const QString &path, QObject *object, QDBusConnection::RegisterOptions options = ExportAdaptors)
bool registerObject(const QString &path, const QString &interface, QObject *object, QDBusConnection::RegisterOptions options = ExportAdaptors)
bool registerService(const QString &serviceName)
bool send(const QDBusMessage &message) const
void swap(QDBusConnection &other)
void unregisterObject(const QString &path, QDBusConnection::UnregisterMode mode = UnregisterNode)
bool unregisterService(const QString &serviceName)
QDBusConnection &operator=(const QDBusConnection &other)

Miembros públicos estáticos

QDBusConnection connectToBus(QDBusConnection::BusType type, const QString &name)
QDBusConnection connectToBus(const QString &address, const QString &name)
QDBusConnection connectToPeer(const QString &address, const QString &name)
void disconnectFromBus(const QString &name)
void disconnectFromPeer(const QString &name)
QByteArray localMachineId()
QDBusConnection sessionBus()
QDBusConnection systemBus()

Descripción detallada

Esta clase es el punto de partida de una sesión de D-Bus. Mediante ella, puedes acceder a objetos e interfaces remotos; conectar señales remotas a las ranuras de tu objeto; registrar objetos, etc.

Las conexiones D-Bus se crean mediante la función ` connectToBus()`, que abre una conexión con el demonio del servidor y realiza el establecimiento de conexión inicial, asociando dicha conexión a un nombre. Los intentos posteriores de conectarse utilizando el mismo nombre devolverán la misma conexión.

A continuación, la conexión se cierra mediante la función disconnectFromBus().

Una vez desconectada, llamar a ` connectToBus()` no restablecerá la conexión; es necesario crear una nueva instancia de `QDBusConnection`.

Para facilitar el uso de los dos tipos de conexión más comunes, las funciones ` sessionBus()` y ` systemBus()` devuelven conexiones abiertas al demonio del servidor de sesión y al demonio del servidor del sistema, respectivamente. Dichas conexiones se abren la primera vez que se utilizan y se cierran cuando se ejecuta el destructor de ` QCoreApplication `.

D-Bus también admite conexiones entre pares, sin necesidad de un demonio de servidor de bus. Mediante esta función, dos aplicaciones pueden comunicarse entre sí e intercambiar mensajes. Esto se consigue pasando una dirección a la función connectToBus(), que fue abierta por otra aplicación D-Bus mediante QDBusServer.

Documentación sobre los tipos de miembros

enum QDBusConnection::BusType

Especifica el tipo de conexión de bus. Los tipos de bus válidos son:

ConstanteValorDescripción
QDBusConnection::SessionBus0el bus de sesión, asociado a la sesión de escritorio en ejecución
QDBusConnection::SystemBus1el bus del sistema, utilizado para comunicarse con procesos de todo el sistema
QDBusConnection::ActivationBus2el bus de activación, el «alias» del bus que inició el servicio

En el bus de sesión se pueden encontrar otras aplicaciones del mismo usuario que comparten la misma sesión de escritorio (de ahí su nombre). En el bus del sistema, sin embargo, suelen encontrarse procesos compartidos por todo el sistema.

enum QDBusConnection::ConnectionCapability
flags QDBusConnection::ConnectionCapabilities

Esta enumeración describe las capacidades disponibles para una conexión D-Bus.

ConstanteValorDescripción
QDBusConnection::UnixFileDescriptorPassing0x0001permite pasar descriptores de archivo de Unix a otros procesos (véase QDBusUnixFileDescriptor)

El tipo ConnectionCapabilities es una definición de tipo (typedef) para QFlags<ConnectionCapability>. Almacena una combinación OR de valores de ConnectionCapability.

Véase también connectionCapabilities().

enum QDBusConnection::RegisterOption
flags QDBusConnection::RegisterOptions

Especifica las opciones para registrar objetos en la conexión. Los valores posibles son:

ConstanteValorDescripción
QDBusConnection::ExportAdaptors0x01exportar el contenido de los adaptadores que se encuentren en este objeto
QDBusConnection::ExportScriptableSlots0x10Exportar las ranuras programables de este objeto
QDBusConnection::ExportScriptableSignals0x20Exportar las señales programables de este objeto
QDBusConnection::ExportScriptableProperties0x40Exportar las propiedades programables de este objeto
QDBusConnection::ExportScriptableInvokables0x80exportar los invocables programables de este objeto
QDBusConnection::ExportScriptableContents0xf0forma abreviada de ExportScriptableSlots | ExportScriptableSignals | ExportScriptableProperties
QDBusConnection::ExportNonScriptableSlots0x100exportar las ranuras no programables de este objeto
QDBusConnection::ExportNonScriptableSignals0x200exportar las señales no programables de este objeto
QDBusConnection::ExportNonScriptableProperties0x400exportar las propiedades no programables de este objeto
QDBusConnection::ExportNonScriptableInvokables0x800exportar los invocables no programables de este objeto
QDBusConnection::ExportNonScriptableContents0xf00forma abreviada de ExportNonScriptableSlots | ExportNonScriptableSignals | ExportNonScriptableProperties
QDBusConnection::ExportAllSlotsExportScriptableSlots|ExportNonScriptableSlotsexportar todas las ranuras de este objeto
QDBusConnection::ExportAllSignalsExportScriptableSignals|ExportNonScriptableSignalsexportar todas las señales de este objeto
QDBusConnection::ExportAllPropertiesExportScriptableProperties|ExportNonScriptablePropertiesexportar todas las propiedades de este objeto
QDBusConnection::ExportAllInvokablesExportScriptableInvokables|ExportNonScriptableInvokablesexportar todos los invocables de este objeto
QDBusConnection::ExportAllContentsExportScriptableContents|ExportNonScriptableContentsexportar todo el contenido de este objeto
QDBusConnection::ExportChildObjects0x1000exportar los objetos hijos de este objeto

El tipo `RegisterOptions` es una definición de tipo para ` QFlags<RegisterOption>`. Almacena una combinación OR de valores de `RegisterOption`.

Véase también registerObject(), QDBusAbstractAdaptor y Uso de adaptadores.

enum QDBusConnection::UnregisterMode

El modo para dar de baja una ruta de objeto:

ConstanteValorDescripción
QDBusConnection::UnregisterNode0Desregistrar solo este nodo: no desregistrar los objetos secundarios
QDBusConnection::UnregisterTree1Desregistrar este nodo y todo su subárbol

Ten en cuenta, sin embargo, que si este objeto se registró con la opción « ExportChildObjects », UnregisterNode también dará de baja los objetos hijos.

Documentación de las funciones de miembro

[explicit] QDBusConnection::QDBusConnection(const QString &name)

Crea un objeto `QDBusConnection` asociado a la conexión denominada ` name`.

Esto no abre la conexión. Para abrirla, debes llamar a connectToBus().

QDBusConnection::QDBusConnection(const QDBusConnection &other)

Crea una copia de la conexión « other ».

[noexcept] QDBusConnection::~QDBusConnection()

Elimina este objeto. Esto no cierra la conexión: para ello, debes llamar a la función ` disconnectFromBus()`.

QDBusPendingCall QDBusConnection::asyncCall(const QDBusMessage &message, int timeout = -1) const

Envía el ` message ` a través de esta conexión y devuelve el resultado de inmediato. Esta función solo es adecuada para llamadas a métodos. Devuelve un objeto de tipo ` QDBusPendingCall `, que puede utilizarse para realizar un seguimiento del estado de la respuesta.

Si no se recibe ninguna respuesta en un plazo de timeout milisegundos, se generará un error automático que indicará que la llamada ha caducado. El valor predeterminado de ` timeout ` es -1, que se sustituirá por un valor definido por la implementación adecuado para las comunicaciones entre procesos (por lo general, 25 segundos). Este tiempo de espera es también el límite máximo de espera en `QDBusPendingCall::waitForFinished()`.

Consulta la función QDBusInterface::asyncCall() para conocer una forma más sencilla de realizar llamadas.

Nota: Las llamadas amétodos de objetos registrados por la propia aplicación nunca son asíncronas debido a limitaciones de implementación.

QString QDBusConnection::baseService() const

Devuelve el nombre único de esta conexión, si el objeto ` QDBusConnection ` está conectado, o un ` QString ` vacío en caso contrario.

Un nombre de conexión único es una cadena con el formato «:x.xxx» (donde x son dígitos decimales) que asigna el demonio del servidor D-Bus al establecer la conexión. Identifica de forma única a este cliente en el bus.

Esta función devuelve un objeto ` QString ` vacío para las conexiones entre pares.

QDBusMessage QDBusConnection::call(const QDBusMessage &message, QDBus::CallMode mode = QDBus::Block, int timeout = -1) const

Envía el mensaje « message » a través de esta conexión y permanece en espera de una respuesta durante un máximo de timeout milisegundos. Esta función solo es adecuada para llamadas a métodos. Devuelve el mensaje de respuesta como valor de retorno, que será de tipo « QDBusMessage::ReplyMessage » o « QDBusMessage::ErrorMessage ».

Si no se recibe ninguna respuesta en un plazo de timeout milisegundos, se generará un error automático que indicará que la llamada ha caducado. El valor predeterminado de timeout es -1, que se sustituirá por un valor definido por la implementación adecuado para las comunicaciones entre procesos (por lo general, 25 segundos).

Consulte la función QDBusInterface::call() para conocer una forma más sencilla de realizar llamadas.

Advertencia: Si mode es QDBus::BlockWithGui, esta función volverá a entrar en el bucle de eventos de Qt para esperar la respuesta. Durante la espera, puede enviar señales y otras llamadas a métodos a tu aplicación. Por lo tanto, esta debe estar preparada para gestionar la reentrada cada vez que se realice una llamada con call().

bool QDBusConnection::callWithCallback(const QDBusMessage &message, QObject *receiver, const char *returnMethod, const char *errorMethod, int timeout = -1) const

Envía el message a través de esta conexión y vuelve inmediatamente. Cuando se recibe la respuesta, se llama al método returnMethod en el objeto receiver. Si se produce un error, se llamará en su lugar al método errorMethod.

Si no se recibe respuesta en un plazo de timeout milisegundos, se generará un error automático que indicará que la llamada ha caducado. El valor predeterminado de timeout es -1, que se sustituirá por un valor definido por la implementación adecuado para las comunicaciones entre procesos (generalmente, 25 segundos).

Esta función solo es adecuada para llamadas a métodos. Se garantiza que la ranura se llamará exactamente una vez con la respuesta, siempre que los tipos de los parámetros coincidan y no se produzca ningún error.

Devuelve ` true ` si se ha enviado el mensaje, o `false` si no se ha podido enviar.

bool QDBusConnection::connect(const QString &service, const QString &path, const QString &interface, const QString &name, QObject *receiver, const char *slot)

Conecta la señal especificada por los parámetros service, path, interface y name a la ranura slot del objeto receiver. Los argumentos service y path pueden estar vacíos, lo que indica una conexión a cualquier señal del par (interface, name), desde cualquier aplicación remota.

Devuelve « true » si la conexión se ha realizado correctamente.

Advertencia: La señal solo se transmitirá al slot si los parámetros coinciden. Esta verificación solo puede realizarse en el momento de recibir la señal, no en el momento de la conexión.

bool QDBusConnection::connect(const QString &service, const QString &path, const QString &interface, const QString &name, const QString &signature, QObject *receiver, const char *slot)

Conecta la señal a la ranura slot del objeto receiver. A diferencia de la sobrecarga anterior de connect(), esta función permite especificar la firma del parámetro que se va a conectar mediante la variable signature. A continuación, la función verificará que dicha firma se pueda enviar a la ranura especificada por slot y, en caso contrario, devolverá false.

Devuelve « true » si la conexión se ha realizado correctamente.

Nota: Esta función comprueba que la firma de la señal coincida con los parámetros de la ranura, pero no comprueba que la señal real exista con la firma dada en el servicio remoto.

Esta es una función sobrecargada.

bool QDBusConnection::connect(const QString &service, const QString &path, const QString &interface, const QString &name, const QStringList &argumentMatch, const QString &signature, QObject *receiver, const char *slot)

Conecta la señal a la ranura slot del objeto receiver. A diferencia de la sobrecarga anterior de connect(), esta función permite especificar la firma del parámetro que se va a conectar mediante la variable signature. A continuación, la función verificará que dicha firma se pueda enviar a la ranura especificada por slot y, en caso contrario, devolverá false.

El parámetro argumentMatch enumera los parámetros de cadena que deben coincidir, en orden secuencial. Ten en cuenta que, para hacer coincidir una cadena vacía, debes pasar un QString que esté vacío pero no sea nulo (es decir, QString("")). Un QString nulo omite la coincidencia en esa posición.

Devuelve « true » si la conexión se ha realizado correctamente.

Nota: Esta función comprueba que la firma de la señal coincida con los parámetros de la ranura, pero no verifica que la señal real exista con la firma dada en el servicio remoto.

Esta es una función sobrecargada.

[static] QDBusConnection QDBusConnection::connectToBus(QDBusConnection::BusType type, const QString &name)

Abre una conexión de tipo « type » con uno de los buses conocidos y le asigna el nombre de conexión « name ». Devuelve un objeto « QDBusConnection » asociado a dicha conexión.

[static] QDBusConnection QDBusConnection::connectToBus(const QString &address, const QString &name)

Abre una conexión a un bus privado en la dirección address y le asigna el nombre de conexión name. Devuelve un objeto ` QDBusConnection ` asociado a dicha conexión.

[static] QDBusConnection QDBusConnection::connectToPeer(const QString &address, const QString &name)

Abre una conexión entre pares en la dirección address y le asigna el nombre de conexión name. Devuelve un objeto ` QDBusConnection ` asociado a dicha conexión.

QDBusConnection::ConnectionCapabilities QDBusConnection::connectionCapabilities() const

Devuelve las capacidades de esta conexión tal y como se han negociado con el servidor de bus o con el par. Si este « QDBusConnection » no está conectado, esta función no devuelve ninguna capacidad.

bool QDBusConnection::disconnect(const QString &service, const QString &path, const QString &interface, const QString &name, QObject *receiver, const char *slot)

Desconecta la señal especificada por los parámetros service, path, interface y name de la ranura slot del objeto receiver. Los argumentos deben ser los mismos que se pasan a la función connect().

Devuelve « true » si la desconexión se ha realizado correctamente.

bool QDBusConnection::disconnect(const QString &service, const QString &path, const QString &interface, const QString &name, const QString &signature, QObject *receiver, const char *slot)

Desconecta la señal especificada por los parámetros service, path, interface, name y signature de la ranura slot del objeto receiver. Los argumentos deben ser los mismos que se pasan a la función connect().

Devuelve « true » si la desconexión se ha realizado correctamente.

Esta es una función sobrecargada.

bool QDBusConnection::disconnect(const QString &service, const QString &path, const QString &interface, const QString &name, const QStringList &argumentMatch, const QString &signature, QObject *receiver, const char *slot)

Desconecta la señal especificada por los parámetros service, path, interface, name, argumentMatch y signature de la ranura slot del objeto receiver. Los argumentos deben ser los mismos que se pasan a la función connect().

Devuelve « true » si la desconexión se ha realizado correctamente.

Esta es una función sobrecargada.

[static] void QDBusConnection::disconnectFromBus(const QString &name)

Cierra la conexión de bus denominada « name ».

Ten en cuenta que, si aún hay objetos ` QDBusConnection ` asociados a la misma conexión, esta no se cerrará hasta que se hayan eliminado todas las referencias. Sin embargo, no se pueden crear más referencias utilizando el constructor ` QDBusConnection `.

[static] void QDBusConnection::disconnectFromPeer(const QString &name)

Cierra la conexión entre pares denominada « name ».

Ten en cuenta que, si todavía hay objetos QDBusConnection asociados a la misma conexión, esta no se cerrará hasta que se eliminen todas las referencias. Sin embargo, no se pueden crear más referencias utilizando el constructor QDBusConnection.

QDBusConnectionInterface *QDBusConnection::interface() const

Devuelve un objeto ` QDBusConnectionInterface ` que representa la interfaz del servidor D-Bus en esta conexión.

bool QDBusConnection::isConnected() const

Devuelve ` true ` si este objeto ` QDBusConnection ` está conectado.

QDBusError QDBusConnection::lastError() const

Devuelve el último error que se ha producido en esta conexión.

Esta función está pensada para código de bajo nivel. Si utilizas QDBusInterface::call(), los códigos de error se indican mediante su valor de retorno.

Véase también QDBusInterface y QDBusMessage.

[static] QByteArray QDBusConnection::localMachineId()

Devuelve el identificador local de la máquina tal y como lo reconoce el sistema D-Bus. Cada nodo u host que ejecuta D-Bus tiene un identificador único que puede utilizarse para distinguirlo de otros hosts en caso de que compartan recursos, como el sistema de archivos.

Ten en cuenta que no se garantiza que el ID de la máquina local se mantenga tras cada reinicio del sistema, por lo que este identificador no debe almacenarse en un almacenamiento persistente (como el sistema de archivos). Solo se garantiza que permanezca constante durante la duración de esta sesión de arranque.

QString QDBusConnection::name() const

Devuelve el nombre de esta conexión, tal y como se ha especificado en el parámetro «name» de la función ` connectToBus()`.

El nombre de conexión puede utilizarse para identificar de forma unívoca las conexiones subyacentes reales a los buses. Las copias creadas a partir de una única conexión siempre compartirán implícitamente la conexión subyacente y, por lo tanto, tendrán el mismo nombre de conexión.

Por el contrario, dos conexiones con nombres diferentes siempre estarán conectadas a buses distintos o tendrán un nombre único diferente (tal y como lo devuelve baseService()) en ese bus.

Véanse también connectToBus() y disconnectFromBus().

QObject *QDBusConnection::objectRegisteredAt(const QString &path) const

Devuelve el objeto que se registró con la función ` registerObject()` en la ruta de objeto indicada por ` path`.

bool QDBusConnection::registerObject(const QString &path, QObject *object, QDBusConnection::RegisterOptions options = ExportAdaptors)

Registra el objeto object en la ruta path y devuelve true si el registro se ha realizado correctamente. El parámetro options especifica qué parte del objeto object se expondrá a través de D-Bus.

Esta función no sustituye a los objetos existentes: si ya hay un objeto registrado en la ruta path, esta función devolverá «false». Utiliza unregisterObject() para darlo de baja primero.

El indicador ExportChildObjects exporta los objetos hijos a D-Bus basándose en la ruta de los objetos registrados y en el QObject::objectName del objeto hijo. Por lo tanto, es importante que el objeto hijo tenga un nombre de objeto.

No se puede registrar un objeto como objeto secundario de un objeto que se haya registrado con ExportChildObjects.

bool QDBusConnection::registerObject(const QString &path, const QString &interface, QObject *object, QDBusConnection::RegisterOptions options = ExportAdaptors)

Registra el objeto object en la ruta path con el nombre de interfaz interface y devuelve true si el registro se ha realizado correctamente. El parámetro options especifica qué parte del objeto object se expondrá a través de D-Bus.

Esta función no sustituye a los objetos existentes: si ya hay un objeto registrado en la ruta path, esta función devolverá «false». Utilice unregisterObject() para darlo de baja primero.

El indicador ExportChildObjects exporta los objetos hijos a D-Bus basándose en la ruta de los objetos registrados y en el QObject::objectName del objeto hijo. Por lo tanto, es importante que el objeto hijo tenga un nombre de objeto.

No se puede registrar un objeto como objeto secundario de un objeto que se haya registrado con ExportChildObjects.

Esta es una función sobrecargada.

bool QDBusConnection::registerService(const QString &serviceName)

Intenta registrar el objeto « serviceName » en el servidor D-Bus y devuelve « true » si el registro se ha realizado correctamente. El registro fallará si el nombre ya está registrado por otra aplicación.

Véase también unregisterService() y QDBusConnectionInterface::registerService().

bool QDBusConnection::send(const QDBusMessage &message) const

Envía el ` message ` a través de esta conexión, sin esperar una respuesta. Esto resulta adecuado para errores, señales y valores de retorno, así como para llamadas cuyos valores de retorno no son necesarios.

Devuelve ` true ` si el mensaje se ha puesto en cola correctamente; en caso contrario, devuelve `false`.

[static] QDBusConnection QDBusConnection::sessionBus()

Devuelve un objeto ` QDBusConnection ` abierto mediante el bus de sesión. La referencia al objeto devuelta por esta función es válida hasta que la aplicación finalice; en ese momento, se cerrará la conexión y se eliminará el objeto.

[noexcept] void QDBusConnection::swap(QDBusConnection &other)

Cambia esta conexión por other. Esta operación es muy rápida y nunca falla.

[static] QDBusConnection QDBusConnection::systemBus()

Devuelve un objeto ` QDBusConnection ` abierto mediante el bus del sistema. La referencia al objeto devuelta por esta función es válida hasta que se ejecute el destructor de ` QCoreApplication`, momento en el que se cerrará la conexión y se eliminará el objeto.

void QDBusConnection::unregisterObject(const QString &path, QDBusConnection::UnregisterMode mode = UnregisterNode)

Dera registra un objeto que se había registrado con la función ` registerObject()` en la ruta del objeto indicada por ` path ` y, si ` mode ` es ` QDBusConnection::UnregisterTree`, también todos sus subobjetos.

Ten en cuenta que no se pueden dar de baja objetos que no se hayan registrado mediante registerObject().

bool QDBusConnection::unregisterService(const QString &serviceName)

Da de baja el servicio serviceName que se había registrado previamente con registerService() y devuelve true si la operación se ha realizado correctamente.

Véanse también registerService() y QDBusConnectionInterface::unregisterService().

QDBusConnection &QDBusConnection::operator=(const QDBusConnection &other)

Crea una copia de la conexión other en este objeto. Ten en cuenta que la conexión a la que hacía referencia este objeto antes de la copia no se desconecta automáticamente.

Véase también disconnectFromBus().

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