Mobile::Wurfl - a perl module interface to WURFL (the Wireless Universal Resource File - http://wurfl.sourceforge.net/).
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://wurfl.sourceforge.net/wurfl.xml} ); my $dbh = DBI->connect( $db_descriptor, $db_username, $db_password ); my $wurfl = Mobile::Wurfl->new( dbh => $dbh ); my $desc = $wurfl->get( 'db_descriptor' ); $wurfl->set( wurfl_home => "/another/path" ); $wurfl->create_tables( $sql ); $wurfl->update(); $wurfl->get_wurfl(); $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();
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.
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://wurfl.sourceforge.net/wurfl.xml}, verbose => 1, );
The list of possible options are as follows:
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.
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.
The username used to connect to the database defined by "METHODS/new/db_descriptor". Default is "wurfl".
The password used to connect to the database defined by "METHODS/new/db_descriptor". Default is "wurfl".
A DBI database handle.
The URL from which to get the wurfl.xml file. Default is http://www.nusho.it/wurfl/dl.php?t=d&f=wurfl.xml.
If set to a true value, various status messages will be output. If value is 1, these messages will be written to a logfile called wurfl.log in "METHODS/new/wurfl_home", if > 1 to STDERR.
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" );
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.
The update method is called to update the database tables with the latest information from wurfl.xml. It calls get_wurfl, and then rebuild_tables, each of which work out what if anything needs to be done (see below). It returns true if there has been an update, and false otherwise.
The rebuild_tables method is called by the update method. It checks the modification time of the locally cached copy of the wurfl.xml file against the last modification time on the database, and if it is greater, rebuilds the database table from the wurfl.xml file.
The get_wurfl method is called by the update method. It 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.
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.
user_agent
actual_device_root
id
fall_back
This method returns a list of the capability groups in WURFL.
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.
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.1
the 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 SonyEricssonK750i
until 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".
This method returns the deviceid for a given user agent string.
This method returns a hashref for a given deviceid. The hashref has keys user_agent, actual_device_root, id, and fall_back.
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.
name
value
groupid
deviceid
This method is similar to the lookup method, except that it returns a value instead if a hash.
This method forces the module to DROP all of the database tables it has created, and remove the locally cached copy of wurfl.xml.
DROP
Ave Wrigley <Ave.Wrigley@itn.co.uk>
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.
To install Mobile::Wurfl, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mobile::Wurfl
CPAN shell
perl -MCPAN -e shell install Mobile::Wurfl
For more information on module installation, please visit the detailed CPAN module installation guide.