> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 旧版协议

> 什么是 VEF 协议、服务器在加载扩展时如何选择协议，以及协议 1 和协议 3 的参考。

当服务器调用扩展中的函数时，它通过一组固定的 C 结构体传入参数并读回结果。自定义类型的工作方式相同：扩展在一个结构体中描述每个类型，服务器在你安装该扩展时以及每次服务器启动时读取该结构体。协议是这些结构体及其填写规则的一个带编号的版本。

每个新协议都会向这些结构体添加内容，但不会移动旧扩展所读取的字段，并且服务器会保留读取每个旧版稳定协议的代码。这就是服务器仍能加载为旧版协议构建的扩展的原因。

你不需要自己设置协议编号。构建扩展所用的 SDK 会设置它：每个 SDK 版本为一个稳定协议构建扩展，其开发版 ABI 头文件（`-DVSQL_USE_DEV_ABI=ON`）则为开发协议构建扩展。要将扩展迁移到更新的协议，请使用更新的 SDK 重新构建它。

## 服务器如何选择协议

当你安装扩展时，服务器提供其最新的协议，扩展则声明其构建时所针对的协议。然后服务器和扩展使用两个编号中较低的那个。例如，提供协议 4 的服务器会以协议 3 与为协议 3 构建的扩展通信，并且不会向该扩展提供协议 4 新增的任何功能。

要查看每个已安装扩展所用的协议，请查询 `INFORMATION_SCHEMA.EXTENSION_REGISTRATION`：

```sql theme={null}
SELECT EXTENSION_NAME, NEGOTIATED_PROTOCOL
FROM INFORMATION_SCHEMA.EXTENSION_REGISTRATION;
```

`NEGOTIATED_PROTOCOL` 列保存服务器和扩展商定的协议。

## 稳定协议和开发协议

奇数编号的协议是稳定协议。目前服务器接受每一个稳定协议，一直追溯到协议 1，因此你为稳定协议构建的扩展无需重新构建即可继续安装到更新的服务器上。

偶数编号的协议是开发版本。服务器只接受它自己的开发协议，并且该协议的结构体可能在两个服务器构建版本之间发生变化。使用开发版 ABI 头文件（`-DVSQL_USE_DEV_ABI=ON`）构建的扩展可能在你更新服务器后停止工作。如果发生这种情况，请针对新服务器重新构建它。

当某个版本将开发协议提升为下一个稳定编号时，服务器会停止接受旧的开发编号。此时 `INSTALL EXTENSION` 会失败，并报错 `extension uses obsolete unstable protocol version`，后面跟着旧编号和当前编号。服务器启动时也会执行同样的检查，因此在安装有此类扩展的情况下服务器不会启动。在升级服务器之前，请针对新版本重新构建每一个使用开发版 ABI 头文件构建的扩展。

| 协议 | 状态 | 构建工具 |
| - | - | - |
| 1 | 稳定 | SDK 0.0.1 至 0.0.3 |
| 2 | 不再支持 | 0.0.3 的开发版 ABI 头文件 |
| 3 | 稳定 | SDK 0.0.4 至 0.0.7 |
| 4 | 开发版 | 0.0.4 至 0.0.7 的开发版 ABI 头文件 |

> [!NOTE]
>
> **0.0.8-dev 中的变更。** 协议 4 成为稳定协议 5，由 SDK 0.0.8 构建。0.0.8 的开发版 ABI 头文件构建协议 6。服务器拒绝协议 4，协议 4 不再受支持。协议 1 和 3 被弃用：服务器仍然接受它们，但新扩展应使用协议 5。

## 协议 3

SDK 0.0.4 至 0.0.7 构建协议 3 扩展。

