FSUtil

FSUtil 对象提供了一些用于处理文件系统的实用方法。它使用 DOpus.FSUtil 方法获取。

方法名称

参数

返回值类型

描述

CancelWatchChanges

<string:id>

none

取消之前通过调用 WatchChanges 方法建立的文件夹或文件更改监视。id 参数是在创建监视器时分配给监视器的 ID。

ComparePath

<string:path1> <string:path2> <string:flags>

bool

比较提供的两个路径字符串是否相等 - 如果两个路径相等，则返回 True，否则返回 False。

可选的 flags 参数允许您修改比较行为。此参数是一个字符串，其中包含以下一个或多个字母（区分大小写）：

使路径比较 区分大小写。

如果 path2 等于或为 path1 的父级，则返回 True。

DisplayName

<string:path> <string:flags>

string

检索路径的显示名称。这是路径的形式，旨在显示给用户，而不是 Opus 内部使用。例如，对于库路径，它将剥离 Opus 用于标识库成员文件夹的内部 ?xxxxxxx 符号。

可选的 flags 参数允许您修改行为。此参数是一个字符串，其中包含以下一个或多个字母（区分大小写）：

用于编辑（返回一个用于编辑而不是显示的字符串）

文件部分（返回显示文件名而不是整个路径）

解析（将库路径解析到其底层文件系统文件夹）

Drives

none

Vector:Drive

返回一个 Vector，其中包含 Drive 对象，每个对象对应系统上的一个驱动器。

使路径比较 区分大小写。

如果 path2 等于或为 path1 的父级，则返回 True。

DisplayName

用于编辑（返回一个用于编辑而不是显示的字符串）

文件部分（返回显示文件名而不是整个路径）

解析（将库路径解析到其底层文件系统文件夹）

Drives

Exists

<string:path> <string:flags>

bool

如果指定的文件、文件夹或设备存在，则返回 True，否则返回 False。

可选的 flags 参数可以设置为 w 以在最终路径组件中使用通配符。

GetADSNames

<string:path>

object:StringSet

返回一个 StringSet ，其中包含为指定文件或文件夹找到的任何备用数据流 (ADS) 的名称。

GetErrorMsg

<int:error>

string

返回系统错误代码的本地化文本描述。

GetFolderPair

<string:path> <string:flags>

object:PairedFolder

返回指定文件夹的对，如果存在。可选的标志与为对配置的选项进行比较；它们允许您控制在哪些条件下返回对，以及在配对文件夹不存在时如何处理它。

默认双栏文件夹

默认导航锁定目标

自动打开导航锁定

默认同步目标

始终在左侧/顶部显示主文件夹

使用路径，即使它不存在

忽略对

上移到第一个存在的父级

GetItem

<string:path>

object:Item

为指定的 filepath 创建一个 Item 对象。

默认双栏文件夹

默认导航锁定目标

自动打开导航锁定

默认同步目标

始终在左侧/顶部显示主文件夹

使用路径，即使它不存在

忽略对

上移到第一个存在的父级

GetItem

GetMetadata

<string:path>

object:Metadata

返回一个 Metadata 对象，该对象表示指定文件的元数据。

GetShellProperty

<string:path>

<string:property> 或 <Map:properties> <string:type>

variant

返回指定文件的一个或多个 shell 属性的值。

文件路径必须作为第一个参数提供。

第二个参数可以是要检索的属性的名称（或 PKEY），在这种情况下，将返回属性值。

或者，第二个参数可以是 Map 对象，它允许您一次检索多个属性。您要检索的每个属性都应使用其名称作为键添加到 Map 中，并使用空字符串作为其值。Map 中的值将被属性值替换。

可选的 type 参数是一个字符串，它允许您控制属性是如何按名称查找的（不区分大小写）：

将使用第一个其原始名称匹配的属性。

将使用第一个其显示名称匹配的属性。

如果没有指定，原始名称和显示名称都可以匹配。请注意，如果 shell 属性由系统作为 SAFEARRAY 类型返回，它将自动转换为 Vector 对象。

将使用第一个其原始名称匹配的属性。

将使用第一个其显示名称匹配的属性。

GetShellPropertyList

<string:pattern> <string:type>

object:ShellProperty

返回一个 Vector ，其中包含 ShellProperty 对象，这些对象表示系统上可用的所有可能的 shell 属性。

您可以选择提供一个通配符 pattern 作为第一个参数 - 如果这样做，则只会返回名称与提供的模式匹配的属性。

可选的 type 参数是一个字符串，它允许您进一步限制属性列表（不区分大小写）：

属性原始名称必须与模式匹配。

