LlrpNet 协议层 API 参考

架构与包图谱

LlrpNet.Core: 帧拆装 (Framing) · 会话传输 (Session) · Codec 注册表

LlrpNet.Protocol: LLRP 1.0.1 / 1.1 / 2.0 强类型消息与参数定义

厂商扩展包: LlrpNet.Protocol.Impinj / LlrpNet.Protocol.Zebra

生成器工具: LlrpNet.ProtocolGenerator (XML/YAML 双输入源)

快速符号索引 (Quick Jump)

LlrpFrameDecoderClass

零内存分配的二进制 LLRP 帧流式拆包器，自动处理 TCP 粘包与半包。

LlrpCodecRegistryClass

强类型消息与二进制线字节流双向转换的全局/局部注册表。

LlrpSessionClass

全双工异步会话通道：按 MessageId 将响应帧匹配到事务，并把未匹配的完整帧发布到 UnsolicitedFrames。

Multi-Version RulesConvention

协议类型使用显式版本命名空间，避免不同 LLRP 版本互相遮蔽。

Framing 帧拆装核心类型

LlrpFrameDecoder Class

命名空间: LlrpNet.Core.Frames

基于 ReadOnlySequence<byte> 的高性能二进制帧流解析器。按 LLRP 消息头中的长度从网络缓冲区移出完整帧，并保留半包缓冲区不变。

方法签名

方法签名	说明
`bool TryReadFrame(ref ReadOnlySequence<byte> buffer, out LlrpFrame frame)`	尝试从缓冲区开头取出一个完整的 LLRP 帧。成功时推进输入序列；数据不足时返回 false 且不修改缓冲区。

实战代码示例 (C# Code Sample)

using System.Buffers;
using LlrpNet.Core.Frames;

var decoder = new LlrpFrameDecoder();

// 模拟接收到的 16 字节 GET_READER_CAPABILITIES 消息二进制报文
byte[] rawBytes =
{
    0x04, 0x01,                   // Version=1 (LLRP 1.0.1), Type=1
    0x00, 0x00, 0x00, 0x10,       // MessageLength=16 bytes
    0x00, 0x00, 0x00, 0x01,       // MessageId=1
    0x00, 0x00, 0x00, 0x00        // Payload
};

ReadOnlySequence<byte> buffer = new(rawBytes);
if (decoder.TryReadFrame(ref buffer, out LlrpFrame frame))
{
    Console.WriteLine($"解析成功: Version={frame.Header.Version}, Type={frame.Header.MessageType}, " +
                      $"Length={frame.Header.MessageLength}, MsgID={frame.Header.MessageId}");
    Console.WriteLine($"负载长度: {frame.Payload.Length} 字节");
}

LlrpMessageHeader Record struct

命名空间: LlrpNet.Core.Protocol

表示所有 LLRP 消息共用的固定 10 字节报头，包含协议版本、消息类型、完整消息长度和 MessageId。

主要方法

方法签名	说明
`static LlrpMessageHeader Decode(ReadOnlySpan<byte> source)`	从网络字节序报头解析并校验协议版本、消息类型和长度。
`void Encode(Span<byte> destination)`	将当前报头编码为 LLRP 网络字节序；目标缓冲区至少需要 10 字节。

Transport 会话与网络传输

LlrpSession Class

命名空间: LlrpNet.Core.Session

全双工异步会话管理通道。负责维护连接生命周期，将响应帧按 MessageId 匹配到 TransactAsync 事务，并将未匹配的完整帧发布到 ReadUnsolicitedFramesAsync()。

实战代码示例 (C# Code Sample)

using System;
using System.Buffers;
using LlrpNet.Core.Frames;
using LlrpNet.Core.Session;
using LlrpNet.Core.Transport;

await using var transport = new LlrpTcpTransport(new LlrpTcpTransportOptions
{
    Host = "192.168.1.100",
    Port = 5084
});
await using var session = new LlrpSession(transport);
await session.ConnectAsync();

var decoder = new LlrpFrameDecoder();
await foreach (ReadOnlyMemory<byte> frameBytes in session.ReadUnsolicitedFramesAsync())
{
    ReadOnlySequence<byte> buffer = new(frameBytes);
    if (decoder.TryReadFrame(ref buffer, out LlrpFrame frame))
    {
        Console.WriteLine($"收到主动上报报文: Type={frame.Header.MessageType}, " +
                          $"MsgID={frame.Header.MessageId}");
    }
}

Codec 编解码器注册表

LlrpCodecRegistry Class

命名空间: LlrpNet.Protocol.Registry

中央编解码器注册表。管理标准 1.0.1 / 1.1 / 2.0 及 Impinj / Zebra 厂商扩展的序列化器与反序列化器。

实战代码示例 (C# Code Sample)

using System;
using LlrpNet.Core.Protocol;
using LlrpNet.Protocol.Messages;
using LlrpNet.Protocol.Parameters;
using LlrpNet.Protocol.Registry;
using LlrpNet.Protocol.Registry.V1_0_1;
using V101Enumerations = LlrpNet.Protocol.Enumerations.V1_0_1;
using V101Messages = LlrpNet.Protocol.Messages.V1_0_1;

// 1. 注册标准 1.0.1 模块
var registry = new LlrpCodecRegistry();
Llrp101StandardModule.Register(registry);

// 2. 强类型消息序列化为二进制
var getCaps = new V101Messages.GET_READER_CAPABILITIES(
    MessageId: 100,
    RequestedData: V101Enumerations.GetReaderCapabilitiesRequestedData.All,
    CustomItems: Array.Empty<ILlrpParameter>());
byte[] wireBytes = registry.EncodeMessage(LlrpProtocolVersion.Version101, getCaps);

// 3. 二进制报文反序列化为强类型实例
ILLRPMessage decoded = registry.DecodeMessage(wireBytes);
if (decoded is V101Messages.GET_READER_CAPABILITIES typedMsg)
{
    Console.WriteLine($"反序列化成功: RequestedData={typedMsg.RequestedData}");
}

多版本命名空间规则

显式多版本命名空间隔离 Convention

LLRPCSharp 要求所有涉及协议类型的代码使用显式别名导入，杜绝使用隐式“默认版本”：

using V101Messages = LlrpNet.Protocol.Messages.V1_0_1;
using V101Parameters = LlrpNet.Protocol.Parameters.V1_0_1;
using V11Messages = LlrpNet.Protocol.Messages.V1_1;
using V11Parameters = LlrpNet.Protocol.Parameters.V1_1;

// 1.0.1 协议类型
V101Parameters.ROSpec roSpec101 = new V101Parameters.ROSpec();

// 1.1 协议类型 (概念相同，版本独立隔离)
V11Parameters.ROSpec roSpec11 = new V11Parameters.ROSpec();