Класс 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 = Q_NULLPTR)

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

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

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

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

QLibrary::QLibrary(const QString &fileName, int verNum, QObject *parent = Q_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 = Q_NULLPTR)

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

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

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.

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

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