fixSharedMemoryDll 异步发送 API —— 返回值与错误处理对接说明

适用对象：通过 fixSharedMemoryDll 向 FIX 发送投影/体数据/图像处理请求的集成方

背景

采集软件通过 fixSharedMemoryDll 把投影数据 + 重建配置发送给 FIX 做 CT 重建。
当一次发送的数据大小超过 FIX 端共享内存通道容量时，发送会同步失败。

典型案例：投影 2400 × 3040 × 360 × 2 字节 = 5009 MB，超过默认通道 1536 × 1536 × 768 × 2 字节 = 3456 MB，发送被拒绝。

必须正确处理这个失败，否则采集软件会卡死或崩溃。

核心契约：检查返回值 reqId

所有异步发送 API（fsChannelSendProjectionAsync / fsChannelSendVolumeAsync /
fsChannelSendImageProcAsync）返回一个 uint32_t reqId：

FIX 源码 nextRequestId() 保证有效 id 从非 0 开始（注释原文：「跳过 0，0 是异步 API 的失败标志」）。

必须的错误处理范式

uint32_t reqId = fsChannelSendProjectionAsync(
    channel, projData, name, NULL, resultPath, reconJson,
    width, height, depth, imageType, vx, vy, vz);

if (reqId == 0) {
    // 发送失败 —— 不要再等完成回调，也不要去读结果内存！
    const char* err = fsChannelGetLastError(channel);
    // err 形如：
    //   "Volume data size (5009 MB) exceeds shared memory size (3456 MB). Increase shared memory configuration."
    showErrorToUser(err);   // 把错误提示给操作员
    return;                 // 终止本次重建流程
}

// reqId > 0：发送成功，正常等待完成回调

最常见的崩溃原因：发送后不检查 reqId，直接进入「等待完成回调」或「读取结果」的逻辑。
失败时 reqId == 0，这条请求根本不存在——等待会永久阻塞，读结果会读到无效数据。

“共享内存不足”错误的处理

错误文本：

Volume data size (XXXX MB) exceeds shared memory size (YYYY MB). Increase shared memory configuration.

• 原因：本次投影/体数据总字节数超过 FIX 端共享内存通道容量。
• 解决：由 FIX 侧把共享内存配置（X / Y / Z 三个维度，对应设置项
  sd_EC_SharedMemoryX/Y/Z）调大到能容纳该数据，重启 FIX 后重试。
• 采集软件无需自动扩容，只需在 reqId == 0 时把错误文本提示给操作员即可。

重要：失败判据与 fsChannelGetLastError 的有效范围

异步发送 API 在同步失败时只通过返回值 reqId == 0 报告失败，不会派发完成回调。
所以请务必在每次发送后检查返回值，不要仅依赖完成回调——否则发送失败时会永久等待一个不会到来的回调（这正是本次崩溃的成因）。

fsChannelGetLastError(channel) 的有效范围：

• ✅ 仅在发送类 API 返回 reqId == 0 后立即读取，才保证返回本次失败原因（如"共享内存不足"）。
• ⚠️ 空 handle、空数据指针、零尺寸等参数级错误也会返回 reqId == 0，但不保证设置错误串（这类属调用方明显的传参错误，自行检查即可）。
• ⚠️ 发送成功（reqId > 0）后不要再读 fsChannelGetLastError，它可能仍是上一次失败的旧值。