Callback Functions
1.
CAPL 函数 >> 以太网 >> SOME/IP IL >>
函数
当 SOME/IP IL 接收到 cevHandle 参数指定事件的通知消息时,会调用此回调函数。需将此回调函数传递给 SomeIpCreateEventConsumer。
语法
capl
void <OnSomeIpEventReceived>( dword cevHandle, dword messageHandle );
参数
- cevHandle :触发回调的事件句柄(参见
SomeIpCreateEventConsumer)。 - messageHandle:SOME/IP 事件的消息句柄。
返回值
可用性
- 版本:8.1 及以上
- 限制:仅适用于以太网
- 仿真/测试设置:支持
示例
capl
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。
语法
capl
void <OnSomeIpFieldNotification>( dword cfHandle, dword messageHandle );
参数
- cfHandle:触发回调的字段句柄。
- messageHandle:SOME/IP 字段通知的消息句柄。
返回值
可用性
- 版本:8.1 SP2 及以上
- 限制:仅适用于以太网
- 仿真/测试设置:支持
示例
假设字段存在于 CANoe 配置的 FIBEX 数据库中,通知 ID=30,Getter ID=31,Setter ID=32,数据类型为 UINT8:
capl
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。
语法
capl
void <OnSomeIpMethodError>( dword methodCallHandle, dword messageErrorHandle );
参数
- methodCallHandle :触发回调的方法句柄(参见
SomeIpAddMethod)。 - messageErrorHandle:SOME/IP 错误消息的句柄。
返回值
可用性
- 版本:14 及以上
- 限制:仅适用于以太网
- 仿真/测试设置:支持
示例
假设方法 ID=31,含输入参数 Member_value1、Member_value2 和返回参数 Result:
capl
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 方法)。
语法
capl
// 形式 1:普通方法(需响应)
void <OnSomeIpMethodRequest>( dword methodHandle, dword messageHandle, dword messageResponseHandle );
// 形式 2:fireAndForget 方法(无需响应)
void <OnSomeIpMethodRequest>( DWORD methodHandle, DWORD messageHandle );
参数
- methodHandle :方法句柄(参见
SomeIpAddMethod)。 - messageHandle:请求消息句柄(含消费者输入参数)。
- messageResponseHandle :响应消息句柄(需通过
SomeIpSetValue...设置结果)。
可用性
- 版本:8.1 及以上
- 限制:仅适用于以太网
- 仿真/测试设置:支持
示例
capl
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。
语法
capl
void <OnSomeIpMethodResponse>(dword methodCallHandle, dword messageResponseHandle );
参数
- methodCallHandle:方法调用句柄。
- messageResponseHandle:响应消息句柄(含返回参数)。
返回值
可用性
- 版本:8.1 及以上
- 限制:仅适用于以太网
- 仿真/测试设置:支持
示例
capl
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。
语法
capl
void <OnSomeIpPrepareEvent>( dword pevHandle, dword messageHandle );
参数
- pevHandle:事件句柄。
- messageHandle :待发送的消息句柄(可通过
SomeIpSetValue...修改参数)。
可用性
- 版本:8.1 及以上
- 限制:仅适用于以太网
- 仿真/测试设置:支持
示例
capl
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 连接建立后触发。
语法(以通用形式为例)
capl
void OnSomeIpClosedTCPConnection(IP_Endpoint localIPEndpoint, IP_Endpoint remoteIPEndpoint);
void OnSomeIpEstablishedTCPConnection(IP_Endpoint localIPEndpoint, IP_Endpoint remoteIPEndpoint);
参数
- localIPEndpoint/remoteIPEndpoint:本地/远程端点信息(含 IP 和端口)。
可用性
- 版本:12.0 SP2 及以上(通用形式)
- 限制:仅适用于以太网
- 仿真/测试设置:支持
示例
capl
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 连接后,将调用此回调函数。
语法
c
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) | 以太网 | --- | • |
示例
c
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)。
语法
c
void OnSomeIpMessage(dword messageHandle);
参数
- messageHandle:接收到的 SOME/IP 消息的句柄,用于读取消息数据的函数需使用此句柄。
返回值
可用性
| 版本 | 限制范围 | 测量设置 | 仿真/测试设置 |
|---|---|---|---|
| 8.1 | 以太网 | --- | • |
示例
10. OnSomeIpProcessRxMessage
CAPL 函数 >> 以太网 >> SOME/IP IL >> OnSomeIpProcessRxMessage
函数
IL 接收到 SOME/IP 消息时调用此回调函数。返回值决定消息是否由 IL 处理或忽略,也可在 IL 处理前修改消息。
语法
c
long OnSomeIpProcessRxMessage(dword messageHandle, long rxChannel);
参数
- messageHandle:触发回调的接收 SOME/IP 消息的句柄。
- rxChannel:接收消息的应用端点通道。
返回值
- 1:消息将被处理。
- 其他值:消息被回调忽略。
可用性
| 版本 | 限制范围 | 测量设置 | 仿真/测试设置 |
|---|---|---|---|
| 8.1 SP2 | 以太网 | --- | • |
示例
c
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 发送前修改消息。
语法
c
long OnSomeIpProcessTxMessage(dword messageHandle, long txChannel);
参数
- messageHandle:触发回调的待发送消息的句柄。
- txChannel:用于发送消息的应用端点通道。
返回值
- 1:消息将被发送。
- 其他值:消息被回调过滤。
可用性
| 版本 | 限制范围 | 测量设置 | 仿真/测试设置 |
|---|---|---|---|
| 8.1 SP2 | 以太网 | --- | • |
示例
c
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 程序中实现此回调函数。事件组状态变化时调用,仅针对本节点消费的事件组。
语法
c
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) | 以太网 | --- | • |
示例
c
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 消费。
语法
c
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) | 以太网 | --- | • |
示例
c
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 程序中实现此回调函数。客户端执行订阅事件组命令时调用。
语法
c
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) | 以太网 | --- | • |
示例
c
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);
}