Wireshark Developer’s Guide
���Next

Wireshark Developer’s Guide

For Wireshark 2.5

Ulf Lamping

Luis E. Ontanon

Graham Bloice

Copyright � 2004-2014 Ulf Lamping, Luis E. Garcia Ontanon, Graham Bloice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation.

All logos and trademarks in this document are property of their respective owners.

Revision History
Revision 1.128 Dec 2014gb
Updated for 1.99.x and 2.0, move to VS2013.
Revision 1.02 Nov 2014gcc
Moved Lua reference from User's Guide to Developer's Guide.
Revision 0.99 Feb 2014gcc
Converted from DocBook to AsciiDoc.
Revision 0.521 Jan 2007ul
Major redesign.
Revision 0.117 Aug 2004ul
Initial version.

Table of Contents

Preface
1. Foreword
2. Who should read this document?
3. Acknowledgements
4. About this document
5. Where to get the latest copy of this document?
6. Providing feedback about this document
7. Typographic Conventions
7.1. Admonitions
7.2. Shell Prompt and Source Code Examples
I. Wireshark Build Environment
1. Introduction
1.1. Introduction
1.2. What is Wireshark?
1.3. Supported Platforms
1.3.1. Unix
1.3.2. Linux
1.3.3. Microsoft Windows
1.4. Development and maintenance of Wireshark
1.4.1. Programming languages used
1.4.2. Open Source Software
1.5. Releases and distributions
1.5.1. Binary distributions
1.5.2. Source code distributions
1.6. Automated Builds (Buildbot)
1.6.1. Advantages
1.6.2. What does the Buildbot do?
1.7. Reporting problems and getting help
1.7.1. Website
1.7.2. Wiki
1.7.3. FAQ
1.7.4. Other sources
1.7.5. Mailing Lists
1.7.6. Bug database (Bugzilla)
1.7.7. Q&A Site
1.7.8. Reporting Problems
1.7.9. Reporting Crashes on UNIX/Linux platforms
1.7.10. Reporting Crashes on Windows platforms
2. Quick Setup
2.1. UNIX: Installation
2.2. Win32/64: Step-by-Step Guide
2.2.1. Optional: Install Chocolatey
2.2.2. Install Microsoft C compiler and SDK
2.2.3. Install Qt
2.2.4. Install Cygwin
2.2.5. Install Python
2.2.6. Install Git
2.2.7. Install CMake
2.2.8. Install and Prepare Sources
2.2.9. Open a Visual Studio Command Prompt
2.2.10. Generate the build files
2.2.11. Build Wireshark
2.2.12. Debug Environment Setup
2.2.13. Optional: Create User’s and Developer’s Guide
2.2.14. Optional: Create a Wireshark Installer
3. Work with the Wireshark sources
3.1. Introduction
3.2. The Wireshark Git repository
3.2.1. The web interface to the Git repository
3.3. Obtain the Wireshark sources
3.3.1. Git over SSH or HTTPS
3.3.2. Git web interface
3.3.3. Buildbot Snapshots
3.3.4. Released sources
3.4. Update the Wireshark sources
3.4.1. Update Using Git
3.4.2. Update Using Source Archives
3.5. Build Wireshark
3.5.1. Building on Unix
3.5.2. Win32 native
3.6. Run generated Wireshark
3.6.1. Unix/Linux
3.6.2. Win32 native
3.7. Debug your generated Wireshark
3.7.1. Unix/Linux
3.7.2. Win32 native
3.8. Make changes to the Wireshark sources
3.9. Contribute your changes
3.9.1. Some tips for a good patch
3.9.2. Code Requirements
3.9.3. Uploading your changes
3.9.4. Backporting a change
3.10. Apply a patch from someone else
3.10.1. Using patch
3.11. Binary packaging
3.11.1. Debian: .deb packages
3.11.2. Red Hat: .rpm packages
3.11.3. macOS: .dmg packages
3.11.4. Win32: NSIS .exe installer
3.11.5. Win32: PortableApps .paf.exe package
4. Tool Reference
4.1. Introduction
4.2. Chocolatey
4.3. Windows: Cygwin
4.3.1. Installing Cygwin using the Cygwin installer
4.3.2. Add/Update/Remove Cygwin Packages
4.3.3. Installing Cygwin using Chocolatey
4.4. GNU compiler toolchain (UNIX only)
4.4.1. gcc (GNU compiler collection)
4.4.2. gdb (GNU project debugger)
4.4.3. ddd (GNU Data Display Debugger)
4.4.4. make (GNU Make)
4.5. Microsoft compiler toolchain (Windows native)
4.5.1. Official Toolchain Packages And Alternatives
4.5.2. cl.exe (C Compiler)
4.5.3. link.exe (Linker)
4.5.4. C-Runtime "Redistributable" Files
4.5.5. Windows (Platform) SDK
4.5.6. HTML Help
4.5.7. Debugger
4.6. bash
4.6.1. UNIX and Cygwin: GNU bash
4.7. Python
4.8. Perl
4.8.1. UNIX and Cygwin: Perl
4.9. Bison
4.9.1. UNIX or Cygwin: bison
4.9.2. Windows Native: Win flex-bison and bison
4.10. Flex
4.10.1. UNIX or Cygwin: flex
4.10.2. Windows Native: Win flex-bison and flex
4.11. Git client
4.11.1. UNIX or Cygwin: git
4.11.2. Windows native: git
4.12. Git Powershell Extensions (optional)
4.13. Git GUI client (optional)
4.14. patch (optional)
4.14.1. UNIX and Cygwin: patch
4.14.2. Windows native: patch
4.15. Windows: NSIS (optional)
4.16. Windows: PortableApps (optional)
5. Library Reference
5.1. Introduction
5.2. Binary library formats
5.2.1. Unix
5.2.2. Win32: MSVC
5.2.3. Win32: cygwin gcc
5.3. Win32: Automated library download
5.4. Qt
5.4.1. Unix
5.4.2. Win32 MSVC
5.5. GTK+ / GLib / GDK / Pango / ATK / GNU gettext / GNU libiconv
5.5.1. Unix
5.5.2. Win32 MSVC
5.6. SMI (optional)
5.6.1. Unix
5.6.2. Win32 MSVC
5.7. c-ares (optional)
5.7.1. Unix
5.7.2. Win32 MSVC
5.8. zlib (optional)
5.8.1. Unix
5.8.2. Win32 MSVC
5.9. libpcap/WinPcap (optional)
5.9.1. Unix: libpcap
5.9.2. Win32 MSVC: WinPcap
5.10. GnuTLS (optional)
5.10.1. Unix
5.10.2. Win32 MSVC
5.11. Gcrypt
5.11.1. Unix
5.11.2. Win32 MSVC
5.12. Kerberos (optional)
5.12.1. Unix
5.12.2. Win32 MSVC
5.13. LUA (optional)
5.13.1. Unix
5.13.2. Win32 MSVC
5.14. PortAudio (optional)
5.14.1. Unix
5.14.2. Win32 MSVC
5.15. GeoIP (optional)
5.15.1. Unix
5.15.2. Win32 MSVC
5.16. WinSparkle (optional)
5.16.1. Win32 MSVC
II. Wireshark Development
6. How Wireshark Works
6.1. Introduction
6.2. Overview
6.3. Capturing packets
6.4. Capture Files
6.5. Dissect packets
7. Introduction
7.1. Source overview
7.2. Coding Style
7.3. The GLib library
8. Packet capturing
8.1. How to add a new capture type to libpcap
9. Packet dissection
9.1. How it works
9.2. Adding a basic dissector
9.2.1. Setting up the dissector
9.2.2. Dissecting the details of the protocol
9.2.3. Improving the dissection information
9.3. How to handle transformed data
9.4. How to reassemble split packets
9.4.1. How to reassemble split UDP packets
9.4.2. How to reassemble split TCP Packets
9.5. How to tap protocols
9.6. How to produce protocol stats
9.7. How to use conversations
9.8. idl2wrs: Creating dissectors from CORBA IDL files
9.8.1. What is it?
9.8.2. Why do this?
9.8.3. How to use idl2wrs
9.8.4. TODO
9.8.5. Limitations
9.8.6. Notes
10. Lua Support in Wireshark
10.1. Introduction
10.2. Example of Dissector written in Lua
10.3. Example of Listener written in Lua
11. Wireshark’s Lua API Reference Manual
11.1. Saving capture files
11.1.1. Dumper
11.1.2. PseudoHeader
11.2. Obtaining dissection data
11.2.1. Field
11.2.2. FieldInfo
11.2.3. Global Functions
11.3. GUI support
11.3.1. ProgDlg
11.3.2. TextWindow
11.3.3. Global Functions
11.4. Post-dissection packet analysis
11.4.1. Listener
11.5. Obtaining packet information
11.5.1. Address
11.5.2. Column
11.5.3. Columns
11.5.4. NSTime
11.5.5. Pinfo
11.5.6. PrivateTable
11.6. Functions for new protocols and dissectors
11.6.1. Dissector
11.6.2. DissectorTable
11.6.3. Pref
11.6.4. Prefs
11.6.5. Proto
11.6.6. ProtoExpert
11.6.7. ProtoField
11.6.8. Global Functions
11.7. Adding information to the dissection tree
11.7.1. TreeItem
11.8. Functions for handling packet data
11.8.1. ByteArray
11.8.2. Tvb
11.8.3. TvbRange
11.9. Custom file format reading/writing
11.9.1. CaptureInfo
11.9.2. CaptureInfoConst
11.9.3. File
11.9.4. FileHandler
11.9.5. FrameInfo
11.9.6. FrameInfoConst
11.9.7. Global Functions
11.10. Directory handling functions
11.10.1. Dir
11.11. Utility Functions
11.11.1. Global Functions
11.12. Handling 64-bit Integers
11.12.1. Int64
11.12.2. UInt64
11.13. Binary encode/decode support
11.13.1. Struct
11.14. GLib Regular Expressions
11.14.1. GRegex
12. User Interface
12.1. Introduction
12.2. The Qt Application Framework
12.2.1. User Experience Considerations
12.2.2. Qt Creator
12.2.3. Source Code Overview
12.2.4. Coding Practices and Naming Conventions
12.2.5. Other Issues and Information
12.3. The GTK library
12.3.1. GTK Version 2.x
12.3.2. GTK Version 3.x
12.3.3. Compatibility GTK versions
12.3.4. GTK resources on the web
12.4. Human Interface Reference Documents
12.5. Adding/Extending Dialogs
12.6. Widget naming
12.7. Common GTK programming pitfalls
12.7.1. Usage of gtk_widget_show() / gtk_widget_show_all()
13. This Document’s License (GPL)

List of Figures

6.1. Wireshark function blocks

List of Tables

1. Typographic Conventions

List of Examples

9.1. Dissector Initialisation.
9.2. Dissector Handoff.
9.3. Dissection.
9.4. Plugin Packet Dissection.
9.5. Registering data structures.
9.6. Dissector data structure globals.
9.7. Dissector starting to dissect the packets.
9.8. Wrapping up the packet dissection.
9.9. Naming the packet types.
9.10. Adding Names to the protocol.
9.11. Adding Flags to the protocol.
9.12. Enhancing the display.
9.13. Decompressing data packets for dissection.
9.14. Reassembling fragments - Part 1
9.15. Reassembling fragments part 2
9.16. Reassembling fragments - Initialisation
9.17. Reassembling fragments - Data
9.18. Reassembling TCP fragments
9.19. Initialising a tap
9.20. Calling a protocol tap
9.21. Initialising a stats interface
9.22. Initialising a stats session
9.23. Generating the stats
���Next
���Preface