Add missing androiddump stuff

Add missing androiddump stuff like:
- release notes
- documentation
- Windows nmake support
- running androiddump as a windows application instead of console on Windows
- addition of androiddump to the Windows installer

Change-Id: I3bc6cc70e4dc96c0cd776f3d965dd2aa0309995d
Reviewed-on: https://code.wireshark.org/review/7981
Petri-Dish: Pascal Quantin <pascal.quantin@gmail.com>
Petri-Dish: Michal Labedzki <michal.labedzki@tieto.com>
Tested-by: Petri Dish Buildbot <buildbot-no-reply@wireshark.org>
Reviewed-by: Michal Labedzki <michal.labedzki@tieto.com>

4 files changed, 363 insertions, 79 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4394a6dd31..2a0b7b11e6 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -70,7 +70,8 @@ man1_MANS = \
 	@dumpcap_man@		\
 	@rawshark_man@		\
 	@dftest_man@		\
-	@randpkt_man@
+	@randpkt_man@		\
+	@androiddump_man@
 man4_MANS = @wiresharkfilter_man@
 man_MANS =
 
@@ -81,8 +82,8 @@ noinst_DATA = asn2deb.1 asn2deb.html idl2deb.1 idl2deb.html idl2wrs.1 idl2wrs.ht
 
 pkgdata_DATA = AUTHORS-SHORT $(top_srcdir)/docbook/ws.css wireshark.html \
 	tshark.html wireshark-filter.html capinfos.html editcap.html \
-	mergecap.html reordercap.html text2pcap.html dumpcap.html rawshark.html \
-	dftest.html randpkt.html
+	mergecap.html reordercap.html text2pcap.html dumpcap.html androiddump.html \
+	rawshark.html dftest.html randpkt.html
 
 #
 # Build the short version of the authors file for the about dialog
@@ -204,6 +205,13 @@ dumpcap.html: dumpcap.pod ../config.h $(top_srcdir)/docbook/ws.css
 	--noindex							\
 	$(srcdir)/dumpcap.pod > dumpcap.html
 
+androiddump.html: androiddump.pod ../config.h $(top_srcdir)/docbook/ws.css
+	$(AM_V_POD2HTML)$(POD2HTML)                     \
+	--title="androiddump - The Wireshark Network Analyzer $(VERSION)"	\
+	--css=$(POD_CSS_URL)						\
+	--noindex							\
+	$(srcdir)/androiddump.pod > androiddump.html
+
 rawshark.html: rawshark.pod ../config.h $(top_srcdir)/docbook/ws.css
 	$(AM_V_POD2HTML)$(POD2HTML)                     \
 	--title="rawshark - The Wireshark Network Analyzer $(VERSION)"	\
@@ -262,6 +270,7 @@ EXTRA_DIST =				\
 	README.wmem			\
 	README.wslua			\
 	README.xml-output		\
+	androiddump.pod			\
 	asn2deb.pod			\
 	capinfos.pod			\
 	captype.pod			\
@@ -269,6 +278,7 @@ EXTRA_DIST =				\
 	dftest.pod			\
 	dumpcap.pod			\
 	editcap.pod			\
+	extcap.pod			\
 	eproto2sgml			\
 	idl2deb.pod			\
 	idl2wrs.pod			\
diff --git a/doc/Makefile.nmake b/doc/Makefile.nmake
index 9978088d2c..dfe2710cf4 100644
--- a/doc/Makefile.nmake
+++ b/doc/Makefile.nmake
@@ -26,13 +26,13 @@ include ../config.nmake
 
 doc: wireshark.html tshark.html wireshark-filter.html capinfos.html \
 	editcap.html idl2wrs.html mergecap.html reordercap.html \
-	text2pcap.html dumpcap.html rawshark.html dftest.html randpkt.html \
-	idl2deb.html asn2deb.html
+	text2pcap.html dumpcap.html androiddump.html rawshark.html dftest.html randpkt.html \
+	idl2deb.html asn2deb.html extcap.html
 
 man: wireshark.1 tshark.1 wireshark-filter.4 capinfos.1 \
 	editcap.1 idl2wrs.1 mergecap.1 reordercap.1 \
-	text2pcap.1 dumpcap.1 rawshark.1 dftest.1 randpkt.1 \
-	idl2deb.1 asn2deb.1
+	text2pcap.1 dumpcap.1 androiddump.1 rawshark.1 dftest.1 randpkt.1 \
+	idl2deb.1 asn2deb.1 extcap.4
 
 wireshark.pod: wireshark.pod.template AUTHORS-SHORT-FORMAT
 	copy /B wireshark.pod.template + AUTHORS-SHORT-FORMAT wireshark.pod
