HACKING

pypacker directory structure
============================

pypacker
	examples		# usage examples for pypacker
	pypacker		# pypacker core logic, routines for handling packet-data, protocols sorted by layers
		layer12		# protocols for ISO/OSI-layer 1 and 2. The name of the module
				# is the same as the main class in this module.
		layer3		# ...for layer 3
		layer4		# ...for layer 4
		layer567	# ...for layer 5, 6 and 7
	tests			# tests for pypacker logic and protocols


Styleguide
==========

- Auto-update header should only be recalculated on changes to relevant headers or data
- All official Python style-guidelines should be applied except the
  preference of space-characters. Tabs must be used throughout
  the code:

	GLOBAL_XYZ[tab]= 123[tab]# some comment

	class someclass()
	# some comment
		[tab]def xyz(self):
		[tab]# Some comment
			[tab][tab]var1 = 123[tab]# some comment
			[tab][tab]pass

- PEP8 configuration:
	[pep8]
	ignore = W191,W0221,E126,E127,E128,E223,E1004
	max-line-length = 160

 Explanation:
	W191: Spaces enforced? -> We use TABS!
	W0221: Overriden Method: Different amount of arguments -> That's not a problem
	E126: continuation line over-indented for hanging indent -> Looks sh$§
	E127: continuation line over-indented for visual indent -> Looks sh$§
	E128: continuation line under-indented for visual indent -> Looks sh$§
	E223: tab before operator -> yep, we use tabs

- Strings are written using double quotes like "string_xyz"
- Readability is more important than performance
- avoid overwriting "__getattribute__"


Adding new protocols
====================

- New protocols are added by subclassing "Packet" and placing them into the
  right "layerX"-directory. The protocol header is basically defined by the
  static field "__hdr__" (see layer12/ethernet.Ethernet). See code documentation
  for classes "MetaPacket" and "Packet" in pypacker/pypacker.py for deeper information.
- Fields can be either simple like ("name", ["format" | None], [int_value | b"bytes_value" | None] [, True])
  or TriggerList-like ("name", None, TriggerList). The last value is set to true in case this is an auto-update field.
- _dissect(...) must be overwritten if the header format can change from its original format.
  This is generally the case when: using TriggerLists, simple fields can get deactivated
  (see ethernet.Ethernet) or simple byte fields are variable in format (initial format None).
- self._init_triggerlist(...) should be called to initiate TriggerLists
- self._init_handler(...) can be called to initiate the handler of the next
  upper layer. Which handler to be called generally depends on the type information
  found in the current layer (see layer12/ethernet.Ethernet -> type)
- bin(...) should be overwritten to update fields which depend on the state of the packet like
  lengths, checksums etc (see layer3/ip.IP -> len, sum) aka auto-update fields. The variable
  update_auto_fields indicates if any field should be updated in general, XXX_au_active in turn indicates
  if the field XXX should be updated (True) or not (see layer3/ip.IP.bin() -> len_au_active) in particular.
- direction(...) should be overwritten to be able to check directions to an other packet
  (see layer12/ethernet.Ethernet)
- reverse_address(...) should be overwritten to be able to reverse source/destination addresses (see ethernet.Ethernet)
- Conveniant access should be enabled using properties:
  xxx_s = pypacker.get_property_ip4("xxx")
  xxx_s = pypacker.get_property_mac("xxx")
  xxx_s = pypacker.get_property_dnsname("xxx")
- Setting/getting values smaller then 1 Byte should be enabled using properties (see layer3/ip.IP -> v, hl)
- Every protocol needs a testcase in tests/test_pypacker.py


See pypacker/pypacker.Packet for more informations on creating new protocols.