python binding update :

    * adding pydoc documentation to doc/README.python
    * possible to access directly libwireshark via libhandle and raw_<tvb|pinfo|tree>
    * transform some methods into properties
    * update sample to reflect changes/features
    * adding comments!!!


svn path=/trunk/; revision=28532

4 files changed, 384 insertions, 31 deletions

diff --git a/AUTHORS b/AUTHORS
index 6fd75d4668..5ff2bb3dd5 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -2595,6 +2595,9 @@ Davide Schiera		<davide.schiera [AT] cacetech.com> {
 }
 
 Sebastien Tandel	<sebastien [AT] tandel.be> {
+        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 <sebastien [AT] tandel [dot] be>
+    # Copyright (c) 2001 by Gerald Combs <gerald@wireshark.org>
+    #
+    # 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")