CAPL学习-SOME/IP交互层-客户端API函数

车载测试工程师2025-12-09 8:21

Client-Side API

SomeIpAddConsumedEventGroup

函数
语法
dword SomeIpAddConsumedEventGroup(dword csiHandle, dword eventGroupId);

功能

该函数用于向由 SomeIpCreateConsumedServiceInstance 创建的消费型服务实例（Consumed Service Instance）添加事件组（Event Group）。

事件组内的对象可通过以下方式注册：

  • 事件（Events）：SomeIpCreateEventConsumer
  • 字段（Fields）：SomeIpCreateFieldConsumer

可通过 SomeIpRemoveConsumedEventGroup 函数移除事件组。

参数

  • csiHandle：消费型服务实例的句柄。
  • eventGroupId：事件组的标识符。

返回值

  • 0：发生错误，可通过 SomeIpGetLastError 函数获取错误信息。
  • >0：创建的消费型事件组的句柄。

可用性

  • 版本：8.1 及以上
  • 限制：仅适用于仿真/测试环境

示例

c 复制代码 
void Initialize()
{
  DWORD aep;  // 应用端点句柄
  DWORD csi;  // 消费型服务实例句柄
  DWORD ceg;  // 消费型事件组句柄
  DWORD cev;  // 消费型事件句柄

  // 打开应用端点
  aep = SomeIpOpenLocalApplicationEndpoint(17, 50002);
  // 创建服务实例
  csi = SomeIpCreateConsumedServiceInstance(aep, 10, 1);
  // 创建事件组
  ceg = SomeIpAddConsumedEventGroup(csi, 1);
  // 创建事件消费者
  cev = SomeIpCreateEventConsumer(csi, 32770, "CallbackEvent1");
}

void CallbackEvent1(DWORD cevHandle, DWORD messageHandle)
{
  // 事件触发时调用此函数，可在此处处理参数
}

SomeIpCallMethod

函数
语法
LONG SomeIpCallMethod(dword methodHandle);

功能

通过向服务器发送请求来发起方法调用。方法所属的服务必须已通过"提供服务"（Offer Service）消息提供，且仍有效，才能成功调用。

背景

成功调用方法需获取提供服务的远程地址和端口，这些信息通过"提供服务"消息传递。

参数

  • methodHandle：由 SomeIpCreateMethodCall 创建的方法调用句柄。

返回值

  • 0：函数执行成功。
  • >0：错误代码。

可用性

  • 版本：8.1 及以上
  • 限制：仅适用于仿真/测试环境

示例

假设方法已在 CANoe 配置的 FIBEX 数据库中定义，方法 ID 为 31，包含两个输入参数 Member_value1 和 Member_value2，以及一个返回参数 Result。

c 复制代码 
variables
{
  DWORD gMc;  // 全局方法调用句柄
}

void Initialize()
{
  DWORD aep;  // 应用端点句柄
  DWORD csi;  // 消费型服务实例句柄

  // 打开应用端点
  aep = SomeIpOpenLocalApplicationEndpoint(0x11, 50002);
  // 创建服务实例
  csi = SomeIpCreateConsumedServiceInstance(aep, 11, 1);
  // 创建方法调用
  gMc = SomeIpCreateMethodCall(csi, 31, "OnMethodResponse");
}

on key 's'
{
  // 按下 's' 键时调用方法
  // 设置方法的两个输入参数
  SomeIpSetValueDWord(gMc, "Member_value1", 11);
  SomeIpSetValueDWord(gMc, "Member_value2", 22);
  // 调用方法
  SomeIpCallMethod(gMc);
}

void OnMethodResponse(dword methodCallHandle, dword messageResponseHandle)
{
  DWORD res;  // 返回参数值
  // 获取返回参数
  res = SomeIpGetValueDWord(messageResponseHandle, "Result");
  write("方法调用返回值: %d", res);
}

SomeIpCreateConsumedServiceInstance

函数
语法

c 复制代码 
dword SomeIpCreateConsumedServiceInstance(dword aepHandle, dword serviceId, dword instanceId);  // 形式1
dword SomeIpCreateConsumedServiceInstance(dword aepHandle, dword serviceId, dword instanceId, dword majorVersion, dword minorVersion);  // 形式2

功能

