CAPL学习-IP API函数-1

IpAddAdapterAddress

函数

功能：为指定索引的网络接口添加IP地址。

语法

long IpAddAdapterAddress(dword ifIndex, dword ipv4address, dword ipv4mask);  
long IpAddAdapterAddress(dword ifIndex, byte ipv6Address[], dword prefix);  
long IpAddAdapterAddress(dword ifIndex, IP_Address address, dword prefix); // 形式3  

说明

• 该函数依赖于所选的协议栈，无法与操作系统TCP/IP栈配合使用。

参数

• ifIndex：1-based网络接口索引。
• ipv4address：要添加的IPv4地址（数值形式）。
• ipv6Address：IPv6地址（16字节数组形式）。
• ipv4mask：IPv4子网掩码（网络字节序）。
• prefix：IPv6前缀长度。
• address：IP_Address类型的地址。

返回值

• 0：成功。
• WSA_INVALID_PARAMETER (87)：接口索引无效。
• SOCKET_ERROR (-1)：失败，需调用IpGetLastSocketError获取详细错误码。

可用性

• 形式1-2：CANoe 8.1+，仅限仿真/测试环境。
• 形式3：CANoe 12.0+，仅限仿真/测试环境。

示例

variables  
{  
  UdpSocket gSocket;  
}  

on start  
{  
  ipAddAdapterAddress(1, IP_Address(192.168.0.116), 24); // 为接口1添加IP地址  
  gSocket = UdpSocket::Open(IP_Endpoint(192.168.0.116:40016));  
  gSocket.SendTo(IP_Endpoint(192.168.0.255:40255), "Hello", 5);  
}  

on preStop  
{  
  ipRemoveAdapterAddress(1, IP_Address(192.168.0.116), 24); // 移除地址  
}  

IpBind

函数

功能 ：将地址和端口与指定的未绑定套接字关联（需配合TcpOpen(0, 0)使用）。

语法

// 函数形式  
long IpBind(dword socket, dword address, dword port); // 形式1（IPv4）  
long IpBind(dword socket, byte ipv6Address[], dword port); // 形式2（IPv6）  
long IpBind(dword socket, IP_Endpoint localEndpoint); // 形式3  

// 方法形式  
socket.Bind(dword address, dword port);  
socket.Bind(byte ipv6address[], dword port);  
socket.Bind(IP_Endpoint localEndpoint);  

说明

• 禁止 在TcpConnect或TcpListen后使用（这两个函数会自动绑定套接字）。

参数

• socket：套接字句柄。
• address：本地IPv4地址（数值形式）。
• ipv6Address：本地IPv6地址（16字节数组）。
• port：本地端口（主机字节序）。
• localEndpoint：IP端点（可指定地址或动态端口）。

示例

variables  
{  
  UdpSocket gSocket;  
  char gRxBuffer[1000];  
}  

on start  
{  
  gSocket = UdpSocket::Open(IP_Endpoint(0.0.0.0)); // 未绑定端口  
}  

on key '1'  
{  
  gSocket.Bind(IP_Endpoint(192.168.0.7:40007)); // 绑定到指定地址和端口  
  gSocket.SendTo(IP_Endpoint(192.168.0.100:40100), "Hello", 5);  
}  

IpGetAdapter

函数

功能：根据以太网通道或VLAN ID获取适配器索引。

语法

dword IpGetAdapter(long channel);  
dword IpGetAdapter(long channel, word vlanId); // VLAN适配器  

参数

• channel：1-based以太网通道索引。
• vlanId：VLAN ID（仅VLAN适配器需要）。

返回值

• 适配器索引；若无匹配则返回0。

示例

variables  
{  
  const long kMAX_CHANNEL = 64;  
  const word kMAX_VLAN = 4094;  
}  

on start  
{  
  long channel;  
  word vlanId;  
  dword ifIndex;  
  for(channel = 1; channel <= kMAX_CHANNEL; channel++)  
  {  
    ifIndex = IpGetAdapter(channel); // 获取通道对应的适配器  
    if(ifIndex > 0)  
    {  
      write("通道 %d 的适配器索引: %d", channel, ifIndex);  
      // 遍历VLAN  
      for(vlanId = 1; vlanId <= kMAX_VLAN; vlanId++)  
      {  
        ifIndex = IpGetAdapter(channel, vlanId);  
        if(ifIndex > 0)  
          write("VLAN %d 的索引: %d", vlanId, ifIndex);  
      }  
    }  
  }  
}  

IpGetAdapterAddress

函数

功能：获取指定接口的IP地址列表。

语法

long IpGetAdapterAddress(dword ifIndex, dword ipv4address[], dword ipv4AddressSize); // IPv4  
long IpGetAdapterAddress(dword ifIndex, byte ipv6Addresses[][], dword ipv6AddressesSize); // IPv6  
long IpGetAdapterAddress(dword ifIndex, IP_Address addresses[], dword &count); // 形式3  

参数

• ifIndex：接口索引。
• ipv4address/ipv6Addresses：存储地址的数组。
• ipv4AddressSize/ipv6AddressesSize：数组大小。
• count：输出参数，实际获取的地址数量。

