class QLibrary#

QLibrary 类在运行时加载共享库。更多…

摘要#

属性#

fileName - 库的文件名
loadHints - 向 load() 函数提供一些提示，以说明其应如何行为

方法#

def __init__()
def errorString()
def fileName()
def isLoaded()
def load()
def loadHints()
定义 resolve()
定义 setFileName()
定义 setFileNameAndVersion()
定义 setLoadHints()
定义 unload()

静态函数#

定义 isLibrary()
定义 resolve()

注意

本文档可能包含从 C++ 自动翻译到 Python 的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 上创建工单来告知我们。

详细说明#

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能存在错误。

一个 QLibrary 对象在单个共享对象文件（我们称之为“库”，但也可称为“DLL”）上操作。一个 QLibrary 以平台无关的方式提供了对库中功能的访问。您可以在构造函数中传递一个文件名，或者使用 setFileName() 显式设置它。当加载库时，如果文件名没有绝对路径，QLibrary 会在所有系统特定的库位置（例如，Unix 上的 LD_LIBRARY_PATH）中搜索。

如果文件名是绝对路径，则尝试先加载此路径。如果找不到文件，QLibrary 将尝试使用不同的平台特定文件前缀（例如，Unix 和 Mac 上的“lib”）和后缀（例如，Unix 上的“`.so`”、Mac 上的“`.dylib`”或 Windows 上的“`.dll`”）。

如果文件路径不是绝对的，那么 QLibrary 会修改搜索顺序，首先尝试系统特定的前缀和后缀，然后尝试指定的文件路径。

这使得可以指定只通过其基本名（即未带后缀）识别的共享库，因此在不同的操作系统中相同的代码可以工作，同时还能最小化查找库的尝试次数。

最重要的功能包括：load() 用以动态加载库文件，isLoaded() 检查加载是否成功，以及 resolve() 用于解析库中的符号。如果库尚未加载，resolve() 函数会尝试加载数据库。可以使用多个 QLibrary 实例来访问相同的物理库。一旦加载，库将保持在内存中，直到应用程序终止。你可以尝试使用 unload() 卸载库，但如果其他 QLibrary 实例正在使用同一库，调用将失败，且卸载只会在每个实例都调用 unload() 的情况下发生。

QLibrary 的典型用例是解析库中的导出符号，并调用该符号所表示的 C 函数。这被称为“显式链接”，与在构建过程链接可执行文件时由链接步骤执行的“隐式链接”相对。

以下代码片段加载一个库，解析符号“mysymbol”，在一切成功的情况下调用该函数。如果出错，例如库文件不存在或符号未定义，函数指针将为 None 且不会调用。

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

要使 resolve() 起作用，符号必须从库中作为 C 函数导出。这意味着如果库是用 C++ 编译器编译的，该函数必须封装在 extern "C" 块中。在 Windows 上，还需要使用 dllexport 宏；有关如何进行的详细信息，请参阅 resolve()。为了方便起见，有一个静态的 resolve() 函数，如果你只是想调用库中的函数而不首先显式加载库，可以使用它。

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

另请参阅

QPluginLoader

class LoadHint#

(inherits enum.Flag) 此枚举描述了可以用来更改加载库时处理方式的可能提示。这些值指示在加载库时符号是如何解析的，并使用 setLoadHints() 函数指定。

常量

描述

QLibrary.ResolveAllSymbolsHint

在加载时解决库中的所有符号，而不仅仅是调用 resolve() 时解决。

QLibrary.ExportExternalSymbolsHint

导出库中的未解决和外部符号，以便在随后加载的动态库中解决。

QLibrary.LoadArchiveMemberHint

允许库的文件名指定归档文件中的一个特定对象文件。如果提供了此提示，库的文件名由一个路径组成，该路径指向归档文件，后跟归档成员的引用。

QLibrary.PreventUnloadHint

防止在调用 close() 时将库从地址空间卸载。如果稍后调用 open()，则不会重新初始化库的静态变量。

QLibrary.DeepBindHint

指示链接器在解决库中外部符号时，优先使用加载库中的定义，而不是加载应用程序中导出的定义。此选项仅在 Linux 上受支持。

另请参阅

loadHints