@@ -209,6 +209,32 @@ dumpcap.html: dumpcap.pod ../config.h ws.css
 	--noindex                                 \
 	dumpcap.pod > dumpcap.html
 
+extcap.4: extcap.pod ../config.h
+	$(POD2MAN)                      \
+	--center="The Wireshark Network Analyzer" \
+	--release=$(VERSION)			 \
+	extcap.pod > extcap.1
+
+extcap.html: extcap.pod ../config.h ws.css
+	$(POD2HTML)                     \
+	--title="extcap - The Wireshark Network Analyzer $(VERSION)" \
+	--css=ws.css \
+	--noindex                                 \
+	extcap.pod > extcap.html
+
+androiddump.1: androiddump.pod ../config.h
+	$(POD2MAN)                      \
+	--center="The Wireshark Network Analyzer" \
+	--release=$(VERSION)			 \
+	androiddump.pod > androiddump.1
+
+androiddump.html: androiddump.pod ../config.h ws.css
+	$(POD2HTML)                     \
+	--title="androiddump - The Wireshark Network Analyzer $(VERSION)" \
+	--css=ws.css \
+	--noindex                                 \
+	androiddump.pod > androiddump.html
+
 rawshark.1: rawshark.pod ../config.h
 	$(POD2MAN)                      \
 	--center="The Wireshark Network Analyzer" \
