====== PDML Specification ====== The PDML language is a very simple language that keeps the information related to a decoded packet. PDML stands for **Packet Details Markup Language** and it is strongly related to NetPDL. This language is used by a NetPDL engine that understands the NetPDL Visualization Extension to create a detailed view of each packet. A detailed view of a packet is an XML file that contains all the most important information related to protocols and fields that are contained in one packet (e.g. the protocols, all the field names and their values, and more). The PDML specification is a way to organize this information. A PDML document lists all the packets contained in a capture file, detailing the most important information for every protocol that has been found in the packet and for each field that has been decoded within the protocol. ===== Structure of a PDML document ===== The PDML document is delimited by the '''' and '''' tags. This tag contains a set of '''' elements, which contains decoded packets. The '''' element can have the following attributes: |**Attribute**|**Description**| |''version'' (optional)|The version of the PDML specification.| |''creator'' (optional)|The creator of the current PDML file. For instance, any file created by the NetBee library has ''creator="NetBee"''.| |''dissectors'' (optional)|The date (in format ''dd-mm-yyyy'') of the last update of the NetPDL protocol database that was used to create the current PDML file.| The '''' element has the following attributes: |**Attribute**|**Description**| |''num'' (required)|The **number** of the current packet within the capture. For instance, a value of "1" means that this is the first packet of the capture, and so on.| |''len'' (required)|The **total length** (in bytes) of the packet.| |''caplen'' (required)|The **captured length** (in bytes), i.e. the length of portion of the packet that has been captured.| |''timestamp'' (required)|The **timestamp** (according to the UNIX ''struct timeval'' structure) of the packet. This is the only field that has a non integer (float) value.| An example of PDML document looks like:

===== Detailing the content of a packet: the element ===== A '''' element can have one or more '''' elements. The '''' element keeps the name of one protocol and it has the following attributes: |**Attribute**|Description| |''name'' (required)|It contains the content of the ''name'' [[netpdl:visualization_expression#Data associated to each NetPDL field|Field Visualization Variable]] that is associated to the current protocol. For instance, this means that this attribute contains the same string present in the ''name'' attribute of the originating '''' of the NetPDL document.| |''longname'' (optional)|It contains the content of the ''longname'' [[netpdl:visualization_expression#Data associated to each NetPDL field|Field Visualization Variable]] that is associated to the current protocol. For instance, this means that this attribute contains the same string present in the ''longname'' attribute of the corresponding '''' of the NetPDL document.| |''size'' (required)|It contains the content of the ''size'' [[netpdl:visualization_expression#Data associated to each NetPDL field|Field Visualization Variable]] that is associated to the current protocol. For instance, this means that this attribute contains the size (in bytes) of the headers of the current protocol.| |''pos'' (required)|It contains the content of the ''pos'' [[netpdl:visualization_expression#Data associated to each NetPDL field|Field Visualization Variable]] that is associated to the current protocol. For instance, this means that this attribute contains the starting position (in bytes) of the headers of the current protocol.| A '''' element must have one or more [[pdml_specification#Detailing the content of a field: the field element|]] child elements. ==== Detailing the content of a field: the element ==== The '''' element contains the information related to a single field. Only NetPDL [[netpdl:core_specs#Protocol fields: the field element|]] elements can create a PDML '''' element. In case of a decoded field, there is no ambiguity concerning the field size or the number (and the type) of fields present in the protocol header. Therefore the PDML does not have the complexity of NetPDL because it does not have to manage variable fields, loops, conditional primitives, and more. The '''' element can have several attributes. These attributes correspond to the [[netpdl:visualization_expression#Data associated to each NetPDL field|Field Visualization Variables]] that are associated to the current field. Supported attributes are the following: ''name'', ''longname'', ''value'', ''showvalue'', ''size'', ''pos'', ''mask'', ''showmap'' and ''showdtl''. For more details about their meaning, please check the appropriate section of the [[netpdl:visualization_expression#Data associated to each NetPDL field|NetPDL Visualization Extension]]. Only the name, value, size and pos attributes are compulsory. However, note that it is not possible to recreate the complete dumped packet by parsing the PDML description. '''' elements can be nested. This is the case of a field that has some other subfield: a NetPDL '''' field might create a nested tree of ''''. This is an example, extracted from the definition of the IP header that has some '''' fields: **NetPDL definition:**

...

**Generated PDML fragment:**

...

==== Example: an ICMP packet ==== This example shows a ICMP packet on an Ethernet network. This packet is made up of a ''geninfo'' protocol, then Ethernet, IP and ICMP. The example shows both the ''showdtl'' and ''showmap'' optional attributes (used, for example, to print detailed information about MAC addresses), and it shows also nested '''' elements (for example in case of the IP //Flags and Fragment Offset// field).

==== An example of a default detailed view ==== A tool that wants to display a detailed view of the packet might use the following algorithm (in pseudo-code):


  if exist(showdtl_attrib)
    print(longname_attrib, " = ", showdtl_attrib);
  else
    if exist(showmap_attrib)
      print(longname_attrib, " = ", showvalue_attrib, " (", showmap_attrib, ")" );
    else
      print(longname_attrib, " = ", showvalue_attrib)

This pseudo-code shows how the information present into the PDML document can be used: if a detailed view is available (''showdtl'' attribute), we can use that value for printing the field. Otherwise, we can print the field name (in "human" form by using the ''longname'' attribute) and its value (in "human" form by using the ''showvalue'' attribute); additionally, if the ''showmap'' attribute is available, we can print that attribute as well. Other attributes (like ''pos'' and ''size'') can be used to enlighten the bytes corresponding to the current field in a dump view of the packet, i.e. a view in which only the hexadecimal dump of the packet is given. ===== Relationship between NetPDL and PDML ===== The relationship between NetPDL and PDML is rather simple. The detailed view originates from the directives contained in the [[netpdl:visualization_expression#Defining the visualization of a field: the showtemplate element|]] element in the NetPDL visualization extension. For this element to be applied, the packet decoding has to be completed, i.e. [[netpdl:visualization_expression#Data associated to each NetPDL field|Field Visualization Variables]] must be associated to all NetPDL fields. The procedure for creating the detailed view involves the execution of the directives present in the [[netpdl:visualization_expression#Defining the visualization of a field: the showtemplate element|]] NetPDL element, and coping the value of the required field/attributes from the NetPDL engine to the PDML document. ===== XML Schema Definition ===== The XML schema definition of the PDML language can be found at the [[netpdl:schema | XSD Schema Page]]. ===== Language license ===== The license of the PDML language can be found at the [[netpdl:license | Language License Page]].