What are CAPI capture files?
As explained in a previous post, CAPI capture files contain the messages that are exchanged between the IVR and the telephone network. These capture files are in the PCAP format, which is a general-purpose format for storing trace information (e.g. network traces).
Viewing CAPI PCAP files
The CAPI PCAP files can be opened using Wireshark.
After opening a CAPI pcap trace file in Wireshark, you’ll see a list of captured messages. For each message the timestamp, size and raw bytes are shown.
By default, Wireshark does not understand the CAPI protocol, so there will not be any extra information about the meaning of the messages.
Wireshark CAPI dissector
In order to let Wireshark understand the CAPI messages, you need to install an extra Wireshark dissector. A dissector is a script which is used by Wireshark to parse messages of a certain protocol.
The CAPI dissector can be installed as follows:
- Download and unzip the CAPI Wireshark dissector: CAPI-1.5
- Copy CAPI.lua to the Wireshark directory (usually C:\Program Files\Wireshark)
- Open the init.lua file in the Wireshark directory and change disable_lua=true into disable_lua=false
- At the and of the init.lua file, add the following line: dofile(“CAPI.lua”)
Now when you open CAPI PCAP files, Wireshark will show more information about each captured message.
Information shown in Wireshark
Aside from the timestamp and size, the other columns will now contain extra information.
Depending on the type of message, the Sender and Receiver columns show the:
- Controller number
- Physical Link Connection Identifier (PLCI)
- Network Call Correlation Identifier (NCCI)
For REQUEST and RESPONSE messages (i.e. going from the IVR to the CAPI DLL) , this information is shown in the Receiver column.
For INDICATION and CONFIRMATION messages (i.e. going from the CAPI DLL to the IVR), this information is shown in the Sender column.
The info column shows the message type (e.g. “CONNECT”) and subtype (e.g. “REQ”).
For most messages, the info column will also contain a short description of the contents of the message. For example, INFO_IND messages also have a textual representation of their Info element (e.g. “CONNECT ACKNOWLEDGE”).
When clicking on a CAPI message, the details of the message are shown in the window below the list of messages.
For each CAPI message three parts are shown:
The Frame section is part of the PCAP file format and not of the CAPI message itself.
- Arrival Time: Date & timestamp of when the message was captured
- Frame number: this is a counter of all the frames in the PCAP file
- Frame length: the length of the message as stored in the PCAP file
- Capture length: the length of the original message as captured
Note that there is a limit on the maximum length of a message in a PCAP file. Therefore the Capture length can be larger than the Frame length. In this case the message is truncated.
The CAPI header is always exactly 8 bytes long and contains the following information:
- Length: length of the total message
- Application ID: this number is assigned to the IVR by the CAPI DLL
- Command: the type of message (e.g. INFO)
- Subcommand: the direction of the message (e.g. IND)
- Message Nbr: a counter
The actual contents of the message, this is different for each type of message.
For more information, see the CAPI specification.
A lot of CAPI messages also use data structures that are defined in the Q931 standard.
If you only want to see certain CAPI messages, you can use Wireshark display filters.
For example, if you only want to see INFO_IND messages, you can enter the following display filter: capi.type == INFO_IND
If you want to see all messages except DATA_B3_REQ/CONF/IND/RESP messages, you can use: !(capi.cmd == DATA_B3)
The parameters you can use are:
- frame.number: The number of the message in the PCAP file (assigned by Wireshark, not part of CAPI)
- capi.nbr: Message number (as in CAPI header)
- capi.len: Length of the message
- capi.app: Application ID
- capi.cmd: Command (e.g. DATA_B3)
- capi.sub: Subcommand (i.e. IND,RESP,REQ or CONF)
- capi.type: Combination of .cmd and .sub (e.g. DATA_B3_IND)
You can use these filters to color packets. To enable this, go to View -> Coloring Rules.
There you can create coloring rules for CAPI:
- CAPI Specification: http://www.capi.org/downloads.html
- Q931 Specification: https://www.itu.int/rec/T-REC-Q.931-199805-I/en
- Lua Overview: http://www.lua.org/pil/contents.html
- Lua Dissectors: http://www.wireshark.org/docs/wsug_html_chunked/lua_module_Proto.html
- PCAP Format: http://wiki.wireshark.org/Development/LibpcapFileFormat