属性显示名称必须与模式匹配。

如果没有指定，原始名称和显示名称都可以匹配。

type 参数支持的附加标志是：

仅限于可查看属性。可查看属性是那些旨在向用户显示的属性 - 它们与资源管理器列选择器 UI 中显示的属性相同。

GetSignature

<string:path> [<bool:verify> 或 <string:flags>]

object:Signature

对于使用 Authenticode 证书签名的文件（通常是 .exe 和 .dll 文件），返回一个 Signature 对象，该对象描述用于签署该文件的签名。

默认情况下，签名不会被验证 - 该方法只会简单地提取并返回有关它的信息。可选的 verify 参数允许您验证文件的完整性。将此值设置为 True 以执行简单的哈希检查（验证文件未被修改，但不检查签名），或使用以下标志来验证签名以及检查文件。

无吊销检查

检查链中最终证书的吊销

检查整个链的吊销

检查整个链，不包括根证书

仅哈希检查

在证书时间戳过期后将证书视为已过期

GetTempDirPath

<int:lifetime>

object:Path

创建一个临时文件夹（具有唯一的名称）并返回指向它的路径，在一个 Path 对象中。使用此方法创建的临时文件夹具有有限的生命周期，在此之后 Opus 将自动删除它们（它还将在关闭和重新启动时清理它们）。默认生命周期为 20 分钟；您可以使用可选参数更改它。

属性原始名称必须与模式匹配。

属性显示名称必须与模式匹配。

仅限于可查看属性。可查看属性是那些旨在向用户显示的属性 - 它们与资源管理器列选择器 UI 中显示的属性相同。

GetSignature

无吊销检查

检查链中最终证书的吊销

检查整个链的吊销

检查整个链，不包括根证书

仅哈希检查

在证书时间戳过期后将证书视为已过期

GetTempDirPath

GetTempFile

<string:suffix> <string:prefix> <string:flags> <object:window>

object:File

创建一个临时文件并返回一个 File 对象，该对象准备写入。

返回的对象支持读取和写入，无需再次打开文件（尽管您可以这样做，如果这样做更简单）。

您可以使用 File.path 属性获取文件的名称。

可以指定一个可选的文件名 suffix；如果没有提供（或传递了空字符串），则默认为 ".tmp"。

还可以指定一个可选的 prefix；如果没有提供（或传递了空字符串），则默认为 "dop"。

在后缀和前缀之间，Opus 将在名称中插入其它字符以确保其唯一性。

例如，DOpus.FSUtil.GetTempFilePath(".txt","cat-") 可能会为文件路径生成 C:\Users\Leo\AppData\Local\Temp\cat-202106230928470962.txt。

可选的 flags 参数可以包含以下一个或多个字母（不区分大小写）：

delete-on-close。文件将在关闭时自动删除。

允许删除。其它进程可以删除文件。

可读共享。其它进程可以读取文件。

可写共享。其它进程可以写入文件。

读、写和删除共享模式影响其它进程在文件仍然打开时允许执行的操作。一旦文件关闭（假设它没有自动删除），其它进程总是可以自由地读取、写入或删除文件。

当使用 delete-on-close 时，其它事物可能无法打开文件，除非他们在打开文件时明确允许删除文件。

可选的 window 参数允许您将 File 对象与 Tab 或 文件窗口 关联，这些对象将在 Opus 需要显示任何对话框时使用（例如，UAC 提升对话框）。

delete-on-close。文件将在关闭时自动删除。

允许删除。其它进程可以删除文件。

可读共享。其它进程可以读取文件。

可写共享。其它进程可以写入文件。

GetTempFilePath

<string:suffix> <string:prefix>

object:Path

创建一个临时文件（具有唯一的名称）并返回指向它的路径，在一个 Path 对象中。

可以指定一个可选的文件名 suffix；如果没有提供（或传递了空字符串），则默认为 ".tmp"。

还可以指定一个可选的 prefix；如果没有提供（或传递了空字符串），则默认为 "dop"。

在后缀和前缀之间，Opus 将在名称中插入其它字符以确保其唯一性。

例如，DOpus.FSUtil.GetTempFilePath(".txt","cat-") 可能会为文件路径生成 C:\Users\Leo\AppData\Local\Temp\cat-202106230928470962.txt。

GetType

<string:path> <string:flags>

string

返回一个字符串，指示指定文件路径的项目类型。如果路径不存在，字符串将为 file、dir 或 invalid。

可选的 flags 参数用于控制对档案的行为。通常，档案将被报告为 dir，但是如果您为 flags 参数指定 "a"，它将被报告为 file。

