From 7423a91e81070596bf319fd076aae0e66e00c30d Mon Sep 17 00:00:00 2001 From: Roland Knall Date: Wed, 30 Dec 2015 14:46:03 +0100 Subject: [PATCH] extcap: Documentation for the new features Add documentation for regular expression usage, required and fileextension arguments Change-Id: I9a27c4263a87774cb997a6f4e1f8783a69d818df Reviewed-on: https://code.wireshark.org/review/12949 Reviewed-by: Roland Knall --- doc/README.extcap | 20 ++++++++++++++++++-- doc/extcap.pod | 15 ++++++++------- 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/doc/README.extcap b/doc/README.extcap index d861e62bdc..cb32683eed 100644 --- a/doc/README.extcap +++ b/doc/README.extcap @@ -87,10 +87,11 @@ interface. Example: $ extcapbin --extcap-interface IFACE --extcap-config -arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}{type=integer}{range=1,15} +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}{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} @@ -139,7 +140,11 @@ These options do have types, for which the following types are being supported: * STRING - Let the user provide a string to the capture - arg {number=1}{call=--message}{display=Message}{tooltip=Package message content}{type=string} + arg {number=1}{call=--server}{display=IP Address}{tooltip=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} + + - validation allows to provide a regular expression string, which is used to check + the user input for validity beyond normal data type or range checks. Back-slashes + must be escaped (as in \\b for \b) * BOOLEAN,BOOLFLAG - this provides the possibility to set a true/false value. BOOLFLAG values will only appear in the command-line if set to true, otherwise they @@ -162,6 +167,17 @@ These options do have types, for which the following types are being supported: value {arg=3}{value=if2}{display=Remote2}{default=false} +VALIDATION OF ARGUMENTS +======================= +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. + + DEVELOPMENT =========== To have extcap support, extcap must be enabled. Moreover the specific extcap must diff --git a/doc/extcap.pod b/doc/extcap.pod index 9c0d42f6b2..511e1a59cd 100644 --- a/doc/extcap.pod +++ b/doc/extcap.pod @@ -58,9 +58,9 @@ Argument type for UI filtering for raw, or UI type for selector: Example 1: - arg {number=0}{call=channel}{display=Wi-Fi Channel}{type=integer} - arg {number=1}{call=chanflags}{display=Channel Flags}{type=radio} - arg {number=2}{call=interface}{display=Interface}{type=selector} + arg {number=0}{call=--channel}{display=Wi-Fi Channel}{type=integer}{required=true} + arg {number=1}{call=--chanflags}{display=Channel Flags}{type=radio} + arg {number=2}{call=--interface}{display=Interface}{type=selector} value {arg=0}{range=1,11} value {arg=1}{value=ht40p}{display=HT40+} value {arg=1}{value=ht40m}{display=HT40-} @@ -69,13 +69,14 @@ Example 1: Example 2: - arg {number=0}{call=usbdevice}{USB Device}{type=selector} + arg {number=0}{call=--usbdevice}{USB Device}{type=selector} value {arg=0}{call=/dev/sysfs/usb/foo/123}{display=Ubertooth One sn 1234} value {arg=0}{call=/dev/sysfs/usb/foo/456}{display=Ubertooth One sn 8901} Example 3: - arg {number=0}{call=usbdevice}{USB Device}{type=selector} + arg {number=0}{call=--usbdevice}{USB Device}{type=selector} + arg {number=1}{call=--server}{display=IP address for log server}{type=string}{validation=(?:\d{1,3}\.){3}\d{1,3}} flag {failure=Permission denied opening Ubertooth device} =head1 Security awareness @@ -90,7 +91,7 @@ Example 3: =item - If an attacker can write to a system binary directory, we're game over anyhow -=item - Don't let wireshark be told to look for capture binaries somewhere else? +=item - Reference the folders tab in the wireshark->about information, to see from which directory extcap is being run =back @@ -104,4 +105,4 @@ B is feature of B. The latest version of B can be found at L. HTML versions of the Wireshark project man pages are available at: -L. \ No newline at end of file +L.