【XLL 文档翻译】【第2部分】C API 回调函数 Excel4, Excel12
Excel4 和 Excel12 函数使得 DLL 可以调用 Excel 工作表函数、宏表函数、命令、XLL特定函数或命令。最近的一些 Excel 版本都支持 Excel12 函数。这两个函数支持下面两种形式。
- 来自于 Excel4/Excel12 可变长度参数列表
- 来自于Excel4v/Excel12v 数组参数
除了将参数传递给这两个函数方法不同以外，这两种形式的功能是相同的。两二种形式的完整描述在 Excel4/Excle12 中。Excel4v/Excel12v 包含了关于这种形式的其它问题。
Excel4/Excel12
从 DLL/XLL 或 代码资源中调用 Excel 内部的 工作表函数、宏表函数、 XLL 特定函数 或 命令。
最近版本的 Excel版本都支持 Excel4。只有 Excel 2007 及其后继续版本支持 Excel12.
这两个回调函数只能通过由 Excel 通过 DLL/XLL 调用。他们也可以间接的通过 VBA 调用。除上面两种情况以外，它们不能在其它任何时间进行调用。例如，当操作系统调用 DLL 时，不能在调用 DllMain 时或其它时刻调用这两个回调函数，或是在DLL创建的其它线程调用。
Excel4v 和 Excel12v 其参数是数组形式，因这些它们的参数，使用的是堆栈中的可变长度列表。在其它方面，Excel4 与 Excel4v，Excel12 与 Excel12v 表现出来的行为都是一样的。
函数原型
int Excel4(int iFunction, LPXLOPER pxRes, int iCount, LPXLOPER argument1, ...);
int Excel12(int iFunction, LPXLOPER12 pxRes, int iCount, LPXLOPER12 argument1, ...);
参数
iFunction ( int )
表示你想调用的 命令、函数或特定的函数，有效的 iFunction 值，参考 “备注” 一节中的内容。
pxRes ( LPXLOPER or LPXLOPER12 )
一个指向 XLOPER（用于Excel4） 或 XLOPER12 （用于Excel12），用于保存评估计算结果。
iCount ( int )
表示后面将传送到函数中的参数的数量。到 Excel 2003 版本为止，此数值可以设置为 0 到 30。在 Excel 2007 中，可以设置为 0 到 255。
argument1, ... （LPXLOPER or LPXLOPER12）
作为函数的可选参数。所有参数必需是 XLOPER 或 XLOPER12 指针。
属性值 / 返回值
必需返回下表中的任意一个值（int）
| 值 | 返回代码 | 描述 |
|---|---|---|
| 0 | xlretSuccess | 函数成功调用返回这个值。但并不意味着，函数没有返回 Excel 错误值。 为了确认错误值，你必需观察 *pxRes* 值类型。 |
| 1 | xlretAbort | 命令或函数异常结束（内部中断）。当 XLM 宏表调用 CLOSE 函数自我关闭或是 Excel 内存不足就会发生这种情况。如果 你接收到此错误，你必需立即退出。DLL 只允许在退出以前调用 xlFree。其它任何的 C API 调用都是不被允许的。 用户可以使用 文件菜单中的 Save 命令保存之前的任何操作。 |
| 2 | xlretInvXlfn | 提供了一个无效的函数成员。如果你使用来自 XLCALL.H 中的常量，这种情况不会发生， 除非你正在调用一些你当前 Excel版本 不支持的常量。 |
| 4 | xlretInvCount | 输入了一个无效的参数数量，到 Excel 2003 ，最大的参数数量是 30，而到了 Excel 2007 ，最大的参数数量达到了 255 个。一些函数需要一个固定的或最小数量的参数数。 |
| 8 | xlretInvXloper | 一个无效的 XLOPER 或 XLOPER12 被传递给函数，或参数中使用了一个错误的数据类型。 |
| 16 | xlretStackOvfl | 发生堆栈溢出。使用 xlStack 监视栈上的空间数量，尽可能的避免在堆栈上分配一个很大的局部（自动）数组和结构，把它们设置为静态的。（注意有可能会发生一个没有被探测到的内在溢出）。 |
| 32 | xlretFailed | 命令等效函数失败，它等效于 宏命令显示宏错误警告对话框。 |
| 64 | xlretUncalced | 调用一个还没有完成计算的一个单元格。这种情况下，DLL 将立即将控制权返还给Excel。在退出函数前，DLL 只允许调用 C-API 函数 xlFree。其它的 C API 是不可以调用的。 |
| 128 | xlretNotThreadSafe | 只会在 Excel 2007 运行时，并且 XLL 工作表函数被声明为线程安全的，才能返回这个值。 多线程重计算期间，尝试调用的函数不是线程安全的， |
备注
有效的 iFunction 值
有效的 iFunction 值都是 xlf 或 xlc 开头的常量，它们定义在 XLCALL.H 中或是以下的特定函数。
| xlAbort | xlEnableXLMsgs | xlGetInst | xlSheetNm |
| xlCoerce | xlFree | xlGetName | xlStack |
| xlDefineBinaryName | xlGetBinaryName | xlSet | xlUDF |
| xlDisableXLMsgs | xlGetHwnd | xlSheetId |
不同的函数类型
Excel4 和 Excel12 在三个函数类型上有区别。函数依据 Excel 调用 DLL 的三种情况进行分类。
- 类型1 来自于工作表的调用，作为重计算的结果。
- 类型2 从函数宏，或工作表调用，其文本类型被注册为数字符号
- 类型3 从对象、宏、菜单、工具栏 、快捷捷、执行Excel4宏，或 工具/宏/运行 命令调用。
下表展示了，每个类型可使用的函数。
| Class 1 | Class 2 | Class 3 |
|---|---|---|
|
任何工作表函数 任何 以xl...开头的 XLL 函数，除了 xlSet. xlfCaller |
任意工作表函数 任何 以xl...开头的 XLL 函数，除了 xlSet. 宏表函数，包括xlfCaller, 但执行在工作空间和打开的工作簿中无任何效果 |
任意工作表函数，包含 xlSet and 命令等效函数. |
命令等效函数显示对话框
如果命令等效函数关联了对话框，你可以在 iFuntcion 函数中设置 xlPrompt 位。这样，Excel 就会在执行命令前显示相应的对话框。
DLL的国际性支持
如果你在 iFunction 中设置了 xlIntl 位，函数或命令命令将和 美版的 Excel 表现是一至的，即使它是运行在国际版本的 Excel 中。
clretUncalced 或 xlretAbort
如果返回值为这二种类型中的一种，你的 DLL 必需清除，并将控制权返还给 Excel。 C API 回调 操作，会在 接到到这种返回值后失效，除了 xlFree 函数。
实例
这个实例使用 Excel12 函数选择调用的单元格
\SAMPLES\EXAMPLE\EXAMPLE.C.
注意 这个函数调用一个命令宏 xlcSelect 因此只会在 XLM 宏表中调用时有效。
short WINAPI Excel12Example(void)
{
XLOPER12 xRes;
Excel12(xlfCaller, &xRes, 0);
Excel12(xlcSelect, 0, 1, (LPXLOPER12)&xRes);
Excel12(xlFree, 0, 1, (LPXLOPER12)&xRes);
return 1;
}
Excel4v/Excel12v
从 DLL/XLL 或代码资源中调用 Excel 内部的工作表函数、宏表函数或命令、或 XLL-only 特定函数或命令
所有最新版本的 Excel4v 都支持 Excel4v 函数。只有 Excel 2007 及其后续版本支持 Excel12v。
这些函数只在 DLL/XLL 回调 Excel 功能可以使用。它们还可以间接的通过 VBA 来调用。除此以外，其它的任何时间都不可以调用这两个函数。例如，它们不能在 操作系统调用 DLL时调用 DllMain 时直接调用这个函数。 DLL 创建的线程也不能调用这个函数。
Excel4 和 Excel12 接收堆栈上的可变长度参数列表，然而 上面的两个函数只接收数组形式的参数。在其它方面，这两组函数是等效的。
函数原型
int _cdecl Excel4v(int iFunction, LPXLOPER pxRes, int iCount,LPXLOPER rgx[]);
int _cdecl Excel12v(int iFunction, LPXLOPER12 pxRes, int iCount,LPXLOPER12 rgx[]);
参数
iFunction (int)
一个数字类型，表明你要调用的 命令、函数 或 特殊函数。有效的 iFunction 值，参考 “Remarks” 一节。
pxRes (LPXLOPER or LPXLOPER12)
XLOPER 或 XLOPER12 类型的指针，用于保留函数的结果值。
iCount (int)
要传送给函数的参数数量。到 Excel 2003 版本，这里的数值最大为30。但是在 Excel 2007 版本，最大数值是 255。
rgx (LPXLOPER[] 或 LPXLOPER12[])
包含要传送给函数的参数数组。数组中的所有参数必需指向 XLOPERs 或 XLOPER12s 类型。
属性值 / 返回值
这些函数的返回值 与 Excel4 和 Excel12 是相同的。
备注
当参数的数量是不是固定，使用这些函数更好。例如，当使用 xlfRegister 注册函数时，参数数量依赖于注册的函数的参数数量。这种情况下就可以使用这些函数。或者当你为 Excel4 或 Excel12 建一个包装函数时，你需要转换变量参数列表才能提供给 Excel4 或 Excel12 。而使用 Excel 4v 或 Excel12v 只需要调用一个包含了所有函数的参数数组就可以了。
实例
在 SAMPLES\FRAMEWRK\FRAMEWRK.C 包含了 Excel 和 Excel12f 函数的实例代码。
