Index of /libdia

      Name                    Last modified       Size  Description


[DIR] Parent Directory        27-May-2007 23:43      -  
[   ] libdia-0.1.tar.gz       27-May-2007 23:43    13k  GZIP compressed docume>


LIBDIA - A PHP library for manipulating network diagram files created using
   DIA (http://www.gnome.org/projects/dia/)


1. APPLICATION
2. REQUIREMENTS
3. TYPICAL USAGE
4. THE MAP FILE
5. AVAILABLE FUNCTIONS
6. OTHER REMARKS
7. LICENSE
8. AUTHOR



1. APPLICATION

  This library was developed specifically solely for the purpose of displayin
  a live (or almost-live - updated every few minutes) map of a small backbone
  network consisting of few Cisco Catalyst switches.
  
  In short:
  - a network map is drawn using "dia"; the connections and devices on the map
    are marked appropiately (see below),
  - a PHP script using libdia loads the pre-drawn static map and inserts live
    network monitoring data information onto the map, outputting a PNG file
    that can be displayed on your Network Operations Center monitors.
  
  The live network data (eg. link utilization, packet loss, etc.) can be
  inserted as: 
  - connection colors (eg. some connections on the map are changed to green,
    red, etc),
  - strings describing the connections,
  - strings describing the devices,
  - background colors of the connections' and devices' descriptions.



2. REQUIREMENTS

  libdia has been tested under PHP 4.4.2-1.1 (from Debian). Your PHP
  must support XML.
  
  The version of dia used in the author's environment is 0.95.
  
  Little effort needed in correcting the code is expected in case further
  versions of dia and/or PHP introduce any incompatibility with libdia.



3. TYPICAL USAGE

	require "libxml.php";
	require "libdia.php";
	
	$dia = new DiaGraph; // Initialize the library
	$dia->Load("maps/catalysts.dia"); // Load a diagram
	
	$dia->SetDeviceLabel("mesh", "mesh\nNot responding", "#ff0000");
                // Set some device label to "mesh\nNot responding"
                // Set the background color to red

	$dia->SetLinkLabel("mesh-chikai", "100%", "#ff0000");
                // Display some packet loss on a link and set the link
                // color to red
	
	$dia->SetLayerVisibility("Clients", false);
                // Disable displaying of some layer on the map
		
	header("Content-type: image/png");
	$dia->SavePNG();	
                // Output PNG to standard output


4. THE MAP FILE

  libdia makes some assumptions about the dia map files that it is processing.
  A sample map is provided together with the libdia package (example.dia).
  
  Your static map must follow these guidelines:
  
  a. The map files are UNCOMPRESSED (if they are not, gzip -d them or uncheck
     "Compress diagram files" when saving diagrams in dia).

  b. A device is defined using any symbol (eg. from "Cisco" libraries)
     AND a "Flowchart - Box" object attached to the device symbol with a
     standard line. The "Flowchart - Box" object should contain the
     device name. Its contents is replaced with whatever is set using
     the SetDeviceLabel() function. Consult the example map.

  c. All connections between devices are defined using STANDARD lines
     (Bezier, PolyLine or just standard straight line). The lines
     have to be connected directly to the symbols representing devices.
     The lines representing a connection MUST have a defined color,
     ie. they CAN'T BE BLACK.
  
  d. If you want to set some texts describing links (this is optional),
     you need to create a "Flowchart - Box" object for every link and
     type "device1-device2" in the box (omitting the quotes);
     device1 and device2 are device names provided in the flowchart
     boxes describing the devices (see a.).
     
     The link descriptions set using libdia will substitute the
     link descriptions (device1-device2) in the box.
  
  
  Actually, these constraints are related to the process of opening
  a file by libdia. After doing the XML parsing, libdia:
  - Searches for all flowchart boxes in the diagram file.
  - Finds all lines connected to these boxes on one end,
    and to something else on the other end.
    The symbols that the lines are connected to on the other
    ends are understood to be DEVICES. The devices' names
    are taken from the flowchart boxes.
  - Finds all lines connecting two devices. These lines
    are considered to be links between the devices.
  - For every two device names, searches for a flowchart box
    containing only "name1-name2" or "name2-name1". These
    boxes are understood to be link labels.
  
  
5. AVAILABLE FUNCTIONS

  - $dia = new DiaGraph (Constructor - no arguments)
     Creates a DiaGraph object, used for manipulating the graph.
     You may load only one graph into a DiaGraph object. 

  
  - $dia->Load(file)
     Loads a DIA file into the object. The file may not be compressed
     and must follow guidelines mentioned in (4).

  
  - $dia->Save(file)
     Saves a DIA file loaded into the object under the given name.

     
  - $dia->SavePNG([file])
     Generates a PNG file from the DIA graph loaded into the object.
     Warning: the dia executable is called to perform this task.
     Thus this will not work in PHP safe mode (system()).

     The path to "dia" is hardcoded in the code ("/usr/bin/dia").
     
     If no file name is given, the image is outputted to stdout
     (remember to set Content-type).


  - $dia->ListDevices()
     Returns an associative array containing the names of devices
     found in the file as keys.

  
  - $dia->ListLayers()
     Returns an associative array containing the names of layers
     found in the file (as keys).

     
  - $dia->ListLinks()
     As above - list of links is returned in keys of an associative
     array (the link names are in form "device1-device2", eg.
     "ergsun-mesh").

   
  - $dia->SetLayerVisibility(layername, visible)
     Makes a graph layer visible (visible = true) or not (visible = false).


  - $dia->SetDeviceLabel(device name, string, [background], [foreground])
     Replaces text in the "Flowchart Box" describing device named "device name"
     with given string (UTF8). If "background" and/or "foreground" arguments
     are provided, the flowchart box background color and/or the text color
     is changed as well (use HTML-like hex-triplet notation eg. "#ff0000").

     
  - $dia->SetLinkLabel(link name, string, [linkcolor], [background],
      [foreground])
     Similar to above - updates a link label. The link name should be given
     in the form "device1-device2" (it may be swapped - libdia will try
     both variants).
     
     If the 3rd argument is provided, the color of the line representing
     link is set to [linkcolor]. Link labels are optional in the map file
     and to change a link's line color you do not need to have it labeled.
     (the "string" argument is ignored if no label is found).


6. OTHER REMARKS

  All text is encoded using UTF-8.
  
  If you want to use PNG output (which is probably the case), you need to have
  dia installed on your server.
  
  If PNG output does not work, please see libdia.php around line 212 and
  check if the path to dia executable is correct for your system:
  system("/usr/bin/dia >/dev/null -e \"" . $outname . "\" -t png " . $tmpfile);


7. LICENSE

  This package is distributed under terms of GNU General Public License.
  See http://www.gnu.org/copyleft/gpl.html for the license text.


8. AUTHOR

  Mateusz Golicz <mateusz.golicz@sileman.pl>. Any feedback is appreciated.
  
  Please note that the author is not a native English speaker and is
  aware of the fact that his language is far from perfect. Reports
  on mistakes in this text are also welcome.

  The simple XML parsing code in libxml.php was based on code included in a
  user comment at www.php.net submitted by <geoffers [at] gmail [dot] com>.