创建消费型服务实例，并将其添加到由 SomeIpOpenLocalApplicationEndpoint 创建的应用端点（Application Endpoint）。

可向服务实例分配以下对象：

  • 事件组（Event Groups）：SomeIpAddConsumedEventGroup
  • 事件（Events）：SomeIpCreateEventConsumer
  • 字段（Fields）：SomeIpCreateFieldConsumer
  • 方法（Methods）：SomeIpCreateMethodCall

可通过 SomeIpReleaseConsumedServiceInstance 删除服务实例。

参数

  • aepHandle：应用端点句柄。
  • serviceId：服务标识符。
  • instanceId：实例标识符。
  • majorVersion：服务接口主版本号（形式2）。
  • minorVersion：服务接口次版本号（形式2）。

返回值

  • 0：发生错误，可通过 SomeIpGetLastError 获取错误信息。
  • >0：创建的消费型服务实例句柄。

可用性

  • 版本：8.1 及以上（形式1）；8.5 SP4 及以上（形式2）
  • 限制：仅适用于仿真/测试环境

示例

c 复制代码 
void Initialize()
{
  DWORD aep;  // 应用端点句柄
  DWORD csi;  // 消费型服务实例句柄
  DWORD ceg;  // 消费型事件组句柄
  DWORD cev;  // 消费型事件句柄

  // 打开应用端点
  aep = SomeIpOpenLocalApplicationEndpoint(17, 50002);
  // 创建服务实例
  csi = SomeIpCreateConsumedServiceInstance(aep, 10, 1);
  // 创建事件组
  ceg = SomeIpAddConsumedEventGroup(csi, 1);
  // 创建事件消费者
  cev = SomeIpCreateEventConsumer(csi, 32770, "CallbackEvent1");
}

void CallbackEvent1(DWORD cevHandle, DWORD messageHandle)
{
  // 事件触发时调用此函数，可在此处处理参数
}

SomeIpCreateEventConsumer

函数
语法
dword SomeIpCreateEventConsumer(dword csiHandle, dword eventId, CHAR onEventCallback[]);

功能

向由 SomeIpCreateConsumedServiceInstance 创建的消费型服务实例添加事件消费者（Event Consumer）。收到匹配事件时，将调用指定的回调函数。

可通过 SomeIpRemoveEventConsumer 移除事件消费者。

参数

  • csiHandle：消费型服务实例句柄（由 SomeIpCreateConsumedServiceInstance 创建）。
  • eventId：事件标识符。
  • onEventCallback：收到匹配事件时调用的回调函数名（参见 <OnSomeIpEventReceived>）。

返回值

  • 0：发生错误，可通过 SomeIpGetLastError 获取错误信息。
  • >0：创建的事件消费者句柄。

可用性

  • 版本：8.1 及以上
  • 限制：仅适用于仿真/测试环境

示例

c 复制代码 
void Initialize()
{
  DWORD aep;  // 应用端点句柄
  DWORD csi;  // 消费型服务实例句柄
  DWORD ceg;  // 消费型事件组句柄
  DWORD cev;  // 消费型事件句柄

  // 打开应用端点
  aep = SomeIpOpenLocalApplicationEndpoint(17, 50002);
  // 创建服务实例
  csi = SomeIpCreateConsumedServiceInstance(aep, 10, 1);
  // 创建事件组
  ceg = SomeIpAddConsumedEventGroup(csi, 1);
  // 创建事件消费者
  cev = SomeIpCreateEventConsumer(csi, 32770, "CallbackEvent1");
}

void CallbackEvent1(DWORD cevHandle, DWORD messageHandle)
{
  // 事件触发时调用此函数，可在此处处理参数
}

SomeIpCreateFieldConsumer

函数
语法
dword SomeIpCreateFieldConsumer(dword csiHandle, long notificationId, long getterId, long setterId, char onFieldNotificationCallback[]);

功能

向由 SomeIpCreateConsumedServiceInstance 创建的消费型服务实例添加字段消费者（Field Consumer）。收到匹配的字段通知时，将调用指定的回调函数（参见 <OnSomeIpFieldNotification>）。

可通过 SomeIpRemoveFieldConsumer 移除字段消费者。

