Tatsuhiko Miyagawa > Mac-Spotlight-0.06 > Mac::Spotlight::MDItem

Download:
Mac-Spotlight-0.06.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.06   Source  

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.

syntax highlighting: