extcap: Add tool-specified helppage

Allow the tool to provide a link to a helppage, displayed
by clicking on help in the configuration dialog.

The URL will be opened using an URL based service, therefore local
as well as remote URLs are possible.

Change-Id: I58b30244e97919d5cf6892faf96536ddc30fb5a7
Reviewed-on: https://code.wireshark.org/review/17549
Reviewed-by: Roland Knall <rknall@gmail.com>

doc/README.extcap

@@ -44,7 +44,7 @@ in the doc/extcap.4 generated man page (in the build dir).
 Example:
 
 $ extcapbin --extcap-interfaces
-extcap {version=1.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}
 
@@ -55,6 +55,8 @@ interface in the about dialog of Wireshark (Qt only).
 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.
+
 STEP2: the extcap is queried for valid DLTs (Data Link Types) for all the
 interfaces returned by the step 1.
 

doc/extcap_example.py

@@ -123,7 +123,7 @@ def extcap_config(interface):
 
 
 def extcap_interfaces():
-	print ("extcap {version=1.0}")
+	print ("extcap {version=1.0}{help=http://www.wireshark.org}")
 	print ("interface {value=example1}{display=Example interface usage for extcap}")
 
 def extcap_dlts(interface):

extcap.c

@@ -105,9 +105,9 @@ extcap_if_exists(const gchar *ifname)
 static gboolean
 extcap_if_exists_for_extcap(const gchar *ifname, const gchar *extcap)
 {
-    gchar *entry = (gchar *)g_hash_table_lookup(ifaces, ifname);
+    extcap_interface * entry = (extcap_interface *)g_hash_table_lookup(ifaces, ifname);
 
-    if ( entry && strcmp(entry, extcap) == 0 )
+    if ( entry && strcmp(entry->extcap_path, extcap) == 0 )
         return TRUE;
 
     return FALSE;
@@ -116,14 +116,15 @@ extcap_if_exists_for_extcap(const gchar *ifname, const gchar *extcap)
 static gchar *
 extcap_if_executable(const gchar *ifname)
 {
-    return (gchar *)g_hash_table_lookup(ifaces, ifname);
+    extcap_interface * interface = (extcap_interface *)g_hash_table_lookup(ifaces, ifname);
+    return interface != NULL ? interface->extcap_path : NULL;
 }
 
 static void
-extcap_if_add(const gchar *ifname, const gchar *extcap)
+extcap_if_add(extcap_interface * interface)
 {
-    if ( !g_hash_table_lookup(ifaces, ifname) )
-        g_hash_table_insert(ifaces, g_strdup(ifname), g_strdup(extcap));
+    if (!g_hash_table_lookup(ifaces, interface->call))
+        g_hash_table_insert(ifaces, g_strdup(interface->call), interface);
 }
 
 static void
@@ -282,7 +283,7 @@ extcap_get_if_dlts(const gchar *ifname, char **err_str) {
     return caps;
 }
 
-static void extcap_free_interface(gpointer i, gpointer user_data _U_) {
+static void extcap_free_interface(gpointer i) {
 
     extcap_interface * interface = (extcap_interface *)i;
 
@@ -292,6 +293,7 @@ static void extcap_free_interface(gpointer i, gpointer user_data _U_) {
     g_free(interface->call);
     g_free(interface->display);
     g_free(interface->version);
+    g_free(interface->help);
 }
 
 static gboolean interfaces_cb(const gchar *extcap, const gchar *ifname _U_, gchar *output, void *data,
@@ -334,7 +336,8 @@ static gboolean interfaces_cb(const gchar *extcap, const gchar *ifname _U_, gcha
                 *il = g_list_append(*il, if_info);
             }
 
-            extcap_if_add(int_iter->call, extcap);
+            int_iter->extcap_path = g_strdup(extcap);
+            extcap_if_add(int_iter);
         }
 
         /* Call for interfaces and tools alike. Multiple calls (because a tool has multiple
@@ -344,8 +347,6 @@ static gboolean interfaces_cb(const gchar *extcap, const gchar *ifname _U_, gcha
         walker = g_list_next(walker);
     }
 
-    g_list_foreach(interfaces, extcap_free_interface, NULL);
-
     return TRUE;
 }
 
@@ -372,7 +373,7 @@ extcap_reload_interface_list(GList **retp, char **err_str) {
     /* ifaces is used as cache, do not destroy its contents when
      * returning or no extcap interfaces can be queried for options */
     if (ifaces == NULL)
-        ifaces = g_hash_table_new_full(g_str_hash, g_str_equal, g_free, g_free);
+        ifaces = g_hash_table_new_full(g_str_hash, g_str_equal, g_free, extcap_free_interface);
     else
         g_hash_table_remove_all(ifaces);
 
@@ -388,6 +389,13 @@ extcap_reload_interface_list(GList **retp, char **err_str) {
     g_free(argv);
 }
 
+gchar *
+extcap_get_help_for_ifname(const char *ifname)
+{
+    extcap_interface * interface = (extcap_interface *)g_hash_table_lookup(ifaces, ifname);
+    return interface != NULL ? interface->help : NULL;
+}
+
 GHashTable *
 extcap_tools_list(void) {
     if ( tools == NULL || g_hash_table_size(tools) == 0 )

extcap.h

@@ -75,6 +75,10 @@ extcap_get_if_dlts(const gchar * ifname, char ** err_str);
 GList *
 append_extcap_interface_list(GList *list, char **err_str);
 
+/* return the help page or NULL for the given ifname */
+gchar *
+extcap_get_help_for_ifname(const char *ifname);
+
 /* get a list of all available extcap tools */
 GHashTable *
 extcap_tools_list(void);

extcap_parser.c

@@ -188,6 +188,8 @@ static extcap_token_sentence *extcap_tokenize_sentence(const gchar *s) {
                 param_type = EXTCAP_PARAM_VALIDATION;
             } else if (g_ascii_strcasecmp(arg, "version") == 0) {
                 param_type = EXTCAP_PARAM_VERSION;
+            } else if (g_ascii_strcasecmp(arg, "help") == 0) {
+                param_type = EXTCAP_PARAM_HELP;
             } else {
                 param_type = EXTCAP_PARAM_UNKNOWN;
             }
@@ -550,11 +552,7 @@ static extcap_interface * extcap_parse_interface_sentence(extcap_token_sentence
     if (sent == EXTCAP_SENTENCE_UNKNOWN)
         return NULL;
 
-    ri = g_new(extcap_interface, 1);
-
-    ri->call = NULL;
-    ri->display = NULL;
-    ri->version = NULL;
+    ri = g_new0(extcap_interface, 1);
 
     ri->if_type = sent;
 
@@ -580,6 +578,11 @@ static extcap_interface * extcap_parse_interface_sentence(extcap_token_sentence
         ri->version = g_strdup(param_value);
     }
 
+    if ((param_value = (gchar *)g_hash_table_lookup(s->param_list, ENUM_KEY(EXTCAP_PARAM_HELP)))
+            != NULL) {
+        ri->help = g_strdup(param_value);
+    }
+
     return ri;
 }
 

extcap_parser.h

@@ -75,7 +75,8 @@ typedef enum {
     EXTCAP_PARAM_REQUIRED,
     EXTCAP_PARAM_SAVE,
     EXTCAP_PARAM_VALIDATION,
-    EXTCAP_PARAM_VERSION
+    EXTCAP_PARAM_VERSION,
+    EXTCAP_PARAM_HELP
 } extcap_param_type;
 
 #define ENUM_KEY(s) GUINT_TO_POINTER((guint)s)
@@ -127,15 +128,12 @@ typedef struct _extcap_arg {
     GList * values;
 } extcap_arg;
 
-typedef struct _extcap_if {
-    gchar * extcap_path;
-    GList * interfaces;
-} extcap_if;
-
 typedef struct _extcap_interface {
-    gchar *call;
-    gchar *display;
-    gchar *version;
+    gchar * call;
+    gchar * display;
+    gchar * version;
+    gchar * help;
+    gchar * extcap_path;
 
     extcap_sentence_type if_type;
 } extcap_interface;

ui/qt/extcap_options_dialog.cpp

@@ -34,6 +34,8 @@
 #include <QHBoxLayout>
 #include <QVBoxLayout>
 #include <QGridLayout>
+#include <QUrl>
+#include <QDesktopServices>
 
 #include "ringbuffer.h"
 #include "ui/capture_ui_utils.h"
@@ -304,8 +306,21 @@ void ExtcapOptionsDialog::on_buttonBox_rejected()
 
 void ExtcapOptionsDialog::on_buttonBox_helpRequested()
 {
-    // Probably the wrong URL.
-    wsApp->helpTopicAction(HELP_EXTCAP_OPTIONS_DIALOG);
+    interface_t device;
+    gchar * interface_help = NULL;
+
+    device = g_array_index(global_capture_opts.all_ifaces, interface_t, device_idx);
+    interface_help = extcap_get_help_for_ifname(device.name);
+
+    if (interface_help)
+    {
+        QUrl help_url = QString(interface_help);
+        QDesktopServices::openUrl(help_url);
+    }
+    else
+    {
+        wsApp->helpTopicAction(HELP_EXTCAP_OPTIONS_DIALOG);
+    }
 }
 
 bool ExtcapOptionsDialog::saveOptionToCaptureInfo()