xlfRegister（窗体 1）

适用于：Excel 2013 | Office 2013 | Visual Studio

可以从 Microsoft Excel 本身调用的 DLL 或 XLL 命令调用。 这等于从 Excel XLM 宏表调用 REGISTER 。

xlfRegister 可以两种形式调用：

• xlfRegister (Form 1) ：注册单个命令或函数。

• xlfRegister (Form 2) ：加载并激活 XLL。

此函数在表单 1 中调用，使 DLL 函数或命令可用于 Excel，将其使用计数设置为 1，并返回其注册 ID，该 ID 可用于稍后使用 xlUDF 或 xlfCall 函数调用函数。 注册 ID 还用于使用 xlfUnregister (Form 1) 注销函数。 如果函数已注册，则调用 xlfRegister 会再次递增其使用计数。

此形式的函数还定义了一个隐藏名称，该名称是函数文本参数 pxFunctionText，其计算结果为函数或命令的注册 ID。 注销函数时，请使用 xlfSetName 删除此名称。 有关详细信息，请参阅 Excel XLL 开发中的已知问题。

Excel12(xlfRegister, LPXLOPER12 pxRes, int iCount,
    LPXLOPER12 pxModuleText,   LPXLOPER12 pxProcedure,
    LPXLOPER12 pxTypeText,     LPXLOPER12 pxFunctionText,
    LPXLOPER12 pxArgumentText, LPXLOPER12 pxMacroType,
    LPXLOPER12 pxCategory,     LPXLOPER12 pxShortcutText,
    LPXLOPER12 pxHelpTopic,    LPXLOPER12 pxFunctionHelp,
    LPXLOPER12 pxArgumentHelp1, LPXLOPER12 pxArgumentHelp2,
        ...);

参数

pxModuleText (xltypeStr)

包含函数的 DLL 的名称。 如果注册的函数也位于当前正在执行的 DLL 中，则可以通过调用仅 XLL 函数 xlGetName 来获取此函数。

pxProcedure (xltypeStr 或 xltypeNum)

如果为字符串，则为 DLL 代码中显示的要调用的函数的名称。 如果为数字，则为要调用的函数的序号导出编号。 为清楚起见，请始终使用字符串形式。

pxTypeText (xltypeStr)

一个可选字符串，指定函数的参数类型和函数的返回值的类型。 有关详细信息，请参阅"备注"部分。 对于包含 xlAutoRegister 函数或 xlAutoRegister12 的独立 DLL (XLL) ，可以省略此参数。

如果调用 xlfRegister 但缺少此参数，Excel 将调用 xlAutoRegister 或 xlAutoRegister12（如果指定 DLL 中存在其中一个），后者应通过提供此信息来正确注册函数。

pxFunctionText (xltypeStr)

函数向导中显示的函数名称。 此参数是可选的;如果省略该函数，则函数在函数向导中不可用，并且只能使用 XLM 宏表中的函数注册 ID 使用 CALL 函数调用。 因此，对于普通工作表使用，应根据需要处理此参数。

pxArgumentText (xltypeStr)

描述函数参数的可选文本字符串。 用户在函数向导中看到此情况。 如果省略它，Excel 将从 pxTypeText 构造基本说明。

pxMacroType (xltypeNum 或 xltypeInt)

指示 XLL 入口点类型的可选参数。 如果省略默认值，则默认值为 1。

