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 <rknall@gmail.com>

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<Extcap> is feature of B<Wireshark>.  The latest version
 of B<Wireshark> can be found at L<https://www.wireshark.org>.
 
 HTML versions of the Wireshark project man pages are available at:
-L<https://www.wireshark.org/docs/man-pages>.
\ No newline at end of file
+L<https://www.wireshark.org/docs/man-pages>.