Home » Networking » Net_MAC » Manual

Constants

Constants – Predefined Constants

NET_MAC_LINE_MAXLENGTH

Constant to represent the maximum length of a line in the manufacturers file.

NET_MAC_ERROR_OK

Error constant: signifies no problem (OK)

NET_MAC_ERROR_BADOPT

Error constant: signifies a bad option being passed to a function

NET_MAC_ERROR_BADDATA

Error constant: signifies bad data being passed to a function

NET_MAC_ERROR_BADDB

Error constant: signifies a bad database connection

NET_MAC_ERROR_BADFILE

Error constant: signifies a bad manufacturers file

Net_MAC::check()

Net_MAC::check() – Validates Media Access Control (MAC) addresses

Synopsis

string Net_MAC::check ( string $input , string $delimiter=':' )

Description

This function will check a MAC address to make sure it is valid.

Parameter

• string $input - The string containing the MAC Address
• string $delimiter - The string representing the delimiter to use when checking the MAC Address

Return value

boolean - TRUE if the MAC address is valid, FALSE otherwise

Note

This function should be called statically.

Example

Using check()

<?php
require_once "Net/MAC.php";

$macaddr = 'AB:CD:EF:00:11:22';

$mac = Net_MAC::check($macaddr);
if ($mac) {
    echo "$macaddr is valid";
}
else {
    echo "$macaddr is invalid";
}
?>

This would output the following:

ab:cd:ef:00:11:22 is valid

Using check() to get a MAC address with a different delimiter

<?php
require_once "Net/MAC.php";

$macaddr = 'AB:CD:EF:00:11:22';

$mac = Net_MAC::check($macaddr, '-');
if ($mac) {
    echo "$macaddr is valid";
}
else {
    echo "$macaddr is invalid";
}
?>

This would output the following:

AB:CD:EF:00:11:22 is invalid

since the delimiter '-' was not used in the provided MAC address.

Net_MAC::format()

Net_MAC::format() – Cleanly formats Media Access Control (MAC) addresses

Synopsis

string Net_MAC::format ( string $input , string $delimiter=':' , boolean $uppercase = true )

Description

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 ':').

Parameter

• string $input - The string containing the MAC Address
• string $delimiter - The string representing the delimiter to use when formatting the MAC Address
• string $uppercase - If set to TRUE (default), the alpha characters in the hexadecimal values in the MAC Address will be returned in uppercase. If FALSE, the alpha characters in the hexadecimal values will be returned in lowercase.

Return value

string - The formatted MAC Address or FALSE if the syntax of the MAC address is invalid

Note

This function should be called statically.

Example

Using format()

<?php
require_once "Net/MAC.php";

$macaddr = 'AB:CD:EF:00:11:22';

if (!Net_MAC::check($macaddr)) {
    echo "$macaddr is invalid";
    exit;
}

$mac = Net_MAC::format($macaddr);
if ($mac) {
    echo "$mac";
}
else {
    echo "$macaddr could not be formatted";
}
?>

This would output the following:

AB:CD:EF:00:11:22

Using format() to get a MAC address with a different delimiter

<?php
require_once "Net/MAC.php";

$macaddr = 'AB:CD:EF:00:11:22';

if (!Net_MAC::check($macaddr)) {
    echo "$macaddr is invalid";
    exit;
}

$mac = Net_MAC::format($macaddr, '-');
if ($mac) {
    echo "$mac";
}
else {
    echo "$macaddr could not be formatted";
}
?>

This would output the following:

AB-CD-EF-00-11-22

Using format() to get a MAC address with all capital alpha characters

<?php
require_once "Net/MAC.php";

$macaddr = 'ab:cd:ef:00:11:22';

if (!Net_MAC::check($macaddr)) {
    echo "$macaddr is invalid";
    exit;
}

$mac = Net_MAC::format($macaddr, '', true);
if ($mac) {
    echo "$mac";
}
else {
    echo "$macaddr could not be formatted";
}
?>

This would output the following:

ABCDEF001122

See

Net_MAC::check(),

Net_MAC::__construct()

Net_MAC::__construct() – Constructor

Synopsis

Net_MAC::__construct ( object $db , array $options )

Description

This is the constructor that will create and populate a valid Net_MAC object.

Parameter