此方法不同于 PathType，PathType 会告诉您底层的“命名空间”类型，而不是仅仅是文件还是文件夹。

Hash

<string:path> 或 <object:Blob>

<string:type>

string 或 object:Vector

计算指定文件或 Blob 的校验和。默认情况下，将计算 MD5 哈希，但您可以使用可选的 type 参数更改哈希/校验和算法。有效值为（不区分大小写）md5、blake3、sha1、sha256、sha512、crc32、crc32_php 和 crc32_php_rev。

您还可以同时指定多个类型（例如，"md5,sha1,sha256"），在这种情况下，将同时计算指定的校验和，并将结果作为 string 的 Vector 返回（按您请求的顺序）。

与其它算法不同，CRC32 是一个概念，而不是一个定义明确的标准。我们提供了您最有可能遇到的三种 CRC32 实现：

CRC32 在 Windows 世界中最常见，与 7-Zip 和 PKZip 等工具称为“CRC32”以及 PHP 称为“CRC32b”相匹配。
CRC32_PHP 比较少见，与 BZIP2 使用的以及 PHP 默认输出的相匹配。
CRC32_PHP_REV 与 CRC32_PHP 相同，但结果的字节顺序相反，如某些工具输出的那样。

示例 (VBScript):

DOpus.FSUtil.Hash("C:\Windows\Notepad.exe","md5")

NewFileAttr

<attributes>

object:FileAttr

创建一个新的 FileAttr 对象，它表示文件属性。

您可以通过传递一个字符串来初始化新对象，该字符串表示要打开的属性（例如，"hsr"），或传递另一个 FileAttr 对象。如果您不传递值，新对象将默认所有属性都关闭。

NewFileSize

<size> 或 <string:"s"> <size>

object:FileSize

创建一个新的 FileSize 对象，它使处理 64 位文件大小变得更容易。

您可以使用多种数据类型（int、string、decimal、currency、另一个 FileSize 对象，或包含恰好 1、2、4 或 8 个字节的 Blob）来初始化它。您可以通过在前面添加 $ 或 0x 来使用十六进制字符串。

示例 (VBScript):

DOpus.FSUtil.NewFileSize(1024)

当只指定大小时，结果将是 无符号 值，这意味着它可以表示更大的大小值，但不能表示负值。

要改为创建一个 有符号 值，请将 "s" 指定为第一个参数，并将大小指定为第二个参数。这区分大小写；它必须是小写字母 "s"。

示例 (VBScript):

DOpus.FSUtil.NewFileSize("s", -1024)

NewPath

<string:path>

object:Path

创建一个新的 Path 对象，初始化为提供的路径字符串。

NewWild

<string:pattern> <string:flags>

object:Wild

创建一个新的 Wild 对象。

如果提供了 pattern 和 flags，则将自动解析模式；否则，您必须在使用返回的对象之前调用其 Parse 方法。

有关有效标志的列表，请参见 Wild.Parse 方法的描述。

OpenFile

<string:path> 或 <object:Blob> <string:mode> <object:window> 或 <string:elevation>

object:File

打开或创建文件并返回一个 File 对象，该对象允许您将文件内容作为二进制数据访问。

始终返回一个 File 对象，即使文件无法打开。在创建返回的对象后立即检查 File.error，以查看是否成功打开了文件。

即使文件未打开，返回对象的一些方法可能仍然有效。例如，如果文件存在但权限阻止您打开它，您仍然可以更改其属性，反之亦然。

第一个参数可以是：

一个字符串或 Path 对象，指定要打开的文件。
一个现有的 Blob 对象，用于创建一个 File 对象，该对象提供对内存块的读/写流访问。

当打开一个 Blob 时，创建的对象将始终处于 读写模式，并且其余参数（mode 和 window/elevation）不会使用，也不需要指定。

当打开文件时，可选的 mode 参数指定如何打开它（区分大小写）：

读取模式。文件可以读取但不能写入。（这是默认设置。）

写入模式。文件可以写入，但不能读取。

读写模式。文件可以从同一个对象读写。

当以 写入模式 或 读写模式 打开时，您可以指定其它 mode 标志来控制如何创建或打开文件（区分大小写）：

仅当文件不存在时才创建新文件。如果文件已经存在，则调用将失败。

始终创建新文件。如果文件已经存在，它将被覆盖，即被截断为零长度。（如果在 w 或 rw 本身上使用，这是默认设置。）

打开现有文件。如果文件不存在，则调用将失败。

打开现有文件。如果文件不存在，则会创建它。

截断现有文件。如果文件存在，它将被截断为零长度。如果文件不存在，则调用将失败。

