Hi Stig,
First, I have to admit that I'm not really aware of the details of the defined LUA API. But as a rule of thumb, I tried to be close as possible to what exists in the C API (not LUA).
Here is an informal description of what rules I tried to follow to create this API :
1) create objects as close as possible to the ones known in libwireshark
There are three "obvious" objects until now : Dissector, Tree, TVB.
2) method name of each object as close as possible as the ones defined in libwireshark. I however modify the name because as C is not object, most of the time, a function includes in its name the conceptual "object" name related to it. This way, it avoids redundance in python API. For example : "proto_tree_add_item" is one method of the "tree" object in the C API. in the python API, the Tree class defines a "add_item" method. With the same idea for "tvb_get_ntohl", the method is defined in the TVB class with the name "get_ntohl".
3) formal parameters of functions :
a) first parameter is in general the "C object" and it does not make any sense to include it for the method defined in a python object. (in fact, in python it appears in the definition and "disappears" when called)
b) it might happen that some other parameters are always defined in the formal parameters of the C API but are not manipulated by the user and might be included automatically by the python API. For these ones, they also disappear from the formal parameters list of the python API.
c) if the parameter takes most of the time one value but sometimes can take another value, it is defined as an optional parameter.
d) if the parameter is totally or partially managed by the python API, it is defined as an optional parameter.
a good example is Tree.add_item(self, field, offset=0, length=-1, little_endian=False, adv=True)
the C API counterpart is : proto_tree_add_item(proto_tree, hfindex, tvb, start, length, little_endian)
- As of rule a), proto_tree is in fact the Tree object => disappear from the formal parameter list
- As of rule b), tvb is not directly manipulated by the user and therefore disappear from the formal parameter list
- As of rule c), little_endian has two possible value False or True. It becomes an optional parameter with the default value set to False.
- As of rule d), "offset" is totally managed by the API with the help of the last *added* parameter which indicates whether offset should be incremented or not. This last parameter is itself an optional parameter with a value of True ("offset" is incremented by "length"). Though, offset is totally managed by the python API, it is possible to increment manually the offset.
There is already two notable exceptions to what I described here above. There exists two others objects (register_info and Subtrees). It is likely that in the future this list of objects will increase because they've initially have been created because of a "ctypes" (python module) limitation.
At the end, they almost serve only as a special dictionary of elements.
For these objects, I used a so interesting feature of python, definition of dynamic attributes.You have a first step in which you add items in this "dictionary" (hf_register_info fields and trees). When you have to refer to one of these while dissecting, you can refer to them as if they were attributes of the related object.
For example, let's say "hf" is a register_info object, you can add something to it by doing :
hf.add("Imaginary Protocol Length", "imaginary.length", FT_UINT8) => Not that you have a lot of optional parameters in here!
and you can refer to this field while dissecting with
hf.imaginary_length
the name of the attribute is the second parameter passed with every '.' changed to '_'
That's all for now .. I'll add this mail to the wiki documentation.
Of course, I'll enjoy any comments (from you or anyone else) to improve the python API whatever it be following the LUA API or not. :)
Regards,
Sebastien Tandel
2009/5/31 Stig Bjørlykke
<stig.bjorlykke@xxxxxxxxx>
Hi,
Do you use the same naming scheme in the Python bindings as we use in
Lua?
I think we should have the same names for equal functionality in both
Python and Lua.
--
Stig Bjørlykke