返回值

• 0：成功。
• ERROR_NOT_ENOUGH_MEMORY (8)：数组空间不足。
• WSAEADDRNOTAVAIL (10049)：无可用地址。

示例

on start  
{  
  IP_Address addresses[10];  
  dword addressesCount;  
  long ifIdx;  
  write("IP配置");  
  for(ifIdx = 1; ifIdx <= ipGetAdapterCount(); ifIdx++)  
  {  
    ipGetAdapterAddress(ifIdx, addresses, addressesCount); // 获取地址列表  
    for(long i = 0; i < addressesCount; i++)  
    {  
      char addrStr[30];  
      addresses[i].PrintAddressToString(addrStr);  
      write("  地址 %d: %s", i+1, addrStr);  
    }  
  }  
}  

IpGetAdapterAddressAsString

函数

功能：获取指定接口的第一个IP地址（字符串形式）。

语法

long IpGetAdapterAddressAsString(dword ifIndex, char address[], dword count);  

参数

• ifIndex：接口索引。
• address：存储地址字符串的缓冲区（点分十进制格式）。
• count：缓冲区大小。

示例

on start  
{  
  char ipAddr[16]; // IPv4字符串缓冲区  
  for(dword ifIdx = 1; ifIdx <= IpGetAdapterCount(); ifIdx++)  
  {  
    long result = IpGetAdapterAddressAsString(ifIdx, ipAddr, elcount(ipAddr));  
    if(result == 0)  
      write("接口 %d 的IP地址: %s", ifIdx, ipAddr);  
    else  
      write("错误: %d", result);  
  }  
}  

IpGetAdapterAddressCount

函数

功能：获取指定接口的IPv4/IPv6地址数量。

语法

long IpGetAdapterAddressCount(dword ifIndex, dword addressFamily);  

参数

• addressFamily：地址族（AF_INET=2表示IPv4，AF_INET6=28表示IPv6）。

返回值

• 地址数量；失败返回SOCKET_ERROR (-1)。

示例

on start  
{  
  const dword AF_INET = 2, AF_INET6 = 28;  
  for(dword ifIdx = 1; ifIdx <= IpGetAdapterCount(); ifIdx++)  
  {  
    long ipv4Count = IpGetAdapterAddressCount(ifIdx, AF_INET);  
    write("接口 %d 的IPv4地址数量: %d", ifIdx, ipv4Count);  
  }  
}  

IpGetAdapterChannel

函数

功能：根据适配器索引获取对应的以太网通道号。

语法

long IpGetAdapterChannel(dword ifIndex);  

返回值

• 以太网通道号（1-based）；无效索引返回0。

示例

on start  
{  
  for(dword ifIdx = 1; ifIdx <= IpGetAdapterCount(); ifIdx++)  
  {  
    long channel = IpGetAdapterChannel(ifIdx);  
    if(channel != 0)  
      write("适配器 %d 关联通道: %d", ifIdx, channel);  
  }  
}  

IpGetAdapterCount

函数

功能：获取网络接口总数（不含环回接口）。

语法

dword IpGetAdapterCount();  

返回值

• 接口数量。

IpGetAdapterDescription

函数

功能：获取指定接口的描述信息。

语法

long IpGetAdapterDescription(dword ifIndex, char name[], dword count);  

参数

• name：存储描述的缓冲区。
• count：缓冲区大小。

示例

on start  
{  
  char descr[256];  
  for(dword ifIdx = 1; ifIdx <= IpGetAdapterCount(); ifIdx++)  
  {  
    long result = IpGetAdapterDescription(ifIdx, descr, elcount(descr));  
    if(result == 0)  
      write("接口 %d 描述: %s", ifIdx, descr);  
  }  
}  

IpGetAdapterGateway

CAPL 函数 >> TCP/IP API >> IpGetAdapterGateway

注意

以下函数签名已弃用（自 8.2 SP2 起）：

long IpGetAdapterGateway(dword ifIndex, dword address[], dword count);  
long IpGetAdapterGateway(dword ifIndex, byte ipv6Address[][], dword count);  

函数

语法

long IpGetAdapterGateway(dword ifIndex, dword& ipv4address);  // 形式 1  
long IpGetAdapterGateway(dword ifIndex, byte ipv6Address[]);   // 形式 2  
long IpGetAdapterGateway(dword ifIndex, dword addressFamily, IP_Address address);  // 形式 3  

功能

检索指定网络接口关联的默认网关地址。

网关信息在测量开始前（预启动阶段）不可用，仅在测量启动后（启动阶段）堆栈完全初始化时可用。

参数

• ifIndex：1 为起始的网络接口索引。操作系统堆栈中会考虑所有适配器地址（包括本地环回地址），顺序取决于操作系统对适配器的枚举方式；CANoe 堆栈中会考虑所有分配的地址（包括 VLAN 地址）。
• ipv4address：返回的数值型 IPv4 网关地址。
• ipv6Address：16 字节数组形式的 IPv6 网关地址。
• addressFamily ：地址族，可能值：
  • 0：优先 IPv4，若无则 IPv6
  • 2：IPv4 地址族
  • 28：IPv6 地址族
