Класс QDBusConnection

Класс QDBusConnection представляет собой подключение к демону шины D-Bus. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Открытые типы

Общедоступные функции

Статические общедоступные члены

Подробное описание

Этот класс является исходной точкой в сессии D-Bus. С его помощью можно получить доступ к удаленным объектам, интерфейсам; подключить удалённые сигналы к слотам вашего объекта; зарегистрировать объекты и т.д.

Соединения D-Bus создаются с помощью функции connectToBus(), которая открывает соединение с демоном сервера и выполняет начальный обмен данными, ассоциируя это соединение с именем. Повторные попытки подключения с использованием того же имени вернут то же самое соединение.

Соединение затем разрывается с помощью функции disconnectFromBus().

После разъединения вызов connectToBus() не восстановит соединение, необходимо создать новый экземпляр QDBusConnection.

Для удобства двух наиболее распространенных типов соединений функции sessionBus() и systemBus() соответственно возвращают открытые соединения с демоном сервера сеанса и демоном сервера системы. Эти соединения открываются при первом использовании и закрываются при выполнении деструктора QCoreApplication.

D-Bus также поддерживает соединения «точка-точка» без необходимости в демоне сервера шины. С помощью этой функции две программы могут общаться и обмениваться сообщениями. Это можно сделать, передав адрес функции connectToBus(), который был открыт другой программой D-Bus с использованием QDBusServer.

Документация по типам членов

enum QDBusConnection::BusType

Определяет тип соединения шины. Допустимые типы шины:

В шине сеанса можно найти другие приложения одного пользователя, которые используют ту же сессию рабочего стола (отсюда и название). Однако в шине системы обычно находятся общие для всей системы процессы.

enum QDBusConnection::ConnectionCapabilityflags QDBusConnection::ConnectionCapabilities

Этот перечисление описывает доступные возможности для соединения D-Bus.

Тип ConnectionCapabilities является типом-псевдонимом для QFlags<ConnectionCapability>. Он хранит логическое ИЛИ комбинацию значений ConnectionCapability.

См. также connectionCapabilities().

enum QDBusConnection::RegisterOptionflags QDBusConnection::RegisterOptions

Определяет параметры для регистрации объектов в соединении. Возможные значения:

Тип RegisterOptions является типом-псевдонимом для QFlags<RegisterOption>. Он хранит логическое ИЛИ комбинацию значений RegisterOption.

См. также registerObject(), QDBusAbstractAdaptor и Использование адаптеров.

enum QDBusConnection::UnregisterMode

Режим для отмены регистрации пути объекта:

Однако, если этот объект был зарегистрирован с опцией ExportChildObjects, UnregisterNode также отключит дочерние объекты.

Документация по членам-функциям

QDBusConnection::QDBusConnection(const QDBusConnection &other)

Создает копию соединения other.

QDBusConnection::QDBusConnection(const QString &name)

Создаёт объект QDBusConnection, подключенный к соединению с именем name.

Это не открывает соединение. Вы должны вызвать connectToBus(), чтобы его открыть.

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

Создаёт копию соединения other в этом объекте. Обратите внимание, что соединение, к которому ссылался этот объект до копирования, не отключается автоматически.

См. также disconnectFromBus().

QDBusConnection::~QDBusConnection()

Удаляет этот объект. Это не закрывает соединение: вы должны вызвать disconnectFromBus(), чтобы сделать это.

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

Отправляет message по этому соединению и возвращает значение немедленно. Эта функция подходит только для вызовов методов. Она возвращает объект типа QDBusPendingCall, который может использоваться для отслеживания статуса ответа.

Если ответ не получен в течение timeout миллисекунд, будет автоматически доставлено сообщение об ошибке, указывающей на истечение времени ожидания вызова. Значение по умолчанию timeout равно -1, которое будет заменено значением, определённым реализацией, подходящим для межпроцессного взаимодействия (обычно 25 секунд). Это время ожидания также является верхней границей ожидания в QDBusPendingCall::waitForFinished().

См. функцию QDBusInterface::asyncCall() для более удобного способа размещения вызовов.

QString QDBusConnection::baseService() const

Возвращает уникальное имя соединения для этого соединения, если этот объект QDBusConnection подключён, или пустую строку QString в противном случае.

Уникальное имя соединения — это строка в формате ":x.xxx" (где x — десятичные цифры), которая назначается демоном сервера D-Bus при подключении. Оно однозначно идентифицирует этого клиента в шине.

Эта функция возвращает пустую строку QString для соединений «клиент-клиент».

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

Отправляет message по этому соединению и блокируется, ожидая ответа, в течение максимум timeout миллисекунд. Эта функция подходит только для вызовов методов. Она возвращает сообщение ответа, которое будет либо QDBusMessage::ReplyMessage, либо QDBusMessage::ErrorMessage.

Если ответ не получен в течение timeout миллисекунд, будет доставлено автоматическое сообщение об ошибке, указывающее на истечение времени ожидания вызова. Значение по умолчанию для timeout равно -1, которое будет заменено определённым реализацией значением, подходящим для межпроцессного взаимодействия (обычно 25 секунд).

