Hi!
I just wrote a little guide, based on my own experiences on how to add
a new datasource and how to contribute code to the libpcap project,
because I found this information quite hard to figure out by myself.
I added a new file named HACKING, and pushed it to my github port,
axos88/libpcap.git.
Some information out there is only intuition, some come from my own
experiences, and probably there are a few stuff that are not quite as
I think they are. Even so I think it's a good start, and it's a good
idea to have something like that.
Please read it, correct it where needed, and tell me your opinions, I
think it would help a lot if it made itself into the main source tree.
Also - as not a native speaker - I'm sure there are quite a few
spelling mistakes as well.
To be easier, I attached the file below:
Regards,
Ákos Vandra
This file is intended to be a quick guide on how to contribute to the libpcap
project. It's purpose is to help people to get to know how the project is
organized, and help them to join and contribute.
Please extend this file with any information that you consider useful, or
better yet, any information that would have made it easier for you to join.
At time of writing I'm also just beginning to get a grasp of what and how,
so some information here might be trivial, but it still might be helpful
for somebody.
Version list:
2011.12.27. by Vandra Ákos - initial creation, two sections:
adding a new
data source
contributing
code
---
Adding a new data source to libpcap
---
I have addded support for the canusb device, so I'll be presenting my
workflow based on it. Please use the dates in the version list and
refer to my code during reading if needed.
Every datasource has 2 parts:
- Discovering the devices present
- Opening and capturing data from the devices
To add support for another, new device one has to add these two functionalities
and register the new code with the main libpcap sources.
Step 1.
Come up with a name for your datasource. My source's name is
"canusb"
Step 2.
Add a new header and source file to the libpcap directory,
usually named
"pcap-$NAME-$PLATFORM.c"
If your datasource is not platform-dependent, you may leave out
the
$PLATFORM part.
For me, it was "pcap-canusb-linux.c"
Step 3.
Usually all functions in these source files will be named
$NAME_XXX like
canusb_create, canusb_platform_finddevs, etc, and will be made
static,
unless they are needed somewhere in the libpcap source.
In my case only two interface functions, create and
platform_finddevs
were needed to be made non-static.
Step 4.
Add interface for device discovery.
Usually, if your datasource is platform dependent, you will add
a
fucntion named $NAME_platform_finddevs, which is responsible for
detecting any present devices, and adding them to the device
list.
It's prototype is:
int canusb_platform_finddevs(pcap_if_t **alldevsp, char
*err_str);
It should do any discovery necessary, and add each found device
with a
call to
pcap_add_if(alldevsp, dev_name, 0, dev_descr, err_str)
where dev_name is the name of the device and dev_descr is a
human-readable description of it.
if the pcap_add_if returns a negative number, your function
should bail,
free any allocated resources and return -1.
if the discovery is successful, it should return the number of
found
devices.
Step 5.
Add interface for creating a handle to your device.
Capturing from device is usually a three-step procedure:
- creating the device handle
- activating the device for reading
- doing the reading itself.
Creating the device should not do anything else but what is
absolutely
necessary to see if the device is not only present, but we have
the
necessary permissions to open it, and read from it.
As libpcap doesn't know anything about how our device works,
creating
the device is also responsible for pointing out the function
which
can do the device activation - using the pcap_t structure
