Класс QLibrary

Класс QLibrary загружает динамически подключаемые библиотеки во время выполнения. Подробнее...

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

Примечание: Все функции в этом классе являются реентерабельными.

Типы публичного доступа

Свойства

• fileName : QString
• loadHints : LoadHints

Функции публичного доступа

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

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

Экземпляр объекта QLibrary работает с одним файлом динамически подключаемой библиотеки (которую мы называем «библиотекой», но она также известна как «DLL»). QLibrary предоставляет независимый от платформы доступ к функциональности библиотеки. Вы можете передать имя файла в конструкторе или установить его явно с помощью setFileName(). При загрузке библиотеки QLibrary ищет её во всех системных расположениях (например, LD_LIBRARY_PATH в Unix), если имя файла не является абсолютным.

Если имя файла является абсолютным путем, то QLibrary пытается загрузить этот путь в первую очередь. Если файл не найден, QLibrary пытается найти имя с разными системно-зависимыми префиксами, такими как «lib» в Unix и Mac, и суффиксами, такими как «.so» в Unix, «.dylib» на Mac или «.dll» на Windows.

Если путь к файлу не является абсолютным, то QLibrary изменяет порядок поиска, пытаясь найти имя с системно-зависимыми префиксами и суффиксами в первую очередь, а затем с указанным именем файла.

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

Наиболее важные функции — load() для динамической загрузки файла библиотеки, isLoaded() для проверки успешности загрузки и resolve() для разрешения символа в библиотеке. Функция resolve() неявно пытается загрузить библиотеку, если она еще не загружена. Можно использовать несколько экземпляров QLibrary для доступа к одной и той же физической библиотеке. После загрузки библиотеки она остается в памяти до завершения приложения. Можно попытаться разгрузить библиотеку с помощью unload(), но если другие экземпляры QLibrary используют ту же библиотеку, вызов завершится неудачей, а разгрузка произойдет только когда все экземпляры вызовут unload().

Типичное использование QLibrary — разрешение экспортированного символа в библиотеке и вызов C-функции, которую этот символ представляет. Это называется «явной линковкой» в отличие от «неявной линковки», которая выполняется на этапе линковки при создании исполняемого файла с использованием библиотеки.

Следующий фрагмент кода загружает библиотеку, разрешает символ «mysymbol» и вызывает функцию, если всё прошло успешно. Если что-то пойдёт не так, например, файла библиотеки не существует или символ не определен, указатель на функцию будет nullptr и не будет вызван.

QLibrary myLib("mylib");
typedef void (*MyPrototype)();
MyPrototype myFunction = (MyPrototype) myLib.resolve("mysymbol");
if (myFunction)
    myFunction();

Символ должен быть экспортирован как C-функция из библиотеки для работы resolve(). Это означает, что функция должна быть обернута в extern "C" блок, если библиотека скомпилирована с помощью компилятора C++. В Windows это также требует использования макроса dllexport; см. resolve() для получения подробностей о том, как это делается. Для удобства есть статическая функция resolve(), которую можно использовать, если нужно вызвать функцию в библиотеке, не загружая её явно:

typedef void (*MyPrototype)();
MyPrototype myFunction =
        (MyPrototype) QLibrary::resolve("mylib", "mysymbol");
if (myFunction)
    myFunction();

См. такжеQPluginLoader.

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

Перечисление QLibrary::LoadHintФлаги QLibrary::LoadHints

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

Тип LoadHints — это typedef для QFlags<LoadHint>. Он хранит логическое ИЛИ из значений LoadHint.

См. также loadHints.

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

QLibrary::QLibrary(const QString &fileName, const QString &version, QObject *parent = nullptr)

Конструирует объект библиотеки с заданным parent, который будет загружать библиотеку, указанную в fileName, и полным номером версии version. В настоящее время номер версии игнорируется в Windows.

Рекомендуется опускать расширение файла в fileName, так как QLibrary будет автоматически искать файл с соответствующим расширением в соответствии с платформой, например, ".so" в Unix, ".dylib" в macOS и iOS, и ".dll" в Windows. (См. fileName.)

QLibrary::QLibrary(const QString &fileName, int verNum, QObject *parent = nullptr)

Конструирует объект библиотеки с заданным parent, который будет загружать библиотеку, указанную в fileName, и номером основной версии verNum. В настоящее время номер версии игнорируется в Windows.

Рекомендуется опускать расширение файла в fileName, так как QLibrary будет автоматически искать файл с соответствующим расширением в соответствии с платформой, например, ".so" в Unix, ".dylib" в macOS и iOS, и ".dll" в Windows. (См. fileName.)