См. функцию QDBusInterface::call() для более удобного способа выполнения вызовов.

Предупреждение: Если mode равен QDBus::BlockWithGui, эта функция повторно войдёт в цикл обработки событий Qt, чтобы дождаться ответа. Во время ожидания она может передавать сигналы и другие вызовы методов вашему приложению. Поэтому оно должно быть готово обработать повторный вход, когда вызов выполняется с помощью call().

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

Отправляет message по этому соединению и возвращает немедленно. Когда ответ получен, метод returnMethod вызывается в объекте receiver. Если произошла ошибка, вместо этого вызывается метод errorMethod.

Если ответ не получен в течение timeout миллисекунд, будет доставлено автоматическое сообщение об ошибке, указывающее на истечение времени ожидания вызова. Значение по умолчанию для timeout равно -1, которое будет заменено определённым реализацией значением, подходящим для межпроцессного взаимодействия (обычно 25 секунд).

Эта функция подходит только для вызовов методов. Гарантируется, что слот будет вызван ровно один раз с ответом, при условии соответствия типов параметров и отсутствия ошибок.

Возвращает true если сообщение было отправлено, или false, если сообщение не удалось отправить.

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

Подключает сигнал, указанный параметрами service, path, interface и name, к слоту slot в объекте receiver. Аргументы service и path могут быть пустыми, обозначая подключение к любому сигналу пары (interface, name) из любого удалённого приложения.

Возвращает true если подключение было успешным.

Предупреждение: Сигнал будет передан только в слот, если параметры соответствуют. Эта проверка может быть выполнена только при получении сигнала, а не при подключении.

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

Это перегруженная функция.

Подключает сигнал к слоту slot в объекте receiver. В отличие от предыдущей перегрузки connect(), эта функция позволяет указать сигнатуру параметров для подключения с помощью переменной signature. Функция затем проверит, может ли эта сигнатура быть передана в указанный слот slot и вернёт false в противном случае.

Возвращает true если подключение было успешным.

Примечание: Эта функция проверяет соответствие сигнатуры сигнала параметрам слота, но не проверяет, существует ли фактический сигнал с данной сигнатурой в удалённой службе.

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)

Это перегруженная функция.

Подключает сигнал к слоту slot в объекте receiver. В отличие от предыдущей перегрузки connect(), эта функция позволяет указать сигнатуру параметров для подключения с помощью переменной signature. Функция затем проверит, может ли эта сигнатура быть передана в указанный слот slot и вернёт false в противном случае.

Параметр argumentMatch перечисляет строковые параметры для сопоставления в последовательном порядке. Обратите внимание, что для сопоставления пустой строки нужно передать QString, который пуст, но не null (т. е., QString("")). Нулевой QString пропускает сопоставление в этой позиции.

Возвращает true если подключение было успешным.

Примечание: Эта функция проверяет соответствие сигнатуры сигнала параметрам слота, но не проверяет, существует ли фактический сигнал с данной сигнатурой в удалённой службе.

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

Открывает соединение типа type с одним из известных шин и связывает с ним имя соединения name. Возвращает объект QDBusConnection, связанный с этим соединением.

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

Открывает соединение с частной шиной по адресу address и связывает с ним имя соединения name. Возвращает объект QDBusConnection, связанный с этим соединением.

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

Открывает соединение «точка-точка» по адресу address и связывает с ним имя соединения name. Возвращает объект QDBusConnection, связанный с этим соединением.

QDBusConnection::ConnectionCapabilities QDBusConnection::connectionCapabilities() const

Возвращает возможности этого соединения, согласованные с сервером шины или peer. Если это QDBusConnection не подключено, эта функция возвращает отсутствующие возможности.

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

Отключает сигнал, указанный параметрами service, path, interface и name, от слота slot в объекте receiver. Аргументы должны быть такими же, как передаваемые в функцию connect().

Возвращает true если отключение было успешным.

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

Это перегруженная функция.

Отключает сигнал, указанный параметрами service, path, interface, name и signature, от слота slot в объекте receiver. Аргументы должны быть такими же, как передаваемые в функцию connect().

Возвращает true если отключение было успешным.

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)

Это перегруженный метод.

Отключает сигнал, указанный параметрами service, path, interface, name, argumentMatch и signature, от слота slot в объекте receiver. Аргументы должны быть такими же, как и те, что переданы в функцию connect().

Возвращает true, если отключение прошло успешно.

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

Закрывает соединение с шиной с именем name.

Обратите внимание, что если с этим соединением все еще связаны объекты QDBusConnection, соединение не будет закрыто, пока все ссылки не будут удалены. Однако больше ссылок создать с помощью конструктора QDBusConnection нельзя.

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

Закрывает соединение с узлом с именем name.

Обратите внимание, что если с этим соединением все еще связаны объекты QDBusConnection, соединение не будет закрыто, пока все ссылки не будут удалены. Однако больше ссылок создать с помощью конструктора QDBusConnection нельзя.

