互操作性

本页面记录了 Interop 目录中导出的接口。

API 约定

所有导出的 API 函数均遵循 COM 约定返回 HRESULT，以指示成功或失败：

HRESULT	含义
`S_OK`	操作成功完成。
`S_FALSE`	操作已完成但无需执行任何操作（例如未找到匹配的效果）。
`E_POINTER`	必需的指针参数为空。
`E_INVALIDARG`	一个或多个参数无效。
`E_UNEXPECTED`	发生意外的内部错误（例如未找到扩展数据）。
`E_FAIL`	操作失败。

生成输出数据的函数会接受一个额外的输出指针参数来接收结果。请使用 SUCCEEDED(hr) / FAILED(hr) 检查返回值。

API 版本跟踪

语义化版本规则

主版本号 (X)：递增表示发生了破坏性变更（向后不兼容的 API 修改）。
示例：删除 API、更改函数参数、修改数据结构导致现有代码损坏。
当此版本号递增时，次版本号和修订号重置为 0（例如 1.2.3 → 2.0.0）。
次版本号 (Y)：递增表示增加了向后兼容的新功能。
示例：添加新的 API 函数、增加不破坏现有代码的新参数。
当此版本号递增时，修订号重置为 0（例如 1.2.3 → 1.3.0）。
修订号 (Z)：递增表示向后兼容的杂项改进（无 API 变更）。
示例：修复崩溃、更正计算、优化内部实现而不改变接口（例如 1.2.3 → 1.2.4）。

GetInteropAPIVersion

HRESULT GetInteropAPIVersion(InteropAPIVersion* pVersion)

通过 pVersion 输出参数返回当前的 Interop API 版本。

参数：
- pVersion：接收版本结构体 { major, minor, patch }。
成功时返回 S_OK，若 pVersion 为空则返回 E_POINTER。

示例（C# P/Invoke）：

[StructLayout(LayoutKind.Sequential)]
public struct InteropAPIVersion
{
    public uint major;
    public uint minor;
    public uint patch;
}

[DllImport("Phobos.dll", CallingConvention = CallingConvention.StdCall)]
public static extern int GetInteropAPIVersion(out InteropAPIVersion pVersion);

InteropAPIVersion version;
int hr = GetInteropAPIVersion(out version);
if (hr >= 0 && version.major >= 1)
{
    // Safe to use features from v1.0.0 onwards
}

已弃用 API 的处理

当某个 API 被弃用时，其函数存根会保留，但会附加一个致命错误处理器。调用方将收到一条描述性错误消息，并且必须停止执行。这可以确保：

断开的链接在运行时立即被检测到（而非静默崩溃）。
清晰的消息可引导开发者了解替代 API 和版本范围。
迁移时间线会记录在错误消息中。

示例（当前未使用）：

// DEPRECATED: Removed in Interop API v2.0.0. Use NewAPI instead.
// Availability: [1.0.0, 2.0.0)
// Calling this will trigger a fatal error with the message:
// "SomeOldAPI_Deprecated has been removed in Interop API v2.0.0 (was available in v1.0.0-v1.x.x). Please use NewAPI."

可用的 API

模块	API	可用范围	状态
AttachEffect	AE_Attach	`[1.0.0, ∞)`	活跃
AttachEffect	AE_Detach	`[1.0.0, ∞)`	活跃
AttachEffect	AE_DetachByGroups	`[1.0.0, ∞)`	活跃
AttachEffect	AE_TransferEffects	`[1.0.0, ∞)`	活跃
BulletExt	Bullet_SetFirerOwner	`[1.0.0, ∞)`	活跃
EventExt	EventExt_AddEvent	`[1.0.0, ∞)`	活跃
TechnoExt	ConvertToType_Phobos	`[1.0.0, ∞)`	活跃
TechnoExt	RegisterCalculateExtraThreatCallback	`[1.0.0, ∞)`	活跃

AttachEffect

AE_Attach

可用范围： [1.0.0, ∞)

HRESULT AE_Attach(
		TechnoClass* pTarget,
		HouseClass* pInvokerHouse,
		TechnoClass* pInvoker,
		AbstractClass* pSource,
		const char** effectTypeNames,
		int typeCount,
		int durationOverride,
		int delay,
		int initialDelay,
		int recreationDelay,
		int* pAttachedCount
)

将一个或多个 AttachEffect 类型附加到目标上。

参数：
- pTarget：要接收效果的目标单位。
- pInvokerHouse：调用方阵营上下文。
- pInvoker：调用方 Techno 上下文。
- pSource：可选来源对象上下文。
- effectTypeNames：AttachEffect 类型名称数组。
- typeCount：effectTypeNames 中的条目数量。
- durationOverride：若非零，则应用持续时间覆盖。
- delay：若大于等于 0，则应用延迟覆盖。
- initialDelay：若大于等于 0，则应用初始延迟覆盖。
- recreationDelay：若大于等于 -1，则应用重建延迟覆盖。
- pAttachedCount：接收已附加的效果数量。
成功时返回 S_OK，若未找到有效的效果类型名称则返回 S_FALSE。
当 pTarget、effectTypeNames 或 pAttachedCount 为空时，失败并返回 E_POINTER。
当 typeCount <= 0 时，失败并返回 E_INVALIDARG。