• address ：用于存储地址的 IP_Address 变量。

返回值

• 0：成功。
• ERROR_NOT_ENOUGH_MEMORY (8)：地址数组空间不足。
• WSA_INVALID_PARAMETER (87)：网络接口索引无效。
• WSAEADDRNOTAVAIL (10049)：无可用网关地址。

可用性

版本	限制	测量设置	仿真/测试设置
7.0（形式 1-2）	---	---	•
12.0（形式 3）	---	---	•

示例

on start  
{  
  long ifIdx;  
  for (ifIdx = 1; ifIdx <= ipGetAdapterCount(); ifIdx++)  
  {  
    ip_Address gatewayAddress;  
    if (ipGetAdapterGateway(ifIdx, 0, gatewayAddress) == 0)  
    {  
      char gatewayStr[30];  
      gatewayAddress.PrintAddressToString(gatewayStr);  
      write("%d. 适配器网关地址: %s", ifIdx, gatewayStr);  
    }  
  }  
}  

IpGetAdapterGatewayAsString

CAPL 函数 >> TCP/IP API >> IpGetAdapterGatewayAsString

函数

语法

long IpGetAdapterGatewayAsString(dword ifIndex, char address[], dword count);  

功能

检索指定网络接口关联的默认网关地址的字符串表示形式。

网关信息在测量开始前（预启动阶段）不可用，仅在测量启动后（启动阶段）堆栈完全初始化时可用。

参数

• ifIndex：1 为起始的网络接口索引。操作系统堆栈中会考虑所有适配器地址（包括本地环回地址），顺序取决于操作系统对适配器的枚举方式；CANoe 堆栈中会考虑所有分配的地址（包括 VLAN 地址）。
• address：用于存储点分十进制格式 IPv4 网关地址的缓冲区。
• count：地址缓冲区大小。

返回值

• 0：成功。
• ERROR_NOT_ENOUGH_MEMORY (8)：缓冲区空间不足。
• WSA_INVALID_PARAMETER (87)：网络接口索引无效。
• WSAEADDRNOTAVAIL (10049)：无可用网关地址。

可用性

版本	限制	测量设置	仿真/测试设置
7.0	---	---	•

示例

on start  
{  
  const dword IPV4_STR_SIZE = 16;  // IPv4 字符串长度  
  dword ifIdx;                     // 接口索引  
  char ipv4GwAddrStr[IPV4_STR_SIZE];  // 人类可读的 IPv4 网关地址  
  long result;                     // 函数结果  

  for (ifIdx = 1; ifIdx <= IpGetAdapterCount(); ifIdx++)  
  {  
    result = IpGetAdapterGatewayAsString(ifIdx, ipv4GwAddrStr, elcount(ipv4GwAddrStr));  
    if (result == 0)  
    {  
      // 成功  
      write("IpGetAdapterGatewayAsString：适配器 %d 返回 IPv4 网关地址: %s", ifIdx, ipv4GwAddrStr);  
    }  
    else  
    {  
      writeLineEx(1, 3, "IpGetAdapterGatewayAsString：错误 %d", result);  
    }  
  }  
}  

IpGetAdapterMacId

CAPL 函数 >> TCP/IP API >> IpGetAdapterMacId

函数

语法

long IpGetAdapterMacId(dword ifIndex, byte macId[]);  // 形式 1  
qword IpGetAdapterMacId(dword ifIndex);               // 形式 2  

功能

返回指定接口的 MAC 地址。

参数

• ifIndex：1 为起始的网络接口索引。操作系统堆栈中会考虑所有适配器地址（包括本地环回地址），顺序取决于操作系统对适配器的枚举方式；CANoe 堆栈中会考虑所有分配的地址（包括 VLAN 地址）。
• macId：用于返回 MAC 地址的 6 字节数组。

返回值

• 形式 1 ：
  • 0：成功。
  • WSA_INVALID_PARAMETER (87)：网络接口索引无效。
  • WSAEADDRNOTAVAIL (10049)：未找到 MAC 地址。
• 形式 2：MAC 地址（qword 类型）；若失败则返回 0。

可用性

版本	限制	测量设置	仿真/测试设置
8.2 SP2（形式 1）	---	---	•
12.0（形式 2）	---	---	•

示例

on start  
{  
  long result;  
  long ifIndex;  
  char adapterDesc[255];  
  byte macId[6];  
  ifIndex = 1;  

  result = ipGetAdapterDescription(ifIndex, adapterDesc, elcount(adapterDesc));  
  if (result != 0)  
  {  
    writeLineEx(1, 3, "获取适配器描述失败。结果: %d", result);  
  }  

  result = IpGetAdapterMacId(ifIndex, macId);  
  if (result != 0)  
  {  
    writeLineEx(1, 3, "获取适配器 MAC 地址失败。结果: %d", result);  
  }  
  else  
  {  
    writeLineEx(1, 0, "适配器 %s 的 MAC 地址为 %02x:%02x:%02x:%02x:%02x:%02x",  
                adapterDesc, macId[0], macId[1], macId[2], macId[3], macId[4], macId[5]);  
  }  
}  