QDBusConnectionInterface *QDBusConnection::interface() const

Возвращает объект QDBusConnectionInterface, представляющий интерфейс сервера D-Bus в этом соединении.

bool QDBusConnection::isConnected() const

Возвращает true, если этот объект QDBusConnection подключен.

QDBusError QDBusConnection::lastError() const

Возвращает последнюю ошибку, произошедшую в этом соединении.

Эта функция предназначена для кода низкого уровня. Если вы используете QDBusInterface::call(), коды ошибок сообщаются её возвращаемым значением.

См. также QDBusInterface и QDBusMessage.

[static] QByteArray QDBusConnection::localMachineId()

Возвращает идентификатор локальной машины, известный системе D-Bus. Каждый узел или хост, на котором работает D-Bus, имеет уникальный идентификатор, который может использоваться для различения его от других хостов, если они разделяют ресурсы, такие как файловая система.

Обратите внимание, что идентификатор локальной машины не гарантируется, что будет сохраняться после перезагрузки системы, поэтому этот идентификатор не следует хранить в постоянном хранилище (например, в файловой системе). Он гарантируется неизменным только в течение текущей сессии работы.

QString QDBusConnection::name() const

Возвращает имя соединения для данного соединения, как указано в параметре name функции connectToBus().

Имя соединения может использоваться для уникальной идентификации фактических базовых соединений с шинами. Копии, созданные из одного соединения, всегда неявно разделяют базовое соединение и, следовательно, имеют то же имя соединения.

В свою очередь, два соединения с разными именами соединения всегда будут подключены к разным шинам или иметь разное уникальное имя (как возвращает baseService()) на этой шине.

См. также connectToBus() и disconnectFromBus().

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

Возвращает объект, который был зарегистрирован с помощью registerObject() по указанному пути объекта path.

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

Регистрирует объект object по пути path и возвращает true, если регистрация прошла успешно. Параметр options определяет, какая часть объекта object будет экспортирована через D-Bus.

Эта функция не заменяет существующие объекты: если объект уже зарегистрирован по пути path, функция вернёт false. Сначала используйте unregisterObject(), чтобы его отменить.

Флаг ExportChildObjects экспортирует дочерние объекты в D-Bus, основываясь на пути зарегистрированных объектов и имени объекта QObject::objectName дочернего объекта. Поэтому важно, чтобы у дочернего объекта было имя.

Вы не можете зарегистрировать объект как дочерний объект для объекта, зарегистрированного с ExportChildObjects.

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

Это перегруженный метод.

Регистрирует объект object по пути path с именем интерфейса interface и возвращает true, если регистрация прошла успешно. Параметр options определяет, какая часть объекта object будет экспортирована через D-Bus.

Эта функция не заменяет существующие объекты: если объект уже зарегистрирован по пути path, функция вернёт false. Сначала используйте unregisterObject(), чтобы его отменить.

Флаг ExportChildObjects экспортирует дочерние объекты в D-Bus, основываясь на пути зарегистрированных объектов и имени объекта QObject::objectName дочернего объекта. Поэтому важно, чтобы у дочернего объекта было имя.

Вы не можете зарегистрировать объект как дочерний объект для объекта, зарегистрированного с ExportChildObjects.

Эта функция была добавлена в Qt 5.5.

bool QDBusConnection::registerService(const QString &serviceName)

Попытка зарегистрировать serviceName на сервере D-Bus и возвращает true, если регистрация прошла успешно. Регистрация завершится неудачно, если имя уже зарегистрировано другим приложением.

См. также unregisterService() и QDBusConnectionInterface::registerService().

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

Отправляет сообщение message по этому соединению без ожидания ответа. Подходит для ошибок, сигналов, возвращаемых значений, а также вызовов, для которых возвращаемые значения не нужны.

Возвращает true, если сообщение было успешно поставлено в очередь, в противном случае false.

[static] QDBusConnection QDBusConnection::sessionBus()

Возвращает объект QDBusConnection, открытый с сеансовой шиной. Ссылка на объект, возвращённую этой функцией, действительна до завершения приложения, в этот момент соединение будет закрыто, а объект удалён.

void QDBusConnection::swap(QDBusConnection &other)

Меняет местами это соединение QDBusConnection с other.

[static] QDBusConnection QDBusConnection::systemBus()

Возвращает объект QDBusConnection, открытый с системной шиной. Ссылка на возвращенный объект действительна до завершения деструктора QCoreApplication, в этот момент соединение будет закрыто, и объект удален.

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

Удаляет объект, зарегистрированный с помощью registerObject() по указанному пути объекта path и, если mode равен QDBusConnection::UnregisterTree, все его дочерние объекты тоже.

Обратите внимание, что вы не можете удалить объекты, которые не были зарегистрированы с помощью registerObject().

bool QDBusConnection::unregisterService(const QString &serviceName)

Отменяет регистрацию службы serviceName, ранее зарегистрированной с помощью registerService(), и возвращает true в случае успеха.

См. также registerService() и QDBusConnectionInterface::unregisterService().