mode 标志还可以包含以下字母（区分大小写）：

Delete-on-close。文件将在关闭时自动删除。（如果其它事物也打开了文件，它将不会被删除，直到所有事物都关闭它。）

强制。如果 Opus 阻止以写入方式打开文件，则 Opus 将清除文件的只读属性；否则，尝试以写入方式打开只读文件将失败。例如，"wof" 类似于 "wo" 模式，但也清除只读属性。

修改模式。如果您想使用 File 对象读取或修改文件的属性，或获取文件的大小，而不读取或写入实际的文件内容，请使用它。

允许删除。其它进程可以在文件关闭之前删除它，但任何删除操作都不会在它关闭之前进行。通过这种方法打开的文件总是允许其它读取器和写入器。

（Opus 13.9.1 及更高版本。）（小写 x。）排除其它读取器。当您打开文件时，其它任何事物都无法以读取方式打开它。如果其它事物已经以读取方式打开它，您请求打开文件的请求将失败。对不支持它的文件系统没有影响。

（Opus 13.9.1 及更高版本。）（大写 X。）排除其它写入器。当您打开文件时，其它任何事物都无法以写入方式打开它。如果其它事物已经以写入方式打开它，您请求打开文件的请求将失败。对不支持它的文件系统没有影响。

当打开一个现有的文件，而其它事物已经标记为要删除时，包括已经以 delete-on-close 模式打开的文件，必须指定 p（允许删除）标志。

非 Windows 文件系统可能具有不同的锁定和共享规则。Opus 会将请求的标志传递给它们，但最终它们的行为方式取决于它们。

可选的第三个参数接收一个 window 对象或一个指示 elevation 模式的字符串。此参数影响在打开文件时可能触发的 UAC 提升提示（以及可能的其它用户界面元素）的行为。它可以是以下之一：

一个 Opus Tab 或 文件窗口 对象，如果需要提升并且尚未获得提升，则 UAC 提示将显示在该对象上。
字符串 "NoElevate"，以完全防止在打开此文件时进行 UAC 提升。
字符串 "ElevateNoAsk"，以防止 UAC 提示，但如果其它事物已经获得了提升，则仍然获得提升（例如，之前的 OpenFile 调用）。

示例 (VBScript):

Set F = DOpus.FSUtil.OpenFile("C:\Test.txt","wrcf","NoElevate")

读取模式。文件可以读取但不能写入。（这是默认设置。）

写入模式。文件可以写入，但不能读取。

读写模式。文件可以从同一个对象读写。

仅当文件不存在时才创建新文件。如果文件已经存在，则调用将失败。

始终创建新文件。如果文件已经存在，它将被覆盖，即被截断为零长度。（如果在 w 或 rw 本身上使用，这是默认设置。）

打开现有文件。如果文件不存在，则调用将失败。

打开现有文件。如果文件不存在，则会创建它。

截断现有文件。如果文件存在，它将被截断为零长度。如果文件不存在，则调用将失败。

Delete-on-close。文件将在关闭时自动删除。（如果其它事物也打开了文件，它将不会被删除，直到所有事物都关闭它。）

修改模式。如果您想使用 File 对象读取或修改文件的属性，或获取文件的大小，而不读取或写入实际的文件内容，请使用它。

允许删除。其它进程可以在文件关闭之前删除它，但任何删除操作都不会在它关闭之前进行。通过这种方法打开的文件总是允许其它读取器和写入器。

PathType

<string:path>

string

返回一个字符串，指示指定文件路径的底层“命名空间”类型。可能的值是：

shell

路径指的是 Windows shell - 例如，类似“此电脑”的虚拟文件夹

filesys

路径是真实文件系统路径 - 例如，C:\Windows

ftp

路径是 FTP 路径

zip

路径是 zip 文件

mtp

路径是 MTP 路径（即便携式设备，如手机或平板电脑）

lib

路径是库

coll

路径是集合

plugin

路径是插件提供的命名空间，很可能是档案（但不是 Zip）

此方法不同于 GetType，GetType 会告诉您某事物是文件还是目录。

shell

路径指的是 Windows shell - 例如，类似“此电脑”的虚拟文件夹

filesys

路径是真实文件系统路径 - 例如，C:\Windows

ftp

路径是 FTP 路径

zip

路径是 zip 文件

mtp

路径是 MTP 路径（即便携式设备，如手机或平板电脑）

lib

路径是库

coll

路径是集合

plugin

路径是插件提供的命名空间，很可能是档案（但不是 Zip）

ReadDir

<string:path> <string:flags>

object:FolderEnum

返回一个 FolderEnum 对象，该对象允许您枚举指定文件夹的内容。