IpGetAdapterMask

CAPL 函数 >> TCP/IP API >> IpGetAdapterMask

函数

语法

long IpGetAdapterMask(dword ifIndex, dword mask[], dword maskSize);  // 形式 1  
long IpGetAdapterMask(dword ifIndex, IP_Address addressMasks[], dword& count);  // 形式 2  

功能

检索指定网络接口关联的地址掩码（子网掩码）。

参数

• ifIndex：1 为起始的网络接口索引。操作系统堆栈中会考虑所有适配器地址（包括本地环回地址），顺序取决于操作系统对适配器的枚举方式；CANoe 堆栈中会考虑所有分配的地址（包括 VLAN 地址）。
• mask：用于存储数值型 IPv4 地址掩码的数组（形式 1）。
• maskSize：掩码数组大小（形式 1）。
• addressMasks ：用于存储地址掩码的 IP_Address 数组（形式 2）。
• count：掩码数组大小（形式 2）。

返回值

• 0：成功。
• ERROR_NOT_ENOUGH_MEMORY (8)：掩码数组空间不足。
• WSA_INVALID_PARAMETER (87)：网络接口索引无效。
• WSAEADDRNOTAVAIL (10049)：无可用适配器地址。

可用性

版本	限制	测量设置	仿真/测试设置
7.0（形式 1）	---	---	•
12.0（形式 2）	---	---	•

示例

on start  
{  
  IP_Address addresses[10];  
  dword addressesCount;  
  IP_Address addrMasks[10];  
  dword addrMasksCount;  
  long addrIdx;  
  long ifIdx;  

  write("IP 配置");  
  for (ifIdx = 1; ifIdx <= ipGetAdapterCount(); ifIdx++)  
  {  
    ipGetAdapterAddress(ifIdx, addresses, addressesCount);  
    ipGetAdapterMask(ifIdx, addrMasks, addrMasksCount);  

    for (addrIdx = 0; addrIdx < addressesCount; addrIdx++)  
    {  
      char addrStr[30];  
      char maskStr[30];  
      addresses[addrIdx].PrintAddressToString(addrStr);  
      addrMasks[addrIdx].PrintAddressToString(maskStr);  
      write(" %d. %s | %s", addrIdx+1, addrStr, maskStr);  
    }  
  }  
}  

IpGetAdapterMaskAsString

CAPL 函数 >> TCP/IP API >> IpGetAdapterMaskAsString

函数

语法

long IpGetAdapterMaskAsString(dword ifIndex, char mask[], dword count);  

功能

检索指定网络接口关联的第一个地址掩码的字符串表示形式。

参数

• ifIndex：1 为起始的网络接口索引。操作系统堆栈中会考虑所有适配器地址（包括本地环回地址），顺序取决于操作系统对适配器的枚举方式；CANoe 堆栈中会考虑所有分配的地址（包括 VLAN 地址）。
• mask：用于存储点分十进制格式地址掩码的缓冲区。
• count：掩码缓冲区大小。

返回值

• 0：成功。
• ERROR_NOT_ENOUGH_MEMORY (8)：缓冲区空间不足。
• WSA_INVALID_PARAMETER (87)：网络接口索引无效。
• WSAEADDRNOTAVAIL (10049)：无可用适配器地址。

可用性

版本	限制	测量设置	仿真/测试设置
7.0	---	---	•

示例

on start  
{  
  const dword IPV4_STR_SIZE = 16;  // IPv4 字符串长度  
  dword ifIdx;                     // 接口索引  
  long result;                     // 函数结果  
  char ipv4AdrStr[IPV4_STR_SIZE];  // 人类可读的 IPv4 地址字符串  
  char ipv4MaskStr[IPV4_STR_SIZE]; // 人类可读的 IPv4 掩码字符串  

  for (ifIdx = 1; ifIdx <= IpGetAdapterCount(); ifIdx++)  
  {  
    IpGetAdapterAddressAsString(ifIdx, ipv4AdrStr, elcount(ipv4AdrStr));  
    result = IpGetAdapterMaskAsString(ifIdx, ipv4MaskStr, elcount(ipv4MaskStr));  

    if (result == 0)  
    {  
      // 成功  
      write("IpGetAdapterMask：索引 %d 的适配器的第一个 IP %s 的掩码为 %s",  
            ipv4AdrStr, ifIdx, ipv4MaskStr);  
    }  
    else  
    {  
      writeLineEx(1, 3, "IpGetAdapterMask：错误 %d", result);  
    }  
  }  
}  

IpGetAdapterVlanDefaultPriority

CAPL 函数 >> TCP/IP API >> IpGetAdapterVlanDefaultPriority

函数

语法

long IpGetAdapterVlanDefaultPriority(dword ifIndex, word& retVlanDefaultPriority);  

功能

