CAPL Reference Skill

Overview

CAPL (Communication Access Programming Language) is the event-driven scripting language for Vector CANoe/CANalyzer. It follows C89/C90 syntax constraints — no C99 or C++ features. This skill provides corrected, production-ready reference material for automotive diagnostic security testing with CAPL + DLL two-layer architecture.

Quick Syntax Rules (C89 Compliance)

• All variable declarations MUST appear at the top of the block (no mixed declarations)
• No // comments in strict C89 (CAPL compiler accepts them, but avoid for portability)
• No snprintf — use sprintf (ensure buffer is large enough)
• No strncpy_s — use strncpy, manually null-terminate
• No _atoi64 — use atol() or parse hex manually
• Local array initialization with {} is NOT supported — assign element by element
• Test Module functions use PascalCase: TestWaitForTimeout, TestStep, etc.

File Structure Template

/*@!Encoding:936*/

includes
{
  #include "Common.can"
}

variables
{
  msTimer tCycle;
  message 0x123 msg_Test;
  long gCounter;
  byte gData[8];
}

on start
{
  gCounter = 0;
  setTimer(tCycle, 100);
}

on timer tCycle
{
  gCounter++;
  msg_Test.dlc = 8;
  msg_Test.byte(0) = gCounter;
  output(msg_Test);
  setTimer(tCycle, 100);
}

on message 0x456
{
  write("Rx 0x456 byte0=0x%02X", this.byte(0));
}

Key Event Handlers

Message Handling

variables
{
  message 0x100 msg_Tx;
  message EngineData msg_Engine;  /* DB-backed message */
}

on start
{
  msg_Tx.dlc = 8;
  msg_Tx.byte(0) = 0x11;
  output(msg_Tx);
}

/* Access DB signal */
on message EngineData
{
  write("Speed=%f", this.EngineSpeed);
}

/* Write signal and send */
on key 's'
{
  msg_Engine.EngineSpeed = 1000;
  output(msg_Engine);
}

Test Module Syntax (PascalCase — Correct!)

testcase TC_SecurityAccess()
{
  TestCaseTitle("TC_SA_01", "Security Access Level 1");

  TestStep("SendSeed", "Send 27 01 RequestSeed");
  /* send request... */

  if (TestWaitForMessage(0x708, 1000) == 1)
  {
    TestStepPass("CheckResp", "Response received");
  }
  else
  {
    TestStepFail("CheckResp", "Response timeout");
  }
}

Correct function names:

All take two parameters (name, description):

TestStep("StepName", "Description of what is being done");
TestStepPass("StepName", "Reason for pass");
TestStepFail("StepName", "Reason for failure");

DLL Integration — CAPL_DLL_INFO4 Table (NOT __declspec)

CRITICAL: CAPL DLL functions are NOT discovered via the Windows DLL export table. They are registered in a special CAPL_DLL_INFO4 table[] array that CANoe reads at load time. This is completely different from standard __declspec(dllexport).

Step 1: Use the Official Sample Project (DO NOT start from empty DLL project)

Path varies by version, search for CAPLdll under:

C:\Users\Public\Documents\Vector\CANoe <version>\Sample Configurations\Programming\CAPLdll

Open the .sln in Visual Studio. The sample project already has:

• Correct header dependencies
• CAPL_DLL_INFO4 table[] format for your CANoe version
• Calling convention macros (CAPL_DLL_CDECL, CAPL_FARCALL, etc.)
• onCaplInit() / onCaplExit() wiring

Step 2: Add Your C/C++ Function

In capldll.cpp, add your function following the same pattern as existing functions:

long MyAdd(long a, long b)
{
    return a + b;
}

Step 3: Register in CAPL_DLL_INFO4 table[]

Add an entry to the table (format varies by CANoe version — always copy from the existing entries in your sample project):

CAPL_DLL_INFO4 table[] =
{
    /* existing entries — do NOT remove */

    {
        "MyAdd",
        (CAPL_FARCALL)MyAdd,
        "long",
        "long a, long b",
        CAPL_DLL_CDECL,
        0,
        CDLL_EXPORT
    },

    { 0, 0 }   /* END MARKER — must keep */
};

Field meanings:

1. "MyAdd" — function name visible to CAPL
2. (CAPL_FARCALL)MyAdd — function pointer
3. "long" — return type string (tells CAPL the return type)
4. "long a, long b" — parameter types string (tells CAPL the argument types)
5. CAPL_DLL_CDECL — calling convention (use the macro from the sample project)
6. 0 — reserved
7. CDLL_EXPORT — export flag

The { 0, 0 } entry MUST be the last entry — it is the table terminator.

Step 4: Compile with Correct Settings

Note: The reference document mentions /MT (static CRT) as an option to avoid needing VC++ redistributable on target machines. This works BUT beware:

小葱技能有更好的技能skills插件。

• Memory allocated in DLL cannot be freed by CANoe, and vice versa
• For simple DLLs this is fine; for DLLs that pass dynamic memory, use /MD

Step 5: Load DLL in CANoe

1. Open CANoe configuration
2. Menu: Configuration → Programming → CAPL DLL (or Options → CAPL → DLL)
3. Add → select your .dll file
4. Recompile the CAPL node
5. Check CAPL Browser / Functions list — your function should appear

Step 6: Call from CAPL

on key 't'
{
  long ret;
  ret = MyAdd(10, 20);
  write("MyAdd(10,20) = %d", ret);
}

Supported Parameter Types in CAPL_DLL_INFO4

For arrays/buffers, always pass the length as a separate long parameter:

long ProcessData(unsigned char* data, long len)
{
    if (data == 0 || len <= 0) return -1;
    /* process data[0] to data[len-1] */
    return 0;
}

Common Pitfalls

See references/capl_pitfalls.md for the full list with explanations.

Reference Files

• references/capl_pitfalls.md — Detailed pitfall explanations and corrections
• references/capl_test_templates.md — Reusable test case templates for UDS/security
• references/capl_dll_guide.md — DLL compilation and CAPL_DLL_INFO4 integration guide

When Receiving CAPL-Related Queries

1. Always verify syntax against C89 constraints before providing code examples
2. Use PascalCase for all Test Module function names
3. Place all variable declarations at the top of each block
4. Reference references/capl_pitfalls.md when user reports a CAPL error
5. For UDS diagnostic flows, use the templates in references/capl_test_templates.md
6. For DLL questions, emphasize: use the official sample project, register in CAPL_DLL_INFO4 table[], do NOT rely on __declspec(dllexport) alone

这个Skill质量不错，专门解决CAPL脚本开发中的常见问题和难点。它对C89语法限制、事件处理、DLL集成等做了清晰说明，特别是能帮助开发者避免像函数命名大小写、变量声明位置这样的典型错误。不过内容专业性较强，更适合有经验的开发者；涉及汽车诊断测试的内容较多，通用性一般；部分文档末尾还有截断缺失。入门用户可能会觉得内容偏深，中高级用户会比较受益。