Класс QLibrary

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

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

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

Типы

Свойства

• fileName : QString
• loadHints : LoadHints

• 1 свойство унаследовано от QObject

Открытые функции

• 32 открытых функций унаследованы от QObject

Статические открытые члены

• 11 статических открытых членов унаследованы от QObject

Дополнительные унаследованные члены

• 1 открытый слот унаследован от QObject
• 2 сигналов унаследовано от QObject
• 9 защищенных функций унаследованы от QObject

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

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

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

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

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

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

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

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

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

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(QObject *parent = nullptr)

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

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

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

Рекомендуется опускать расширение файла в 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, const QString &version, QObject *parent = nullptr)

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

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

[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. Библиотека загружается при необходимости. Функция возвращает 0, если символ не удалось разрешить или библиотеку не удалось загрузить.

Пример:

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). Библиотека остается загруженной до завершения работы приложения.

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

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

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

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

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

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

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

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

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

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

Функция была добавлена в 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().