> [!NOTE]
>
> **0.0.8-dev 中的变更。** 你使用这些 SDK 之一构建的扩展在更新的服务器上继续工作，行为不变，你不需要重新构建它。
>
> 如果你使用 0.0.8 SDK 重新构建它，它会迁移到协议 5，并可以使用以下功能：
>
> * `.max_result_length()`，用于设置 STRING 或 BINARY 函数结果列的大小，使物化结果不会被截断至参数宽度。
> * [加载和卸载钩子](https://villagesql.com/docs/zh/sdk/cpp/development.md#extension-load-and-unload-hooks)，即 `.on_init()` 和 `.on_deinit()`。
> * [可变长度自定义类型](https://villagesql.com/docs/zh/sdk/cpp/type-operations.md#variable-length-types)，即 `.variable_length_type()`。
> * 用于原始字节的 `BINARY` 参数和结果类型。
> * 自定义类型的二进制形式，即 `.from_binary()` 和 `.to_binary()`，可在 SQL 中以 `TYPE::from_binary` 和 `TYPE::to_binary` 调用。
> * 能看到常量参数值的 prerun。
> * [在解析时进行类型检查](https://villagesql.com/docs/zh/sdk/cpp/development.md#deciding-a-functions-type-parameters-at-resolution-time)，即 `.bind_and_check_types()`。
> * `out.set()` 会完整返回大于缓冲区的 STRING 值，而协议 3 会截断该值。
> * 从函数中逃逸的异常会使语句失败并返回错误。
>
> 重新构建后有一处行为变化：协议 3 和协议 5 传递 STRING 参数的方式不同。协议 3 函数收到的是参数的原始字节，未经更改，使用参数自身的字符集。协议 5 函数收到的是 utf8mb4 文本形式的参数，由服务器从调用方的字符集转换而来。例如，latin1 字符串 `_latin1 X'E9'`（é）到达协议 3 函数时是单个字节 `E9`，到达协议 5 函数时是两个字节 `C3 A9`。如果参数是并非有效 utf8mb4 的二进制字符串，语句会失败：
>
> ```text theme={null}
> ERROR 3854 (HY000) at line 1: Cannot convert string '\xFF\x00' from binary to utf8mb4
> ```
>
> 在重新构建之前，请找出每一个从 STRING 参数读取原始字节的函数（例如哈希函数或加密函数），并将该参数声明为 `BINARY`。这同样适用于以[协议 1 样式](#protocol-1)编写的扩展。

## 协议 1

协议 1 自 0.0.1 起一直保持稳定。服务器仍然接受它，但它很可能会在未来版本中被弃用。请使用 [使用 C++ 创建扩展](https://villagesql.com/docs/zh/extensions/build/create.md) 和 [C++ 开发](https://villagesql.com/docs/zh/sdk/cpp/development.md) 指南中的类型化 API 编写新扩展。本节是以协议 1 样式编写的现有扩展的参考。更新的 SDK 仍能编译这种样式，并为其自身的稳定协议构建该扩展。

> [!NOTE]
>
> **0.0.8-dev 中的变更。** 协议 1 被弃用。服务器仍然接受它，但新扩展应使用协议 5。

### 函数指针类型 API

协议 1 中的自定义类型使用显式函数指针进行注册，而不是使用 `vsql::make_type<>` 模板。函数签名与类型化的等效签名不同。它们接受原始指针和长度，而不接受 `Arg` 和 `Result` 对象。

#### 函数签名

```cpp theme={null}
// Encode: Convert string representation to binary.
// Returns false on success, true on error.
bool encode_mytype(unsigned char* buffer, size_t buffer_size,
                   const char* from, size_t from_len, size_t* length) {
    // Parse 'from' string and write binary to 'buffer'.
    // Set *length to bytes written.
    // Return false on success, true on error (e.g., set *length = 0).
}

// Decode: Convert binary to string representation.
// Returns false on success, true on error.
bool decode_mytype(const unsigned char* buffer, size_t buffer_size,
                   char* to, size_t to_size, size_t* to_length) {
    // Read binary from 'buffer' and write string to 'to'.
    // Set *to_length to string length.
    // Return false on success, true on error.
}

// Compare: enables ORDER BY and indexing (required).
int compare_mytype(const unsigned char* data1, size_t len1,
                   const unsigned char* data2, size_t len2) {
    // Return: negative if data1<data2, 0 if equal, positive if data1>data2.
}

// Hash: custom hash (optional, uses default binary hash if omitted).
size_t hash_mytype(const unsigned char* data, size_t len) {
    // Return hash value for the binary data.
}
```

#### 注册

这种形式需要 `#include <villagesql/extension.h>`（而不是 `<villagesql/vsql.h>`）以及 `using namespace villagesql;`。

```cpp theme={null}
#include <villagesql/extension.h>
using namespace villagesql;

constexpr const char* MYTYPE = "mytype";

VEF_GENERATE_ENTRY_POINTS(
  make_extension()
    .type(make_type(MYTYPE)
      .persisted_length(16)              // Fixed storage size in bytes
      .max_decode_buffer_length(64)      // Max string representation size
      .encode(&encode_mytype)
      .decode(&decode_mytype)
      .compare(&compare_mytype)          // Enables ORDER BY and indexes
      .hash(&hash_mytype)                // Optional custom hash
      .build())
    .func(make_func<&mytype_constructor>("MYTYPE")  // Constructor function
      .returns(MYTYPE)
      .param(REAL)
      .param(REAL)
      .build())
);
```

`vsql::make_type<kMyTypeName>()`（带有编译时字符串 NTTP）是首选形式。`make_type(MYTYPE)`（没有模板参数）是协议 1 形式——它仍受支持，但很可能会在未来版本中被弃用。

### 原始 ABI 样式（函数）

协议 1 VDF 实现可以直接传递原始 C 结构体，而不是使用类型化包装器。这种样式仍受支持，但很可能会在未来版本中被弃用——对于所有新代码，请使用 [类型化参数/结果 API](https://villagesql.com/docs/zh/sdk/cpp/development.md#argument-and-result-types)。

```cpp theme={null}
#include <villagesql/extension.h>
using namespace villagesql;

void add_impl(vef_context_t* ctx,
              vef_invalue_t* a, vef_invalue_t* b,
              vef_vdf_result_t* result) {
  if (a->is_null || b->is_null) {
    result->type = VEF_RESULT_NULL;
    return;
  }
  result->int_value = a->int_value + b->int_value;
  result->type = VEF_RESULT_VALUE;
}

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .func(make_func<&add_impl>("add_impl")
                  .returns(INT)
                  .param(INT)
                  .param(INT)
                  .build()))
```

这种逐参数传递的原始签名——`void(vef_context_t*, vef_invalue_t* arg0, ..., vef_vdf_result_t*)`——只有来自 `<villagesql/extension.h>` 的 `make_func<>()` 才能识别。来自 `<villagesql/vsql.h>` 的 `make_func<>()` 会在编译时拒绝任何原始的 `vef_context_t*`/`vef_invalue_t*`/`vef_vdf_result_t*` 签名。

#### 结果常量

原始 ABI 通过在 `result->type` 上设置的 `vef_return_value_type_t` 来传达结果状态：

| 常量 | 值 | 含义 |
| - | - | - |
| `VEF_RESULT_VALUE` | 0 | 成功——输出位于相应的联合体字段中 |
| `VEF_RESULT_NULL` | 1 | 结果为 SQL NULL |
| `VEF_RESULT_WARNING` | 2 | 行级警告——执行继续，该行返回 NULL，并添加一条 SQL 警告 (3200) |
| `VEF_RESULT_ERROR` | 3 | 致命错误——语句执行被中止；消息位于 `result->error_msg` 中 |

使用类型化 API 时，`out.set()`、`out.set_null()`、`out.warning()` 和 `out.error()` 会自动处理这一点。

#### 协议 1 中的聚合注册

来自 `<villagesql/extension.h>` 的 `make_func<>()` 构建器没有 `.clear<>()` 或 `.accumulate<>()` 成员。这些方法只存在于来自 `<villagesql/vsql.h>` 的独立构建器 `make_aggregate_func<State, &result_fn>()` 上，该构建器使用基于 `State&` 的类型化签名，而不是原始的 `vef_context_t*`/`vef_vdf_args_t*` 指针。对于所有新代码，请使用 [类型化聚合方法](https://villagesql.com/docs/zh/sdk/cpp/development.md#aggregate-vdfs)。`VEF_PROTOCOL_3` 或更高版本的原始注册也可以手动在 `vef_func_desc_t` 中设置 `clear` 和 `accumulate` 回调。

```cpp theme={null}
#include <villagesql/vsql.h>
#include <optional>
using namespace vsql;

using SumState = std::optional<long long>;

void my_clear(SumState &s) { s = std::nullopt; }
void my_acc(SumState &s, IntArg v) {
  if (!v.is_null()) s = s.value_or(0) + v.value();
}
void my_result(const SumState &s, IntResult out) {
  if (!s.has_value()) { out.set_null(); return; }
  out.set(s.value());
}

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .func(make_aggregate_func<SumState, &my_result>("my_agg")
                  .returns(INT).param(INT)
                  .clear<&my_clear>()        // void(SumState&)
                  .accumulate<&my_acc>()     // void(SumState&, IntArg)
                  .build()))
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.