参数

  • csiHandle：消费型服务实例句柄（由 SomeIpCreateConsumedServiceInstance 创建）。
  • notificationId：字段通知标识符。若字段不支持通知，需设为 -1。
  • getterId：字段获取方法（Getter）标识符。调用 Getter 前需通过 SomeIpCreateMethodCall 创建方法，并使用 SomeIpCallMethod 调用。若不支持 Getter，设为 -1。
  • setterId：字段设置方法（Setter）标识符。调用 Setter 前需通过 SomeIpCreateMethodCall 创建方法，并使用 SomeIpCallMethod 调用。若不支持 Setter，设为 -1。
  • onFieldNotificationCallback：收到字段通知消息时调用的回调函数。

返回值

  • 0：发生错误，可通过 SomeIpGetLastError 获取错误信息。
  • >0：创建的字段消费者句柄。

可用性

  • 版本：8.1 SP2 及以上
  • 限制：仅适用于仿真/测试环境

示例

假设字段已在 CANoe 配置的 FIBEX 数据库中定义，通知 ID 为 30，Getter ID 为 31，Setter ID 为 32，数据类型为标准类型（如 UINT8）。

c 复制代码 
variables
{
  DWORD gMcGetter;  // Getter 方法调用句柄
  DWORD gMcSetter;  // Setter 方法调用句柄
}

void Initialize()
{
  CONST DWORD FieldNotificationID = 30;
  CONST DWORD FieldGetterID = 31;
  CONST DWORD FieldSetterID = 32;
  DWORD aep;  // 应用端点句柄
  DWORD csi;  // 消费型服务实例句柄
  DWORD ceg;  // 消费型事件组句柄

  // 打开应用端点
  aep = SomeIpOpenLocalApplicationEndpoint(17, 50002);
  // 创建服务实例
  csi = SomeIpCreateConsumedServiceInstance(aep, 12, 1);
  // 创建事件组
  ceg = SomeIpAddConsumedEventGroup(csi, 300);
  // 创建字段消费者及 Getter/Setter 方法调用
  SomeIpCreateFieldConsumer(csi, FieldNotificationID, FieldGetterID, FieldSetterID, "OnFieldNotification");
  gMcGetter = SomeIpCreateMethodCall(csi, FieldGetterID, "OnFieldGetterResponse");
  gMcSetter = SomeIpCreateMethodCall(csi, FieldSetterID, "OnFieldSetterResponse");
}

void OnFieldNotification(DWORD pfHandle, DWORD messageHandle)
{
  write("收到字段通知");
  // 处理逻辑
}

void OnFieldGetterResponse(dword methodCallHandle, dword messageResponseHandle)
{
  write("收到 Getter 响应");
  // 处理逻辑
}

void OnFieldSetterResponse(dword methodCallHandle, dword messageResponseHandle)
{
  write("收到 Setter 响应");
  // 处理逻辑
}

on key 'g'
{
  // 调用 Getter 方法
  SomeIpCallMethod(gMcGetter);
}

on key 's'
{
  // 设置字段值（标准类型无需路径）
  SomeIpSetValueDWord(gMcSetter, "", 200);
  // 调用 Setter 方法
  SomeIpCallMethod(gMcSetter);
}

SomeIpCreateMethodCall

函数
语法

c 复制代码 
dword SomeIpCreateMethodCall(dword csiHandle, dword methodId, char onSomeIpMethodResponse[]);  // 形式1  
dword SomeIpCreateMethodCall(dword csiHandle, dword methodId);  // 形式2  
dword SomeIpCreateMethodCall(dword csiHandle, dword methodId, char onSomeIpMethodResponse[], char onSomeIpMethodError[]);  // 形式3

功能

为消费者创建方法调用。通过函数返回值，可使用 SomeIpSetValue... 设置方法参数，再通过 SomeIpCallMethod 调用方法。

注意

  • 形式1：异步调用，客户端调用后不会阻塞等待响应。SOME/IP IL 不支持同步调用。
  • 形式2：适用于服务端创建方法时使用 fireAndForget 参数的场景（参见 SomeIpAddMethod）。
  • 可通过 SomeIpRemoveMethodCall 移除方法调用。

