PassThruQueueMsgs v5.0

将消息加入通道队列以进行传输

最后修改：2026 年 1 月 13 日

说明

该函数将消息加入指定通道的 pass-thru 设备发送队列。执行成功时返回 STATUS_NOERROR，并更新 pNumMsgs 指针所指向的值，使其包含实际加入队列的消息数量。

注意：该函数取代了在早期版本 SAE J2534 API（v04.04）中使用的 PassThruWriteMsgs。

long PassThruQueueMsgs(
    unsigned long ChannelID,
    PASSTHRU_MSG *pMsg,
    unsigned long *pNumMsgs
)

工作特性

消息按照传入的顺序加入队列（索引为 0 的消息排在第一，索引为 1 的排在第二，依此类推）
消息必须能够完整地放入发送队列
该函数不会等待队列中出现空闲空间
pMsg 所指向的结构体不会被修改
通过该函数传入的消息，其优先级低于周期性消息（PassThruStartPeriodicMsg）

ISO 15765 逻辑通道的特性

ISO 15765 逻辑通道可以将其网络地址或 TxFlags 与创建通道时所指定的 RemoteAddress 或 RemoteTxFlags 不一致的单帧（single frame）加入队列。

重要：尝试将地址不一致的分段消息（multi-frame）加入队列将导致 ERR_MSG_NOT_ALLOWED 错误。

参数

ChannelID

输入参数。通过调用 PassThruConnect() 或 PassThruLogicalConnect() 获取的物理或逻辑通信通道标识符。

pMsg

输入参数。指向由应用程序分配的 PASSTHRU_MSG 结构体数组的指针，其中包含要加入队列的消息。

pNumMsgs

输入/输出参数。指向 unsigned long 变量的指针：

调用时：包含要加入队列的消息数量
返回时：包含实际成功加入队列的消息数量

返回的错误代码

代码	说明
STATUS_NOERROR	函数执行成功。所有消息均已加入队列。
ERR_CONCURRENT_API_CALL	在上一次调用完成之前调用了 J2534 API 函数
ERR_DEVICE_NOT_OPEN	`PassThruOpen()` 未被成功调用
ERR_INVALID_CHANNEL_ID	`ChannelID` 值无效
ERR_DEVICE_NOT_CONNECTED	与 pass-thru 设备通信出错。设备已断开连接。
ERR_NOT_SUPPORTED	设备不支持针对该 `ChannelID` 的此函数
ERR_NULL_PARAMETER	`pMsg` 或 `pNumMsgs` 为 NULL
ERR_MSG_PROTOCOL_ID	`PASSTHRU_MSG` 结构体中的 `ProtocolID` 与通道的 `ProtocolID` 不一致
ERR_INVALID_MSG	消息结构体对该 `ChannelID` 无效
ERR_MSG_NOT_ALLOWED	尝试将地址/标志与 ISO 15765 逻辑通道参数不一致的分段消息加入队列
ERR_BUFFER_FULL	发送队列已满。`pNumMsgs` 包含实际加入队列的消息数量。
ERR_FAILED	未定义的错误。请使用 `PassThruGetLastError()` 获取说明。

示例

C/C++ 示例

#include "j2534_dll.hpp"

unsigned long channelID = ...; // 来自 PassThruConnect/PassThruLogicalConnect 的通道 ID

// 准备消息
PASSTHRU_MSG msg = {0};
msg.ProtocolID = ISO15765;
msg.TxFlags = ISO15765_FRAME_PAD;

// 数据：UDS 请求 Read Data By Identifier (0x22)
unsigned char data[] = {0x00, 0x00, 0x07, 0xDF, 0x22, 0xF1, 0x90};
memcpy(msg.Data, data, sizeof(data));
msg.DataSize = sizeof(data);

unsigned long numMsgs = 1;

// 将消息放入队列
long ret = PassThruQueueMsgs(channelID, &msg, &numMsgs);

if (ret == STATUS_NOERROR) {
    printf("队列中的消息数：%lu\n", numMsgs);
} else if (ret == ERR_BUFFER_FULL) {
    printf("队列已满，已放入的消息数：%lu\n", numMsgs);
} else {
    char error[256];
    PassThruGetLastError(error);
    printf("错误：%s\n", error);
}

Python 示例（ctypes）

from ctypes import *

j2534 = cdll.LoadLibrary("libj2534_v05_00.dylib")

# PASSTHRU_MSG 结构体
class PASSTHRU_MSG(Structure):
    _fields_ = [
        ("ProtocolID", c_ulong),
        ("RxStatus", c_ulong),
        ("TxFlags", c_ulong),
        ("Timestamp", c_ulong),
        ("DataSize", c_ulong),
        ("ExtraDataIndex", c_ulong),
        ("Data", c_ubyte * 4128)
    ]

channel_id = c_ulong(...)  # 通道 ID

# 准备消息
msg = PASSTHRU_MSG()
msg.ProtocolID = 0x06  # ISO15765
msg.TxFlags = 0x40     # ISO15765_FRAME_PAD

# UDS 请求 Read Data By Identifier
data = bytes([0x00, 0x00, 0x07, 0xDF, 0x22, 0xF1, 0x90])
for i, b in enumerate(data):
    msg.Data[i] = b
msg.DataSize = len(data)

num_msgs = c_ulong(1)

# 将消息放入队列
ret = j2534.PassThruQueueMsgs(channel_id, byref(msg), byref(num_msgs))

if ret == 0:  # STATUS_NOERROR
    print(f"队列中的消息数：{num_msgs.value}")
elif ret == 0x11:  # ERR_BUFFER_FULL
    print(f"队列已满，已放入：{num_msgs.value}")
else:
    error = create_string_buffer(256)
    j2534.PassThruGetLastError(error)
    print(f"错误：{error.value.decode()}")

与 PassThruWriteMsgs（v04.04）的比较

特性	PassThruWriteMsgs (v04.04)	PassThruQueueMsgs (v05.00)
行为	带超时的阻塞式调用	非阻塞，立即返回
Timeout 参数	有	无
逻辑通道支持	无	有