In the first step the extcap is queried for its interfaces.

$ extcapbin --extcap-interfaces

This call must print the existing interfaces for this extcap and must return 0. The output must conform to the grammar specified for extcap, and it is specified in the doc/extcap.4 generated man page (in the build dir).

Wireshark 2.9 and later also pass --extcap-version=x.x, which provides the calling Wireshark’s major and minor version. This can be used to change behavior depending on the Wireshark version in question.

Example call for interface query. 

$ extcap_example.py --extcap-interfaces --extcap-version=4.0
extcap {version=1.0}{help=Some help url}
interface {value=example1}{display=Example interface 1 for extcap}
interface {value=example2}{display=Example interface 2 for extcap}

The version for the extcap sentence (which may exist as many times as is needed, but only the last one will be used) will be used for displaying the version information of the extcap interface in the about dialog of Wireshark.

The value for each interface will be used in subsequent calls as the interface name <iface>.

Using the help argument, an interface may provide a generic help URL for the extcap utility.

Next, the extcap binary is queried for all valid DLTs for all the interfaces returned by step 1.

$ extcap_example.py --extcap-dlts --extcap-interface <iface>

This call must print the valid DLTs for the interface specified. This call is made for all the interfaces and must return 0.

Example for the DLT query. 

$ extcap_example.py --extcap-interface IFACE --extcap-dlts
dlt {number=147}{name=USER1}{display=Demo Implementation for Extcap}

A binary or script which neither provides an interface list or a DLT list will not show up in the extcap interfaces list.

The extcap binary is next asked for the configuration of each specific interface

$ extcap_example.py --extcap-interface <iface> --extcap-config

Each interface can have custom options that are valid for this interface only. Those config options are specified on the command line when running the actual capture. To allow an end-user to specify certain options, such options may be provided using the extcap config argument.

To share which options are available for an interface, the extcap responds to the command --extcap-config, which shows all the available options (aka additional command line options).

Those options are used to build a configuration dialog for the interface.

Example for interface options. 

$ extcap_example.py --extcap-interface <iface> --extcap-config
arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}{type=integer}{range=1,15}{required=true}
arg {number=1}{call=--message}{display=Message}{tooltip=Package message content}{placeholder=Please enter a message here ...}{type=string}
arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag}
arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}
arg {number=4}{call=--server}{display=IP address for log server}{type=string}{validation=\\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\b}
value {arg=3}{value=if1}{display=Remote1}{default=true}
value {arg=3}{value=if2}{display=Remote2}{default=false}

Now the user can click on the options and change them. They are sent to the extcap when the capture is launched.

There are several kind of options available:

Once the interfaces are listed and configuration is customized by the user the capture can be started.

$ extcap_example.py --extcap-interface <iface> [params] --capture [--extcap-capture-filter <cfilter>]
  --fifo FIFO

To run the capture, the extcap must implement the --capture, --extcap-capture-filter and --fifo options.

They are automatically added by Wireshark, which opens the fifo for reading. All the other options are automatically added to run the capture. The extcap interface is used like all other interfaces (meaning that capture on multiple interfaces, as well as stopping and restarting the capture is supported).

@echo off
C:\Windows\py.exe C:\Path\to\my\extcap.py %*

A selector may be reloaded from the configuration dialog of the extcap application within Wireshark. With the reload argument (defaults to false), the entry can be marked as reloadable.

arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}{reload=true}{placeholder=Load interfaces...}

After this has been defined, the user will get a button displayed in the configuration dialog for this extcap application, with the text "Load interfaces…​" in this case, and a generic "Reload" text if no text has been provided.

The extcap utility is then called again with all filled out arguments and the additional parameter --extcap-reload-option <option_name>. It is expected to return a value section for this option, as it would during normal configuration. The provided option list is then presented as the selection, a previous selected option will be reselected if applicable.

Arguments may be set with {required=true} which enforces a value being provided, before a capture can be started using the extcap options dialog. This is not being checked, if the extcap is started via a simple double-click. The necessary fields are marked for the customer, to ensure a visibility for the end customer of the required argument.

Additionally text and number arguments may also be checked using a regular expression, which is provided using the validation attribute (see example above). The syntax for such a check is the same as for Qt RegExp classes. This feature is only active in the Qt version of Wireshark.

The controls are similar to the arguments, but without the call element. All controls may be given a default value at startup and most can be changed during capture, both by the extcap and the user (depending on the type of control).

All controls must provide a number, by which they are identified. No number may be provided twice. All options must present the elements type and display, where type provides the type of control to add to the toolbar and display providing the name in the GUI.

Additionally tooltip and placeholder may be provided, which will give the user information about what to enter into this field.

All controls, except from the logger, help and restore buttons, may be disabled (and enabled) in GUI by the extcap during capture. This can be because of set-once operations, or operations which takes some time to complete.

All control values which are changed by the user (not equal to the default value) will be sent to the extcap utility when starting a capture. The extcap utility may choose to discard initial values and set new values, depending on implementation.

These types are defined as controls:

In addition to the controls it’s possible to send a single message from the extcap utility to the user. This message can be put in the status bar or displayed in a information, warning or error dialog which must be accepted by the user. This message does not use the NUMBER argument so this can have any value.