参数

  • csiHandle：消费型服务实例句柄（由 SomeIpCreateConsumedServiceInstance 创建）。
  • methodId：方法标识符。
  • onResponseCallback：收到响应时调用的回调函数（参见 <OnSomeIpMethodResponse>）。
  • onErrorCallback：收到 SOME/IP 错误消息时调用的回调函数（参见 <OnSomeIpMethodError>）。

返回值

  • 0：发生错误，可通过 SomeIpGetLastError 获取错误信息。
  • >0：方法调用句柄。

可用性

  • 版本：8.1（形式1、2）；14（形式3）
  • 限制：仅适用于仿真/测试环境

示例

假设方法已在 CANoe 配置的 FIBEX 数据库中定义，方法 ID 为 31，包含两个输入参数 Member_value1 和 Member_value2，以及一个返回参数 Result。

c 复制代码 
variables
{
  DWORD gMc;  // 全局方法调用句柄
}

void Initialize()
{
  DWORD aep;  // 应用端点句柄
  DWORD csi;  // 消费型服务实例句柄

  // 打开应用端点
  aep = SomeIpOpenLocalApplicationEndpoint(0x11, 50002);
  // 创建服务实例
  csi = SomeIpCreateConsumedServiceInstance(aep, 11, 1);
  // 创建方法调用
  gMc = SomeIpCreateMethodCall(csi, 31, "OnMethodResponse");
}

on key 's'
{
  // 按下 's' 键时调用方法
  // 设置输入参数
  SomeIpSetValueDWord(gMc, "Member_value1", 11);
  SomeIpSetValueDWord(gMc, "Member_value2", 22);
  // 调用方法
  SomeIpCallMethod(gMc);
}

void OnMethodResponse(dword methodCallHandle, dword messageResponseHandle)
{
  DWORD res;  // 返回参数值
  // 获取返回值
  res = SomeIpGetValueDWord(messageResponseHandle, "Result");
  write("方法调用返回值: %d", res);
}

SomeIpReleaseConsumedServiceInstance

函数
语法
LONG SomeIpReleaseConsumedServiceInstance(dword csiHandle);

功能

删除由 SomeIpCreateConsumedServiceInstance 创建的消费型服务实例。服务实例关联的对象（事件组、事件、字段、方法）将随实例一同删除。若重新创建服务实例，需重新创建所有对象。

参数

  • csiHandle：待删除的消费型服务实例句柄。

返回值

  • 0：函数执行成功。
  • >0：错误代码。

可用性

  • 版本：8.1 及以上
  • 限制：仅适用于仿真/测试环境

示例

c 复制代码 
on key 'c'
{
  DWORD aep;  // 应用端点句柄
  DWORD csi;  // 消费型服务实例句柄

  // 打开应用端点
  aep = SomeIpOpenLocalApplicationEndpoint(17, 50002);
  // 创建服务实例
  csi = SomeIpCreateConsumedServiceInstance(aep, 10, 1);
  // ... 执行操作 ...
  // 释放服务实例
  SomeIpReleaseConsumedServiceInstance(csi);
  // ... 应用端点可继续使用 ...
}

版本 ：14 SP2
© Vector Informatik GmbH

SomeIpRemoveConsumedEventGroup

函数

从已消费的服务实例中移除事件组。该事件组需通过 SomeIpAddConsumedEventGroup 预先添加。

移除事件组时，分配给该组的事件、字段和方法不会被删除。

语法

capl 复制代码 
LONG SomeIpRemoveConsumedEventGroup( dword cevgHandle );

参数

  • cevgHandle：已消费事件组的句柄。

返回值

  • 0：函数执行成功

  • 0：错误代码

可用性

  • 版本：8.1 及以上
  • 限制：仅适用于仿真/测试环境

示例

capl 复制代码 
on key 'c'  
{  
  DWORD aep;       // 应用端点句柄  
  DWORD csi;       // 已消费服务实例句柄  
  DWORD ceg;       // 已消费事件组句柄  

  // 打开应用端点  
  aep = SomeIpOpenLocalApplicationEndpoint(17, 50002);  
  // 创建服务实例  
  csi = SomeIpCreateConsumedServiceInstance(aep, 10, 1);  
  // 创建事件组  
  ceg = SomeIpAddConsumedEventGroup(csi, 1);  

  // ... 执行其他操作  

  // 移除已消费事件组  
  SomeIpRemoveConsumedEventGroup(ceg);  

  // ... 应用端点和服务实例仍可继续使用  
}