实际上，应对工作表函数使用 1,1 用于宏工作表等效函数， (注册为要从工作表调用的类型 #) ，对命令使用 2。

pxCategory (xltypeStr 或 xltypeNum)

一个可选参数，可用于指定新函数或命令应属于哪个类别。 函数向导将函数除以类型 (类别) 。 可以指定类别名称或序列号，其中数字是类别在函数向导中出现的位置。 有关详细信息，请参阅“类别名称”部分。 如果省略它，则假定为“用户定义”类别。

pxShortcutText (xltypeStr)

一个单字符、区分大小写的字符串，指定分配给此命令的控制键。 例如，“A”将此命令分配给 CONTROL+SHIFT+A。 此参数是可选的，仅用于命令。

pxHelpTopic (xltypeStr)

对帮助文件 (.chm 或 .hlp 的可选引用) 在用户单击“帮助”按钮时显示 (自定义函数) 显示。 可以是 窗体 filepath!HelpContextID 或 https://address/path_to_file_in_site!0。 “！” 之前和之后的两个部分是必需的。 HelpContextID 不得包含单引号，Excel 将转换为长度为 4 个字节的无符号整数（小数形式）。 使用 URL 窗体时，Excel 仅打开引用的帮助文件。

pxFunctionHelp (xltypeStr)

在函数向导中选择自定义函数时描述自定义函数的可选字符串。

pxArgumentHelp1 (xltypeStr)

可选。 在函数向导中选择函数时，描述函数的自定义参数的第一个字符串。 在 Excel 2003 及更早版本中， xlfRegister 最多可以采用 30 个参数，以便只能为前 20 个函数参数提供此帮助。 从 Excel 2007 开始， xlfRegister 最多可以采用 255 个参数，因此可以为最多 245 个函数参数提供此帮助。

属性值/返回值

如果注册成功，此函数将返回函数的寄存器 ID (xltypeNum) ，该 ID 可用于调用 DLL 中的 xlUDF 和 xlfUnregister ，或在 XLM 宏表中与 CALL 和 UNREGISTER 一起使用。 否则，它将返回 #VALUE！ 错误。

备注

数据类型

pxTypeText 参数指定返回值的数据类型，以及 DLL 函数或代码资源的所有参数的数据类型。 pxTypeText 的第一个字符指定返回值的数据类型。 其余字符表示所有参数的数据类型。 例如，返回浮点数并采用整数和浮点数作为参数的 DLL 函数需要 pxTypeText 参数的“BIB”。

以下两个表中汇总了 Excel 用于与 XLL 交换数据的数据类型和结构。

第一个表列出了所有版本的 Excel 中支持的类型。

在 Excel 2007 中，引入了以下数据类型来支持较大的网格和长 Unicode 字符串。

从 Excel 2010 开始，引入了以下数据类型：

下列字符串类型用于就地修改的参数：F、F%、G 和 G%。

使用上表中显示的数据类型时，请注意以下事项：

• C 语言声明假定编译器默认使用 8 字节双精度、2 字节短整数和 4 字节长整数。
• 使用 __stdcall 调用约定调用 DLL 和代码资源中的所有函数。
• 任何按引用返回数据类型的函数（即返回指向某个对象的指针）都可以安全地返回 null 指针。 Excel 将 null 指针解释为 #NUM！ 错误。

其他数据类型信息

本节包含有关 E、 F、 F%、 G、 G%、 K、 O、 P、 Q、 R 和 U 数据类型的详细信息，以及有关 pxTypeText 参数的其他信息。

E 数据类型

Excel 要求使用 E 数据类型的 DLL 将指针传递到堆栈上的浮点数。 这可能会导致某些语言出现问题 (例如 Borland C++) ，这些语言要求在协处理器模拟器堆栈上传递数字。 解决方法是传递指向协处理器堆栈上的数字的指针。 以下示例演示如何从 Borland C++ 返回 double。

typedef double * lpDbl;
extern "C" lpDbl __stdcall AddDbl(double D1,
    double D2, WORD npDbl)
{
    lpDbl Result;
    Result = (lpDbl)MK_FP(_SS, npDbl);
    *Result = D1 + D2;
    return (Result);
}

F、F%、G 和 G% 数据类型

对于 F、 F%、 G 和 G% 数据类型，函数可以修改由 Excel 分配的字符串缓冲区。 如果返回值类型代码是这些类型之一，Excel 将忽略函数返回的值。 相反，Excel 在函数参数列表中搜索第一个相应的数据类型 (F、 F%、 G 或 G%) ，然后将分配的字符串缓冲区的当前内容作为返回值。 所有版本的 Excel 都为 F 和 G ASCII 字符串分配 256 个字节，从 Excel 2007 开始，为 F% 和 G% Unicode 字符串分配了 65,536 字节，足以容纳 32,768 个 Unicode 字符。 请记住，缓冲区必须包含类型 为 G 和 G%) 的计数字符 (或类型 F 和 F%) 类型 (null 终止字符，以便实际的最大字符串长度为 255 和 32,767。 Unicode 字符串以及类型 F% 和 G% 参数只能通过 Excel 中的 C API 使用。

K% 和 K% 数据类型

K 和 K% 数据类型分别使用指向可变大小的 FP 和 FP12 结构的指针。 这些结构在 XLLCALL.H 中定义。 仅从 Excel 2007 开始支持 FP12 结构以及 K% 参数类型。

O 和 O% 数据类型

O 和 O% 数据类型只能用于参数，不能用于返回值，尽管可以返回值，我修改了 O 或 O% 类型参数。 每个传递三个项：指向数组中行数的指针、指向数组中列数的指针，以及指向浮点数的二维数组的指针。

若要修改由 O 或 O% 数据类型就地传递的数组，可以使用“O”>或“>O%”作为 pxTypeText 参数。 有关修改数组的详细信息，请参阅本主题中的“就地修改：声明为 Void 的函数”部分。

创建 O 数据类型是为了与 Fortran DLL 直接兼容，后者按引用传递参数。

从 Excel 2007 开始支持 O%， 它容纳 Excel 支持的更多行。

P 和 Q 数据类型

当 DLL 函数参数注册为采用 类型 P XLOPER 或 类型 Q XLOPER12s 时，Excel 在准备这些参数时将单单元格引用转换为简单值和对数组的多单元格引用。 换句话说， P 和 Q 类型将始终作为以下类型之一出现在函数中： xltypeNum、 xltypeStr、 xltypeBool、 xltypeErr、 xltypeMulti、 xltypeMissing 或 xltypeNil，但不是 xltypeRef 或 xltypeSRef ，因为这些类型始终是取消引用。 仅从 Excel 2007 开始支持 XLOPER12，因此，仅支持 Q 类型参数。

如果类型 xltypeMissing 或 xltypeNil 用于返回值，则 Excel 会将这些类型解释为数值零。 当调用方省略参数时，将传递 xltypeMissing。 当调用方传递对空单元格的引用时，将传递 xltypeNil。 当单元格区域转换为 xltypeMulti 以类型 P 或 Q 传递时，该区域中的任何空白单元格将转换为 xltypeNil 数组元素。 文本数组中缺少的元素类似于 xltypeNil 元素的传递方式。

可变函数和重新计算

在工作表上，可以使 DLL 函数或代码资源具有可变性，以便每次重新计算工作表时，它都会重新计算。 为此，请在 pxTypeText 参数的最后一个参数代码后面添加感叹号 (！) 。

声明为 void 的函数

有两种情况需要将函数声明为返回 void。 在这两种情况下，函数都通过其他方式返回其结果。

就地修改

对于 pxTypeText 中的返回类型代码，可以使用个位数 n，其中 n 是 1 到 9 的数字。 这指示 Excel 在返回值in_pxTypeText_as_n_th参数指向的位置中获取变量的值。 这也称为就地修改。 The_n_th参数必须是 (C、D、E、F、F%、G、G%、K%、L%、M、N、O、O%、P、Q、R 或 U) 的按引用传递数据类型。 还必须使用 C/C++ 语言中的 void 关键字 (keyword) 声明 DLL 函数或代码资源 (或使用 Pascal 语言) 的过程关键字 (keyword) 。

例如，采用以 null 结尾的字符串和两个指向整数的指针作为参数的 DLL 函数可以就地修改字符串。 使用“1FMM”作为 pxTypeText 参数，并将函数声明为 void。

早期版本的 Excel 在 pxTypeText 的开头使用>，表示函数已声明为 void，并且第一个参数将被就地修改-除了第一个参数之外，无法修改任何其他参数。 >在当前 Excel 版本中等效于 n = 1，并且>仅在向后兼容的情况下，支持在同步函数中使用 。

异步函数

异步函数（在 pxTypeText 中使用类型为 X 的参数表示）不会从初始函数调用返回其结果。 相反，必须将异步函数声明为 void，然后外接程序通过回调返回结果。 异步函数必须在 pxTypeText 的开头使用 > 进行注册。 在异步函数中， > 表示函数声明为 void，但不指示第一个参数已就地修改。 有关异步函数的详细信息，请参阅 异步 User-Defined 函数。

将工作表功能注册为宏工作表等效项 (处理未计算的单元格)

在 pxTypeText 中的最后一个参数代码之后放置一#个字符，为函数提供与宏表上的函数相同的调用权限。 这些任务如下：

• 函数可以检索在此重新计算周期中尚未计算的单元格的值。

• 该函数可以调用类 2) 函数 (任何 XLM 信息，例如 xlfGetCell。

• 如果不存在数字符号 (#) ：计算未计算的单元格会导致 xlretUncalced 错误，并在计算单元格后再次调用当前函数;调用 xlfCaller 以外的任何 XLM 信息函数都会导致 xlretInvXlfn 错误。

将工作表注册为线程安全

从 Excel 2007 开始，Excel 可以执行多线程工作簿重新计算。 这意味着它可以将线程安全函数的不同实例分配给并发线程进行重新计算。 从 Excel 2007 开始，大多数内置工作表函数都是线程安全的。 从 Excel 2007 开始，Excel 还允许 XL 将工作表函数注册为线程安全。 为此，请在 pxTypeText 中的最后一个参数代码后面添加一$个字符。

如果已将函数注册为线程安全，则必须确保它以线程安全的方式运行，尽管 Excel 拒绝通过 C API 进行任何线程不安全调用。 例如，如果线程安全函数尝试调用 xlfGetCell，调用将失败并显示 xlretNotThreadSafe 错误。

将工作表注册为群集安全

从 Excel 2010 开始，Excel 可以将函数调用卸载到指定的计算群集提供程序。 有关详细信息，请参阅 群集安全函数。 注册为群集安全的任何 XLL 工作表函数都参与卸载（如果群集可用）。 群集安全函数通过在 pxTypeText 参数中的最后一个参数代码后面添加 & 字符来注册。

如果已将函数注册为群集安全，则必须确保它以群集安全的方式运行。 有关详细信息，请参阅 群集安全函数。

类别名称

使用以下准则来确定要放入 XLL 函数的类别。

• 如果函数执行了用户作为外接程序用户界面的一部分可以执行的操作，则应将该函数置于 “命令” 类别中。
• 如果函数返回有关加载项状态的信息或任何其他有用信息，则应将该函数置于 “信息 ”类别中。
• 外接程序绝不应将函数或命令添加到 “用户定义” 类别。 此类别供最终用户独占使用。

-使用 pxCategory 参数对 xlfRegister 指定类别。 这可以是对应于硬编码标准类别之一的数字或文本，也可以是 DLL 指定的新类别的文本。 如果给定的文本尚不存在，Excel 将使用该名称创建一个新类别。

下表列出了在工作表中查看 “粘贴函数 ”对话框时可见的标准类别。

此外，从宏工作表中查看 “粘贴函数 ”对话框时，也可以看到这些类别。

示例

请参阅 中 xlAutoOpen 函数的代码 \SAMPLES\GENERIC\GENERIC.C。

另请参阅

• REGISTER.ID
• 注销
• 实用的基本 C API XLM 函数