Callback Functions
1.
CAPL 函数 » 以太网 » SOME/IP IL »
函数
当 SOME/IP IL 接收到 cevHandle 参数指定事件的通知消息时，会调用此回调函数。需将此回调函数传递给 SomeIpCreateEventConsumer。
语法
void ( dword cevHandle, dword messageHandle ); 参数
- cevHandle：触发回调的事件句柄（参见
SomeIpCreateEventConsumer）。 - messageHandle：SOME/IP 事件的消息句柄。
返回值
—
可用性
- 版本：8.1 及以上
- 限制：仅适用于以太网
- 仿真/测试设置：支持
示例
variables
{DWORD aep; // 应用端点句柄DWORD csi; // 消费型服务实例句柄DWORD ceg; // 消费型事件组句柄DWORD cev; // 消费型事件句柄
}
on start()
{aep = SomeIpOpenLocalApplicationEndpoint(17, 50002); // 打开应用端点csi = SomeIpCreateConsumedServiceInstance(aep, 10, 1); // 创建服务实例ceg = SomeIpAddConsumedEventGroup(csi, 1); // 创建事件组cev = SomeIpCreateEventConsumer(csi, 32770, "CallbackEvent1"); // 创建事件消费者
}
void CallbackEvent1 (DWORD cevHandle, DWORD messageHandle)
{// 事件接收后执行，可在此处理参数
}2.
CAPL 函数 » 以太网 » SOME/IP IL »
函数
当 SOME/IP IL 接收到 pfHandle 参数指定字段的通知消息时，调用此回调函数。需传递给 SomeIpCreateFieldConsumer。
语法
void ( dword cfHandle, dword messageHandle ); 参数
- cfHandle：触发回调的字段句柄。
- messageHandle：SOME/IP 字段通知的消息句柄。
返回值
—
可用性
- 版本：8.1 SP2 及以上
- 限制：仅适用于以太网
- 仿真/测试设置：支持
示例
假设字段存在于 CANoe 配置的 FIBEX 数据库中，通知 ID=30，Getter ID=31，Setter ID=32，数据类型为 UINT8：
variables
{DWORD gMcGetter; // Getter 方法句柄DWORD gMcSetter; // Setter 方法句柄
}
void Initialize()
{CONST DWORD FieldNotificationID = 30;CONST DWORD FieldGetterID = 31;CONST DWORD FieldSetterID = 32;DWORD aep, csi, ceg;aep = SomeIpOpenLocalApplicationEndpoint(17, 50002); // 打开应用端点csi = SomeIpCreateConsumedServiceInstance(aep, 12, 1); // 创建服务实例ceg = SomeIpAddConsumedEventGroup(csi, 300); // 创建事件组// 创建字段消费者及 Getter/Setter 方法SomeIpCreateFieldConsumer(csi, FieldNotificationID, FieldGetterID, FieldSetterID, "OnSomeIpFieldNotification");gMcGetter = SomeIpCreateMethodCall(csi, FieldGetterID, "OnFieldGetterResponse");gMcSetter = SomeIpCreateMethodCall(csi, FieldSetterID, "OnFieldSetterResponse");
}
void OnSomeIpFieldNotification(DWORD pfHandle, DWORD messageHandle)
{write("字段通知已接收"); // 处理通知
}
void OnFieldGetterResponse(dword methodCallHandle, dword messageResponseHandle)
{write("字段 Getter 响应已接收"); // 处理 Getter 响应
}
void OnFieldSetterResponse(dword methodCallHandle, dword messageResponseHandle)
{write("字段 Setter 响应已接收"); // 处理 Setter 响应
}
on key 'g' { SomeIpCallMethod(gMcGetter); } // 调用 Getter
on key 's'
{SomeIpSetValueDWord(gMcSetter, "", 200); // 设置字段值SomeIpCallMethod(gMcSetter); // 调用 Setter
}3.
CAPL 函数 » 以太网 » SOME/IP IL »
函数
方法调用发生错误时触发的回调函数，需传递给 SomeIpCreateMethodCall。
语法
void ( dword methodCallHandle, dword messageErrorHandle ); 参数
- methodCallHandle：触发回调的方法句柄（参见
SomeIpAddMethod）。 - messageErrorHandle：SOME/IP 错误消息的句柄。
返回值
—
可用性
- 版本：14 及以上
- 限制：仅适用于以太网
- 仿真/测试设置：支持
示例
假设方法 ID=31，含输入参数 Member_value1、Member_value2 和返回参数 Result：
variables { DWORD gMc; } // 全局方法调用句柄
void Initialize()
{DWORD aep = SomeIpOpenLocalApplicationEndpoint(0x11, 50002); // 打开应用端点DWORD csi = SomeIpCreateConsumedServiceInstance(aep, 11, 1); // 创建服务实例gMc = SomeIpCreateMethodCall(csi, 31, "OnMethodResponse", "OnMethodError"); // 创建方法调用
}
on key 's'
{SomeIpSetValueDWord(gMc, "Member_value1", 11); // 设置输入参数SomeIpSetValueDWord(gMc, "Member_value2", 22);SomeIpCallMethod(gMc); // 调用方法
}
void OnMethodResponse(dword methodCallHandle, dword messageResponseHandle)
{DWORD res = SomeIpGetValueDWord(messageResponseHandle, "Result"); // 获取返回值write("方法返回值: %d", res);
}
void OnMethodError(dword methodCallHandle, dword messageErrorHandle)
{// 错误处理逻辑
}4.
CAPL 函数 » 以太网 » SOME/IP IL »
函数
消费者调用 SomeIpAddMethod 创建的方法时触发，支持两种语法形式（普通/ fireAndForget 方法）。
语法
// 形式 1：普通方法（需响应）
void ( dword methodHandle, dword messageHandle, dword messageResponseHandle );
// 形式 2：fireAndForget 方法（无需响应）
void ( DWORD methodHandle, DWORD messageHandle ); 参数
- methodHandle：方法句柄（参见
SomeIpAddMethod）。 - messageHandle：请求消息句柄（含消费者输入参数）。
- messageResponseHandle：响应消息句柄（需通过
SomeIpSetValue...设置结果）。
可用性
- 版本：8.1 及以上
- 限制：仅适用于以太网
- 仿真/测试设置：支持
示例
variables { DWORD gPm; } // 提供型方法句柄
void Initialize()
{DWORD aep = SomeIpOpenLocalApplicationEndpoint(17, 50002); // 打开应用端点DWORD psi = SomeIpCreateProvidedServiceInstance(aep, 11, 1); // 创建服务实例gPm = SomeIpAddMethod(psi, 31, "OnMethodRequest"); // 创建方法
}
void OnMethodRequest(dword methodHandle, dword messageHandle, dword messageResponseHandle)
{WORD val1 = SomeIpGetValueDWord(messageHandle, "Member_value1"); // 获取输入参数WORD val2 = SomeIpGetValueDWord(messageHandle, "Member_value2");SomeIpSetValueDWord(messageResponseHandle, "Result", val1 + val2); // 设置响应结果
}5.
CAPL 函数 » 以太网 » SOME/IP IL »
函数
方法调用成功后触发的回调函数，需传递给 SomeIpCreateMethodCall。
语法
void (dword methodCallHandle, dword messageResponseHandle ); 参数
- methodCallHandle：方法调用句柄。
- messageResponseHandle：响应消息句柄（含返回参数）。
返回值
—
可用性
- 版本：8.1 及以上
- 限制：仅适用于以太网
- 仿真/测试设置：支持
示例
variables { DWORD gMc; } // 全局方法调用句柄
void Initialize()
{DWORD aep = SomeIpOpenLocalApplicationEndpoint(0x11, 50002); // 打开应用端点DWORD csi = SomeIpCreateConsumedServiceInstance(aep, 11, 1); // 创建服务实例gMc = SomeIpCreateMethodCall(csi, 31, "OnMethodResponse"); // 创建方法调用
}
on key 's'
{SomeIpSetValueDWord(gMc, "Member_value1", 11); // 设置输入参数SomeIpSetValueDWord(gMc, "Member_value2", 22);SomeIpCallMethod(gMc); // 调用方法
}
void OnMethodResponse(dword methodCallHandle, dword messageResponseHandle)
{DWORD res = SomeIpGetValueDWord(messageResponseHandle, "Result"); // 获取返回值write("方法返回值: %d", res);
}6.
CAPL 函数 » 以太网 » SOME/IP IL »
函数
事件发送前触发，用于更新消息内容，需传递给 SomeIpAddEvent。
语法
void ( dword pevHandle, dword messageHandle ); 参数
- pevHandle：事件句柄。
- messageHandle：待发送的消息句柄（可通过
SomeIpSetValue...修改参数）。
可用性
- 版本：8.1 及以上
- 限制：仅适用于以太网
- 仿真/测试设置：支持
示例
variables
{DWORD aep, psi, peg, pev; // 应用端点/服务/事件组/事件句柄
}
on start()
{aep = SomeIpOpenLocalApplicationEndpoint(17, 50002); // 打开应用端点psi = SomeIpCreateProvidedServiceInstance(aep, 10, 1); // 创建服务实例peg = SomeIpAddProvidedEventGroup(psi, 1); // 创建事件组pev = SomeIpAddEvent(psi, 1, "OnPrepareEvent1"); // 创建事件SomeIpAddEventToEventgroup(peg, pev); // 事件添加到组SomeIpSetProperty(pev, "CycleTimeMs", 1000); // 设置周期发送（1000ms）
}
void OnPrepareEvent1 (DWORD eventHandle, DWORD messageHandle)
{// 发送前更新事件参数
}7. TCP 连接状态回调
CAPL 函数 » 以太网 » SOME/IP IL
函数
- OnSomeIpClosedTCPConnection：TCP 连接关闭后触发。
- OnSomeIpEstablishedTCPConnection：TCP 连接建立后触发。
语法（以通用形式为例）
void OnSomeIpClosedTCPConnection(IP_Endpoint localIPEndpoint, IP_Endpoint remoteIPEndpoint);
void OnSomeIpEstablishedTCPConnection(IP_Endpoint localIPEndpoint, IP_Endpoint remoteIPEndpoint);参数
- localIPEndpoint/remoteIPEndpoint：本地/远程端点信息（含 IP 和端口）。
可用性
- 版本：12.0 SP2 及以上（通用形式）
- 限制：仅适用于以太网
- 仿真/测试设置：支持
示例
void OnSomeIpEstablishedTCPConnection(IP_Endpoint localIPEndpoint, IP_Endpoint remoteIPEndpoint)
{char localStr[128], remoteStr[128];localIPEndpoint.PrintEndpointToString(localStr); // 端点信息转字符串remoteIPEndpoint.PrintEndpointToString(remoteStr);write("已建立连接: %s <-> %s", localStr, remoteStr);
}
void OnSomeIpClosedTCPConnection(IP_Endpoint localIPEndpoint, IP_Endpoint remoteIPEndpoint)
{// 连接关闭处理逻辑
}8. OnSomeIpEstablishedIPv6TCPConnection、OnSomeIpEstablishedIPv4TCPConnection、OnSomeIpEstablishedTCPConnection
CAPL 函数 » 以太网 » SOME/IP IL » OnSomeIpEstablishedIPv6TCPConnection、OnSomeIpEstablishedIPv4TCPConnection、OnSomeIpEstablishedTCPConnection
函数
当 IL 的应用端点建立传入或传出 TCP 连接后，将调用此回调函数。
语法
void OnSomeIpEstablishedIPv6TCPConnection(byte localIPv6Address[], dword localPort, byte remoteIPv6Address[], dword remotePort); // 形式 1
void OnSomeIpEstablishedIPv4TCPConnection(dword localIPv4Address, dword localPort, dword remoteIPv4Address, dword remotePort); // 形式 2
void OnSomeIpEstablishedTCPConnection(IP_Endpoint localIPEndpoint, IP_Endpoint remoteIPEndpoint); // 形式 3 参数
- localIPv6Address：本地 IPv6 地址。
- remoteIPv6Address：远程 IPv6 地址。
- localIPv4Address：本地 IPv4 地址。
- remoteIPv4Address：远程 IPv4 地址。
- localPort：本地 TCP 端口号。
- remotePort：远程 TCP 端口号。
- localIPEndpoint：IP_Endpoint 类型对象，包含本地端点的地址/端口。
- remoteIPEndpoint：IP_Endpoint 类型对象，包含远程端点的地址/端口。
返回值
- 0：函数执行成功。
0：错误代码。
可用性
| 版本 | 限制范围 | 测量设置 | 仿真/测试设置 |
|---|---|---|---|
| 11.0 SP3（形式 1-2） | 以太网 | — | • |
| 12.0 SP2（形式 3） | 以太网 | — | • |
示例
void OnSomeIpEstablishedTCPConnection(IP_Endpoint localIPEndpoint, IP_Endpoint remoteIPEndpoint)
{
char localEndpointStr[128], remoteEndpointStr[128];
localIPEndpoint.PrintEndpointToString(localEndpointStr);
remoteIPEndpoint.PrintEndpointToString(remoteEndpointStr);
Print("Local Endpoint: %s, Remote Endpoint: %s", localEndpointStr, remoteEndpointStr);
}9. OnSomeIpMessage
CAPL 函数 » 以太网 » SOME/IP IL » OnSomeIpMessage
函数
可在 CAPL 程序中实现此回调函数，以在接收到 SOME/IP 消息时收到通知。该函数仅针对 IL 的本地应用端点上接收的 SOME/IP 消息调用（参见 SomeIpOpenLocalApplicationEndpoint）。
语法
void OnSomeIpMessage(dword messageHandle);参数
- messageHandle：接收到的 SOME/IP 消息的句柄，用于读取消息数据的函数需使用此句柄。
返回值
—
可用性
| 版本 | 限制范围 | 测量设置 | 仿真/测试设置 |
|---|---|---|---|
| 8.1 | 以太网 | — | • |
示例
—
10. OnSomeIpProcessRxMessage
CAPL 函数 » 以太网 » SOME/IP IL » OnSomeIpProcessRxMessage
函数
IL 接收到 SOME/IP 消息时调用此回调函数。返回值决定消息是否由 IL 处理或忽略，也可在 IL 处理前修改消息。
语法
long OnSomeIpProcessRxMessage(dword messageHandle, long rxChannel);参数
- messageHandle：触发回调的接收 SOME/IP 消息的句柄。
- rxChannel：接收消息的应用端点通道。
返回值
- 1：消息将被处理。
- 其他值：消息被回调忽略。
可用性
| 版本 | 限制范围 | 测量设置 | 仿真/测试设置 |
|---|---|---|---|
| 8.1 SP2 | 以太网 | — | • |
示例
long OnSomeIpProcessRxMessage(dword messageHandle, long rxChannel)
{
DWORD msgId = 0;
LONG errorCode = 0;
LONG errorOccurred = 0;
// 从 SOME/IP 消息获取数据
if ((msgId = SomeIpGetMessageId(messageHandle)) == 0)
{
// 检查上一函数是否执行正确
if ((errorCode = SomeIpGetLastError()) != 0)
{
write("SOME/IP IL 发生错误：错误代码：%d", errorCode);
errorOccurred = 1;
} // if
} // if
if (errorOccurred == 0)
{
write("接收到消息 ID 为 0x%08x 的 SOME/IP 消息", msgId);
return 1;
} // if
else
{
return 0;
} // else
}11. OnSomeIpProcessTxMessage
CAPL 函数 » 以太网 » SOME/IP IL » OnSomeIpProcessTxMessage
函数
IL 准备发送 SOME/IP 消息时调用此回调函数。返回值决定消息是否发送或阻塞，也可在 IL 发送前修改消息。
语法
long OnSomeIpProcessTxMessage(dword messageHandle, long txChannel);参数
- messageHandle：触发回调的待发送消息的句柄。
- txChannel：用于发送消息的应用端点通道。
返回值
- 1：消息将被发送。
- 其他值：消息被回调过滤。
可用性
| 版本 | 限制范围 | 测量设置 | 仿真/测试设置 |
|---|---|---|---|
| 8.1 SP2 | 以太网 | — | • |
示例
long OnSomeIpProcessTxMessage(dword messageHandle, long txChannel)
{
DWORD msgId = 0;
LONG errorCode = 0;
LONG errorOccurred = 0;
// 从 SOME/IP 消息获取数据
if ((msgId = SomeIpGetMessageId(messageHandle)) == 0)
{
// 检查上一函数是否执行正确
if ((errorCode = SomeIpGetLastError()) != 0)
{
write("SOME/IP IL 发生错误：错误代码：%d", errorCode);
errorOccurred = 1;
} // if
} // if
if (errorOccurred == 0)
{
write("将要发送消息 ID 为 0x%08x 的 SOME/IP 消息", msgId);
return 1;
} // if
else
{
return 0;
} // else
}12. OnSomeIpSDClientEventGroupStatusChanged
CAPL 函数 » 以太网 » SOME/IP IL » OnSomeIpSDClientEventGroupStatusChanged
函数
事件消费者（客户端）需监控事件组状态变化时，可在 CAPL 程序中实现此回调函数。事件组状态变化时调用，仅针对本节点消费的事件组。
语法
void OnSomeIpSDClientEventGroupStatusChanged(dword serviceId, dword instanceId, dword eventGroupId, long status); // 形式 1
void OnSomeIpSDClientEventGroupStatusChanged(dword serviceId, dword majorVersion, dword instanceId, dword eventGroupId, long status); // 形式 2 参数
- serviceId：状态变化的服务 ID。
- instanceId：实例 ID。
- eventGroupId：事件组 ID。
- status：0（未订阅），1（已订阅）。
- majorVersion：服务接口主版本。
返回值
—
可用性
| 版本 | 限制范围 | 测量设置 | 仿真/测试设置 |
|---|---|---|---|
| 8.1（形式 1） | 以太网 | — | • |
| 8.5 SP4（形式 2） | 以太网 | — | • |
示例
void OnSomeIpSDClientEventGroupStatusChanged(dword serviceId, dword instanceId, dword eventGroupId, long status)
{
char buffer[100];
if (status == 0)
{
snprintf(buffer, elcount(buffer), "未订阅");
}
else if (status == 1)
{
snprintf(buffer, elcount(buffer), "已订阅");
}
else
{
snprintf(buffer, elcount(buffer), "状态未定义");
}
write("服务 %d（实例 %d）的事件组（ID %d）：\r\n%s", serviceId, instanceId, eventGroupId, buffer);
}13. OnSomeIpSDClientServiceStatusChanged
CAPL 函数 » 以太网 » SOME/IP IL » OnSomeIpSDClientServiceStatusChanged
函数
客户端需监控服务状态变化时，可在 CAPL 程序中实现此回调函数。服务状态变化时调用，无论服务是否通过 SomeIpCreateConsumedServiceInstance 消费。
语法
void OnSomeIpSDClientServiceStatusChanged(dword serviceId, dword instanceId, LONG status); // 形式 1
void OnSomeIpSDClientServiceStatusChanged(dword serviceId, dword majorVersion, dword instanceId, LONG status); // 形式 2 参数
- serviceId：状态变化的服务 ID。
- instanceId：实例 ID。
- status：0（服务不可用），1（服务可用）。
- majorVersion：服务接口主版本。
返回值
—
可用性
| 版本 | 限制范围 | 测量设置 | 仿真/测试设置 |
|---|---|---|---|
| 8.1（形式 1） | 以太网 | — | • |
| 8.5 SP4（形式 2） | 以太网 | — | • |
示例
void OnSomeIpSDClientServiceStatusChanged(dword serviceId, dword majorVersion, dword instanceId, LONG status)
{
char buffer[100];
if (status == 0)
{
snprintf(buffer, elcount(buffer), "服务不可用");
}
else if (status == 1)
{
snprintf(buffer, elcount(buffer), "服务可用");
}
else
{
snprintf(buffer, elcount(buffer), "状态未定义");
}
write("服务 %d（实例 %d，主版本 %d）：\r\n%s", serviceId, instanceId, majorVersion, buffer);
}14. OnSomeIpSDServerEventGroupStatusChanged
CAPL 函数 » 以太网 » SOME/IP IL » OnSomeIpSDServerEventGroupStatusChanged
函数
服务端需监控订阅者添加时，可在 CAPL 程序中实现此回调函数。客户端执行订阅事件组命令时调用。
语法
void OnSomeIpSDServerEventGroupStatusChanged(dword serviceId, dword instanceId, dword eventGroupId, long status, dword newIpAddress, dword newPort); // 形式 1
void OnSomeIpSDServerEventGroupStatusChanged(dword serviceId, dword majorVersion, dword instanceId, dword eventGroupId, long status, dword newIpAddress, dword newPort); // 形式 2 参数
- serviceId：状态变化的服务 ID。
- instanceId：实例 ID。
- eventGroupId：事件组 ID。
- status：0（未订阅），1（已订阅）。
- newIpAddress：接收订阅的 IPv4 地址。
- newPort：接收订阅的源端口。
- majorVersion：服务接口主版本。
返回值
—
可用性
| 版本 | 限制范围 | 测量设置 | 仿真/测试设置 |
|---|---|---|---|
| 8.1（形式 1） | 以太网 | — | • |
| 8.5 SP4（形式 2） | 以太网 | — | • |
示例
void OnSomeIpSDServerEventGroupStatusChanged(dword serviceId, dword instanceId, dword eventGroupId, long status, dword newIpAddress, dword newPort)
{
char buffer[100];
if (status == 0)
{
snprintf(buffer, elcount(buffer), "未订阅");
}
else if (status == 1)
{
snprintf(buffer, elcount(buffer), "已订阅");
}
else
{
snprintf(buffer, elcount(buffer), "状态未定义");
}
write("服务 %d（实例 %d）的事件组（ID %d）：\r\n%s", serviceId, instanceId, eventGroupId, buffer);
}