C++ on 纪伟的个人博客

C++ 基础与原生互操作（五）：为 P/Invoke 设计稳定的 C 接口

Fri, 14 Aug 2026 10:00:00 +0800

写在前面

前四篇已经建立了语言、生命周期和 ABI 模型。最后用一个小型设备库把它们连起来：DLL 内部使用 C++ 类和 std::string，公共边界只暴露 C 函数、固定宽度整数、不透明句柄和 UTF-8 缓冲区，再由 C# 通过 LibraryImport 调用。

一、先定义边界规则

跨语言接口应先回答这些问题，再写代码：

句柄：谁创建、谁销毁，空句柄是否合法；
所有权：内存由哪一侧分配和释放，函数返回后指针还能用多久；
尺寸：长度按字节还是元素，是否包含字符串终止符；
编码：使用 UTF-8、UTF-16 还是平台相关编码；
错误：返回值是数据还是状态码，如何取得详细信息；
并发：同一句柄能否并发调用，销毁能否与其他调用同时发生；
版本：怎样扩展接口而不破坏既有调用者。

本例约定：所有函数使用 C 链接和 cdecl；返回 int32_t 状态码；名称使用 UTF-8；句柄由 create 创建、destroy 销毁；输出字符串采用“两次调用”查询容量（查询容量返回“缓冲区不足”状态只是一种约定，也有 SDK 对纯查询返回成功——C# 原生互操作系列（四）的示例即采用后者）；异常绝不跨出 DLL。带结构体参数时的 struct_size/api_version 演进惯例，见 C# 原生互操作与设备 SDK（八）：C++ ABI 与跨平台封装。

二、公共 C 头文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


// device_api.h
#pragma once

#include <stddef.h>
#include <stdint.h>

#if defined(_WIN32)
 #if defined(DEVICE_NATIVE_BUILD)
 #define DEVICE_API __declspec(dllexport)
 #else
 #define DEVICE_API __declspec(dllimport)
 #endif
 #define DEVICE_CALL __cdecl
#else
 #define DEVICE_API __attribute__((visibility("default")))
 #define DEVICE_CALL
#endif

#ifdef __cplusplus
 #define DEVICE_NOEXCEPT noexcept
extern "C" {
#else
 #define DEVICE_NOEXCEPT
#endif

typedef struct device_handle device_handle;

enum device_status
{
 DEVICE_OK = 0,
 DEVICE_INVALID_ARGUMENT = 1,
 DEVICE_BUFFER_TOO_SMALL = 2,
 DEVICE_INTERNAL_ERROR = 3
};

DEVICE_API int32_t DEVICE_CALL device_create(
 const char* endpoint_utf8,
 device_handle** out_handle) DEVICE_NOEXCEPT;

DEVICE_API void DEVICE_CALL device_destroy(
 device_handle* handle) DEVICE_NOEXCEPT;

DEVICE_API int32_t DEVICE_CALL device_read(
 device_handle* handle,
 double* out_value) DEVICE_NOEXCEPT;

DEVICE_API int32_t DEVICE_CALL device_get_name(
 device_handle* handle,
 char* buffer,
 size_t capacity,
 size_t* out_required) DEVICE_NOEXCEPT;

#ifdef __cplusplus
}
#endif

这份头文件也能被 C 编译器解析：C++ 专属的 extern "C" 和 noexcept 由 __cplusplus 条件保护，不透明结构体只公开名称、不公开布局。

接口刻意没有暴露 std::string、C++ 类、引用、异常或模板。device_handle** 是输出参数：成功后调用者得到一个不透明指针，只能交回本库函数。

三、DLL 内部使用 C++ 实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81


// device_api.cpp
#include "device_api.h"

#include <cstring>
#include <string>
#include <utility>

struct device_handle
{
 explicit device_handle(std::string endpoint_value)
 : endpoint(std::move(endpoint_value))
 {
 }

 std::string endpoint;
 double latest_value = 42.5;
};

int32_t DEVICE_CALL device_create(
 const char* endpoint_utf8,
 device_handle** out_handle) noexcept
{
 if (endpoint_utf8 == nullptr || endpoint_utf8[0] == '\0' ||
 out_handle == nullptr)
 {
 return DEVICE_INVALID_ARGUMENT;
 }

 *out_handle = nullptr;

 try
 {
 *out_handle = new device_handle(endpoint_utf8);
 return DEVICE_OK;
 }
 catch (...)
 {
 return DEVICE_INTERNAL_ERROR;
 }
}

void DEVICE_CALL device_destroy(device_handle* handle) noexcept
{
 delete handle; // delete nullptr 是安全的
}

int32_t DEVICE_CALL device_read(
 device_handle* handle,
 double* out_value) noexcept
{
 if (handle == nullptr || out_value == nullptr)
 {
 return DEVICE_INVALID_ARGUMENT;
 }

 *out_value = handle->latest_value;
 return DEVICE_OK;
}

int32_t DEVICE_CALL device_get_name(
 device_handle* handle,
 char* buffer,
 size_t capacity,
 size_t* out_required) noexcept
{
 if (handle == nullptr || out_required == nullptr)
 {
 return DEVICE_INVALID_ARGUMENT;
 }

 const size_t required = handle->endpoint.size() + 1;
 *out_required = required;

 if (buffer == nullptr || capacity < required)
 {
 return DEVICE_BUFFER_TOO_SMALL;
 }

 std::memcpy(buffer, handle->endpoint.c_str(), required);
 return DEVICE_OK;
}

公共函数的声明已在头文件中带导出属性和 C 链接，定义包含该头文件并保持签名一致即可。每个可能触发 C++ 异常的入口都必须在异常穿越 ABI 前拦住；本例 device_create 中字符串构造和内存分配都可能失败，所以用 catch (...) 转为状态码。

