NAME
Mobile::Wurfl - a perl module interface to WURFL (the Wireless Universal Resource File - http://wurfl.sourceforge.net/).
SYNOPSIS
my $wurfl = Mobile::Wurfl->new(
wurfl_home => "/path/to/wurfl/home",
db_descriptor => "DBI:mysql:database=wurfl:host=localhost",
db_username => 'wurfl',
db_password => 'wurfl',
wurfl_url => q{http://www.nusho.it/wurfl/dl.php?t=d&f=wurfl.xml},
verbose => 1,
);
my $desc = $wurfl->get( 'db_descriptor' );
$wurfl->set( wurfl_home => "/another/path" );
$wurfl->create_tables( $sql );
$wurfl->update( force => 1 );
$wurfl->rebuild_tables();
my @devices = $wurfl->devices();
for my $device ( @devices )
{
print "$device->{user_agent} : $device->{id}\n";
}
my @groups = $wurfl->groups();
my @capabilities = $wurfl->capabilities();
for my $group ( @groups )
{
@capabilities = $wurfl->capabilities( $group );
}
my $ua = $wurfl->canonical_ua( "SonyEricssonK750i/R1J Browser/SEMC-Browser/4.2 Profile/MIDP-2.0 Configuration/CLDC-1.1" );
my $deviceid = $wurfl->deviceid( $ua );
my $wml_1_3 = $wurfl->lookup( $ua, "wml_1_3" );
print "$wml_1_3->{name} = $wml_1_3->{value} : in $wml_1_3->{group}\n";
my $fell_back_to = wml_1_3->{deviceid};
my $width = $wurfl->lookup_value( $ua, "max_image_height", no_fall_back => 1 );
$wurfl->cleanup();DESCRIPTION
Mobile::Wurfl is a perl module that provides an interface to mobile device information represented in wurfl (http://wurfl.sourceforge.net/). The Mobile::Wurfl module works by saving this device information in a database (preferably mysql).
It offers an interface to create the relevant database tables from a SQL file containing "CREATE TABLE" statements (a sample is provided with the distribution). It also provides a method for updating the data in the database from the wurfl.xml file hosted at http://www.nusho.it/wurfl/dl.php?t=d&f=wurfl.xml.
It provides methods to query the database for lists of capabilities, and groups of capabilities. It also provides a method for generating a "canonical" user agent string (see "canonical_ua").
Finally, it provides a method for looking up values for particular capability / user agent combinations. By default, this makes use of the hierarchical "fallback" structure of wurfl to lookup capabilities fallback devices if these capabilities are not defined for the requested device.
METHODS
new
The Mobile::Wurfl constructor takes an optional list of named options; e.g.:
my $wurfl = Mobile::Wurfl->new(
wurfl_home => "/path/to/wurfl/home",
db_descriptor => "DBI:mysql:database=wurfl:host=localhost",
db_username => 'wurfl',
db_password => 'wurfl',
wurfl_url => q{http://www.nusho.it/wurfl/dl.php?t=d&f=wurfl.xml},
verbose => 1,
);The list of possible options are as follows:
- wurfl_home
-
Used to set the default home diretory for Mobile::Wurfl. This is where the cached copy of the wurfl.xml file is stored. It defaults to current directory.
- db_descriptor
-
A database descriptor - as used by DBI to define the type, host, etc. of database to connect to. This is where the data from wurfl.xml will be stored, in two tables - device and capability. The default is "DBI:mysql:database=wurfl:host=localhost" (i.e. a mysql database called wurfl, hosted on localhost.
- db_username
-
The username used to connect to the database defined by "METHODS/new/db_descriptor". Default is "wurfl".
- db_password
-
The password used to connect to the database defined by "METHODS/new/db_descriptor". Default is "wurfl".
- wurfl_url
-
The URL from which to get the wurfl.xml file. Default is http://www.nusho.it/wurfl/dl.php?t=d&f=wurfl.xml.
- verbose
-
If set to a true value, various status messages will be output to STDERR. If false, these messages will be written to a logfile called wurfl.log in "METHODS/new/wurfl_home".
set / get
The set and get methods can be used to set / get values for the constructor options described above. Their usage is self explanatory:
my $desc = $wurfl->get( 'db_descriptor' );
$wurfl->set( wurfl_home => "/another/path" );create_tables
The create_tables method is used to create the database tables required for Mobile::Wurfl to store the wurfl.xml data in. It can be passed as an argument a string containing appropriate SQL "CREATE TABLE" statements. If this is not passed, it uses appropriate statements for a mysql database (see __DATA__ section of the module for the specifics). This should only need to be called as part of the initial configuration.
update( [ force => 1 ] )
The update method is called to update the database tables with the latest information from wurfl.xml. It first checks to see if the locally cached version of the wurfl.xml file is up to date by doing a HEAD request on the WURFL URL, and comparing modification times. If there is a newer version of the file at the WURFL URL, or if the locally cached file does not exist, then the module will GET the wurfl.xml file from the WURFL URL. If this has been done, the module will parse the wurfl.xml file, and populate the database with the new data. The update method can be passed a "force" option, which will force the wurfl.xml file to be fetched and the database tables re-populated even if the WURFL URL is not newer than the locally cached copy.
rebuild_tables
The rebuild_tables method is called by the update method if the WURFL URL is more recent than the locally cached copy of wurfl.xml. It can also be called directly if you wish to re-parse the wurfl.xml file and rebuild the database tables without checking (and possibly retrieving) the WURFL URL.
devices
This method returns a list of all the devices in WURFL. This is returned as a list of hashrefs, each of which has keys user_agent, actual_device_root, id, and fall_back.
groups
This method returns a list of the capability groups in WURFL.
capabilities( group )
This method returns a list of the capabilities in a group in WURFL. If no group is given, it returns a list of all the capabilites.
canonical_ua( ua_string )
This method takes a user agent string as an argument, and tries to find a matching "canonical" user agent in WURFL. It does this simply by recursively doing a lookup on the string, and if this fails, chopping anything after and including the last "/" in the string. So, for example, for the user agent string:
SonyEricssonK750i/R1J Browser/SEMC-Browser/4.2 Profile/MIDP-2.0 Configuration/CLDC-1.1the canonical_ua method would try the following:
SonyEricssonK750i/R1J Browser/SEMC-Browser/4.2 Profile/MIDP-2.0 Configuration/CLDC-1.1
SonyEricssonK750i/R1J Browser/SEMC-Browser/4.2 Profile/MIDP-2.0 Configuration
SonyEricssonK750i/R1J Browser/SEMC-Browser/4.2 Profile
SonyEricssonK750i/R1J Browser/SEMC-Browser
SonyEricssonK750i/R1J Browser
SonyEricssonK750iuntil it found a user agent string in WURFL, and then return it (or return undef if none were found). In the above case (for WURFL v2.0) it returns the string "SonyEricssonK750i".
deviceid( ua_string )
This method returns the deviceid for a given user agent string.
device( deviceid )
This method returns a hashref for a given deviceid. The hashref has keys user_agent, actual_device_root, id, and fall_back.
lookup( ua_string, capability, [ no_fall_back => 1 ] )
This method takes a user agent string and a capability name, and returns a hashref representing the capability matching this combination. The hashref has the keys name, value, groupid and deviceid. By default, if a capability has no value for that device, it recursively falls back to its fallback device, until it does find a value. You can discover the device "fallen back to" by accessing the deviceid key of the hash. This behaviour can be controlled by using the "no_fall_back" option.
lookup_value( ua_string, capability, [ no_fall_back => 1 ] )
This method is similar to the lookup method, except that it returns a value instead if a hash.
cleanup()
This method forces the module to DROP all of the database tables it has created, and remove the locally cached copy of wurfl.xml.
AUTHOR
Ave Wrigley <Ave.Wrigley@itn.co.uk>
COPYRIGHT
Copyright (c) 2004 Ave Wrigley. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.