AE_Detach

可用范围： [1.0.0, ∞)

HRESULT AE_Detach(
		TechnoClass* pTarget,
		const char** effectTypeNames,
		int typeCount,
		int* pRemovedCount
)

根据显式的效果类型名称移除效果。

参数：
- pTarget：要从中移除效果的目标单位。
- effectTypeNames：要移除的 AttachEffect 类型名称数组。
- typeCount：effectTypeNames 中的条目数量。
- pRemovedCount：接收已移除的效果数量。
成功时返回 S_OK，若未找到匹配的效果则返回 S_FALSE。
当 pTarget、effectTypeNames 或 pRemovedCount 为空时，失败并返回 E_POINTER。
当 typeCount <= 0 时，失败并返回 E_INVALIDARG。

AE_DetachByGroups

可用范围： [1.0.0, ∞)

HRESULT AE_DetachByGroups(
		TechnoClass* pTarget,
		const char** groupNames,
		int groupCount,
		int* pRemovedCount
)

根据 AttachEffect 组名移除效果。

参数：
- pTarget：要从中移除效果的目标单位。
- groupNames：组名数组。
- groupCount：groupNames 中的条目数量。
- pRemovedCount：接收已移除的效果数量。
成功时返回 S_OK，若未找到匹配的组则返回 S_FALSE。
当 pTarget、groupNames 或 pRemovedCount 为空时，失败并返回 E_POINTER。
当 groupCount <= 0 时，失败并返回 E_INVALIDARG。

AE_TransferEffects

可用范围： [1.0.0, ∞)

HRESULT AE_TransferEffects(
		TechnoClass* pSource,
		TechnoClass* pTarget
)

将所有附加效果从来源转移到目标。

参数：
- pSource：来源单位。
- pTarget：目标单位。
成功时返回 S_OK。
当 pSource 或 pTarget 为空时，失败并返回 E_POINTER。

原版类扩展

TechnoExt

ConvertToType_Phobos

可用范围： [1.0.0, ∞)

HRESULT ConvertToType_Phobos(FootClass* pThis, TechnoTypeClass* toType)

将一个 FootClass 实例转换为另一种 TechnoType。

参数：
- pThis：要转换的单位。
- toType：目标 TechnoType。
转换成功时返回 S_OK。
若类型不兼容则返回 E_INVALIDARG。
备注：
- 此 API 直接转发至 TechnoExt::ConvertToType。

RegisterCalculateExtraThreatCallback

可用范围： [1.0.0, ∞)

typedef double (*CalculateExtraThreatCallback)(TechnoClass* pThis, ObjectClass* pTarget, double originalThreat);

HRESULT RegisterCalculateExtraThreatCallback(CalculateExtraThreatCallback callback)

注册一个回调函数，用于计算单位的额外威胁值。

参数：
- callback：回调函数指针，返回计算后的威胁修正值。签名：double callback(TechnoClass* pThis, ObjectClass* pTarget, double originalThreat)。
成功时返回 S_OK。
当 callback 为空时，失败并返回 E_POINTER。
行为：
- 如果 callback 非空，则将其添加到内部回调列表中。
- 当威胁计算发生时，所有已注册的回调都会被调用以计算额外的威胁贡献。
- 可以注册多个回调，它们会按注册顺序执行。
备注：
- 回调的调用方式为 totalThreat = cb(pThis, pTarget, totalThreat)。

BulletExt

Bullet_SetFirerOwner

可用范围： [1.0.0, ∞)

HRESULT Bullet_SetFirerOwner(BulletClass* pBullet, HouseClass* pHouse)

更新子弹扩展中记录的发射方阵营。

参数：
- pBullet：子弹实例。
- pHouse：新的发射方阵营（若调用方有意清除所有权，可为空）。
如果找到并更新了子弹扩展，则返回 S_OK。
当 pBullet 为空时，失败并返回 E_POINTER。
当 pBullet 没有对应的 BulletExt 条目时，失败并返回 E_UNEXPECTED。

EventExt

EventExt_AddEvent

可用范围： [1.0.0, ∞)

HRESULT EventExt_AddEvent(EventExt* pEventExt)

在一个 EventExt 对象上调用 AddEvent。

参数：
- pEventExt：事件扩展实例。
若 AddEvent 成功则返回 S_OK，若 AddEvent 返回 false 则返回 S_FALSE。
当 pEventExt 为空时，失败并返回 E_POINTER。