• object $db - This parameter must be a valid MDB2 object.
• 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:

  Net_MAC::__construct() options

  Option	Description
  tablename	The name of the table where MAC address vendor information lives
  macaddrcol	The name of the column containing the MAC address prefixes
  vendorcol	The name of the column containing the vendor name
  desccol	The name of the column containing any extra descriptive information derived from the vendor list

Return value

void - No return value. A Net_MAC_Exception Exception object will be thrown if there is an error during construction

Note

The constructor can throw exceptions on error, so the constructor should always be called from inside a try/catch block.

Example

Instantiating a Net_MAC object

<?php
require_once 'Net/MAC.php';
require_once 'MDB2.php';

$db_type = 'pgsql';
$db_host = 'localhost';
$db_user = 'username';
$db_name = 'dbname';
$db_pass = 'password';

$dsn = "$db_type://$db_user:$db_pass@$db_host/$db_name";

$dbh =& MDB2::factory($dsn);

if (MDB2::isError($dbh)) {
  echo "MDB2 Error: ".$dbh->getUserInfo();
}

$dboptions = array('tablename' => 'macvendors',
           'macaddrcol' => 'macaddr',
           'vendorcol' => 'vendor',
           'desccol' => 'description');

try {
  $nmh =& new Net_MAC($dbh, $dboptions);
} catch (Net_MAC_Exception $e) {
  echo 'Net_MAC Error: ' . $e->getMessage();
  exit;
}
?>

Throws

throws Net_MAC_Exception

See

MDB2::factory()

MDB2::isError()

PEAR_Error::getUserInfo()

setMAC()

setMAC() – Sets the MAC address in the object

Synopsis

mixed setMAC ( string $macaddr , string $delimiter = ':' )

Description

This method will set the MAC address in the object given the passed MAC address and the MAC address delimiter. This method also makes use of the check() method to make sure that the MAC address is valid.

Parameter

• string $macaddr - The string representing the MAC address
• string $delimiter - The string representing the delimiter to use when verifying the MAC Address

Return value

boolean - Returns TRUE if the MAC address is set correctly, FALSE otherwise (i.e. the MAC address is not valid).

Note

This function can not be called statically.

Example

Using setMAC()

<?php
require_once 'Net/MAC.php';
require_once 'MDB2.php';

$db_type = 'pgsql';
$db_host = 'localhost';
$db_user = 'username';
$db_name = 'dbname';
$db_pass = 'password';

$dsn = "$db_type://$db_user:$db_pass@$db_host/$db_name";

$dbh =& MDB2::factory($dsn);

if (MDB2::isError($dbh)) {
  echo "MDB2 Error: ".$dbh->getUserInfo();
}

$dboptions = array('tablename' => 'macvendors',
           'macaddrcol' => 'macaddr',
           'vendorcol' => 'vendor',
           'desccol' => 'description');

try {
  $nmh =& new Net_MAC($dbh, $dboptions);
} catch (Net_MAC_Exception $e) {
  echo 'Net_MAC Error: ' . $e->getMessage();
  exit;
}

$nmh->setMAC('00:11:22:33:44:55');
?>

See

Net_MAC::__construct()

MDB2::factory()

MDB2::isError()

PEAR_Error::getUserInfo()

importVendors()

importVendors() – Import a manufacturers' file to the database or to an array

Synopsis

mixed importVendors ( string $file , boolean $doReturn = false )

Description

This method will parse a manufacturers' file, such as the one from http://anonsvn.wireshark.org/wireshark/trunk/manuf, containing a list of MAC address prefix-to-vendor relationships. If the $doReturn parameter is FALSE, then the data will be imported into the database defined by the factory of this class. However, if $doReturn is TRUE, 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'.

Parameter

• string $file - The filename or URL of the manufacturers' file to parse
• string $doReturn - If TRUE, an array will be returned, if FALSE, the data will be imported into the database.

Return value

mixed - If $doReturn is TRUE, the method will return an array. Otherwise, the method will return TRUE on success. A Net_MAC_Exception Exception object will be thrown on failure in either case.

Note

This function can not be called statically.

This method can throw exceptions on error, so the method should always be called from inside a try/catch block.

Example

Using importVendors() with a URL

<?php
require_once 'Net/MAC.php';
require_once 'MDB2.php';

$db_type = 'pgsql';
$db_host = 'localhost';
$db_user = 'username';
$db_name = 'dbname';
$db_pass = 'password';

$dsn = "$db_type://$db_user:$db_pass@$db_host/$db_name";