真实设备库还应定义句柄并发规则，并在内部加锁或要求调用者串行访问。本例的名称在创建后不再变化，因此两次调用查询字符串长度不会发生容量竞争；可变字符串则需要快照、版本或单次填充等额外设计。

四、构建动态库

Windows 的 Developer PowerShell：

1
2


cl /std:c++20 /EHsc /W4 /LD /DDEVICE_NATIVE_BUILD device_api.cpp /Fe:device_native.dll
dumpbin /exports device_native.dll

Linux：

1
2
3
4
5


g++ -std=c++20 -Wall -Wextra -Wpedantic \
 -fPIC -fvisibility=hidden -shared \
 device_api.cpp -o libdevice_native.so

nm -D --defined-only libdevice_native.so

检查结果应包含 device_create、device_destroy、device_read 和 device_get_name。构建机器能生成 DLL 不等于目标机器必然能加载，还要随部署核对目标架构和动态依赖。

五、C# 侧声明入口

面向 .NET 7 及更高版本，Microsoft 建议在支持的场景优先使用源生成的 LibraryImport。项目需要允许不安全代码，因为字符串输出示例直接固定字节缓冲区：

1
2
3
4


<PropertyGroup>
 <TargetFramework>net10.0</TargetFramework>
 <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
</PropertyGroup>

声明必须逐项匹配 C ABI：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;

internal static partial class NativeMethods
{
 private const string LibraryName = "device_native";

 internal const int Ok = 0;
 internal const int BufferTooSmall = 2;

