Delphi中适配Windows API的数组定义：IKnownFolderManager::GetFolderIds

背景说明 #

Windows已知文件夹API中，IKnownFolderManager::GetFolderIds的原生C++定义为：

HRESULT GetFolderIds([out] KNOWNFOLDERID **ppKFId, [in, out] UINT *pCount);

调用成功后，ppKFId指向一个KNOWNFOLDERID（GUID）数组，调用者需要用CoTaskMemFree手动释放该数组，这是标准流程。

但在Delphi Alexandria 11.2的ShlObj.pas中，该函数被翻译成：

function GetFolderIds(ppKFId: array of TKnownFolderID; var pCount: UINT): HRESULT; stdcall;

其中TKnownFolderID是TGUID的类型别名。

问题核心 #

原Delphi的接口定义存在错误，无法满足正常调用需求：

• 原生API的ppKFId是输出参数，要求接收一个指向指针的指针，用于返回分配好的数组地址；
• 而Delphi的array of TKnownFolderID是开放数组参数，调用时传递的是数组首元素的地址+数组长度，和原生API的参数语义完全不匹配，导致无论怎么定义变量，都无法正确接收返回的数组，更无法通过CoTaskMemFree释放。

你尝试的多种方式均失败，本质原因就是这个定义错误：

• 用动态数组时，传递的是数组内容（nil）而非地址，触发保护异常；
• 静态数组无法转换为可释放的指针；
• 强制转换指针的写法不规范，还会导致数量参数无法正确更新。

正确解决方案 #

将IKnownFolderManager.GetFolderIds的定义修改为符合原生API语义的版本：

type
  PKnownFolderID = ^TKnownFolderID;

function GetFolderIds(var ppKFId: PKnownFolderID; var pCount: UINT): HRESULT; stdcall;

调用示例：

var
  FolderManager: IKnownFolderManager;
  FolderList: PKnownFolderID;
  Count: UINT;
  I: Integer;
begin
  if Succeeded(CoCreateInstance(CLSID_KnownFolderManager, nil, CLSCTX_INPROC_SERVER, IID_IKnownFolderManager, FolderManager)) then
  begin
    Count := 0;
    if Succeeded(FolderManager.GetFolderIds(FolderList, Count)) then
    begin
      try
        // 遍历使用数组内容
        for I := 0 to Count - 1 do
        begin
          // 处理 FolderList[I]
        end;
      finally
        // 释放数组
        CoTaskMemFree(FolderList);
      end;
    end;
  end;
end;

这个写法可以正常获取文件夹列表和数量，且能通过CoTaskMemFree正确释放数组。

结论 #

原Delphi ShlObj.pas中的GetFolderIds定义属于翻译错误，完全不符合原生API的参数语义，无法正常使用。修改为指针指针的形式后，才能正确调用并遵循COM内存管理规范。

内容的提问来源于stack exchange，提问作者Ray Cernis