SomeIpRemoveEventConsumer

函数

从已消费的服务实例中移除事件。该事件需通过 SomeIpCreateEventConsumer 预先添加。

移除后，SomeIpCreateEventConsumer 注册的回调函数将不再被调用。

语法

capl 复制代码 
dword SomeIpRemoveEventConsumer( dword cevHandle );

参数

  • cevHandle：待移除事件的句柄（参见 SomeIpCreateEventConsumer）。

返回值

  • 0：函数执行成功

  • 0：错误代码

可用性

  • 版本：8.1 及以上
  • 限制：仅适用于仿真/测试环境

示例

capl 复制代码 
on key 'c'  
{  
  DWORD aep;       // 应用端点句柄  
  DWORD csi;       // 已消费服务实例句柄  
  DWORD ceg;       // 已消费事件组句柄  
  DWORD cev;       // 已消费事件句柄  

  // 打开应用端点  
  aep = SomeIpOpenLocalApplicationEndpoint(17, 50002);  
  // 创建服务实例  
  csi = SomeIpCreateConsumedServiceInstance(aep, 10, 1);  
  // 创建事件组  
  ceg = SomeIpAddConsumedEventGroup(csi, 1);  
  // 创建事件消费者  
  cev = SomeIpCreateEventConsumer(csi, 32770, "CallbackEventA1");  

  // ... 执行其他操作  

  // 移除事件消费者  
  SomeIpRemoveEventConsumer(cev);  

  // ... 应用端点、服务实例和事件组仍可继续使用  
}

SomeIpRemoveFieldConsumer

函数

从已消费的服务实例中移除字段。该字段需通过 SomeIpCreateFieldConsumer 预先添加。

移除后，SomeIpCreateFieldConsumer 注册的回调函数将不再被调用。

语法

capl 复制代码 
long SomeIpRemoveFieldConsumer( dword cfHandle );

参数

  • cfHandle：SomeIpCreateFieldConsumer 创建的字段句柄。

返回值

  • 0：函数执行成功

  • 0：错误代码

可用性

  • 版本：8.1 SP2 及以上
  • 限制：仅适用于仿真/测试环境

示例

capl 复制代码 
variables  
{  
  CONST DWORD FieldNotificationID = 30;  // 字段通知ID  
  CONST DWORD FieldGetterID = 31;        // 字段获取方法ID  
  CONST DWORD FieldSetterID = 32;        // 字段设置方法ID  
  DWORD aep;       // 应用端点句柄  
  DWORD csi;       // 已消费服务实例句柄  
  DWORD ceg;       // 已消费事件组句柄  
  DWORD cfHandle;  // 已消费字段句柄  
  DWORD gMcGetter; // 获取方法调用句柄  
  DWORD gMcSetter; // 设置方法调用句柄  
}  

on start()  
{  
  // 打开应用端点  
  aep = SomeIpOpenLocalApplicationEndpoint(17, 50002);  
  // 创建服务实例  
  csi = SomeIpCreateConsumedServiceInstance(aep, 12, 1);  
  // 创建事件组  
  ceg = SomeIpAddConsumedEventGroup(csi, 300);  

  // 创建字段消费者及对应的获取/设置方法  
  cfHandle = SomeIpCreateFieldConsumer(csi, FieldNotificationID, FieldGetterID, FieldSetterID, "OnFieldNotification");  
  gMcGetter = SomeIpCreateMethodCall(csi, FieldGetterID, "OnFieldGetterResponse");  
  gMcSetter = SomeIpCreateMethodCall(csi, FieldSetterID, "OnFieldSetterResponse");  
}  

// 字段通知回调  
void OnFieldNotification(DWORD pfHandle, DWORD messageHandle)  
{  
  write("字段通知已接收");  
  // ... 处理通知  
}  

// 获取方法响应回调  
void OnFieldGetterResponse(dword methodCallHandle, dword messageResponseHandle)  
{  
  write("字段获取响应已接收");  
  // ... 处理响应  
}  

// 设置方法响应回调  
void OnFieldSetterResponse(dword methodCallHandle, dword messageResponseHandle)  
{  
  write("字段设置响应已接收");  
  // ... 处理响应  
}  