常量	描述
QLibrary.ResolveAllSymbolsHint	在加载时解决库中的所有符号，而不仅仅是调用 `resolve()` 时解决。
QLibrary.ExportExternalSymbolsHint	导出库中的未解决和外部符号，以便在随后加载的动态库中解决。
QLibrary.LoadArchiveMemberHint	允许库的文件名指定归档文件中的一个特定对象文件。如果提供了此提示，库的文件名由一个路径组成，该路径指向归档文件，后跟归档成员的引用。
QLibrary.PreventUnloadHint	防止在调用 close() 时将库从地址空间卸载。如果稍后调用 open()，则不会重新初始化库的静态变量。
QLibrary.DeepBindHint	指示链接器在解决库中外部符号时，优先使用加载库中的定义，而不是加载应用程序中导出的定义。此选项仅在 Linux 上受支持。

class LoadStatusTag#

注意

可以直接在 from __feature__ import true_property 使用时使用属性，否则通过访问函数进行使用。

property fileName: str#

此属性持有库的文件名。

建议在文件名中省略文件的扩展名，因为 QLibrary 将自动查找具有适当扩展名的文件（请参阅 isLibrary() ）。

在加载库时，QLibrary 寻找所有系统特定的库位置（例如，Unix 上的 LD_LIBRARY_PATH），除非文件名具有绝对路径。库成功加载后，fileName() 返回库的完全限定文件名，包括承包在构造函数或传递给 setFileName() 的完整路径。

例如，在 Unix 平台上成功加载 “GL” 库后，fileName() 将返回 “libGL.so”。如果文件名最初传递为 “/usr/lib/libGL”，fileName() 将返回 “/usr/lib/libGL.so”。

访问函数

fileName()
setFileName()

property loadHints: Combination.of.QLibrary.LoadHint#

此属性包含提供给 load() 函数的关于其行为的某些提示。

您可以为如何解析符号提供一些提示。通常，符号不会在加载时解析，而是在懒惰模式下解析（即在调用 resolve() 方法时）。如果您将加载提示设置为 ResolveAllSymbolsHint ，则如果平台支持，则将在加载时解析所有符号。

设置 ExportExternalSymbolsHint 将使库中的外部符号可供后续加载的库解析。

如果设置了 LoadArchiveMemberHint ，则文件名由两个组件组成：一个路径，该路径是存档文件的引用，后跟第二个组件，该组件是存档成员的引用。例如，fileName libGL.a(shr_64.o) 将指向名为 libGL.a 的存档文件中的库 shr_64.o。此功能仅在 AIX 平台受支持。

加载提示的解释取决于平台，如果您使用它，您可能是在对编译平台做出假设，因此仅在您了解其后果时使用它们。

默认情况下，不设置这些标志，因此库将以懒惰符号解析的方式加载，并且不会将外部符号导出以供其他动态加载的库解析。

注意

只有在此对象未关联到文件时才能清除提示。只有在设置文件名后才能添加提示（《提示》将与旧提示进行或运算）。

注意

加载库后设置此属性不会产生影响，loadHints() 不会反映这些更改。

注意

此属性在所有引用同一库的 QLibrary 实例之间共享。

访问函数

loadHints()
setLoadHints()

__init__(fileName[, parent=None])#

参数：

fileName – 字符串
parent – QObject

使用指定的 fileName 构造库对象，并加载指定的库，其中包含给定的 parent 。

我们建议在 fileName 中省略文件的扩展名，因为 QLibrary 将根据平台自动查找带有适当后缀的文件，例如 Unix 上的 “.so”，macOS 和 iOS 上的 “.dylib”，以及 Windows 上的 “.dll”。（见 fileName 。）

__init__(fileName, version[, parent=None])

参数：

fileName – 字符串
version – str
parent – QObject

使用给定的 parent 构造一个库对象，将加载数据库，由 fileName 和完整版本号 version 指定。当前，在 Windows 上版本号被忽略。

__init__(fileName, verNum[, parent=None])

参数：

fileName – 字符串
verNum – int
parent – QObject

使用给定的 parent 构造一个库对象，将加载数据库，由 fileName 和主版本号 verNum 指定。当前，在 Windows 上版本号被忽略。

__init__([parent=None])

参数：: parent – QObject

使用给定的 parent 构造库。

errorString()#

返回类型:: str

返回描述最后发生的错误的文本字符串。当前，只有在 load() 、 unload() 或 resolve() 操作失败的情况下，errorString 才会被设置。

fileName()#

返回类型:: str

另请参阅

setFileName()

属性 fileNameᅟ 的获取。

static isLibrary(fileName)#

参数：: fileName – 字符串
返回类型:: bool

如果 fileName 有有效的库后缀则返回 true；否则返回 false。

平台

有效的后缀

Windows

.dll, .DLL