QLibrary::QLibrary(const QString &fileName, QObject *parent = nullptr)

Конструирует объект библиотеки с заданным parent, который будет загружать библиотеку, указанную в fileName.

Рекомендуется опускать расширение файла в fileName, так как QLibrary будет автоматически искать файл с соответствующим расширением в соответствии с платформой, например, ".so" в Unix, ".dylib" в macOS и iOS, и ".dll" в Windows. (См. fileName.)

QLibrary::QLibrary(QObject *parent = nullptr)

Конструирует библиотеку с заданным parent.

[virtual] QLibrary::~QLibrary()

Удаляет объект QLibrary.

Если unload() не вызывался явно, библиотека остается в памяти до завершения приложения.

См. также isLoaded() и unload().

QString QLibrary::errorString() const

Возвращает строку текста с описанием последней произошедшей ошибки. В настоящее время errorString будет установлен только в том случае, если load(), unload() или resolve() по какой-то причине завершились неудачно.

[static] bool QLibrary::isLibrary(const QString &fileName)

Возвращает true если fileName имеет допустимое расширение для загружаемой библиотеки; в противном случае возвращает false.

Конечные номера версий в Unix игнорируются.

bool QLibrary::isLoaded() const

Возвращает true если библиотека загружена; в противном случае возвращает false.

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

bool QLibrary::load()

Загружает библиотеку и возвращает true если библиотека была загружена успешно; в противном случае возвращает false. Так как resolve() всегда вызывает эту функцию перед разрешением каких-либо символов, нет необходимости вызывать ее явно. В некоторых ситуациях вам может потребоваться загрузить библиотеку заранее, в этом случае вы используете эту функцию.

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

QFunctionPointer QLibrary::resolve(const char *symbol)

Возвращает адрес экспортированного символа symbol. Библиотека загружается при необходимости. Функция возвращает nullptr если символ не удалось разрешить или если библиотеку не удалось загрузить.

Пример:

typedef int (*AvgFunction)(int, int);

AvgFunction avg = (AvgFunction) library->resolve("avg");
if (avg)
    return avg(5, 8);
else
    return -1;

Символ должен быть экспортирован как функция C из библиотеки. Это означает, что функция должна быть обернута в extern "C" если библиотека скомпилирована с помощью компилятора C++. В Windows также необходимо явно экспортировать функцию из DLL, используя директиву компилятора __declspec(dllexport), например:

extern "C" MY_EXPORT int avg(int a, int b)
{
    return (a + b) / 2;
}

где MY_EXPORT определено как

#ifdef Q_OS_WIN
#define MY_EXPORT __declspec(dllexport)
#else
#define MY_EXPORT
#endif

[static] QFunctionPointer QLibrary::resolve(const QString &fileName, const char *symbol)

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

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

Функция возвращает nullptr если символ не удалось разрешить или если библиотеку не удалось загрузить.

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

[static] QFunctionPointer QLibrary::resolve(const QString &fileName, int verNum, const char *symbol)

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

Загружает библиотеку fileName с номером основной версии verNum и возвращает адрес экспортированного символа symbol. Обратите внимание, что fileName не должно включать платформозависимый суффикс файла; (см. fileName). Библиотека остается загруженной до завершения работы приложения. verNum игнорируется в Windows.

Функция возвращает nullptr если символ не был разрешен или библиотека не смогла загрузиться.

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

[static] QFunctionPointer QLibrary::resolve(const QString &fileName, const QString &version, const char *symbol)

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

Загружает библиотеку fileName с полным номером версии version и возвращает адрес экспортированного символа symbol. Обратите внимание, что fileName не должно включать платформозависимый суффикс файла; (см. fileName). Библиотека остается загруженной до завершения работы приложения. version игнорируется в Windows.

Функция возвращает nullptr если символ не был разрешен или библиотека не смогла загрузиться.

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

void QLibrary::setFileNameAndVersion(const QString &fileName, int versionNumber)

Устанавливает свойство fileName и номер основной версии соответственно на fileName и versionNumber. versionNumber игнорируется в Windows.

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

void QLibrary::setFileNameAndVersion(const QString &fileName, const QString &version)

Устанавливает свойство fileName и полный номер версии соответственно на fileName и version. Параметр version игнорируется в Windows.

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

bool QLibrary::unload()

Выгружает библиотеку и возвращает true если библиотека была выгружена; в противном случае возвращает false.

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

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

Обратите внимание, что на Mac OS X 10.3 (Panther) динамические библиотеки не могут быть выгружены.

См. также resolve() и load().