diff --git a/doc/androiddump.pod b/doc/androiddump.pod
new file mode 100644
index 0000000000..c0788bb465
--- /dev/null
+++ b/doc/androiddump.pod
@@ -0,0 +1,221 @@
+
+=head1 NAME
+
+androiddump - Provide interfaces to capture from Android devices
+
+=head1 SYNOPSIS
+
+B<androiddump>
+S<[ B<--help> ]>
+S<[ B<--version> ]>
+S<[ B<--extcap-interfaces> ]>
+S<[ B<--extcap-dlts> ]>
+S<[ B<--extcap-interface>=E<lt>interfaceE<gt> ]>
+S<[ B<--extcap-config> ]>
+S<[ B<--capture> ]>
+S<[ B<--fifo>=E<lt>path to file or pipeE<gt> ]>
+S<[ B<--adb-server-ip>=E<lt>IP addressE<gt> ]>
+S<[ B<--adb-server-tcp-port>=E<lt>TCP portE<gt> ]>
+S<[ B<--logcat-text>=E<lt>TRUE or FALSEE<gt> ]>
+S<[ B<--bt-server-tcp-port>=E<lt>TCP portE<gt> ]>
+S<[ B<--bt-forward-socket>=E<lt>TRUE or FALSEE<gt> ]>
+S<[ B<--bt-local-ip>=E<lt>IP addressE<gt> ]>
+S<[ B<--bt-local-tcp-port>=E<lt>TCP portE<gt> ]>
+
+B<androiddump>
+S< B<--extcap-interfaces> >
+S<[ B<--adb-server-ip>=E<lt>IP addressE<gt> ]>
+S<[ B<--adb-server-tcp-port>=E<lt>TCP portE<gt> ]>
+
+B<androiddump>
+S< B<--extcap-interface>=E<lt>interfaceE<gt> >
+S<[ B<--extcap-dlts> ]>
+
+B<androiddump>
+S< B<--extcap-interface>=E<lt>interfaceE<gt> >
+S<[ B<--extcap-config> ]>
+
+B<androiddump>
+S< B<--extcap-interface>=E<lt>interfaceE<gt> >
+S< B<--fifo>=E<lt>path to file or pipeE<gt> >
+S< B<--capture> >
+
+=head1 DESCRIPTION
+
+B<Androiddump> is a extcap tool that provide interfaces to capture from
+Android device. There is only two requirements:
+
+1. You must have Android SDK and add it PATH environment variable.
+PATH should contain directory with tools like "adb" and "android".
+Android SDK for various platform are available on:
+https://developer.android.com/sdk/index.html#Other
+
+2. You must have permission to Android devices.
+
+
+Supported interfaces:
+
+=over 4
+
+=item 1. Logcat Main (binary or text)
+
+=item 2. Logcat System (binary or text)
+
+=item 3. Logcat Events (binary or text)
+
+=item 4. Logcat Radio (binary or text)
+
+=item 5. Logcat Crash (text; Lollipop)
+
+=item 6. Bluetooth Hcidump (<Kitkat)
+
+=item 7. Bluetooth Bluedroid External Parser (Kitkat)
+
+=item 8. Bluetooth BtsnoopNet (Lollipop)
+
+=back
+
+Please note that it will work also for FirefoxOS.
+
+NOTE: If one of device require ADB Authentication you need accept or reject that
+request. Otherwise no devices will be available.
+
+=head1 OPTIONS
+
+=over 4
+
+=item --help
+
+Print program arguments.
+
+=item --version
+
+Print program version.
+
+=item --extcap-interfaces
+
+List available interfaces.
+
+=item --extcap-interface=E<lt>interfaceE<gt>
+
+Use specified interfaces.
+
+=item --extcap-dlts
+
+List DLTs of specified interface.
+
+=item --extcap-config
+
+List configuration options of specified interface.
+
+=item --capture
+
+Start capturing from specified interface save saved it in place specified by --fifo.
+
+=item --fifo=E<lt>path to file or pipeE<gt>
+
+Save captured packet to file or send it through pipe.
+
+=item --adb-server-ip=E<lt>IP addressE<gt>
+
+Use other then default (127.0.0.1) ADB daemon's IP address.
+
+=item --adb-server-tcp-port=E<lt>TCP portE<gt>
+
+Use other then default (5037) ADB daemon's TCP port.
+
+=item --logcat-text=E<lt>TRUE or FALSEE<gt>
+
+If TRUE then use text logcat rather then binary. This option has effect only on
+Logcat interfaces. This have no effect from Lollipop where is no binary Logcat
+available.
+
+Defaults to FALSE.
+
+=item --bt-server-tcp-port=E<lt>TCP portE<gt>
+
+Use other then default Bluetooth server TCP port on Android side.
+On Lollipop defaults is 8872, earlier 4330.
+
+=item --bt-forward-socket=E<lt>TRUE or FALSEE<gt>
+
+If TRUE then socket from Android side is forwarded to host side.
+
+Defaults to FALSE.
+
+=item --bt-local-ip=E<lt>IP addressE<gt>
+
+Use other then default (127.0.0.1) IP address on host side for forwarded socket.
+
+=item --bt-local-tcp-port=E<lt>TCP portE<gt>
+
+Specify port to be used on host side for forwarded socket.
+
+=back
+
+=head1 EXAMPLES
+
+To see program arguments:
+
+    androiddump --help
+
+To see program version:
+
+    androiddump --version
+
+To see interfaces:
+
+    androiddump --extcap-interfaces
+
+  Example output:
+    interface {display=Android Logcat Main}{value=android-logcat-main-MSM7627A}
+    interface {display=Android Logcat System}{value=android-logcat-system-MSM7627A}
+    interface {display=Android Logcat Radio}{value=android-logcat-radio-MSM7627A}
+    interface {display=Android Logcat Events}{value=android-logcat-events-MSM7627A}
+    interface {display=Android Bluetooth Hcidump}{value=android-bluetooth-hcidump-MSM7627A}
+
+To see interface DLTs:
+
+    androiddump --extcap-interface=android-bluetooth-hcidump-MSM7627A --extcap-dlts
+
+  Example output:
+    dlt {number=99}{name=BluetoothH4}{display=Bluetooth HCI UART transport layer plus pseudo-header}
+
+
+To see interface configuration options:
+
+    androiddump --extcap-interface=android-bluetooth-hcidump-MSM7627A --extcap-dlts
+
+  Example output:
+    arg {number=0}{call=--adb-server-ip}{display=ADB Server IP Address}{type=string}{default=127.0.0.1}
+    arg {number=1}{call=--adb-server-tcp-port}{display=ADB Server TCP Port}{type=integer}{range=0,65535}{default=5037}
+
+
+To capture:
+
+    androiddump --extcap-interface=android-bluetooth-hcidump-MSM7627A --fifo=/tmp/bluetooth.pcapng --capture
+
+NOTE: To stop capturing CTRL+C/kill/terminate application.
+
+=head1 SEE ALSO
+
+wireshark(1), tshark(1), dumpcap(1), extcap(4)
+
+=head1 NOTES
+
+B<Androiddump> is part of the B<Wireshark> distribution.  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>.
+
+=head1 AUTHORS
+
+  Original Author
+  -------- ------
+  Michal Labedzki             <michal.labedzki[AT]tieto.com>
+
+
+  Contributors
+  ------------
+  Roland Knall              <rknall[AT]gmail.com>
diff --git a/doc/extcap.pod b/doc/extcap.pod
index c6cc9bb1bc..d450088165 100644
--- a/doc/extcap.pod
+++ b/doc/extcap.pod
@@ -3,76 +3,103 @@
 
 extcap - Extcap grammar elements
 
