From b099ece66f5e6d4ccd725f4b40a62828e4e9ca62 Mon Sep 17 00:00:00 2001 From: standel Date: Sat, 30 May 2009 13:37:02 +0000 Subject: python binding update : * adding pydoc documentation to doc/README.python * possible to access directly libwireshark via libhandle and raw_ * transform some methods into properties * update sample to reflect changes/features * adding comments!!! git-svn-id: http://anonsvn.wireshark.org/wireshark/trunk@28532 f5534014-38df-0310-8fa8-9805f1628bb7 --- AUTHORS | 3 + doc/README.python | 299 +++++++++++++++++++++++ epan/wspython/wspy_dissector.py | 103 ++++++-- epan/wspython/wspy_dissectors/homeplug.py.sample | 10 +- 4 files changed, 384 insertions(+), 31 deletions(-) create mode 100644 doc/README.python diff --git a/AUTHORS b/AUTHORS index 6fd75d4668..5ff2bb3dd5 100644 --- a/AUTHORS +++ b/AUTHORS @@ -2595,6 +2595,9 @@ Davide Schiera { } Sebastien Tandel { + embedding python in *shark + subtrees management for ptvcursor + gcc warning hunter Homeplug support } diff --git a/doc/README.python b/doc/README.python new file mode 100644 index 0000000000..0d6cb8a901 --- /dev/null +++ b/doc/README.python @@ -0,0 +1,299 @@ +Help on module wspy_dissector: + +NAME + wspy_dissector + +FILE + /Users/standel/xcode/wireshark/wireshark.git/epan/wspython/wspy_dissector.py + +DESCRIPTION + # wspy_dissector.py + # + # $Id: $ + # + # Wireshark Protocol Python Binding + # + # Copyright (c) 2009 by Sebastien Tandel + # Copyright (c) 2001 by Gerald Combs + # + # This program is free software; you can redistribute it and/or + # modify it under the terms of the GNU General Public License + # as published by the Free Software Foundation; either version 2 + # of the License, or (at your option) any later version. + # + # This program is distributed in the hope that it will be useful, + # but WITHOUT ANY WARRANTY; without even the implied warranty of + # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + # GNU General Public License for more details. + # + # You should have received a copy of the GNU General Public License + # along with this program; if not, write to the Free Software + # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +CLASSES + __builtin__.object + Dissector + Subtree + TVB + Tree + register_info + + class Dissector(__builtin__.object) + | #Dissector class : base class to write a dissector in python + | + | Methods defined here: + | + | __hash__(self) + | + | __init__(self, protocol_name, short_desc, short) + | + | __str__(self) + | + | __unicode__(self) + | + | advance(self, step) + | method used to change the value of the offset + | + | create_dissector_handle(self, protocol=None) + | create_dissector_handle : see proto.h + | + | display(self) + | + | dissect(self) + | point of entry when starting dissecting a packet. This method must be + | therefore overloaded by the object implementing the dissector of a specific + | protocol. + | + | find_dissector(self, protocol) + | find_dissector : see proto.h + | + | pre_dissect(self) + | private method executed right before dissect in order to retrieve some + | internal information and enabling the possibility to add the base tree of + | this protocol dissection to the tree without any user intervention + | + | protocol(self) + | + | protocol_ids(self) + | defined a list of tuples containing three values. Each tuple is defining + | the parameters of dissector_add(). This function MUST be defined when + | implementing the dissector of a specific protocol. + | + | register_handoff(self) + | private method used during the registration of protocol dissectors + | + | register_protocol(self) + | private function called by libwireshark when registering all + | protocols + | + | ---------------------------------------------------------------------- + | Data descriptors defined here: + | + | __dict__ + | dictionary for instance variables (if defined) + | + | __weakref__ + | list of weak references to the object (if defined) + | + | hf + | hf property : hf_register_info fields. every defined field is available + | as an attribute of this object + | + | libhandle + | libhandle property : return a handle to the libwireshark lib. You don't + | want to use this in normal situation. Use it only if you know what you're + | doing. + | + | offset + | offset property : if is the current offset computed from the + | dissection. + | + | raw_pinfo + | raw_pinfo property : return the raw pinfo pointer. You can use this with + | libhandle. You don't want to use this in normal situation. Use it only if + | you know what you're doing. + | + | raw_tree + | raw_tree property : returns the raw tree pointer. You can use this with + | libhandle. You don't want to use this in normal situation. Use it only if + | you know what you're doing. + | + | raw_tvb + | raw_tvb property : returns the raw tvb pointer. You can use this with + | libhandle. You don't want to use this in normal situation. Use it only if + | you know what you're doing. + | + | subtrees + | subtrees property : subtress definition. every subtree added is + | accessible as an attribute of this object + | + | tree + | tree property : initial tree at the start of the dissection + + class Subtree(__builtin__.object) + | #Subtrees definition + | #Every subtree added can be accesses as an attribute after having been + | #registered + | + | Methods defined here: + | + | __getattr__(self, name) + | + | __init__(self, wsl, protocol) + | + | add(self, name) + | + | has_user_defined_protocol_tree(self) + | + | register(self) + | + | ---------------------------------------------------------------------- + | Data descriptors defined here: + | + | __dict__ + | dictionary for instance variables (if defined) + | + | __weakref__ + | list of weak references to the object (if defined) + + class TVB(__builtin__.object) + | #tvb class implementation + | #see proto.h + | + | Methods defined here: + | + | __init__(self, wsl, tvb, dissector) + | + | get_guint8(self, offset=-1) + | + | get_letohl(self, offset=-1) + | + | get_letohs(self, offset=-1) + | + | get_ntohl(self, offset=-1) + | + | get_ntohs(self, offset=-1) + | + | get_ptr(self, offset=-1) + | #STA TODO : check that we can do that + | + | length(self) + | + | length_remaining(self, offset=-1) + | + | reported_length(self) + | + | reported_length_remaining(self, offset=-1) + | + | ---------------------------------------------------------------------- + | Data descriptors defined here: + | + | __dict__ + | dictionary for instance variables (if defined) + | + | __weakref__ + | list of weak references to the object (if defined) + + class Tree(__builtin__.object) + | #Tree class implementation + | #see proto.h + | + | Methods defined here: + | + | __init__(self, tree, dissector) + | + | add_item(self, field, offset=0, length=-1, little_endian=False, adv=True) + | add an item to the tree + | + | add_subtree(self, subtree) + | add a subtree to the tree + | + | add_text(self, string, offset=0, length=-1, adv=True) + | add text to the tree + | + | add_uint(self, field, value, offset=0, length=4, adv=True) + | add unsigned integer to the tree + | + | ---------------------------------------------------------------------- + | Data descriptors defined here: + | + | __dict__ + | dictionary for instance variables (if defined) + | + | __weakref__ + | list of weak references to the object (if defined) + | + | raw_tree + + class register_info(__builtin__.object) + | # hf_register_info from usual dissectors + | + | Methods defined here: + | + | __del__(self) + | + | __init__(self, wsl) + | + | add(self, name, short_desc, type=6, display=1, strings=None, bitmask=0, desc=None) + | + | display(self) + | + | get(self) + | + | register(self, protocol) + | + | ---------------------------------------------------------------------- + | Data descriptors defined here: + | + | __dict__ + | dictionary for instance variables (if defined) + | + | __weakref__ + | list of weak references to the object (if defined) + +FUNCTIONS + POINTER(...) + + pointer(...) + +DATA + BASE_CUSTOM = 6 + BASE_DEC = 1 + BASE_DEC_HEX = 4 + BASE_HEX = 2 + BASE_HEX_DEC = 5 + BASE_NONE = 0 + BASE_OCT = 3 + FT_ABSOLUTE_TIME = 15 + FT_BOOLEAN = 2 + FT_BYTES = 22 + FT_DOUBLE = 14 + FT_EBCDIC = 19 + FT_ETHER = 21 + FT_FLOAT = 13 + FT_FRAMENUM = 27 + FT_GUID = 29 + FT_INT16 = 9 + FT_INT24 = 10 + FT_INT32 = 11 + FT_INT64 = 12 + FT_INT8 = 8 + FT_IPXNET = 26 + FT_IPv4 = 24 + FT_IPv6 = 25 + FT_NONE = 0 + FT_OID = 30 + FT_PCRE = 28 + FT_PROTOCOL = 1 + FT_RELATIVE_TIME = 16 + FT_STRING = 17 + FT_STRINGZ = 18 + FT_UINT16 = 4 + FT_UINT24 = 5 + FT_UINT32 = 6 + FT_UINT64 = 7 + FT_UINT8 = 3 + FT_UINT_BYTES = 23 + FT_UINT_STRING = 20 + + diff --git a/epan/wspython/wspy_dissector.py b/epan/wspython/wspy_dissector.py index e44f529cfe..31ed0c83ba 100644 --- a/epan/wspython/wspy_dissector.py +++ b/epan/wspython/wspy_dissector.py @@ -174,24 +174,60 @@ class Dissector(object): self.__hf = None self.__subtree = None - def fields(self): + def _fields(self): + '''hf property : hf_register_info fields. every defined field is available + as an attribute of this object''' if not self.__hf: self.__hf = register_info(self.__wsl) return self.__hf + hf = property(_fields) - def subtrees(self): + def _subtrees(self): + '''subtrees property : subtress definition. every subtree added is + accessible as an attribute of this object''' if not self.__subtree: self.__subtree = Subtree(self.__wsl, self.__short) return self.__subtree + subtrees = property(_subtrees) - def tree(self): + def _tree(self): + '''tree property : initial tree at the start of the dissection''' if not self.__Tree: self.__Tree = Tree(self.__tree, self) return self.__Tree + tree = property(_tree) def display(self): print self.__short + def _libhandle(self): + '''libhandle property : return a handle to the libwireshark lib. You don't + want to use this in normal situation. Use it only if you know what you're + doing.''' + return self.__wsl + libhandle = property(_libhandle) + + def _raw_tree(self): + '''raw_tree property : returns the raw tree pointer. You can use this with + libhandle. You don't want to use this in normal situation. Use it only if + you know what you're doing.''' + return self.__tree + raw_tree = property(_raw_tree) + + def _raw_pinfo(self): + '''raw_pinfo property : return the raw pinfo pointer. You can use this with + libhandle. You don't want to use this in normal situation. Use it only if + you know what you're doing.''' + return self.__pinfo + raw_pinfo = property(_raw_pinfo) + + def _raw_tvb(self): + '''raw_tvb property : returns the raw tvb pointer. You can use this with + libhandle. You don't want to use this in normal situation. Use it only if + you know what you're doing.''' + return self.__tvb + raw_tvb = property(_raw_tvb) + def __str__(self): # STA TODO : keep with short_desc because used in the hash table of # dissectors in C code. If it is modified, it won't work anymore @@ -207,6 +243,8 @@ class Dissector(object): return self.__protocol def register_protocol(self): + '''private function called by libwireshark when registering all + protocols''' self.__protocol = \ self.__wsl.proto_register_protocol( \ self.__protocol_name, self.__short_desc, \ @@ -216,37 +254,48 @@ class Dissector(object): self.__subtree.register() def dissect(self): + '''point of entry when starting dissecting a packet. This method must be + therefore overloaded by the object implementing the dissector of a specific + protocol.''' pass def pre_dissect(self): + '''private method executed right before dissect in order to retrieve some + internal information and enabling the possibility to add the base tree of + this protocol dissection to the tree without any user intervention''' self.__tvb = self.__wsl.py_tvbuff() self.__pinfo = self.__wsl.py_pinfo() self.__tree = self.__wsl.py_tree() #self.__wsl.print_current_proto(py_object(pinfo)) - subt = self.subtrees() + subt = self.subtrees try: if not subt.has_user_defined_protocol_tree(): - tree = self.tree() - p_tree = tree.add_item(self.protocol()) + p_tree = self.tree.add_item(self.protocol()) self.__Tree = p_tree.add_subtree(subt.homeplug) except: print e self.dissect() def protocol_ids(self): + '''defined a list of tuples containing three values. Each tuple is defining + the parameters of dissector_add(). This function MUST be defined when + implementing the dissector of a specific protocol.''' return [ (None, 0, None) ] def create_dissector_handle(self, protocol=None): + '''create_dissector_handle : see proto.h''' gdissector = self.__wsl.py_generic_dissector() if not protocol: protocol = self.__protocol return self.__wsl.create_dissector_handle(gdissector, protocol) def find_dissector(self, protocol): + '''find_dissector : see proto.h''' return self.__wsl.find_dissector(protocol) def register_handoff(self): + '''private method used during the registration of protocol dissectors''' #TODO STA : think how we would use dissector_add in an easy way *and* with #the possibility to add the same dissector for TCP and UDP (extend #py_generic_dissector) @@ -268,16 +317,14 @@ class Dissector(object): raise def advance(self, step): + '''method used to change the value of the offset''' self.__offset += step - def offset(self): + def _offset(self): + '''offset property : if is the current offset computed from the + dissection.''' return self.__offset - - def _wsl(self): - return self.__wsl - - def _tvb(self): - return self.__tvb + offset = property(_offset) #Tree class implementation #see proto.h @@ -285,14 +332,18 @@ class Tree(object): def __init__(self, tree, dissector): self.__dissector = dissector self.__tree = tree - self.__wsl = dissector._wsl() - self.__tvb = dissector._tvb() + self.__wsl = dissector.libhandle + self.__tvb = dissector.raw_tvb + + def _raw_tree(self): + return self.__tree + raw_tree = property(_raw_tree) def add_item(self, field, offset=0, length=-1, little_endian=False, adv=True): '''add an item to the tree''' try: tree = self.__wsl.proto_tree_add_item(self.__tree, \ - field, self.__tvb, self.__dissector.offset(), length, \ + field, self.__tvb, self.__dissector.offset, length, \ little_endian) except Exception, e: print e @@ -304,7 +355,7 @@ class Tree(object): def add_uint(self, field, value, offset=0, length=4, adv=True): '''add unsigned integer to the tree''' try: - tree = self.__wsl.proto_tree_add_uint(self.__tree, field, self.__tvb, self.__dissector.offset(), length, value) + tree = self.__wsl.proto_tree_add_uint(self.__tree, field, self.__tvb, self.__dissector.offset, length, value) except Exception, e: print e else: @@ -315,7 +366,7 @@ class Tree(object): def add_text(self, string, offset=0, length=-1, adv=True): '''add text to the tree''' try: - tree = self.__wsl.proto_tree_add_text(self.__tree, self.__tvb, self.__dissector.offset(), length, string) + tree = self.__wsl.proto_tree_add_text(self.__tree, self.__tvb, self.__dissector.offset, length, string) except Exception, e: print e else: @@ -345,7 +396,7 @@ class TVB(object): def length_remaining(self, offset=-1): if offset < 0: - offset = self.__dissector.offset() + offset = self.__dissector.offset return self.__wsl.tvb_length_remaining(self.__tvb, offset) def reported_length(self): @@ -353,38 +404,38 @@ class TVB(object): def reported_length_remaining(self, offset=-1): if offset < 0: - offset = self.__dissector.offset() + offset = self.__dissector.offset return self.__wsl.tvb_length_remaining(self.__tvb, offset) def get_guint8(self, offset=-1): if offset < 0: - offset = self.__dissector.offset() + offset = self.__dissector.offset return self.__wsl.tvb_get_guint8(self.__tvb) def get_ntohs(self, offset=-1): if offset < 0: - offset = self.__dissector.offset() + offset = self.__dissector.offset return self.__wsl.tvb_get_ntohs(self.__tvb, offset) def get_ntohl(self, offset=-1): if offset < 0: - offset = self.__dissector.offset() + offset = self.__dissector.offset return self.__wsl.tvb_get_ntohl(self.__tvb, offset) def get_letohl(self, offset=-1): if offset < 0: - offset = self.__dissector.offset() + offset = self.__dissector.offset return self.__wsl.tvb_get_letohl(self.__tvb, offset) def get_letohs(self, offset=-1): if offset < 0: - offset = self.__dissector.offset() + offset = self.__dissector.offset return self.__wsl.tvb_get_letohs(self.__tvb, offset) #STA TODO : check that we can do that def get_ptr(self, offset=-1): if offset < 0: - offset = self.__dissector.offset() + offset = self.__dissector.offset return self.__wsl.tvb_get_ptr(self.__tvb, offset) #how to get this working ??? check how application uses this! diff --git a/epan/wspython/wspy_dissectors/homeplug.py.sample b/epan/wspython/wspy_dissectors/homeplug.py.sample index d12a29c139..73d7f5d449 100644 --- a/epan/wspython/wspy_dissectors/homeplug.py.sample +++ b/epan/wspython/wspy_dissectors/homeplug.py.sample @@ -17,15 +17,15 @@ class homeplug(Dissector): self.dissect_melen() def dissect_mctrl(self): - self.hf = self.fields() - self.subt = self.subtrees() - self.c_tree = self.tree() + self.subt = self.subtrees + self.c_tree = self.tree try: tree = self.c_tree.add_item(self.hf.homeplug_mctrl, length=1, adv=False) mctrl_tree = tree.add_subtree(self.subt.mctrl) mctrl_tree.add_item(self.hf.homeplug_mctrl_rsvd, length=1, adv=False) mctrl_tree.add_item(self.hf.homeplug_mctrl_ne, length=1) + #item = self.libhandle.proto_tree_add_text(mctrl_tree.raw_tree, self.raw_tvb, 0, 1, "test") => example using libhandle except Exception, e: print e @@ -63,7 +63,7 @@ def register_protocol(): # # Register Protocol Fields # - hf = tp.fields() + hf = tp.hf # MAC Control Field hf.add("Mac Control Field", "homeplug.mctrl", FT_NONE, BASE_NONE) hf.add("Reserved", "homeplug.mctrl.rsvd", FT_UINT8, bitmask=HOMEPLUG_MCTRL_RSVD) @@ -83,7 +83,7 @@ def register_protocol(): # # Register Subtrees # - subt = tp.subtrees() + subt = tp.subtrees #subt.add("homeplug") => we let Dissector output the main tree of this protocol subt.add("mctrl") subt.add("mehdr") -- cgit v1.2.3