cvs: pear /Net_MAC MAC.php package.xml package2.xml

atex Sat Dec 30 22:12:43 2006 UTC Added files: /pear/Net_MAC MAC.php package.xml package2.xml Log: - Added the Net_MAC directory for the Net_MAC package - Added the package XML files and the MAC.php file

http://cvs.php.net/viewvc.cgi/pear/Net_MAC/MAC.php?view=markup&rev=1.1 Index: pear/Net_MAC/MAC.php +++ pear/Net_MAC/MAC.php <?php /* * This file contains the MAC class * * Copyright (c) 2006 Andrew Teixeira * * LICENSE: This source file is subject to version 3.0 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_0.txt. If you did not receive a copy of * the PHP License and are unable to obtain it through the web, please * send a note to license@php.net so we can mail you a copy immediately. * * $Id: MAC.php,v 1.1 2006/12/30 22:12:43 atex Exp $ */ /** * Require PEAR/Exception.php since we will be using PEAR Exceptions * in this class. */ require_once 'PEAR/Exception.php'; /** * Constant to represent the maximum length of a line in the * manufacturers file. */ define('NET_MAC_LINE_MAXLENGTH', 256); /** * Error constant: signifies no problem (OK) */ define ('NET_MAC_ERROR_OK', 0); /** * Error constant: signifies a bad option being passed to a function */ define ('NET_MAC_ERROR_BADOPT', 1); /** * Error constant: signifies bad data being passed to a function */ define ('NET_MAC_ERROR_BADDATA', 2); /** * Error constant: signifies a bad database connection */ define ('NET_MAC_ERROR_BADDB', 3); /** * Error constant: signifies a bad manufacturers file */ define ('NET_MAC_ERROR_BADFILE', 4); /** * Extension of the main PEAR_Exception Class for use with the Net_MAC * class. * * @author Andrew Teixeira <ateixeira@gmail.com> * @package Net_MAC * @version 1.0 * @access public */ class Net_MAC_Exception extends PEAR_Exception {} /** * Class to validate and cleanly format Media Access Control (MAC) * addresses * * @author Andrew Teixeira <ateixeira@gmail.com> * @package Net_MAC * @version 1.0 * @access public */ class Net_MAC { /** * The MAC address to work on. * * @access protected * @var string */ protected $_macaddr; /** * A database instance to use in looking up MAC-to-vendor * relationships. * * @access protected * @var object */ protected $_db; /** * The options to use while connecting to the database. * * @access protected * @var array */ protected $_dbOptions; /** * The default constructor * * This is the default constructor that will create and populate a * valid Net_MAC object. * * @access public * * @param object $db A valid instantiated {@link * http://pear.php.net/package/MDB2/ MDB2} object to use when * adding/retrieving information from the database for MAC address * vendors * @param array $options An array of options to use with the * database in retrieving MAC address vendors. The associative * array should have key/value pairs as follows: * * <ul> * <li><b>tablename</b>: The name of the table where MAC address * vendor information lives</li> * <li><b>macaddrcol</b>: The name of the column containing the * MAC address prefixes</li> * <li><b>vendorcol</b>: The name of the column containing the * vendor name</li> * <li><b>desccol</b>: The name of the column containing any * extra descriptive information derived from the vendor list</li> * </ul> * * @return void No return value. A {@link Net_MAC_Exception * Net_MAC_Exception} Exception object will be thrown if there is * an error during construction so the constructor should be * called from a try/catch block */ function __construct(&$db, $options = NULL) { require_once 'MDB2.php'; $this->_db = NULL; $this->_macaddr = NULL; $this->_dbOptions = NULL; if (!is_a($db, 'MDB2_Driver_Common')) { throw new Net_MAC_Exception('Bad database object', NET_MAC_ERROR_BADDB); } if (!is_array($options)) { throw new Net_MAC_Exception('Second parameter must be an array', NET_MAC_ERROR_BADOPT); } if (!isset($options['tablename'])) { throw new Net_MAC_Exception('No table name given in options', NET_MAC_ERROR_BADDATA); } if (!isset($options['macaddrcol'])) { throw new Net_MAC_Exception('No MAC address column name given in options', NET_MAC_ERROR_BADDATA); } if (!isset($options['vendorcol'])) { throw new Net_MAC_Exception('No vendor column name given in options', NET_MAC_ERROR_BADDATA); } if (!isset($options['desccol'])) { throw new Net_MAC_Exception('No description column name given in options', NET_MAC_ERROR_BADDATA); } $this->_db = $db; $this->_db->loadModule('Extended'); $this->_dbOptions = $options; } /* end default constructor */ /** * Checks a MAC address * * This function will check a MAC address to make sure it is * valid. * * @access static * * @param string $input The string containing the MAC Address * @param string $delimiter The string representing the delimiter * to use when verifying the MAC Address * * @return string <b>true</b> if the MAC address is valid, * <b>false</b> otherwise */ static function check($input, $delimiter = ':') { // Check for 6 octets without any punctuation $retval = preg_match('/^([0-9a-fA-F][0-9a-fA-F]\Q'.$delimiter.'\E){5}([0-9a-fA-F][0-9a-fA-F]){1}$/', $input); return $retval; } /* end method check */ /** * Sets the MAC address * * This method will set the MAC address in the class. * * @access public * * @param string $macaddr The string representing the MAC address * @param string $delimiter The string representing the delimiter * to use when verifying the MAC Address * * @return bool Returns <b>true</b> if the MAC address is set * correctly, <b>false</b> otherwise */ function setMAC($macaddr, $delimiter = ':') { $validMAC = self::check($macaddr, $delimiter); if ($validMAC) { $this->_macaddr = $macaddr; return true; } return false; } /* end method setMac */ /** * Formats a MAC address * * This function will format a MAC address into XX:XX:XX:XX:XX:XX * format from whatever format is passed to the function. The * delimiter (: in the example above) will be replaced with * whatever string is passed to the $delimiter parameter * (default :). * * @access static * * @param string $input The string containing the MAC Address * @param string $delimiter The string representing the delimiter * to use when formatting the MAC Address * @param bool $uppercase If set to true (default), the * hexadecimal values in the MAC Address will be returned in * uppercase. If false, the hexadecimal values will be returned * in lowercase. * * @return string The formatted MAC Address or <b>false</b> on * error */ static function format($input, $delimiter = ':', $uppercase = true) { /* Replace all characters not in a valid MAC address with * nothing. We are going to be testing for a MAC address as * XXXXXXXXXXXX instead of XX:XX:XX:XX:XX:XX */ $macaddr = preg_replace('/[g-zG-Z]*\W*_*/', '', $input); /* If $uppercase is true, set all the alpha characters to * uppercase, otherwise set all the alpha characters to * lowercase */ $macaddr = ($uppercase) ? strtoupper($macaddr) : strtolower($macaddr); // Check for 6 octets without any punctuation if (!preg_match('/^([0-9a-fA-F][0-9a-fA-F]){6}$/', $macaddr)) { return false; } // Add back in the $delimiter delimiters $macaddr = preg_replace('/([0-9a-fA-F][0-9a-fA-F]){1}/', '$1' . $delimiter, $macaddr); // Remove the trailing $delimiter $macaddr = preg_replace('/' . $delimiter . '$/', '', $macaddr); return $macaddr; } /* end method format */ /** * Import a manufacturers' file to the database * * This method will parse a manufacturers' file, such as the one * from {@link * http://anonsvn.wireshark.org/wireshark/trunk/manuf}, containing * a list of MAC address prefix-to-vendor relationships. If the * $doReturn parameter is <b>false</b>, then the data will be * imported into the database defined by the factory of this * class. However, if $doReturn is <b>true</b>, then the return * will be an associative array with the key being the MAC address * prefix and the data being an associative array with the keys * 'vendor' and 'description'. * * @access public * * @param string $file The filename or URL of the manufacturers' * file to parse. * @param bool $doReturn If <b>true</b>, an array will be * returned, if <b>false</b>, the data will be imported into the * database. (default: false) * * @return mixed If $doReturn is true, the method will return an * array. Otherwise, the method will return <b>true</b> on * success. A {@link Net_MAC_Exception Net_MAC_Exception} * Exception object will be thrown on failure in either case. */ function importVendors($file, $doReturn = false) { if ($file == NULL) { throw new Net_MAC_Exception('No file or URL given', NET_MAC_ERROR_BADFILE); } $fp = @fopen($file, 'r'); if ($fp == false) { throw new Net_MAC_Exception('Cannot open the file or URL given', NET_MAC_ERROR_BADFILE); } if ($doReturn) { $retArr = array(); } else { // Prepare parameters for MDB2->buildManipSQL() $fields = array ($this->_dbOptions['macaddrcol'], $this->_dbOptions['vendorcol'], $this->_dbOptions['desccol']); $sql = $this->_db->buildManipSQL($this->_dbOptions['tablename'], $fields, MDB2_AUTOQUERY_INSERT); $query = $this->_db->prepare($sql); } while ($line = fgets($fp, NET_MAC_LINE_MAXLENGTH)) { // Remove comments if ( preg_match('/^\#/', $line) ) { continue; } if ( preg_match('/^([0-9A-Fa-f][0-9A-Fa-f]:){2}([0-9A-Fa-f][0-9A-Fa-f]){1}/', $line) ) { $pieces = preg_split('/\s+/', $line); // Since the file is space-delimited, we now need to // reconstruct the description field if it existed $desc = NULL; for ($i = 3; $i < count($pieces); $i++) { $desc .= $pieces[$i].' '; } $desc = rtrim($desc); if ( (isset($pieces[0])) && (isset($pieces[1])) ) { if ($doReturn) { $retArr[$pieces[0]] = array('vendor' => $pieces[1], 'description' => $desc); } else { $values = array($pieces[0], $pieces[1], $desc); $result = $query->execute($values); } } } } return ($doReturn) ? $retArr : true; } /* end method importVendors */ /** * Finds the vendor for a MAC address * * This method will search through the database to find a vendor * that matches the MAC address stored in the class using {@link * setMAC setMAC}. If the $macList parameter is set, the method * will use the array stored in $macList as the data source to * find the MAC vendor instead of the database. The array would * have to be an array with the same characteristics as one * returned from the {@link importVendors importVendors} method * when using the $doReturn parameter. * * @access public * * @param bool $getDescription If set to true, the return value * will be an array with keys 'vendor' and 'description'. * Normally the method will simply return the vendor name. * @param array $macList An optional list of MAC-to-vendor * relationships to search instead of using the * database. (default: NULL) * * @return mixed Returns an associative array if $getDescription * is <b>true</b>, returns a string with the vendor name if * $getDescription is <b>false</b>. If the MAC vendor cannot be * found in the vendor list, <b>false</b> is returned. */ function findVendor($getDescription = false, $macList = NULL) { if ($macList == NULL) { $macaddrcol = $this->_dbOptions['macaddrcol']; $vendorcol = $this->_dbOptions['vendorcol']; $desccol = $this->_dbOptions['desccol']; /* The manufacturers' list only uses the first 3 octets, * so we need to get that portion of the stored MAC * address. */ $macaddr = substr(self::format($this->_macaddr, ':'), 0, 8); // Prepare parameters for MDB2->buildManipSQL() $fields = array ($macaddrcol, $vendorcol, $desccol); $where = "$macaddrcol = '$macaddr'"; $sql = $this->_db->buildManipSQL($this->_dbOptions['tablename'], $fields, MDB2_AUTOQUERY_SELECT, $where); $query = $this->_db->prepare($sql); $result = $query->execute($values); if ( (MDB2::isError($result)) || ($result->numRows() == 0) ) { return false; } $macInfo = $result->fetchRow(MDB2_FETCHMODE_ASSOC); if ($getDescription) { return array($vendorcol => $macInfo[$vendorcol], $desccol => $macInfo[$desccol]); } else { return $macInfo[$vendorcol]; } } else { return false; } } /* end method findVendor */ } /* end class Net_MAC */ /* * Local variables: * tab-width: 4 * c-basic-offset: 4 * End: */ ?> http://cvs.php.net/viewvc.cgi/pear/Net_MAC/package.xml?view=markup&rev=1.1 Index: pear/Net_MAC/package.xml +++ pear/Net_MAC/package.xml <?xml version="1.0"?> <package version="1.0"> <name>Net_MAC</name> <summary>Validates and formats MAC addresses</summary> <description> This package validates and cleanly formats Media Access Control (MAC) addresses. The Net_MAC class can also import a list of MAC address vendors and store them in a database which the class can then use to identify vendors of any MAC address. </description> <license uri="http://www.php.net/license/3_01.txt">PHP License 3.01</license> <maintainers> <maintainer> <name>Andrew Teixeira</name> <role>lead</role> <user>atex</user> <email>atex@php.net</email> </maintainer> </maintainers> <release> <version>0.1.0</version> <state>alpha</state> <date>2006-12-13</date> <license>PHP License 3.01</license> <notes> * First release </notes> <filelist> <dir name="/"> <dir name="Net" role="php"> <file>MAC.php</file> </dir> </dir> </filelist> <deps> <dep type="php" rel="gt" version="4.2" optional="no" /> </deps> </release> <changelog> <release> <version>0.1.0</version> <state>alpha</state> <date>2006-12-13</date> <notes> * First release </notes> </release> </changelog> </package> http://cvs.php.net/viewvc.cgi/pear/Net_MAC/package2.xml?view=markup&rev=1.1 Index: pear/Net_MAC/package2.xml +++ pear/Net_MAC/package2.xml <?xml version="1.0" encoding="UTF-8"?> <package packagerversion="1.4.7" version="2.0" xmlns="http://pear.php.net/dtd/package-2.0" xmlns:tasks="http://pear.php.net/dtd/tasks-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0 http://pear.php.net/dtd/tasks-1.0.xsd http://pear.php.net/dtd/package-2.0 http://pear.php.net/dtd/package-2.0.xsd"> <name>Net_MAC</name> <channel>pear.php.net</channel> <summary>Validates and formats MAC addresses</summary> <description> This package validates and cleanly formats Media Access Control (MAC) addresses. The Net_MAC class can also import a list of MAC address vendors and store them in a database which the class can then use to identify vendors of any MAC address. </description> <lead> <name>Andrew Teixeira</name> <user>atex</user> <email>atex@php.net</email> <active>yes</active> </lead> <date>2006-12-13</date> <time>20:33:00</time> <version> <release>0.1.0</release> <api>0.1.0</api> </version> <stability> <release>alpha</release> <api>alpha</api> </stability> <license>PHP License 3.01</license> <notes>* First release </notes> <contents> <dir name="/"> <dir name="Net"> <file name="MAC.php" role="php" /> </dir> <!-- //Net --> </dir> <!-- / --> </contents> <dependencies> <required> <php> <min>4.2</min> <exclude>4.2</exclude> </php> <pearinstaller> <min>1.4.0b1</min> </pearinstaller> </required> </dependencies> <phprelease /> <changelog> <release> <version> <release>0.1.0</release> <api>0.1.0</api> </version> <stability> <release>alpha</release> <api>alpha</api> </stability> <date>2006-12-13</date> <license>PHP License 3.01</license> <notes>* First release </notes> </release> </changelog> </package>