on key 'g'  
{  
  // 调用获取方法  
  SomeIpCallMethod(gMcGetter);  
}  

on key 's'  
{  
  // 设置字段值（通用数据类型无需路径）  
  SomeIpSetValueDWord(gMcSetter, "", 200);  
  // 调用设置方法  
  SomeIpCallMethod(gMcSetter);  
}  

on key 'r'  
{  
  // 移除字段消费者  
  SomeIpRemoveFieldConsumer(cfHandle);  
}

SomeIpRemoveMethodCall

函数

从已消费的服务实例中移除方法调用。该方法需通过 SomeIpCreateMethodCall 预先添加。

移除后，方法句柄失效，无法再通过 SomeIpCallMethod 调用。

语法

capl 复制代码 
LONG SomeIpRemoveMethodCall( dword methodHandle );

参数

  • methodHandle：方法句柄。

返回值

  • 0：函数执行成功

  • 0：错误代码

可用性

  • 版本：8.1 及以上
  • 限制：仅适用于仿真/测试环境

示例

假设方法存在于 CANoe 配置的 FIBEX 数据库中，方法 ID 为 31，含两个输入参数 Member_value1、Member_value2 和返回参数 Result。

capl 复制代码 
variables  
{  
  DWORD gMc;  // 全局方法调用句柄  
}  

on key 'e'  
{  
  DWORD aep;  // 应用端点句柄  
  DWORD csi;  // 已消费服务实例句柄  

  // 打开应用端点  
  aep = SomeIpOpenLocalApplicationEndpoint(0x11, 50002);  
  // 创建服务实例  
  csi = SomeIpCreateConsumedServiceInstance(aep, 11, 1);  

  // 创建方法调用  
  gMc = SomeIpCreateMethodCall(csi, 31, "OnMethodResponse");  

  // 设置输入参数并调用方法  
  SomeIpSetValueDWord(gMc, "Member_value1", 11);  
  SomeIpSetValueDWord(gMc, "Member_value2", 22);  
  SomeIpCallMethod(gMc);  
}  

on key 'r'  
{  
  // 移除方法调用  
  SomeIpRemoveMethodCall(gMc);  
}  

// 方法响应回调  
void OnMethodResponse(dword methodCallHandle, dword messageResponseHandle)  
{  
  DWORD res;  // 返回参数值  

  // 获取返回参数  
  res = SomeIpGetValueDWord(messageResponseHandle, "Result");  
  write("方法调用返回值: %d", res);  
}
相关推荐
lcyw3 小时前
A MSE+Fmp4+websocket+H265播放器
网络·websocket·网络协议
运维行者_3 小时前
PostgreSQL 十大性能问题及解决方案
运维·服务器·网络·数据库·postgresql·智能路由器·snmp
koping_wu3 小时前
【计算机网络】OSI七层模型、TCP协议、HTTP协议
tcp/ip·计算机网络·http
卓码软件测评3 小时前
Gatling WebSocket测试支持：ws、wsConnect、sendText、checkTextMessage详解
网络·websocket·网络协议·测试工具·ci/cd·自动化
chase。3 小时前
【学习笔记】线性复杂度微分逆运动学：增广拉格朗日视角深度解析
人工智能·笔记·学习
Ronin3053 小时前
【Linux网络】NAT、代理服务、内网穿透
linux·网络·智能路由器·内网穿透·nat·代理服务器·内网打洞
YJlio3 小时前
Active Directory 工具学习笔记（10.5）：AdInsight 数据捕获与显示选项——把噪声压下去，把关键抬上来
人工智能·笔记·学习
zxb@hny4 小时前
Hazel游戏引擎学习
学习·游戏引擎
feathered-feathered4 小时前
网络套接字——Socket网络编程（TCP编程详解）
java·网络·后端·网络协议·tcp/ip
热门推荐
01GitHub 镜像站点02【超详细教程】手把手教你从微软官网免费下载Windows 10官方原版ISO镜像（2025最新版）03安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）04UV安装并设置国内源05React CVE-2025-55182漏洞排查与修复指南06Linux下V2Ray安装配置指南07BongoCat - 跨平台键盘猫动画工具08智能库存管理的需求预测模型：从业务痛点到落地代码的完整实践09从入门到实战：Gemini 3 使用指南速览10在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）