Класс QLibrary

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

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

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

Типы public

Свойства

• fileName : QString
• loadHints : LoadHints

Функции public

Статические public члены

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

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

Если имя файла — абсолютный путь, сначала предпринимается попытка загрузить его по этому пути. Если файл не найден, QLibrary пытается найти его с помощью различных платформенно-зависимых префиксов имени файла (например, «lib» в Unix и macOS) и суффиксов (например, «.so» в Unix, «.dylib» в macOS или «.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() по какой-либо причине завершатся неудачно.

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

[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 в случае, если символ не удалось разрешить или библиотеку не удалось загрузить.

Функция была добавлена в Qt 4.4.

См. также 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.

Функция была добавлена в Qt 4.4.

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

bool QLibrary::unload()

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

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

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

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

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