 [LibraryImport(
 LibraryName,
 EntryPoint = "device_create",
 StringMarshalling = StringMarshalling.Utf8)]
 [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
 internal static partial int Create(string endpointUtf8, out nint handle);

 [LibraryImport(LibraryName, EntryPoint = "device_destroy")]
 [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
 internal static partial void Destroy(nint handle);

 [LibraryImport(LibraryName, EntryPoint = "device_read")]
 [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
 internal static partial int Read(DeviceSafeHandle handle, out double value);

 [LibraryImport(LibraryName, EntryPoint = "device_get_name")]
 [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
 internal static unsafe partial int GetName(
 DeviceSafeHandle handle,
 byte* buffer,
 nuint capacity,
 out nuint required);
}

库名不写平台后缀，让 .NET 按平台尝试相应名称。部署时仍需把 device_native.dll 或 libdevice_native.so 放到运行时可解析的位置；复杂部署可使用 NativeLibrary.SetDllImportResolver 明确解析策略。

六、用 `SafeHandle` 接管句柄

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


using Microsoft.Win32.SafeHandles;

internal sealed class DeviceSafeHandle : SafeHandleZeroOrMinusOneIsInvalid
{
 internal DeviceSafeHandle(nint handle)
 : base(ownsHandle: true)
 {
 SetHandle(handle);
 }

 protected override bool ReleaseHandle()
 {
 NativeMethods.Destroy(handle);
 return true;
 }
}

SafeHandle 让句柄释放进入 .NET 的可靠生命周期机制。普通调用把 DeviceSafeHandle 直接传给 P/Invoke，运行时会在调用期间保护它不被并发释放；不要为了省事到处取 DangerousGetHandle() 再传裸 nint。

再封装成业务可用的托管类型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83


using System.Text;

public sealed class Device : IDisposable
{
 private readonly DeviceSafeHandle _handle;

 private Device(DeviceSafeHandle handle)
 {
 _handle = handle;
 }

 public static Device Open(string endpoint)
 {
 var status = NativeMethods.Create(endpoint, out var rawHandle);
 if (status != NativeMethods.Ok)
 {
 throw new InvalidOperationException(
 $"device_create failed: {status}");
 }

 DeviceSafeHandle? safeHandle = null;
 try
 {
 safeHandle = new DeviceSafeHandle(rawHandle);
 return new Device(safeHandle);
 }
 catch
 {
 if (safeHandle is null)
 {
 NativeMethods.Destroy(rawHandle);
 }
 else
 {
 safeHandle.Dispose();
 }

 throw;
 }
 }

 public double Read()
 {
 var status = NativeMethods.Read(_handle, out var value);
 if (status != NativeMethods.Ok)
 {
 throw new InvalidOperationException(
 $"device_read failed: {status}");
 }

 return value;
 }

 public unsafe string GetName()
 {
 var status = NativeMethods.GetName(
 _handle, null, 0, out var required);

 if (status != NativeMethods.BufferTooSmall || required == 0 ||
 required > int.MaxValue)
 {
 throw new InvalidOperationException(
 $"device_get_name(size) failed: {status}");
 }

 var buffer = GC.AllocateUninitializedArray<byte>((int)required);
 fixed (byte* pointer = buffer)
 {
 status = NativeMethods.GetName(
 _handle, pointer, required, out var writtenRequired);

 if (status != NativeMethods.Ok || writtenRequired != required)
 {
 throw new InvalidOperationException(
 $"device_get_name(data) failed: {status}");
 }
 }

 return Encoding.UTF8.GetString(buffer, 0, buffer.Length - 1);
 }

 public void Dispose() => _handle.Dispose();
}

使用方式：

1
2


using var device = Device.Open("camera-1");
Console.WriteLine($"{device.GetName()}: {device.Read()}");

生产代码可以为状态码建立专用异常类型。上例还处理了一个容易遗漏的极端路径：原生创建已成功，但托管包装对象构造失败；此时根据 SafeHandle 是否已接管所有权，选择直接销毁裸句柄或释放安全句柄，避免泄漏。

七、为什么不直接返回字符串指针

这样的接口看似方便：

1

const char* device_get_name(device_handle* handle);

但调用者必须猜测返回指针：

是静态字符串、句柄内部缓存还是新分配内存；
下次调用后是否失效；
是否线程安全；
应由谁、用什么函数释放。

“调用者提供缓冲区 + 库返回所需容量”虽然多一步，却把分配和释放留在同一侧。另一种合理设计是 DLL 分配并提供专用 device_free，但必须保证任何成功返回的指针都由匹配函数释放。

八、常见反模式

直接导出 std::string、std::vector 或 C++ 类给 P/Invoke；
让 C++ 异常越过导出函数；
返回内部临时对象的地址；
用 int 同时表示状态和任意长度，却不说明负值、溢出和单位；
使用 bool、long、wchar_t 却不固定跨平台映射；
DLL 内分配，C# 用不匹配的分配器释放；
只在 x64 Debug 环境测试，不验证 Release、目标架构和干净机器部署；
只要 EntryPoint 找得到就认为签名正确。

更完整的 C# 封送、加载诊断、回调和 SafeHandle 细节，可继续阅读 C# 原生互操作与设备 SDK 系列。

九、本系列最终模型

现在可以把整条链路串起来：

1
2
3
4
5
6
7


C++ 类、容器与 RAII
 ↓ 封装在动态库内部
窄而稳定的 C ABI
 ↓ 导出符号 + 明确调用约定
.NET LibraryImport / P/Invoke
 ↓ SafeHandle + 托管包装
上位机业务代码

C++ 内部可以充分使用类、模板和标准库；跨语言边界则有意退回更小、更明确的 C 兼容合同。这不是放弃 C++ 的能力，而是把变化快、依赖工具链的实现细节隔离在 DLL 内，让 C# 只依赖可验证的二进制接口。

参考资料

C++ 基础与原生互操作（四）：库、符号与 ABI

Thu, 13 Aug 2026 10:00:00 +0800

写在前面

一个 C++ 函数在源码里叫 open_device，并不代表其他程序一定能在 DLL 中按这个名字找到它。跨文件调用依赖链接，跨动态库调用还依赖导出表、加载器和 ABI。本篇把这些容易混在一起的概念拆开。

一、翻译单元与链接符号

每个 .cpp 文件连同展开后的头文件通常形成一个翻译单元（translation unit，也常译作编译单元）。编译器分别处理翻译单元，链接器再把目标文件和库组合起来。

1
2
3
4


// math_api.h
#pragma once

double add(double left, double right);

1
2
3
4
5
6
7


// math_api.cpp
#include "math_api.h"

double add(double left, double right)
{
 return left + right;
}

头文件声明使调用处能通过类型检查，math_api.cpp 中的定义则产生链接所需的符号。如果定义没有参与最终链接，会出现未解析外部符号；如果不符合规则地提供多个定义，也可能链接失败或形成违反单一定义规则的程序。

二、静态库和动态库

产物	Windows 常见形式	Linux 常见形式	主要作用
目标文件	`.obj`	`.o`	单个翻译单元的编译结果
静态库	`.lib`	`.a`	链接时把所需目标代码纳入最终产物
动态库	`.dll`	`.so`	运行时由加载器映射，并解析导出符号
导入库	`.lib`	通常直接链接 `.so`（或指向 SONAME 的链接名符号链接）	Windows 原生链接器用来描述 DLL 入口

Windows 的 .lib 既可能是静态库，也可能是 DLL 的导入库，必须结合生成方式判断。P/Invoke 在运行时加载的是 DLL，不使用 C++ 链接器所需的 .lib；但原生 C++ 调用者通常会在构建时链接导入库。

动态库还可能依赖其他动态库。主 DLL 文件存在，不代表加载一定成功：依赖缺失、进程架构不一致、搜索路径错误或运行库缺失都会在调用入口之前造成失败。

三、ABI 是二进制层面的合同

API 描述源码如何调用；ABI（Application Binary Interface）描述编译后二进制怎样协作，通常包括：

参数如何放入寄存器或栈、返回值如何传递；
类型宽度、对齐、结构体和类布局；
函数调用约定；
符号命名和名称修饰；
异常传播、运行库和内存分配约定。

C++ 标准不规定一个跨所有编译器和平台的统一 ABI。即使两份代码都符合相同语言标准，由不同工具链、选项或标准库构建，也不能据此推断二进制接口必然兼容。

这也是“头文件能看懂”却仍然“DLL 调不通”的根本原因：P/Invoke 对接的是 ABI，而不是 C++ 源码语法。

四、名称修饰与 `extern "C"`

C++ 支持重载，下面两个函数源码名相同：

1
2


int convert(int value);
double convert(double value);

链接器需要区分它们，因此编译器会把函数名、参数类型、命名空间等信息编码到链接名称中，这称为名称修饰（name mangling）。不同工具链的修饰规则可能不同。

1

extern "C" int open_device(const char* endpoint);

extern "C" 为函数指定 C 语言链接，避免 C++ 重载式名称修饰，使导出名称更适合其他语言查找。但它不等于“这个接口已经跨平台稳定”：参数布局、调用约定、类型宽度和所有权仍需单独设计，而且同一作用域中不能依靠 C 链接名称导出重载组。

五、Windows 导出与跨平台可见性

可以用宏把平台差异集中在公共头文件中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


#pragma once

#if defined(_WIN32)
 #if defined(DEVICE_NATIVE_BUILD)
 #define DEVICE_API __declspec(dllexport)
 #else
 #define DEVICE_API __declspec(dllimport)
 #endif
 #define DEVICE_CALL __cdecl
#else
 #define DEVICE_API __attribute__((visibility("default")))
 #define DEVICE_CALL
#endif

extern "C" DEVICE_API int DEVICE_CALL device_version();

构建 DLL 本身时定义 DEVICE_NATIVE_BUILD，Windows 编译器把函数写入 DLL 导出表；原生 C++ 消费者包含同一头文件时不定义它，声明会变成 dllimport。P/Invoke 消费者不编译这个头文件，但其声明仍必须匹配最终 ABI。这里的简化形式依赖 C++ 编译器；完整的 C/C++ 双解析公共头写法见下一篇。

在 64 位 Windows 的常规 x64 ABI 下，__cdecl、__stdcall 等传统约定大多不再像 32 位 x86 那样改变参数传递方式，但显式约定仍能表达合同，并避免 32 位构建时双方不一致。不要拿 x64 上“碰巧都能调用”的现象反推所有架构。

Linux 共享库默认可能暴露许多全局符号。项目可用 -fvisibility=hidden 隐藏默认符号，再用 visibility("default") 只开放公共入口，从而缩小 ABI 表面。

六、用 CMake 描述库目标

CMake 是跨平台构建系统生成器，不是编译器。下面的项目可用 MSVC、GCC 或 Clang 后端构建共享库：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


cmake_minimum_required(VERSION 3.20)
project(device_native LANGUAGES CXX)

add_library(device_native SHARED
 device_api.cpp
 device_api.h
)

target_compile_features(device_native PRIVATE cxx_std_20)
target_compile_definitions(device_native PRIVATE DEVICE_NATIVE_BUILD)

set_target_properties(device_native PROPERTIES
 CXX_VISIBILITY_PRESET hidden
 VISIBILITY_INLINES_HIDDEN YES
)

if(MSVC)
 target_compile_options(device_native PRIVATE /W4 /permissive-)
else()
 target_compile_options(device_native PRIVATE -Wall -Wextra -Wpedantic)
endif()

常见构建命令：

1
2


cmake -S . -B build
cmake --build build --config Release

-S 指定源码目录，-B 指定独立构建目录。Visual Studio 等多配置生成器需要 --config Release 选择配置；单配置生成器通常在配置阶段通过 CMAKE_BUILD_TYPE 选择，不能假设两者行为完全相同。

CMake 的 SHARED 目标在 Windows 通常产生 DLL 和导入库，在 Linux 通常产生 .so。具体文件名、后缀和输出目录仍受平台、生成器和项目属性影响。

七、检查导出符号

Windows 开发者命令行可使用：

1

dumpbin /exports device_native.dll

Linux 常用：

1
2


nm -D --defined-only libdevice_native.so
readelf --dyn-syms libdevice_native.so

你希望看到稳定的 device_version 之类的 C 入口，而不是带有大量问号、类型编码或命名空间信息的 C++ 修饰名。

符号检查只证明“入口被导出”，不能证明 P/Invoke 参数、结构布局和调用约定正确。后者需要对照公共头文件，并以实际调用测试验证。

八、Debug / Release 与运行库边界

Debug 和 Release 不只是“有没有日志”：优化、迭代器检查、运行库选择和二进制布局都可能不同。不要把 Debug 版原生库误当作可随意交付的生产依赖。

尤其要避免一边分配、另一边用不匹配的运行库释放。例如 DLL 返回由内部 new[] 分配的缓冲区，C# 再调用不对应的释放方式，可能破坏堆。可靠做法包括：

调用者提供缓冲区和容量；
DLL 同时提供配对的 create / destroy 或 allocate / free；
对象始终由创建它的模块销毁；
文档明确线程安全、生命周期和版本兼容策略。

九、DLL 能否 P/Invoke 的判断清单

拿到一个 C++ SDK 时依次确认：

当前进程与 DLL 的架构是否一致；
DLL 是否导出可定位的非托管函数入口；
是否提供 C 兼容头文件，而不是只导出 C++ 类；
调用约定、整数宽度、结构布局和字符编码是什么；
每个指针是否可空、长度单位是什么、谁拥有内存；
错误怎样返回，异常是否被挡在 DLL 内；
DLL 的依赖库和运行库是否随部署完整；
回调能从哪些线程触发，句柄能否并发使用。

如果供应商只提供 C++ 类接口，常见办法不是在 C# 中猜 ABI，而是增加一层由兼容工具链构建的原生包装 DLL，对外暴露 C ABI。现有文章 C# 原生互操作与设备 SDK（八）：C++ ABI 与跨平台封装从 C# 调用方讨论了这条路线。

十、本篇小结

库文件只是载体，真正连接双方的是 ABI。extern "C" 解决的是语言链接和名称修饰的一部分，导出宏解决符号可见性的一部分；类型布局、调用约定、内存所有权和错误边界仍需共同设计。下一篇将把这些规则落到一套可以被 P/Invoke 调用的完整接口上。

参考资料

C++ 基础与原生互操作（三）：对象、RAII 与现代资源管理

Wed, 12 Aug 2026 10:00:00 +0800

写在前面

C# 有垃圾回收，C++ 没有一个负责回收所有对象的托管堆，但这不等于现代 C++ 要在业务代码里到处手写 delete。C++ 的核心做法是把资源所有权放进对象，让析构函数随着作用域结束自动执行，这就是 RAII。

一、`struct` 和 `class`

两者都可以有字段、成员函数、构造函数、继承关系和访问控制。主要语言差异是默认权限：struct 成员和继承默认 public，class 默认 private。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


#include <stdexcept>
#include <string>
#include <utility>

class TemperatureSensor
{
public:
 explicit TemperatureSensor(std::string name)
 : name_(std::move(name))
 {
 if (name_.empty())
 {
 throw std::invalid_argument("name must not be empty");
 }
 }

 [[nodiscard]] const std::string& name() const noexcept
 {
 return name_;
 }

private:
 std::string name_;
};

这段代码里：

构造函数保证对象一旦构造成功，名称就有效；
explicit 防止单个字符串被意外隐式转换为 TemperatureSensor；
成员初始化列表直接初始化 name_；
成员函数末尾的 const 表示不修改当前对象的可观察状态；
noexcept 表示函数承诺不让异常逃出；
[[nodiscard]] 提醒调用者不要无意忽略返回值。

二、RAII 管的不只是内存

RAII 全称 Resource Acquisition Is Initialization。资源可以是内存，也可以是文件、锁、套接字、设备句柄或相机采集会话。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


#include <cstdio>
#include <stdexcept>

class File
{
public:
 explicit File(const char* path)
 : handle_(std::fopen(path, "rb"))
 {
 if (handle_ == nullptr)
 {
 throw std::runtime_error("failed to open file");
 }
 }

 ~File()
 {
 std::fclose(handle_);
 }

 File(const File&) = delete;
 File& operator=(const File&) = delete;

private:
 std::FILE* handle_;
};

当 File 离开作用域时，析构函数会运行；正常返回和异常展开都会触发这种自动清理。这里禁止复制，是因为两个对象若持有同一个 FILE*，可能重复关闭。

真实项目更常直接使用标准库已有的 std::ifstream，上例只是展示如何把一对 open / close 封装成所有权类型。

三、优先遵循 Rule of Zero

如果类的成员已经会正确管理自身资源，外层类通常不需要手写析构、复制或移动操作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


#include <string>
#include <vector>

class Batch
{
public:
 void add(double value)
 {
 values_.push_back(value);
 }

private:
 std::string recipe_name_;
 std::vector<double> values_;
};

std::string 和 std::vector 会自动管理其内存，因此 Batch 的编译器生成操作通常已经正确。这称为 Rule of Zero：尽量让资源管理下沉到专门类型，业务类型不直接处理裸资源。

只有直接拥有特殊资源时，才需要认真设计析构、复制构造、复制赋值、移动构造和移动赋值。常见概括是 Rule of Five，但它不是要求每个类都机械写五个函数。

四、复制与移动表达不同语义

1
2
3


std::string first = "camera-1";
std::string copied = first; // copied 拥有独立值
std::string moved = std::move(first); // 允许转移 first 的资源

移动后的 first 仍是有效对象，但其具体值通常只保证满足该类型文档规定的“有效但未指定状态”；可以销毁或重新赋值，不应假设它仍包含原字符串。

std::move 本身不移动数据，它只是把表达式转换为允许选择移动操作的值类别。真正发生什么由目标类型的构造或赋值操作决定。

按值传参并不必然很慢。现代编译器可进行复制消除；自 C++17 起，当函数返回与返回类型相同的类类型纯右值时，结果对象会由该表达式直接初始化，不调用复制或移动构造函数。返回命名局部变量的 NRVO 仍不是强制保证。类型也可以提供低成本移动，因此应先让接口语义清楚，再依据测量结果优化。

五、智能指针表达所有权

1
2
3
4


#include <memory>

auto unique_sensor = std::make_unique<TemperatureSensor>("camera-1");
auto shared_sensor = std::make_shared<TemperatureSensor>("camera-2");

std::unique_ptr<T> 表示独占所有权，不可复制，可以移动；
std::shared_ptr<T> 通过引用计数表达共享所有权；
std::weak_ptr<T> 观察由 shared_ptr 管理的对象而不增加强引用，可用于打破共享所有权环。

不要因为“更保险”就默认使用 shared_ptr。它增加状态、原子引用计数等成本，也可能因环形引用让对象无法释放。C++ Core Guidelines 建议除非确实需要共享所有权，否则优先 unique_ptr。

裸指针和引用仍有合理用途：它们通常表达非拥有访问。关键不是“代码里绝不能出现 T*”，而是接口能否区分拥有者和借用者。

六、异常与错误边界

C++ 异常会沿调用栈展开，并析构已经完整构造的自动对象：

1
2
3
4
5
6
7


void run_device(); // 设备工作逻辑，可能抛出异常

void acquire_and_run()
{
 File config("device.bin");
 run_device(); // 即使这里抛异常，config 仍会被析构
}

但异常安全依赖 RAII。如果先取得裸资源，后续步骤抛异常，就可能泄漏。

异常也不能跨越 C ABI 或 P/Invoke 边界。不同语言运行时不知道如何可靠传播和销毁对方的异常对象。导出函数应在 C++ 边界捕获全部异常，转换为错误码或明确的错误对象：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


extern "C" int run_device_safely() noexcept
{
 try
 {
 run_device();
 return 0;
 }
 catch (const std::exception&)
 {
 return 1;
 }
 catch (...)
 {
 return 2;
 }
}

noexcept 函数若仍有异常逃出，程序会调用 std::terminate；所以不能只写声明而忘记封闭所有可能抛出的路径。

七、模板先理解用途，不必立刻深挖

模板让代码按类型生成实例：

1
2
3
4
5
6
7


template <typename T>
T clamp(T value, T minimum, T maximum)
{
 if (value < minimum) return minimum;
 if (maximum < value) return maximum;
 return value;
}

std::vector<double>、std::unique_ptr<TemperatureSensor> 都是模板实例。模板通常需要在使用点看到定义，因此大量实现会出现在头文件中。编译错误也可能展开为很长的模板诊断，先找到最靠近自己调用代码的类型不匹配通常更有效。

模板是 C++ 内部很强的抽象工具，但不应直接出现在 P/Invoke 接口里。跨语言调用需要的是运行时可定位的具体导出符号，而不是让 C# 实例化 C++ 模板。

八、C++ 对象为什么不宜直接导出给 C#

直接导出 C++ 类会把许多实现细节变成 ABI 契约：

类的内存布局、对齐和虚函数表；
构造、析构和名称修饰规则；
编译器、标准库与运行库版本；
异常模型和内存分配器；
模板实例与内联实现。

如果 DLL 和调用者都由同一 C++ 工具链统一构建，这种接口可以工作；但 P/Invoke 不理解这些 C++ 语义。更稳妥的办法是在 DLL 内部保留现代 C++ 类，对外只暴露不透明句柄和 C 函数。第五篇会实现这种“外 C、内 C++”的分层。

九、本篇小结

现代 C++ 的资源安全核心不是手工记住每一个 delete，而是把所有权交给具有析构函数的对象。局部对象、标准容器、unique_ptr 和专用句柄类型让清理随生命周期自动发生。跨到 P/Invoke 边界时，不导出这些实现类型，而是把它们藏在 DLL 内部。

参考资料

C++ 基础与原生互操作（二）：类型、指针、引用与生命周期

Tue, 11 Aug 2026 10:00:00 +0800

写在前面

阅读 C++ SDK 头文件时，最容易卡住的不是 if 和 for，而是 const char*、void**、T&、数组长度和谁负责释放内存。本篇不把指针讲成玄学，而是围绕三个问题展开：对象在哪里、一个表达式指向谁、对象能活多久。

一、类型决定可执行的操作

C++ 内置了整数、浮点、字符和布尔类型，也允许定义枚举、结构体和类：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#include <cstdint>

enum class DeviceState : std::uint32_t
{
 disconnected = 0,
 ready = 1,
 running = 2,
 faulted = 3
};

struct Measurement
{
 std::uint64_t sequence;
 double value;
 DeviceState state;
};

std::uint32_t、std::uint64_t 等固定宽度整数在平台提供对应精确宽度类型时可用，适合协议字段和经过设计的 ABI。普通 int 至少为 16 位，但标准不承诺它在所有平台都恰好是 32 位。跨语言边界不能只凭本机经验猜大小。

sizeof(T) 返回类型或对象占用的字节数，但结构体大小不一定等于各字段大小简单相加：编译器可能为对齐插入填充。字段类型一致也不代表不同编译器选项下的布局一定兼容。

二、值、引用和指针

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


void increment_value(int value) // 得到副本
{
 ++value;
}

void increment_reference(int& value) // 借用原对象，可修改
{
 ++value;
}

void increment_pointer(int* value) // 指向对象，也可以为空
{
 if (value != nullptr)
 {
 ++*value;
 }
}

调用方式如下：

1
2
3
4


int count = 1;
increment_value(count); // count 仍为 1
increment_reference(count); // count 变为 2
increment_pointer(&count); // count 变为 3

T 按值传递，函数获得一个参数对象；复制可能被移动或省略规则优化，但接口语义仍是值；
T& 是引用，必须绑定到有效对象，常表示非空借用；
T* 是指针，保存地址，可用 nullptr 表示没有对象；
&object 取得地址，*pointer 解引用并访问所指对象。

引用不是“更安全的指针”这么简单。引用和指针都可能在目标对象生命周期结束后悬空；区别主要体现在语法和接口表达力，而非自动生命周期管理。

三、`const` 要看修饰的是谁

1
2
3
4


int count = 1; // 沿用上一节的计数变量
const int* pointer_to_const = nullptr; // 不能通过指针修改 int
int* const const_pointer = &count; // 指针本身不能改指向
const int* const both = &count; // 两者都不能改

函数参数中最常见的是：

1

double average(const double* values, std::size_t count);

它表示函数只读 values 指向的元素，但没有说明指针能否为空、实际有多少元素、内存由谁拥有。count 和指针之间的对应关系只是接口约定，调用者必须同时满足。

在纯 C++ 内部代码中可使用 std::span<const double> 把“指针 + 长度”组合为一个非拥有视图：

1
2
3


#include <span>

double average(std::span<const double> values);

不过 std::span 是 C++ 标准库类型，不应直接放进供 P/Invoke 使用的 C ABI。跨边界时仍需展开为基础类型。

四、数组、容器与字符串

1
2
3
4
5
6
7


#include <string>
#include <string_view>
#include <vector>

std::vector<double> samples { 1.2, 2.4, 3.6 };
std::string owned_name = "camera-1";
std::string_view borrowed_name = owned_name;

std::vector<T> 拥有一段连续元素，可自动管理容量和释放内存；
std::string 拥有字符序列；
std::string_view 只是字符视图，不拥有底层数据；
原生数组 T[N] 的长度是类型的一部分，但传给多数函数后常退化为指针，长度信息不会随指针自动传递。

string_view 很轻量，但必须比它观察的数据活得短。下面的函数会返回悬空视图：

1
2
3
4
5


std::string_view broken_name()
{
 std::string temporary = "camera-1";
 return temporary; // 返回后 temporary 被销毁
}

动态库也不能把内部临时 std::string 的 c_str() 返回给 C# 后继续假设它永远有效。字符串编码、终止符、缓冲区容量和有效期必须成为接口契约的一部分。

五、存储位置不等于生命周期模型

初学资料常把内存简单分成“栈”和“堆”，但 C++ 标准层面更重要的是存储期和对象生命周期：

1
2
3
4
5
6
7
8
9


int global_value = 1; // 静态存储期
thread_local int last_code; // 线程存储期

void process()
{
 int local_value = 2; // 自动存储期
 auto dynamic_value = new int(3); // 动态存储期
 delete dynamic_value;
}

局部对象通常由实现放在调用栈，但优化器可以改变具体存放方式；new 创建的对象具有动态存储期，必须由匹配的所有者释放。现代 C++ 业务代码一般不应裸写上面的 new / delete，而应优先使用局部对象、容器和智能指针。

对象生命周期结束后，之前指向它的指针不会自动变成 nullptr。继续解引用就是未定义行为：程序可能崩溃、貌似正常，或在优化构建中表现完全不同。

六、未定义行为为什么危险

常见来源包括：

数组或缓冲区越界；
解引用空指针或悬空指针；
读取未初始化的基础类型；
有符号整数溢出；
数据竞争；
用不匹配的方式释放内存。

“未定义”不是“标准规定必须抛异常”。它表示程序已经违反语言要求，标准不再约束后续行为。调试版能运行不能证明代码正确，跨编译器、跨优化级别或升级工具链后尤其容易暴露问题。

MSVC 可使用 AddressSanitizer 帮助发现部分内存错误：

1

cl /std:c++20 /EHsc /fsanitize=address sample.cpp

GCC 和 Clang 常用：

1

g++ -std=c++20 -fsanitize=address,undefined -fno-omit-frame-pointer sample.cpp

Sanitizer 是运行时检测工具，只能覆盖实际执行到的路径，不能替代正确的所有权设计和测试。

七、怎样读 SDK 函数签名

假设厂商头文件给出：

1
2
3
4
5


int read_frame(
 device_handle* device,
 std::uint8_t* buffer,
 std::size_t capacity,
 std::size_t* bytes_written);

逐项追问：

device 是否允许为空，由谁创建和销毁？
buffer 是调用者提供的可写内存，还是函数会替换指针？
capacity 以字节还是元素计数？
bytes_written 是否必填，失败时是否仍会写入？
返回 int 是状态码还是实际长度？错误码如何解释？
函数返回后，库是否仍保留任何指针？是否允许并发调用？

头文件只描述类型，未必描述完整契约。P/Invoke 声明必须以供应商头文件和文档为依据，不能只看函数名字推断。

八、跨 ABI 时需要更保守

在 DLL 边界应谨慎对待这些类型：

long：Windows 上通常为 32 位，许多 64 位 Unix 平台上为 64 位；
wchar_t：Windows 常为 16 位，许多 Unix 平台常为 32 位；
bool：不要假设与 C# 默认 P/Invoke 布尔封送布局相同；
size_t：随进程位数变化，C# 通常用 nuint 对应；
指针和句柄：随进程架构变化，C# 通常用 nint 或 SafeHandle；
C++ 标准库类型：std::string、std::vector 等布局属于具体实现的 ABI，不直接暴露给 P/Invoke。

更稳妥的公共接口使用固定宽度整数、明确的指针 + 长度、显式编码和不透明句柄。C# 侧的具体类型映射可继续阅读 C# 原生互操作与设备 SDK（二）：C# 类型与 C ABI。

九、本篇小结

值表达独立对象，引用和指针通常表达借用或间接访问，但它们不会自动管理目标生命周期。现代 C++ 内部优先让容器和资源管理对象持有内存；进入 ABI 边界后，再把接口收窄为尺寸、编码和所有权都明确的基础类型。

参考资料

C++ 基础与原生互操作（一）：语言、工具链与程序构建

Mon, 10 Aug 2026 10:00:00 +0800

写在前面

当 C# 项目需要调用厂商 DLL 时，文档里常会同时出现 .h、.lib、.dll、extern "C" 和 __declspec(dllexport)。如果只从 P/Invoke 声明入手，很容易把“函数签名写对”当成全部问题，却不知道这个 DLL 是怎样生成的、为什么符号找不到，以及头文件究竟是不是程序的一部分。

本系列面向已有 C# 等语言经验、需要阅读或维护原生 SDK 的开发者。目标不是穷举 C++ 语法，而是建立一套够用的模型：看懂常见代码，知道怎样编译和链接，并能为跨语言调用设计合理边界。示例使用 C++20 中成熟、常见的能力。

一、C++ 到底是什么

C++ 是一门由 ISO 标准定义的通用编程语言。标准描述语法、类型系统、抽象机制和标准库接口，但不会给你一个名为“C++”的唯一运行程序。真正把源码变成目标平台程序的是具体工具链，例如：

Microsoft Visual C++（MSVC）：Windows 和 Visual Studio 中常见；
GCC：Linux 发行版中常见；
Clang/LLVM：Windows、Linux、macOS 均可使用。

“C++”“编译器”“标准库”“IDE”不是同一个东西。Visual Studio 是开发环境，cl.exe 才是 MSVC 编译器驱动程序；GCC 的 C++ 驱动通常叫 g++，Clang 的通常叫 clang++。

C++ 常被称为编译型语言，因为典型实现会在运行前把源代码编译、链接为目标平台机器码。不过，语言标准主要规定程序的可观察行为，并不强制实现必须采用某一条内部流水线。工程上把它理解为“通常提前编译成特定平台的原生程序”就够用了。

二、第一个程序

1
2
3
4
5
6
7
8
9


#include <iostream>
#include <string>

int main()
{
 const std::string name = "C++";
 std::cout << "Hello, " << name << '\n';
 return 0;
}

这几行已经包含了不少 C++ 概念：

#include 由预处理阶段处理，把所需声明引入当前翻译单元；
std::string 和 std::cout 来自标准库的 std 命名空间；
const 表示初始化后不能通过这个名称修改对象；
main 是常规宿主环境中 C++ 可执行程序的入口，返回 0 通常表示成功；
语句通常以分号结束，代码块由花括号界定。

不要为了少写几个字符就在头文件或大型项目中使用 using namespace std;。显式写出 std:: 能说明名称来自哪里，也可降低大型工程中的名称冲突风险。

2.1 在 Windows 上编译

在 “Developer PowerShell for Visual Studio” 中执行：

1
2


cl /std:c++20 /EHsc /W4 hello.cpp
.\hello.exe

/std:c++20 选择语言模式，/EHsc 启用常规 C++ 异常语义，/W4 打开较严格的警告。普通 PowerShell 若没有初始化 Visual Studio 开发环境，可能找不到 cl，这不等于编译器没有安装。

2.2 在 Linux 上编译

1
2


g++ -std=c++20 -Wall -Wextra -Wpedantic hello.cpp -o hello
./hello

编译器警告应当进入日常反馈闭环，但“零警告”不等于程序不存在未定义行为、生命周期错误或业务缺陷。

三、从源码到程序发生了什么

可以先用四个阶段理解常规构建：

1
2
3
4
5
6
7


源文件与头文件
 ↓ 预处理：展开 #include、宏和条件编译
翻译单元
 ↓ 编译：语法/类型检查并生成目标代码
目标文件（Windows 常见 .obj，Unix 常见 .o）
 ↓ 链接：解析跨文件符号和依赖库
可执行文件或库（.exe、.dll、.so、.a、.lib 等）

实际工具链可能把若干阶段合并执行，但排错时区分它们很重要：

语法错误、类型不匹配通常是编译错误；
“无法解析的外部符号”或 undefined reference 通常是链接错误；
程序启动后找不到 DLL / .so 是加载阶段问题；
成功加载后入口点不存在，往往是导出名、架构或声明不匹配。

四、`.cpp` 与 `.h` 各自负责什么

头文件通常放供其他翻译单元使用的声明，源文件放定义：

1
2
3
4


// temperature.h
#pragma once

double celsius_to_fahrenheit(double value);

1
2
3
4
5
6
7


// temperature.cpp
#include "temperature.h"

double celsius_to_fahrenheit(double value)
{
 return value * 9.0 / 5.0 + 32.0;
}

1
2
3
4
5
6
7
8


// main.cpp
#include "temperature.h"
#include <iostream>

int main()
{
 std::cout << celsius_to_fahrenheit(25.0) << '\n';
}

声明告诉编译器“这个名称是什么”，定义提供实体或实现。头文件本身通常不是独立编译单元；它会被 #include 到一个或多个源文件中。#pragma once 用于避免同一头文件在一个翻译单元中被重复包含，主流编译器均支持；跨工具链公共头也常使用传统 include guard。

分别编译再链接时，命令大致如下：

1
2


cl /std:c++20 /EHsc /W4 /c temperature.cpp main.cpp
link temperature.obj main.obj /OUT:temperature.exe

如果头文件只写了声明，却没有把包含定义的目标文件或库交给链接器，源码可以通过编译，最后仍会链接失败。

五、先掌握这些基础语法

下面的函数足以串起变量、分支、循环、容器和函数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


#include <vector>

double average_positive(const std::vector<double>& values)
{
 double sum = 0.0;
 int count = 0;

 for (const double value : values)
 {
 if (value <= 0.0)
 {
 continue;
 }

 sum += value;
 ++count;
 }

 return count == 0 ? 0.0 : sum / count;
}

读函数签名时从外向内看：它名为 average_positive，返回 double，接收一个 std::vector<double> 的常量引用。const ...& 表示函数借用现有容器、不会复制整个 vector，并承诺不通过该引用修改它。

C# 开发者还应注意：

C++ 局部变量不会自动获得 C# 字段那样的默认值；未初始化的基础类型可能具有不确定值；
整数除法仍会截断小数，5 / 2 得到 2；
== 比较对象时调用何种语义由类型和运算符定义决定；
编译通过不代表访问越界、悬空指针等错误会被运行时统一拦截。

六、C++、C 和 C++/CLI 不要混为一谈

C 是另一门语言，和 C++ 有大量共同语法，但拥有自己的标准和类型规则；
原生 C++ 通常生成目标平台的原生代码，可构建 DLL、.so 和可执行文件；
C++/CLI 是 Microsoft 面向 .NET 互操作的语言扩展，可同时接触托管与原生世界，但不是跨平台 C++ 的同义词；
P/Invoke 描述 .NET 如何调用非托管库的函数入口，不会直接理解任意 C++ 类、模板或重载。

因此，看到“C++ DLL”时还不能断定它能直接 P/Invoke。你首先需要知道它导出了哪些符号，以及是否提供了稳定的 C 兼容入口。第四、第五篇会把这条边界完整接起来。

七、本篇小结

C++ 是语言，MSVC、GCC、Clang 是常见工具链实现。源文件经过预处理、编译和链接，最终成为可执行文件或库；头文件主要提供声明，不是 DLL 本身。遇到原生 SDK 时，先区分编译、链接、加载和调用阶段，很多看似神秘的 P/Invoke 故障就有了明确位置。

C++ on 纪伟的个人博客

C++ 基础与原生互操作（五）：为 P/Invoke 设计稳定的 C 接口

写在前面

一、先定义边界规则

二、公共 C 头文件

三、DLL 内部使用 C++ 实现

四、构建动态库

五、C# 侧声明入口

六、用 SafeHandle 接管句柄

七、为什么不直接返回字符串指针

八、常见反模式

九、本系列最终模型

参考资料

C++ 基础与原生互操作（四）：库、符号与 ABI

写在前面

一、翻译单元与链接符号

二、静态库和动态库

三、ABI 是二进制层面的合同

四、名称修饰与 extern "C"

五、Windows 导出与跨平台可见性

六、用 CMake 描述库目标

七、检查导出符号

八、Debug / Release 与运行库边界

九、DLL 能否 P/Invoke 的判断清单

十、本篇小结

参考资料

C++ 基础与原生互操作（三）：对象、RAII 与现代资源管理

写在前面

一、struct 和 class

二、RAII 管的不只是内存

三、优先遵循 Rule of Zero

四、复制与移动表达不同语义

五、智能指针表达所有权

六、异常与错误边界

七、模板先理解用途，不必立刻深挖

八、C++ 对象为什么不宜直接导出给 C#

九、本篇小结

参考资料

C++ 基础与原生互操作（二）：类型、指针、引用与生命周期

写在前面

一、类型决定可执行的操作

二、值、引用和指针

三、const 要看修饰的是谁

四、数组、容器与字符串

五、存储位置不等于生命周期模型

六、未定义行为为什么危险

七、怎样读 SDK 函数签名

八、跨 ABI 时需要更保守

九、本篇小结

参考资料

C++ 基础与原生互操作（一）：语言、工具链与程序构建

写在前面

一、C++ 到底是什么

二、第一个程序

2.1 在 Windows 上编译

2.2 在 Linux 上编译

三、从源码到程序发生了什么

四、.cpp 与 .h 各自负责什么

五、先掌握这些基础语法

六、C++、C 和 C++/CLI 不要混为一谈

七、本篇小结

参考资料

六、用 `SafeHandle` 接管句柄

四、名称修饰与 `extern "C"`

一、`struct` 和 `class`

三、`const` 要看修饰的是谁

四、`.cpp` 与 `.h` 各自负责什么