返回指定索引适配器的 VLAN 优先级。若适配器非 VLAN 接口，则返回错误码 WSA_INVALID_PARAMETER (87)。

参数

• ifIndex：1 为起始的网络接口索引。
• retVlanDefaultPriority：适配器的优先级。

返回值

• 0：成功。
• WSA_INVALID_PARAMETER (87)：网络接口索引无效或非 VLAN 适配器。
• SOCKET_ERROR (-1)：函数失败，调用 IpGetLastError 获取详细错误码。

可用性

版本	限制	测量设置	仿真/测试设置
11.0	---	---	•

示例

on start  
{  
  dword adapterCount;  
  dword ifIndex;  
  word prio;  
  long result;  

  adapterCount = ipGetAdapterCount();  
  for (ifIndex = 1; ifIndex <= adapterCount; ifIndex++)  
  {  
    result = IpGetAdapterVlanDefaultPriority(ifIndex, prio);  
    if (result == 0)  
    {  
      write("适配器 %d 的 VLAN 优先级为 %d", ifIndex, prio);  
    }  
  }  
}  

IpGetAdapterVlanId

CAPL 函数 >> TCP/IP API >> IpGetAdapterVlanId

函数

语法

long IpGetAdapterVlanId(dword ifIndex, word& retVlanId);  

功能

返回指定索引适配器的 VLAN ID。若适配器非 VLAN 接口，则返回错误码 WSA_INVALID_PARAMETER (87)。

参数

• ifIndex：1 为起始的网络接口索引。
• retVlanId：适配器的 VLAN ID。

返回值

• 0：成功。
• WSA_INVALID_PARAMETER (87)：网络接口索引无效或非 VLAN 适配器。
• SOCKET_ERROR (-1)：函数失败，调用 IpGetLastError 获取详细错误码。

可用性

版本	限制	测量设置	仿真/测试设置
11.0	---	---	•

示例

on start  
{  
  dword adapterCount;  
  dword ifIndex;  
  word vlanId;  
  long result;  

  adapterCount = ipGetAdapterCount();  
  for (ifIndex = 1; ifIndex <= adapterCount; ifIndex++)  
  {  
    result = ipGetAdapterVlanId(ifIndex, vlanId);  
    if (result == 0)  
    {  
      write("适配器 %d 的 VLAN ID 为 %d", ifIndex, vlanId);  
    }  
  }  
}  

IpGetAddressAsArray

CAPL 函数 >> TCP/IP API >> IpGetAddressAsArray

函数

将冒号分隔格式的地址字符串转换为 16 字节数组，数组中的地址字节按网络字节序排列。

语法

dword IpGetAddressAsArray( char address[], byte ipv6Address[]);  

参数

• address

  待转换的 IPv6 地址字符串（数值形式）。

• ipv6Address

  用于存储转换后 IPv6 地址的 16 字节数组。

返回值

• 0xFFFFFF：指定的地址字符串无效。
• 0x0：函数执行成功，结果已存入数组。

可用性

版本	仅限测量设置	仅限仿真/测试设置
8.0	---	•
11.0	---	•

示例

on start  
{  
  const dword IPV6_STR_SIZE = 40;  // IPv6 字符串长度  
  int i;                           // 循环变量  
  byte ipv6Addr[16];               // IPv6 地址字节数组  
  dword result;                    // 函数返回结果  
  char ipv6AddrStr[IPV6_STR_SIZE] = "2001:DB8:85A3:8D3:1319:8A2E:370:7344";  

  write("Converting IPv6 Address %s to bytes...", ipv6AddrStr);  
  result = IpGetAddressAsArray(ipv6AddrStr, ipv6Addr);  

  if (result == 0)  
  {  
    // 转换成功  
    write("IpGetAddressAsArray: returned array with IPv6 bytes:");  
    for (i = 0; i < 16; i++)  
    {  
      write("Byte %.2d = 0x%.2x", i, ipv6Addr[i]);  
    }  
  }  
  else  
  {  
    writeLineEx(1, 3, "IpGetAddressAsArray: The specified address string was invalid.");  
  }  
}  

IpGetAddressAsNumber

CAPL 函数 >> TCP/IP API >> IpGetAddressAsNumber

函数

将点分格式的 IPv4 地址字符串转换为网络字节序的数值形式。

语法

dword IpGetAddressAsNumber( char address[]);  

参数

• address
  待转换的 IPv4 地址字符串（数值形式）。

返回值

• 4294967295（0xFFFFFFFF，等效于 "255.255.255.255"）：指定的地址字符串无效。
• 其他值：输入 IPv4 地址字符串对应的数值形式。

可用性

版本	仅限测量设置	仅限仿真/测试设置
7.0	---	•
11.0	---	•

示例

on start  
{  
  const dword IPV4_STR_SIZE = 16;  // IPv4 字符串长度  
  char ipv4AddrStr[IPV4_STR_SIZE] = "129.168.111.222";  

  write("Converting IPv4 Address %s to numerical value => 0x%x",  
        ipv4AddrStr, IpGetAddressAsNumber(ipv4AddrStr));  
}  