可选的 flags 字符串可以包含一个或多个标志字符（不区分大小写）：

递归地枚举文件夹，列出文件夹的内容、其子文件夹、它们的子文件夹等等。

跳过链接。在递归地枚举文件夹时，防止遍历符号链接和联结点。

Shell 枚举。请求 Windows Shell 枚举非文件系统文件夹。例如，Windows 10 上的 快速访问 文件夹可以使用 ReadDir("/quickaccess","s") 枚举；如果没有 "s"，它将无法工作，因为快速访问不是一个真实的文件系统目录。

从加密的档案中抑制密码对话框。

如果您不需要任何标志，请完全跳过第二个参数。您可能会看到较旧的脚本将 True 和 False 作为第二个参数传递，以打开和关闭递归；这已过时，但出于兼容性考虑仍受支持。

递归地枚举文件夹，列出文件夹的内容、其子文件夹、它们的子文件夹等等。

跳过链接。在递归地枚举文件夹时，防止遍历符号链接和联结点。

从加密的档案中抑制密码对话框。

Resolve

<string:path> <string:flags>

object:Path

将指定的路径字符串解析为其真实文件系统路径，支持转换：

文件夹别名 到它们指向的真实路径。
库和 文件集合 项目到其真实文件系统路径。
{apppath|appname} 形式的应用程序路径。
环境变量。
可选地，联结点 和 符号链接 可以解析到它们的目標。

可以安全地传递不需要解析的路径；该路径将被原样返回，因此您可以在不先检查是否需要的情况下对它们进行调用。

将当前目录传递给外部软件的脚本通常应该首先对该路径调用 Resolve，否则它们可能会将类似 /desktop 的别名传递给无法理解它们的软件。

可选的 flags 字符串可以包含以下字母（不区分大小写）：

返回规范路径。这将把短文件名扩展为其真实的 long filename 表示形式。

将联结点和符号链接解析到其目標文件夹。

请注意，Path 对象也有类似的 Resolve 方法，它们会就地修改它们。

返回规范路径。这将把短文件名扩展为其真实的 long filename 表示形式。

将联结点和符号链接解析到其目標文件夹。

SameDrive

<string:path1> <string:path2> <string:flags>

bool

如果指定的两个路径都引用同一个驱动器或分区，则返回 True。

可选的 flags 字符串可以包含以下一个或多个字母（区分大小写）：

| c | 将 CD 刻录暂存区 视为 CD（或其它可写入的光学介质）本身。 | | m | 处理 NTFS 挂载点。（如果任何路径可能位于指向不同驱动器的挂载点下方，则速度较慢但更准确。） | | r | 仅限真实路径。（跳过仅对 FTP 站点和 MTP 设备等有用处的额外处理。） | | s | 测试路径是否指向由 Windows subst 命令创建的相同驱动器上的驱动器号。 | | u | 比较 FTP 用户。（默认情况下，如果 FTP 路径指向同一个 FTP 站点，则它们被视为“同一驱动器”。u 标志添加了两个路径必须具有相同用户名才能被视为“同一驱动器”的要求。） | | z | 如果 path1 位于 Zip 文件或其它压缩包内部，则只有当 path2 是压缩包本身或位于同一压缩包内部时，才将其视为在“同一驱动器”上。 | | Z | 如果 path1 位于 Zip 文件或其它压缩包内部，则只有当 path2 位于同一压缩包内部时，才将其视为在“同一驱动器”上。 |

如果未指定 z 或 Z，则压缩包本质上被视为普通目录，并将被视为与指向压缩包所在相同驱动器的任何路径在“同一驱动器”上，包括该驱动器上的其它压缩包路径。

WatchChanges

<string:id> <string:path> <string:flags>

int

建立对文件夹或文件的更改监控。成功返回 0，失败返回错误代码。

当受监控的文件或文件夹发生更改时，脚本的 OnFilesystemChange 事件将被触发。

id 参数允许您为该观察者提供一个 ID，该 ID 用于在发生更改时识别它。dir 是文件系统文件夹的完整路径，或者如果设置了 i 标志，则是文件的路径。

可选标志：

监控文件夹中的文件更改（例如创建文件）

递归 - 监控子文件夹

监控文件属性更改

监控文件大小更改

监控最后写入时间更改

监控单个文件而不是文件夹

使用 CancelWatchChanges 方法取消监控。

监控文件夹中的文件更改（例如创建文件）

递归 - 监控子文件夹

监控文件属性更改

监控文件大小更改

监控最后写入时间更改

监控单个文件而不是文件夹

最后更新于11个月前