package LibTracker::Client;
use 5.008008;
use strict;
use warnings;
use Carp;
require Exporter;
use AutoLoader;
our @ISA = qw(Exporter);
# This allows declaration use LibTracker::Client ':all';
our %EXPORT_TAGS = ( 'all' => [ qw(
DATA_DATE
DATA_NUMERIC
DATA_STRING
DATA_STRING_INDEXABLE
SERVICE_APPLICATIONS
SERVICE_APPOINTMENTS
SERVICE_BOOKMARKS
SERVICE_CONTACTS
SERVICE_CONVERSATIONS
SERVICE_DEVELOPMENT_FILES
SERVICE_DOCUMENTS
SERVICE_EMAILATTACHMENTS
SERVICE_EMAILS
SERVICE_FILES
SERVICE_FOLDERS
SERVICE_HISTORY
SERVICE_IMAGES
SERVICE_MUSIC
SERVICE_OTHER_FILES
SERVICE_PLAYLISTS
SERVICE_PROJECTS
SERVICE_TASKS
SERVICE_TEXT_FILES
SERVICE_VFS_DEVELOPMENT_FILES
SERVICE_VFS_DOCUMENTS
SERVICE_VFS_FILES
SERVICE_VFS_FOLDERS
SERVICE_VFS_IMAGES
SERVICE_VFS_MUSIC
SERVICE_VFS_OTHER_FILES
SERVICE_VFS_TEXT_FILES
SERVICE_VFS_VIDEOS
SERVICE_VIDEOS
) ],
'services' => [ qw(
SERVICE_APPLICATIONS
SERVICE_APPOINTMENTS
SERVICE_BOOKMARKS
SERVICE_CONTACTS
SERVICE_CONVERSATIONS
SERVICE_DEVELOPMENT_FILES
SERVICE_DOCUMENTS
SERVICE_EMAILATTACHMENTS
SERVICE_EMAILS
SERVICE_FILES
SERVICE_FOLDERS
SERVICE_HISTORY
SERVICE_IMAGES
SERVICE_MUSIC
SERVICE_OTHER_FILES
SERVICE_PLAYLISTS
SERVICE_PROJECTS
SERVICE_TASKS
SERVICE_TEXT_FILES
SERVICE_VFS_DEVELOPMENT_FILES
SERVICE_VFS_DOCUMENTS
SERVICE_VFS_FILES
SERVICE_VFS_FOLDERS
SERVICE_VFS_IMAGES
SERVICE_VFS_MUSIC
SERVICE_VFS_OTHER_FILES
SERVICE_VFS_TEXT_FILES
SERVICE_VFS_VIDEOS
SERVICE_VIDEOS
) ],
'metadata' => [ qw(
DATA_DATE
DATA_NUMERIC
DATA_STRING
DATA_STRING_INDEXABLE
) ] );
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
our @EXPORT = ();
our $VERSION = '0.02';
sub AUTOLOAD {
# This AUTOLOAD is used to 'autoload' constants from the constant()
# XS function.
my $constname;
our $AUTOLOAD;
($constname = $AUTOLOAD) =~ s/.*:://;
croak "&LibTracker::Client::constant not defined" if $constname eq 'constant';
my ($error, $val) = constant($constname);
if ($error) { croak $error; }
{
no strict 'refs';
# Fixed between 5.005_53 and 5.005_61
#XXX if ($] >= 5.00561) {
#XXX *$AUTOLOAD = sub () { $val };
#XXX }
#XXX else {
*$AUTOLOAD = sub { $val };
#XXX }
}
goto &$AUTOLOAD;
}
require XSLoader;
XSLoader::load('LibTracker::Client', $VERSION);
# Preloaded methods go here.
# Autoload methods go after =cut, and are processed by the autosplit program.
1;
__END__
=head1 NAME
LibTracker::Client - Perl interfce to libtrackerclient
=head1 SYNOPSIS
use LibTracker::Client qw(:all);
my $name = LibTracker::Client->service_name(0);
my $type = LibTracker::Client->service_type($name);
die "zero somehow is not equal to zero" if( $type != 0 );
my $tracker = LibTracker::Client->get_instance();
print "Tracker version : ", $tracker->get_version();
print "Tracker status : ", $tracker->get_status();
my $main_only = 0;
my $s = $tracker->get_services( $main_only );
while ( my ($key, $val) = each %{$s} ) {
print "$key : $val\n";
}
# searching text and displaying results with snippets
my $searchtext = shift;
my $r = $tracker->search_text(0, SERVICE_FILES, $searchtext, 0, 100);
foreach my $result ( @{$r} ) {
my $snippet = $tracker->get_snippet(SERVICE_FILES, $result, $searchtext);
print "$result : $snippet\n";
}
undef $tracker;
=head1 DESCRIPTION
Tracker is a tool designed to extract information and metadata about your
personal data so that it can be searched easily and quickly.
By using Tracker, you no longer have to remember where you've left your
files. To locate a file you only need to remember something about it, such
as a word in the document or the artist of the song. This is because as well
as searching for files in the traditional way, by name and location, Tracker
searches files' contents and metadata.
Tracker is available from http://www.gnome.org/projects/tracker/
libtrackerclient is the Tracker client library. This module implements the
Perl interface to libtrackerclient.
=head1 INTERFACE
=head2 STATIC METHODS
=over
=item service_name()
args:
servicetype(int) : Service Type Id
Converts the service type to the corresponding name.
=back
=over
=item service_type()
args:
servicename(string) : Service Name
Converts the service name to the corresponding type.
=back
=over
=item get_instance()
args:
none
Establishes a connection to trackerd and returns an instance of this class.
Returns undef on failure. The connection to trackerd is persistent and is
disconnected only when the returned refrence goes out of scope, is undef-ed,
or is otherwise DESTROYed.
=back
=head2 INSTANCE METHODS
=over
=item get_version()
args:
none
Gets the tracker version. Returns undef on failure.
=back
=over
=item get_status()
args:
none
Gets the tracker status. Returns undef on failure.
=back
=over
=item get_services()
args:
mainonly(int) : gets only the main services is this is TRUE
Returns a hashref containing the tracker services. I could only get a reference to an empty hash each time I tried, so I don't really know what this does. It is however, included for completeness.
=back
=over
=item get_metadata()
args:
servicetype(int) : The tracker service type
id(string) : The path of the document for which
metadata is requested
keys(arrayref) : Reference to an array containing
metdata fields.
Returns a hashref with the requested metadata. If the call succeeds, the keys
of the hashref are the keys supplied in the array, and the vlues are the
corresponding values. Returns undef on failure. The call will fail even if
one of the requested keys turns out to be invalid. A list of valid fields
can be obtained with a call to F<get_registered_metadata_classes()>.
=back
=over
=item set_metadata()
args:
servicetype(int) : The tracker service type
id(string) : The path of the document for which
metadata is requested
data(hashref) : Reference to a hash containing
metdata fields and values.
Returns the number of metadata fields set on success. This would always be
equal to the number of keys in the data hash passed to it. Returns undef on
failure. The call will fail even if one of the supplied metadata fields
turns out to be invalid.
A list of valid metadata fields can be obtained with a call to
F<get_registered_metadata_classes()>.
=back
=over
=item register_metdata_type()
args:
name(string) : The name of the metadata type to register
type(int) : The type. One of the DATA_* constants.
Registers the new metadata type. Does not return anything. Croaks on
failure. A metadata type is the metadata field from F<get_metadata()> and
F<set_metadata()>.
=back
=over
=item get_metadata_type_details()
args:
name(string) : The name of the metadata type
Returns a reference blessed into LibTracker::Client::MetaDataTypeDetails on
success. Returns undef on failure.
=back
=over
=item get_registered_metadata_classes()
args:
none
Returns a reference to an array containing the names of the registered
metadata classes. Returns undef on failure.
=back
=over
=item get_registered_metadata_types()
args:
classname(string) : Class name
Returns a reference to an array containing the names of the registered
metadata types for the given class. Returns undef on failure.
=back
=over
=item get_writeable_metadata_types()
args:
classname(string) : Class name
Returns a reference to an array containing the names of the writeable
metadata types for the given class. Returns undef on failure.
=back
=over
=item get_all_keywords()
args:
servicetype(int) : The service type to get keywords for
Returns a reference to an array containing all the tags for the given service
type. Returns undef on failure.
=back
=over
=item get_keywords()
args:
servicetype(int) : service type
id(string) : the path of the file to get the
keywords for
Returns a reference to an array containing the tags for the given path.
Returns undef on failure.
=back
=over
=item add_keywords()
args:
servicetype(int) : service type
id(string) : the path of the file to set the
keywords for
values(arrayref) : keywords to add.
Adds the given keywords to the specified path. On success, returns the
number of keywords added, which is ALWAYS equal to the number of keywords
given. Returns undef on failure.
=back
=over
=item remove_keywords()
args:
servicetype(int) : service type
id(string) : the path of the file to remove the
keywords from
values(arrayref) : keywords to remove.
Removes the given keywords from the specified path. On success, returns the
number of keywords removed, which is ALWAYS equal to the number of keywords
given. Returns undef on failure.
=back
=over
=item remove_all_keywords()
args:
servicetype(int) : service type
id(string) : the path of the file to remove the
keywords from
Removes all the keywords from the specified path. On success, returns a TRUE
value. Returns undef on failure.
=back
=over
=item search_keywords()
args:
lqi(int) : the live query id
servicetype(int) : service type
keywords(arrayref) : keywords to search for
offset(int) : return results from this pos
maxhits(int) : number of hits to return
Searches for the specified keywords with the given parameters. On success,
returns a reference to an array containing the results. Returns undef on
failure.
=back
=over
=item search_text()
args:
lqi(int) : the live query id
servicetype(int) : service type
searchtext(string) : text to search for
offset(int) : return results from this pos
maxhits(int) : number of hits to return
Searches for the specified text with the given parameters. On success,
returns a reference to an array containing the results. Returns undef on
failure.
=back
=over
=item get_snippet()
args:
servicetype(int) : service type
path(string) : the path to get the snippet from
searchtext(string) : text to search for
Returns a snippet matching the searchtext in the specified file. The search
text is enclosed in HTML bold tags. Returns undef on failure.
=back
=over
=item search_metadata()
args:
servicetype(int) : service type
field(string) : the field to search
searchtext(string) : text to search for
offset(int) : return results from this pos
maxhits(int) : number of hits to return
Searches for the specified text in the specified field. Returns a maximum of
maxhits results starting from the given offset. On success, returns a
reference to an array containing the results. Returns undef on failure.
=back
=over
=item get_suggestion()
args:
searchtext(string) : text to search for
maxdist(int) : maximum distance (fuzziness)
Given the search text, returns a close enough suggestion which would yield
search results. Close enough is decided by the maxdist parameter. Returns
undef on failure.
=back
=over
=item get_files_by_service()
args:
lqi(int) : live query id
servicetype(int) : service type
offset(int) : return results from this pos
maxhits(int) : number of hits to return
Returns an arrayref containing the files for the specified service type. A
maximum of maxhits files are returned, starting at the given offset. Returns
undef on failure.
=back
=head2 EXPORT
None by default.
=head2 Exportable constants
DATA_DATE
DATA_NUMERIC
DATA_STRING
DATA_STRING_INDEXABLE
SERVICE_APPLICATIONS
SERVICE_APPOINTMENTS
SERVICE_BOOKMARKS
SERVICE_CONTACTS
SERVICE_CONVERSATIONS
SERVICE_DEVELOPMENT_FILES
SERVICE_DOCUMENTS
SERVICE_EMAILATTACHMENTS
SERVICE_EMAILS
SERVICE_FILES
SERVICE_FOLDERS
SERVICE_HISTORY
SERVICE_IMAGES
SERVICE_MUSIC
SERVICE_OTHER_FILES
SERVICE_PLAYLISTS
SERVICE_PROJECTS
SERVICE_TASKS
SERVICE_TEXT_FILES
SERVICE_VFS_DEVELOPMENT_FILES
SERVICE_VFS_DOCUMENTS
SERVICE_VFS_FILES
SERVICE_VFS_FOLDERS
SERVICE_VFS_IMAGES
SERVICE_VFS_MUSIC
SERVICE_VFS_OTHER_FILES
SERVICE_VFS_TEXT_FILES
SERVICE_VFS_VIDEOS
SERVICE_VIDEOS
=head1 SEE ALSO
The tracker project home at http://www.gnome.org/projects/tracker/
LibTracker::Client specific communication with the author :
ltcp@theoldmonk.net
LibTracker::Client homepage at http://www.theoldmonk.net/ltcp/
=head1 AUTHOR
Devendra Gera, E<lt>gera@theoldmonk.netE<gt>
=head1 COPYRIGHT AND LICENSE
Copyright (C) 2008 by Devendra Gera
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.
=cut