版本信息

Version 14 SP2

© Vector Informatik GmbH

IpGetStackParameter

函数

该函数用于读取TCP/IP协议栈参数的值。参数名称以点分隔的路径形式给出。

语法

long IpGetStackParameter(char parameterName[], long value);  
long IpGetStackParameter(dword ifIndex, char parameterName[], long value);  

支持读取的参数

• canoe.interface.mtu：获取接口的最大传输单元（MTU）大小，需指定接口索引。
• canoe.ipv6.default_scope：获取IPv6协议栈的默认作用域，用于链路本地地址的目的地址。
• net.inet.tcp.delayed_ack：检查TCP延迟确认算法是否启用。默认启用，TCP会尝试将ACK标志捎带在下一个响应数据包中。
• net.inet.tcp.rfc1323：检查RFC1323扩展是否启用。CANoe 12.0及以上版本默认启用。
• net.inet.tcp.rexmit_max：获取TCP连接的最大重传超时时间。

注意事项

• 函数依赖于所选的协议栈。
• 该功能不能与操作系统的TCP/IP协议栈配合使用。

参数

• ifIndex：1-based的网络接口索引。
• parameterName ：参数路径字符串（例如 net.inet.tcp.delayed_ack）。
• value：返回的参数值。

返回值

• 0：函数执行成功。
• WSA_INVALID_PARAMETER (87)：指定的网络接口索引无效。
• SOCKET_ERROR (-1) ：函数失败，调用 IpGetLastError 获取详细错误码。

示例

on start  
{  
  LONG result;  
  LONG ifIndex;  
  LONG value;  

  // 获取接口1的MTU  
  ifIndex = 1;  
  result = ipGetStackParameter(ifIndex, "canoe.interface.mtu", value);  
  if(result != 0) {  
    writeLineEx(1, 3, "获取接口%d的MTU失败，结果：%d", ifIndex, result);  
  } else {  
    writeLineEx(1, 0, "接口%d的MTU为%d字节", ifIndex, value);  
  }  

  // 获取IPv6默认作用域  
  result = ipGetStackParameter("canoe.ipv6.default_scope", value);  
  if(result != 0) {  
    writeLineEx(1, 3, "获取IPv6默认作用域失败，结果：%d", result);  
  } else {  
    writeLineEx(1, 0, "IPv6默认作用域已设置为接口%d", value);  
  }  

  // 获取TCP延迟确认状态  
  result = ipGetStackParameter("net.inet.tcp.delayed_ack", value);  
  if(result != 0) {  
    writeLineEx(1, 3, "获取延迟确认行为失败，结果：%d", result);  
  } else {  
    if(value == 0) {  
      writeLineEx(1, 0, "TCP延迟确认已禁用");  
    } else {  
      writeLineEx(1, 0, "TCP延迟确认已启用");  
    }  
  }  
}  

IpGetSocketOption

函数

读取指定套接字选项的值。

语法

long IpGetSocketOption(dword socket, char level[], char name[], long &value);  

方法

socket.GetSocketOption(char level[], char name[], long &value);  

参数

• socket：套接字句柄。
• level ：选项定义的层级（例如 SOL_SOCKET (0xFFFF)）。
• name ：选项名称（例如 SO_BROADCAST (0x0020)）。
• value：返回的选项值。

返回值

• 0：成功。
• WSA_INVALID_PARAMETER (87)：套接字索引无效。
• SOCKET_ERROR (-1) ：失败，调用 IpGetLastSocketError 获取详细错误码。

示例

on start  
{  
  char errorMessage[255];  
  long socket;  
  long result;  
  long value;  

  // 打开UDP套接字  
  socket = udpOpen(0, 0);  
  if(socket == ~0) {  
    write("打开UDP套接字失败，错误码：%d", ipGetLastError());  
  }  

  // 获取套接字类型（UDP=2，TCP=1）  
  result = ipGetSocketOption(socket, "SOL_SOCKET", "SO_TYPE", value);  
  if(result != 0) {  
    ipGetLastSocketErrorAsString(socket, errorMessage, elcount(errorMessage));  
    write("获取SO_TYPE选项失败，错误：%s", errorMessage);  
  } else {  
    write("套接字类型：%d", value);  
  }  

  // 获取IP_TTL值  
  result = ipGetSocketOption(socket, "IPPROTO_IP", "IP_TTL", value);  
  if(result != 0) {  
    ipGetLastSocketErrorAsString(socket, errorMessage, elcount(errorMessage));  
    write("获取IP_TTL选项失败，错误：%s", errorMessage);  
  } else {  
    write("套接字的IP TTL值：%d", value);  
  }  
}  

IpGetSocketName

函数

返回套接字的本地绑定地址和端口。

语法

// IPv4  
long IpGetSocketName(dword socket, dword &ipv4Address, dword &port);  
// IPv6  
long IpGetSocketName(dword socket, byte ipv6Address[], dword &port);  
// IP端点  
long IpGetSocketName(dword socket, IP_Endpoint localEndpoint);  

参数

• socket：套接字句柄。
• ipv4Address：返回的IPv4地址（数值形式）。
• ipv6Address：16字节数组，返回IPv6地址。
• port：本地绑定端口。
• localEndpoint ：IP_Endpoint 变量，存储本地端点的地址和端口。

返回值

• 0：成功。
• WSA_INVALID_PARAMETER (87)：套接字索引无效。
• SOCKET_ERROR (-1) ：失败，调用 IpGetLastSocketError 获取详细错误码。

示例

on start  
{  
  LONG ipv4SocketHandle;  
  DWORD port;  
  DWORD ipv4Address[1];  
  CHAR addressStr[49];  

  // 打开IPv4 UDP套接字（隐式绑定）  
  ipGetAdapterAddress(1, ipv4Address, elcount(ipv4Address));  
  ipv4SocketHandle = udpOpen(ipv4Address[0], 123);  
  if(ipv4SocketHandle == ~0) {  
    writeLineEx(1, 3, "%BASE_FILE_NAME%: 打开套接字失败，错误码：%d", ipGetLastError());  
  }  

  // 获取本地绑定地址和端口  
  ipGetSocketName(ipv4SocketHandle, ipv4Address[0], port);  
  ipGetAddressAsString(ipv4Address[0], addressStr, elcount(addressStr));  
  writeLineEx(1, 1, "%BASE_FILE_NAME%: IPv4套接字绑定到地址%s，端口%d", addressStr, port);  
}  

IpGetSocketAddressFamily

函数

返回指定套接字的地址族。

语法

long IpGetSocketAddressFamily(dword socket);  

返回值

• AF_INET (2)：IPv4地址族。
• AF_INET6 (28)：IPv6地址族。
• SOCKET_ERROR (-1)：无效的套接字句柄。

示例

on start  
{  
  const dword INVALID_SOCKET = ~0;  
  dword socket = INVALID_SOCKET;  
  byte ipv6Addr[16];  
  dword port = 12345;  
  long result;  

  // 创建IPv4 UDP套接字  
  socket = UdpOpen(0, port);  
  result = IpGetSocketAddressFamily(socket);  
  if(result != -1) {  
    writeLineEx(1, 3, "地址族：%d", result); // 输出2（AF_INET）  
  } else {  
    writeLineEx(1, 3, "无效的套接字句柄");  
  }  
  UdpClose(socket);  

  // 创建IPv6 UDP套接字  
  IpGetAddressAsArray("::", ipv6Addr); // 获取IPv6零地址  
  socket = UdpOpen(ipv6Addr, 0);  
  result = IpGetSocketAddressFamily(socket);  
  if(result != -1) {  
    writeLineEx(1, 3, "地址族：%d", result); // 输出28（AF_INET6）  
  } else {  
    writeLineEx(1, 3, "无效的套接字句柄");  
  }  
  UdpClose(socket);  
}  

IpGetLastSocketErrorAsString

函数

获取指定套接字上一次失败操作的错误消息（对应Winsock 2错误码）。

语法

long IpGetLastSocketErrorAsString(dword socket, char text[], dword count);  

参数

• socket：套接字句柄。
• text：存储错误消息的缓冲区。
• count：缓冲区大小。

返回值

• 0：成功，错误消息写入缓冲区；若错误码无效，格式为"Unknown error: x"。
• WSA_INVALID_PARAMETER (87)：套接字无效。

示例

on start  
{  
  const dword INVALID_SOCKET = ~0;  
  dword socket = INVALID_SOCKET;  
  char errMsg[255];  

  // 创建套接字  
  socket = UdpOpen(0, 1);  

  // 触发错误（例如使用无效参数调用UdpSendTo）  
  if(UdpSendTo(socket, 0, 0, "a", 1) == -1) {  
    IpGetLastSocketErrorAsString(socket, errMsg, elcount(errMsg));  
    writeLineEx(1, 3, "错误消息：%s", errMsg);  
  }  

  UdpClose(socket);  
}  

IpGetLastSocketError

函数

返回指定套接字上一次失败操作的Winsock 2错误码。

语法

long IpGetLastSocketError(dword socket);  

返回值

• WSA_INVALID_PARAMETER (87)：套接字无效。
• 其他值：Winsock 2 WSAGetLastError 函数返回的错误码。

示例

on start  
{  
  const dword INVALID_SOCKET = ~0;  
  dword socket = INVALID_SOCKET;  

  socket = UdpOpen(0, 0);  
  if(UdpSendTo(socket, 0, 0, "a", 1) == -1) {  
    writeLineEx(1, 3, "错误码：%d", IpGetLastSocketError(socket));  
  }  
  UdpClose(socket);  
}  

IpGetLastError

函数

返回上一次失败操作的Winsock 2错误码。

语法

long IpGetLastError();  

返回值

Winsock 2 WSAGetLastError 函数返回的错误码。

示例

on start  
{  
  // 触发错误（例如使用无效地址调用TcpOpen）  
  TcpOpen(0xffffffff, 1);  
  writeLineEx(1, 3, "错误码：%d", IpGetLastError()); // 输出10049（无效地址）  
}  

IpGetHostByName

函数

将主机名解析为IP地址。优先在CANoe仿真设置中查找，未找到则通过DNS请求（依赖操作系统协议栈）。

语法

// IPv4  
long IpGetHostByName(char hostname[], dword ipv4Address[], dword &count);  
// IPv6  
long IpGetHostByName(char hostname[], byte ipv6Address[][], dword &count);  
// IP_Address数组  
long IpGetHostByName(char hostname[], IP_Address addresses[], dword &count);  

参数

• hostname：主机名。
• ipv4Address/ipv6Address：存储解析的IP地址数组。
• count：输入时为缓冲区大小，输出时为解析的地址数量。
• addresses ：存储IPv4/IPv6地址的 IP_Address 数组。

返回值

• 0：成功。
• ERROR_NOT_ENOUGH_MEMORY (8)：缓冲区不足。
• WSAEWOULDBLOCK (10035) ：异步完成，通过 OnIpGetHostByName 回调返回结果。
• WSAHOST_NOT_FOUND (11001)：主机未找到。

示例

on start  
{  
  char addrStr[47];  
  long result;  
  dword count;  
  dword loop;  
  dword v4Addrs[10];  
  byte v6Addrs[10][16];  

  // 获取"ECU 1"的IPv4地址  
  count = elCount(v4Addrs);  
  result = IpGetHostByName("ECU 1", v4Addrs, count);  
  if(result == 0) {  
    write("ECU 1的IPv4地址：");  
    for(loop = 0; loop < count; loop++) {  
      ipGetAddressAsString(v4Addrs[loop], addrStr, elcount(addrStr));  
      write("%s", addrStr);  
    }  
  }  

  // 获取"ECU 1"的IPv6地址  
  count = elCount(v6Addrs);  
  result = IpGetHostByName("ECU 1", v6Addrs, count);  
  if(result == 0) {  
    write("ECU 1的IPv6地址：");  
    for(loop = 0; loop < count; loop++) {  
      ipGetAddressAsString(v6Addrs[loop], addrStr, elcount(addrStr));  
      write("%s", addrStr);  
    }  
  }  
}  

IpGetAddressAsString

IpGetAddressAsString

CAPL 函数 >> TCP/IP API >> IpGetAddressAsString

函数

该函数将网络字节序（大端序）的数值地址转换为点分格式的地址字符串（如"192.168.0.10"）。对于 IPv6，地址字符串采用冒号分隔格式（如"1234:5678:9ABC:DEF1:2345:6789:ABCD:EF12"）。

语法

long IpGetAddressAsString( dword numericAddress, char address[], dword count);  
long IpGetAddressAsString( byte ipv6Address[], char address[], dword count);  

参数

• numericAddress

  待转换的 IPv4 数值地址。

• ipv6Address

  本地 IPv6 地址，存储在 16 字节数组中。

• address

  用于存储转换后 IPv4/IPv6 地址的缓冲区。

• count

  地址缓冲区的大小。

返回值

• 0：函数执行成功。
• ERROR_NOT_ENOUGH_MEMORY (8)：地址缓冲区空间不足。
• WSA_INVALID_PARAMETER (87)：指定的地址无效。

可用性

版本	限制范围	测量设置	仿真/测试设置
7.0	---	---	•
11.0	---	•	•

示例

on start  
{  
  const dword IPV4_STR_SIZE = 16;  // IPv4 字符串长度  
  const dword IPV6_STR_SIZE = 40;  // IPv6 字符串长度  
  dword ipv4Addr = 0xde6fa881;     // IPv4 地址（192.168.111.222）  
  char ipv4AddrStr[IPV4_STR_SIZE]; // IPv4 地址字符串缓冲区  
  char ipv6AddrStr[IPV6_STR_SIZE]; // IPv6 地址字符串缓冲区  
  long result;                     // 函数返回结果  

  // IPv6 地址（2001:DB8:85A3:8D3:1319:8A2E:370:7344）  
  byte ipv6Addr[16] = {0x20,0x01,0x0D,0xB8,0x85,0xA3,0x08,0xD3,  
                       0x13,0x19,0x8A,0x2E,0x03,0x70,0x73,0x44};  

  // 转换 IPv4 地址  
  result = IpGetAddressAsString(ipv4Addr, ipv4AddrStr, elcount(ipv4AddrStr));  
  if (result == 0)  
  {  
    write("IpGetAddressAsString: Address 0x%x => %s", ipv4Addr, ipv4AddrStr);  
  }  
  else  
  {  
    writeLineEx(1, 3, "IpGetAddressAsString: Error %d", result);  
  }  

  // 转换 IPv6 地址  
  result = IpGetAddressAsString(ipv6Addr, ipv6AddrStr, elcount(ipv6AddrStr));  
  if (result == 0)  
  {  
    write("IpGetAddressAsString: IPv6 address bytes => %s", ipv6AddrStr);  
  }  
  else  
  {  
    writeLineEx(1, 3, "IpGetAddressAsString: Error %d", result);  
  }  
}