$dbh =& MDB2::factory($dsn);

if (MDB2::isError($dbh)) {
  echo "MDB2 Error: ".$dbh->getUserInfo();
}

$dboptions = array('tablename' => 'macvendors',
           'macaddrcol' => 'macaddr',
           'vendorcol' => 'vendor',
           'desccol' => 'description');

try {
  $nmh =& new Net_MAC($dbh, $dboptions);
} catch (Net_MAC_Exception $e) {
  echo 'Net_MAC Error: ' . $e->getMessage();
  exit;
}

try {
  $nmh->importVendors('http://anonsvn.wireshark.org/wireshark/trunk/manuf');
} catch (Net_MAC_Exception $e) {
  echo 'Net_MAC Error: ' . $e->getMessage();
  exit;
}
?>

This would output an error only if there is an error importing the file from the URL.

Using importVendors() with a file, returning an array

<?php
require_once 'Net/MAC.php';
require_once 'MDB2.php';

$db_type = 'pgsql';
$db_host = 'localhost';
$db_user = 'username';
$db_name = 'dbname';
$db_pass = 'password';

$dsn = "$db_type://$db_user:$db_pass@$db_host/$db_name";

$dbh =& MDB2::factory($dsn);

if (MDB2::isError($dbh)) {
  echo "MDB2 Error: ".$dbh->getUserInfo();
}

$dboptions = array('tablename' => 'macvendors',
           'macaddrcol' => 'macaddr',
           'vendorcol' => 'vendor',
           'desccol' => 'description');

$nmh =& Net_MAC::factory($dbh, $dboptions);
if (PEAR::isError($nmh)){
  echo 'Net_MAC Error: '.$nmh->getMessage();
}

$vendorArr = $nmh->importVendors('./manuf')
if (PEAR::isError(!$vendorArr)) {
  echo 'Net_MAC: ' . $err->getUserInfo();
  exit;
}

print_r($vendorArr);
?>

This would output the entire list of MAC address vendors on success and an error message on failure.

Throws

throws Net_MAC_Exception

See

Net_MAC::__construct()

MDB2::factory()

MDB2::isError()

PEAR_Error::getUserInfo()

findVendor()

findVendor() – Finds the vendor of the MAC address stored in the object

Synopsis

mixed findVendor ( string $getDescription = false , string $macList = null )

Description

This method will search through the database to find a vendor that matches the MAC address stored in the class using 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 importVendors() method when using the $doReturn parameter.

Parameter

• string $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.
• string $macList - An optional list of MAC-to-vendor relationships to search instead of using the database.

Return value

mixed - Returns an associative array if $getDescription is TRUE, returns a string with the vendor name if $getDescription is FALSE. If the MAC vendor cannot be found in the vendor list, FALSE is returned.

Note

This function can not be called statically.

Example

Using findVendor()

<?php
require_once 'Net/MAC.php';
require_once 'MDB2.php';

$db_type = 'pgsql';
$db_host = 'localhost';
$db_user = 'username';
$db_name = 'dbname';
$db_pass = 'password';

$dsn = "$db_type://$db_user:$db_pass@$db_host/$db_name";

$dbh =& MDB2::factory($dsn);

if (MDB2::isError($dbh)) {
  echo "MDB2 Error: ".$dbh->getUserInfo();
}

$dboptions = array('tablename' => 'macvendors',
           'macaddrcol' => 'macaddr',
           'vendorcol' => 'vendor',
           'desccol' => 'description');

try {
  $nmh =& new Net_MAC($dbh, $dboptions);
} catch (Net_MAC_Exception $e) {
  echo 'Net_MAC Error: ' . $e->getMessage();
  exit;
}

$nmh->setMAC('00:11:22:33:44:55');
$result = $nmh->findVendor(true);
if (is_array($result)) {
  foreach($result as $key => $value) {
    echo "$key: $value<br>\n";
  }
}
else {
  echo $result;
}
?>

This would output the following:

vendor: Cimsys
description: CIMSYS Inc

See

Net_MAC::__construct()

MDB2::factory()

MDB2::isError()

PEAR_Error::getUserInfo()

Net_MAC_Exception

Net_MAC_Exception – Exception class for Net_MAC package

Net_MAC_Exception

This class is a simple derivation of the PEAR_Exception class and simply exists for the use of throwing exceptions for this class.