PySide6.QtCore.QLibrary¶

class QLibrary¶

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

概要¶

属性¶

fileNameᅟ - 库的文件名
loadHintsᅟ - 为load()函数提供一些关于其行为方式的提示

方法¶

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

注意

本文档可能包含从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()

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

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

另请参阅

QPluginLoader

class LoadHint¶

(继承自 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”。

Access functions:

fileName()
setFileName()

property loadHintsᅟ: Combination of QLibrary.LoadHint¶

此属性为 load() 函数提供一些关于其应如何行为的提示。

你可以提供一些关于符号如何解析的提示。通常，符号不会在加载时解析，而是延迟解析（即当调用resolve()时）。如果你将loadHints设置为ResolveAllSymbolsHint，那么如果平台支持，所有符号将在加载时解析。

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

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

负载提示的解释依赖于平台，如果你使用它，你可能正在对编译的平台做出一些假设，因此只有在理解其后果的情况下才使用它们。

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

注意

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

注意

在库加载后设置此属性无效，loadHints() 将不会反映这些更改。

注意

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

Access functions:

loadHints()
setLoadHints()

__init__([parent=None])¶

Parameters:: 父对象 – QObject

使用给定的parent构建一个库。

__init__(fileName[, parent=None])

Parameters:

fileName – str
parent – QObject

使用给定的parent构造一个库对象，该对象将加载由fileName指定的库。

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

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

Parameters:

fileName – str
version – str
parent – QObject

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

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

Parameters:

fileName – str
verNum – int
parent – QObject

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

errorString()¶

Return type:: 字符串

返回一个包含最后发生错误的描述文本字符串。目前，errorString 仅在 load()、unload() 或 resolve() 由于某种原因失败时才会被设置。

fileName()¶

Return type:: 字符串

另请参阅

setFileName()

属性 fileNameᅟ 的获取器。

static isLibrary(fileName)¶

Parameters:: fileName – str
Return type:: 布尔

如果 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()¶

Return type:: 布尔

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

注意

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

另请参阅

load()

load()¶

Return type:: 布尔

加载库并在库成功加载时返回true；否则返回false。由于resolve()在解析任何符号之前总是调用此函数，因此不需要显式调用它。在某些情况下，您可能希望提前加载库，这时您将使用此函数。

另请参阅

unload()

loadHints()¶

Return type:: LoadHint 的组合

另请参阅

setLoadHints()

属性 loadHintsᅟ 的获取器。

resolve(symbol)¶

Parameters:: symbol – str
Return type:: 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

static resolve(fileName, symbol)

Parameters:

fileName – str
symbol – str

Return type:

QFunctionPointer

这是一个重载函数。

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

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

另请参阅

resolve()

static resolve(fileName, version, symbol)

Parameters:

fileName – str
version – str
symbol – str

Return type:

QFunctionPointer

这是一个重载函数。

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

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

另请参阅

resolve()

static resolve(fileName, verNum, symbol)

Parameters:

fileName – str
verNum – int
symbol – str

Return type:

QFunctionPointer

这是一个重载函数。

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

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

另请参阅

resolve()

setFileName(fileName)¶

Parameters:: fileName – str

另请参阅

fileName()

属性 fileNameᅟ 的设置器。

setFileNameAndVersion(fileName, version)¶

Parameters:

fileName – str
version – str

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

另请参阅

setFileName()

setFileNameAndVersion(fileName, verNum)

Parameters:

fileName – str
verNum – int

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

另请参阅

setFileName()

setLoadHints(hints)¶

Parameters:: 提示 – LoadHint 的组合

另请参阅

loadHints()

属性 loadHintsᅟ 的设置器。

unload()¶

Return type:: 布尔

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

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

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

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

另请参阅

resolve() load()