/ 
Mobile-Wurfl-1.09
River stage zero No dependents
/ Mobile::Wurfl

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://sourceforge.net/projects/wurfl/files/WURFL/latest/wurfl-latest.xml.gz/download},
);

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();

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://kent.dl.sourceforge.net/sourceforge/wurfl/wurfl-latest.xml.gz.

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://sourceforge.net/projects/wurfl/files/WURFL/latest/wurfl-latest.xml.gz/download},,
    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 /tmp.

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".

dbh

A DBI database handle.

wurfl_url

The URL from which to get the wurfl.xml file, this can be uncompressed or compressed with zip or gzip Default is http://sourceforge.net/projects/wurfl/files/WURFL/latest/wurfl-latest.xml.gz/download.

verbose

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.

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

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.

rebuild_tables

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.

get_wurfl

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.

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.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".

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.