-=head1 SYNOPSIS
-
-Suggested config grammar elements:
-arg (options)       argument for CLI calling
-number  Reference # of argument for other values, display order
-call        Literal argument to call (--call=...)
-display     Displayed name
-default     Default value, in proper form for type
-range       Range of valid values for UI checking (min,max) in proper form
-type        Argument type for UI filtering for raw, or UI type for selector:
-        integer
-        unsigned
-        long (may include scientific / special notation)
-float
-menu (display popup menu in UI)
-selector (display selector table, all values as strings)
-boolean (display checkbox)
-radio (display group of radio buttons with provided values, all values as strings)
-
-value (options) Values for argument selection
+=head1 DESCRIPTION
+
+Grammar elements:
+
+=over 4
+
+=item arg (options)
+
+argument for CLI calling
+
+=item number
+
+Reference # of argument for other values, display order
+
+=item call
+
+Literal argument to call (--call=...)
+
+=item display
+
+Displayed name
+
+=item default
+
+Default value, in proper form for type
+
+=item range
+
+Range of valid values for UI checking (min,max) in proper form
+
+=item type
+
+Argument type for UI filtering for raw, or UI type for selector:
+
+    integer
+    unsigned
+    long (may include scientific / special notation)
+    float
+    selector (display selector table, all values as strings)
+    boolean (display checkbox)
+    radio (display group of radio buttons with provided values, all values as strings)
+
+=item value (options)
+
+    Values for argument selection
     arg     Argument # this value applies to
-value       Passed value
-display     Displayed value
-default     Boolean (true if default, all others ignored, ie default=true)
-
-flag (options)      external-capture level flags
-    dedicated   Bypass dumpcap & mux for high speed
-    failure     Failure message
-
-
-Possible grammar example:
-
-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}
-value {arg=0}{range=1,11}
-value {arg=1}{value=ht40p}{display=HT40+}
-value {arg=1}{value=ht40m}{display=HT40-}
-value {arg=1}{value=ht20}{display=HT20}
-value {arg=2}{value=wlan0}{display=wlan0}
-
-Example 2
-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}
-flag {failure=Permission denied opening Ubertooth device}
-
-
-Security awareness:
-
-- Users running wireshark as root, we can’t save you
-- Dumpcap retains suid/setgid and group+x permissions to allow users in wireshark group only
-- Third-party capture programs run w/ whatever privs they’re installed with
-- If an attacker can write to a system binary directory, we’re game over anyhow
-- Don’t let wireshark be told to look for capture binaries somewhere else?
-
-Notes:
-- daemonized dumpcap?
-- multiuser?
-- sync_pipe.h commands
-- expand pipe commands to have status notifications, etc?
-- Wireshark->dumpcap options for channel control, etc?
-
-TODO
-define grammar
-write grammar to HTML mockup
-sketch interface with dumpcap
-launch external-pcap from wireshark, bypass dumpcap
-launch external-pcap from wireshark, hand fd to dumpcap
-extract netif capture as first cap source
\ No newline at end of file
+
+=back
+
+=head1 EXAMPLES
+
+Exampl 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}
+    value {arg=0}{range=1,11}
+    value {arg=1}{value=ht40p}{display=HT40+}
+    value {arg=1}{value=ht40m}{display=HT40-}
+    value {arg=1}{value=ht20}{display=HT20}
+    value {arg=2}{value=wlan0}{display=wlan0}
+
+Example 2:
+
+    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}
+    flag {failure=Permission denied opening Ubertooth device}
+
+=head1 Security awareness
+
+=over 4
+
+=item - Users running wireshark as root, we can't save you
+
+=item - Dumpcap retains suid/setgid and group+x permissions to allow users in wireshark group only
+
+=item - Third-party capture programs run w/ whatever privs they're installed with
+
+=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?
+
+=back
+
+=head1 SEE ALSO
+
+wireshark(1), tshark(1), dumpcap(1), androiddump(1)
+
+=head1 NOTES
+
+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