package Mac::Spotlight::MDItem;
use 5.008;
use strict;
use warnings;
require Exporter;
our @ISA = qw(Exporter);
# FIXME: We could auto-created these with AUTOLOAD but then how to get
# them into the caller's namespace?
our %EXPORT_TAGS = ( 'constants' => [ qw(
kMDItemAttributeChangeDate
kMDItemAudiences
kMDItemAuthors
kMDItemCity
kMDItemComment
kMDItemContactKeywords
kMDItemContentCreationDate
kMDItemContentModificationDate
kMDItemContentType
kMDItemContributors
kMDItemCopyright
kMDItemCountry
kMDItemCoverage
kMDItemCreator
kMDItemDescription
kMDItemDueDate
kMDItemDurationSeconds
kMDItemEmailAddresses
kMDItemEncodingApplications
kMDItemFinderComment
kMDItemFonts
kMDItemHeadline
kMDItemIdentifier
kMDItemInstantMessageAddresses
kMDItemInstructions
kMDItemKeywords
kMDItemKind
kMDItemLanguages
kMDItemLastUsedDate
kMDItemNumberOfPages
kMDItemOrganizations
kMDItemPageHeight
kMDItemPageWidth
kMDItemPhoneNumbers
kMDItemProjects
kMDItemPublishers
kMDItemRecipients
kMDItemRights
kMDItemSecurityMethod
kMDItemStarRating
kMDItemStateOrProvince
kMDItemTextContent
kMDItemTitle
kMDItemVersion
kMDItemWhereFroms
kMDItemPixelHeight
kMDItemPixelWidth
kMDItemColorSpace
kMDItemBitsPerSample
kMDItemFlashOnOff
kMDItemFocalLength
kMDItemAcquisitionMake
kMDItemAcquisitionModel
kMDItemISOSpeed
kMDItemOrientation
kMDItemLayerNames
kMDItemWhiteBalance
kMDItemAperture
kMDItemProfileName
kMDItemResolutionWidthDPI
kMDItemResolutionHeightDPI
kMDItemExposureMode
kMDItemExposureTimeSeconds
kMDItemEXIFVersion
kMDItemAlbum
kMDItemHasAlphaChannel
kMDItemRedEyeOnOff
kMDItemMeteringMode
kMDItemMaxAperture
kMDItemFNumber
kMDItemExposureProgram
kMDItemExposureTimeString
kMDItemAudioBitRate
kMDItemCodecs
kMDItemDeliveryType
kMDItemMediaTypes
kMDItemStreamable
kMDItemTotalBitRate
kMDItemVideoBitRate
kMDItemAppleLoopDescriptors
kMDItemAppleLoopsKeyFilterType
kMDItemAppleLoopsLoopMode
kMDItemAppleLoopsRootKey
kMDItemAudioChannelCount
kMDItemAudioEncodingApplication
kMDItemAudioSampleRate
kMDItemAudioTrackNumber
kMDItemComposer
kMDItemIsGeneralMIDISequence
kMDItemKeySignature
kMDItemLyricist
kMDItemMusicalGenre
kMDItemMusicalInstrumentCategory
kMDItemMusicalInstrumentName
kMDItemRecordingDate
kMDItemRecordingYear
kMDItemTempo
kMDItemTimeSignature
kMDItemDisplayName
kMDItemFSContentChangeDate
kMDItemFSCreationDate
kMDItemFSExists
kMDItemFSInvisible
kMDItemFSIsExtensionHidden
kMDItemFSIsReadable
kMDItemFSIsWriteable
kMDItemFSLabel
kMDItemFSName
kMDItemFSNodeCount
kMDItemFSOwnerGroupID
kMDItemFSOwnerUserID
kMDItemFSSize
kMDItemPath
) ] );
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'constants'} } );
our @EXPORT = qw();
our $VERSION = '0.06';
require XSLoader;
XSLoader::load('Mac::Spotlight::MDItem', $VERSION);
sub new {
my ($class, $path) = @_;
my $mditem = _new($path) or return;
bless { mdiObj => $mditem, _standalone => 1 }, $class;
}
sub get {
my ($self, $attr) = @_;
return _get($self->{mdiObj}, $attr);
}
sub DESTROY {
my $self = shift;
_destroy($self->{mdiObj}) if $self->{_standalone};
}
1;
__END__
# Below is stub documentation for your module. You'd better edit it!
=head1 NAME
Mac::Spotlight::MDItem - Examine the results of a Spotlight query
=head1 SYNOPSIS
use Mac::Spotlight::MDItem ':constants';
my $item = Mac::Spotlight::MDItem->new("/Users/miyagawa/Pictures/Hawaii.jpg");
print $item->get(kMDItemKind), "\n"; # JPEG image
use Mac::Spotlight::MDQuery ':constants';
my $mdq = new Mac::Spotlight::MDQuery('kMDItemTitle == "*Battlestar*"c');
$mdq->setScope(kMDQueryScopeComputer);
$mdq->execute();
$mdq->stop();
my @results = $mdq->getResults();
for my $r (@results) {
print $r->get(kMDItemTitle), "\n";
print $r->get(kMDItemKind), "\n";
my $listref = $r->get(kMDItemAuthors);
foreach $a (@$listref) {
print "$a\n";
}
if ($r->get(kMDItemStreamable)) {
print "Content is streamable\n";
}
print scalar localtime($r->get(kMDItemContentCreationDate)), "\n";
}
=head1 DESCRIPTION
Mac::Spotlight is primarily accessed through two subpackages MDQuery
and MDItem. An MDQuery object is used to run a query and obtain the
results. The results are in a list containing zero or more MDItem
objects. This POD documents the methods of MDItem, including all of
the attributes which can be search criteria or search results. See the
POD for MDQuery for the details of setting up and executing a
Spotlight query.
=head1 METHODS
=over 4
=item C<get>
The result of calling MDQuery::getResults() is a list of zero or more
blessed MDItem objects. MDItem objects support only one method, get(),
but the things you can get with get() are many and varied.
get() takes one argument, which is a kMDItem* constant indicating the
attribute you wish to retrieve. The return value of get() is always a
single scalar. That scalar may be a string, a number, or a reference
depending on which attribute key you requested. An attribute key can
theoretically return anything but in practice the types of returned
values are limited to a handful.
For the complete list of MDItem attribute keys and what they return,
refer to L<http://developer.apple.com/documentation/Carbon/Reference/MDItemRef/Reference/chapter_1.3_section_1.html>. Check the EXPORTS section of this
POD for a list of the attributes currently supported by
Mac::Spotlight. Below we describe how the returned Core Foundation
values are translated into Perl values. But first the rule: get()
returns undef IF AND ONLY IF the requested attribute does not exist
for this MDItem. undef is never a legitimate return value for an
attribute and undef does not signal an error. undef only means that
the requested attribute does not exist for this item. For example,
most files which are not songs or pictures will not have a
kMDItemAlbum.
If an attribute key is documented as returning a CFString, the scalar
returned by get() will contain a UTF-8 encoded string.
If an attribute key is documented as returning a CFDate, get() will
return a string which is the date formatted as if you had called
"scalar localtime($somevalue)" in Perl.
If an attribute key returns a CFNumber, get() will return a I<floating
point> value in the scalar.
If an attribute key returns a CFBoolean, get() will return either 1 or
0. Never undef! Remember the rule.
If an attribute key returns a CFArray, get() will return a reference
to an anonymous list which contains scalars translated according to
whether the CFArray held CFStrings, CFDates, etc.
=head2 EXPORT
None by default.
=head2 Exportable values
If you use the ":constants" tag when you use Mac::Spotlight::MDItem,
you will pull the kMDItem* constants into your current namespace. If
you chose not to you can still access the constants via their fully
qualified namespace.
Here is a list of all the currently defined kMDItem* constants. For a
description of what each one means, and what each returns, refer to
L<http://developer.apple.com/documentation/Carbon/Reference/MDItemRef/index.html>. If you see attributes on the web page which are not listed here,
Apple has added new attributes and Mac::Spotlight needs to catch up.
=over
=item kMDItemAttributeChangeDate
=item kMDItemAudiences
=item kMDItemAuthors
=item kMDItemCity
=item kMDItemComment
=item kMDItemContactKeywords
=item kMDItemContentCreationDate
=item kMDItemContentModificationDate
=item kMDItemContentType
=item kMDItemContributors
=item kMDItemCopyright
=item kMDItemCountry
=item kMDItemCoverage
=item kMDItemCreator
=item kMDItemDescription
=item kMDItemDueDate
=item kMDItemDurationSeconds
=item kMDItemEmailAddresses
=item kMDItemEncodingApplications
=item kMDItemFinderComment
=item kMDItemFonts
=item kMDItemHeadline
=item kMDItemIdentifier
=item kMDItemInstantMessageAddresses
=item kMDItemInstructions
=item kMDItemKeywords
=item kMDItemKind
=item kMDItemLanguages
=item kMDItemLastUsedDate
=item kMDItemNumberOfPages
=item kMDItemOrganizations
=item kMDItemPageHeight
=item kMDItemPageWidth
=item kMDItemPhoneNumbers
=item kMDItemProjects
=item kMDItemPublishers
=item kMDItemRecipients
=item kMDItemRights
=item MDItemSecurityMethod
=item kMDItemStarRating
=item kMDItemStateOrProvince
=item kMDItemTextContent
=item kMDItemTitle
=item kMDItemVersion
=item kMDItemWhereFroms
=item kMDItemPixelHeight
=item kMDItemPixelWidth
=item kMDItemColorSpace
=item kMDItemBitsPerSample
=item kMDItemFlashOnOff
=item kMDItemFocalLength
=item kMDItemAcquisitionMake
=item kMDItemAcquisitionModel
=item kMDItemISOSpeed
=item kMDItemOrientation
=item kMDItemLayerNames
=item kMDItemWhiteBalance
=item kMDItemAperture
=item kMDItemProfileName
=item kMDItemResolutionWidthDPI
=item kMDItemResolutionHeightDPI
=item kMDItemExposureMode
=item kMDItemExposureTimeSeconds
=item kMDItemEXIFVersion
=item kMDItemAlbum
=item kMDItemHasAlphaChannel
=item kMDItemRedEyeOnOff
=item kMDItemMeteringMode
=item kMDItemMaxAperture
=item kMDItemFNumber
=item kMDItemExposureProgram
=item kMDItemExposureTimeString
=item kMDItemAudioBitRate
=item kMDItemCodecs
=item kMDItemDeliveryType
=item kMDItemMediaTypes
=item kMDItemStreamable
=item kMDItemTotalBitRate
=item kMDItemVideoBitRate
=item kMDItemAppleLoopDescriptors
=item kMDItemAppleLoopsKeyFilterType
=item kMDItemAppleLoopsLoopMode
=item kMDItemAppleLoopsRootKey
=item kMDItemAudioChannelCount
=item kMDItemAudioEncodingApplication
=item kMDItemAudioSampleRate
=item kMDItemAudioTrackNumber
=item kMDItemComposer
=item kMDItemIsGeneralMIDISequence
=item kMDItemKeySignature
=item kMDItemLyricist
=item kMDItemMusicalGenre
=item kMDItemMusicalInstrumentCategory
=item kMDItemMusicalInstrumentName
=item kMDItemRecordingDate
=item kMDItemRecordingYear
=item kMDItemTempo
=item kMDItemTimeSignature
=item kMDItemDisplayName
=item kMDItemFSContentChangeDate
=item kMDItemFSCreationDate
=item kMDItemFSExists
=item kMDItemFSInvisible
=item kMDItemFSIsExtensionHidden
=item kMDItemFSIsReadable
=item kMDItemFSIsWriteable
=item kMDItemFSLabel
=item kMDItemFSName
=item kMDItemFSNodeCount
=item kMDItemFSOwnerGroupID
=item kMDItemFSOwnerUserID
=item kMDItemFSSize
=item kMDItemPath
=back
=head1 SEE ALSO
Mac::Spotlight::MDQuery
=head1 AUTHOR
Adrian Hosey, E<lt>alh@warhound.orgE<gt>
Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
=head1 COPYRIGHT AND LICENSE
Copyright (C) 2005 by Adrian Hosey
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.6 or,
at your option, any later version of Perl 5 you may have available.
=cut