Unix/Linux

.so

AIX

.a

HP-UX

.sl, .so（HP-UXi）

macOS 和 iOS

.dylib, .bundle, .so

平台	有效的后缀
Windows	`.dll`, `.DLL`
Unix/Linux	`.so`
AIX	`.a`
HP-UX	`.sl`, `.so`（HP-UXi）
macOS 和 iOS	`.dylib`, `.bundle`, `.so`

Unix中的尾随版本号被忽略。

isLoaded()#

返回类型:: bool

如果load() 成功，则返回 true；否则返回 false。

注意

在Qt 6.6之前，如果同一库中的另一个 QLibrary 对象导致其被加载，即使没有调用 load()，此函数也会返回 true。

另请参阅

load()

load()#

返回类型:: bool

加载库并返回 true，如果库已成功加载，否则返回 false。由于 resolve() 总是调用此函数来解析其自身未知的符号，因此通常不需要显式调用它。在某些情况下，您可能希望在预处理时加载库，这种情况下您会使用此函数。

另请参阅

unload()

loadHints()#

返回类型:: LoadHint 的组合

另请参阅

setLoadHints()

属性 loadHintsᅟ 的获取器。

static resolve(fileName, version, symbol)#

参数：

fileName – 字符串
version – str
symbol – str

返回类型:

QFunctionPointer

这是一个重载的函数。

使用完整的版本号 version 加载库 fileName 并返回导出符号 symbol 的地址。请注意，fileName 不应包含平台特定的文件后缀；（见 fileName）。直到应用程序退出，库继续加载。在Windows上忽略 version。

如果符号无法解析或库无法加载，则函数返回 None。

另请参阅

resolve()

static resolve(fileName, symbol)

参数：

fileName – 字符串
symbol – str

返回类型:

QFunctionPointer

这是一个重载的函数。

加载库 fileName 并返回导出符号 symbol 的地址。注意，fileName 不应包含平台特定的文件后缀；（参见 fileName）。库在应用程序退出之前保持加载状态。

如果符号无法解析或库无法加载，则函数返回 None。

另请参阅

resolve()

static resolve(fileName, verNum, symbol)

参数：

fileName – 字符串
verNum – int
symbol – str

返回类型:

QFunctionPointer

这是一个重载的函数。

加载主版本号为 verNum 的库 fileName 并返回导出符号 symbol 的地址。注意，fileName 不应包含平台特定的文件后缀；（参见 fileName）。库在应用程序退出之前保持加载状态。在 Windows 上，verNum 被忽略。

如果符号无法解析或库无法加载，则函数返回 None。

另请参阅

resolve()

resolve(symbol)

参数：: symbol – str
返回类型:: QFunctionPointer

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能存在错误。

返回导出符号 symbol 的地址。如果需要则加载库。如果符号无法解析或库无法加载，则函数返回 None。

示例

typedef int (AvgFunction)(int, int)
avg = (AvgFunction) library.resolve("avg")
if avg:
    return avg(5, 8)
else:
    return -1

符号必须作为库中的 C 函数导出。这意味着如果库是用 C++ 编译器编译的，则函数必须用 extern "C" 包装。在 Windows 上，您还必须使用 __declspec(dllexport) 编译器指令显式地从 DLL 中导出函数，例如

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

setFileName(fileName)#

参数：: fileName – 字符串

另请参阅

fileName()

属性的设置器 fileNameᅟ。

setFileNameAndVersion(fileName, version)#

参数：

fileName – 字符串
version – str

将属性 fileName 和完整版本号分别设置为 fileName 和 version。在 Windows 上，version 参数被忽略。

另请参阅

setFileName()

setFileNameAndVersion(fileName, verNum)

参数：

fileName – 字符串
verNum – int

将属性 fileName 和主版本号分别设置为 fileName 和 versionNumber。在 Windows 上，versionNumber 被忽略。

另请参阅

setFileName()

setLoadHints(hints)#

参数：: hints – combines LoadHint

另请参阅

loadHints()

设置属性 loadHints 的调用者。

unload()#

返回类型:: bool

卸载库，如果库可以被卸载，则返回 true；否则返回 false。

在应用程序终止时，这会发生自动，所以通常你不需要调用此函数。

如果其他 QLibrary 实例正在使用相同的库，调用将失败，卸载只会在每个实例都调用 unload() 时发生。

请注意，在 macOS 上，无法卸载动态库。 QLibrary::unload() 将返回 true，但库将保留在进程中的加载状态。

另请参阅

resolve() load()