NAME

Mac::Spotlight::MDItem - Examine the results of a Spotlight query

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";
}

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.

METHODS

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

EXPORT

None by default.

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

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

MDItemSecurityMethod

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

SEE ALSO

Mac::Spotlight::MDQuery

AUTHOR

Adrian Hosey, <alh@warhound.org>

Tatsuhiko Miyagawa <miyagawa@bulknews.net>

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.