macFinderInfo

#!/usr/bin/env perl -w
#
# macFinderInfo: Extract and diplay Mac 'finderInfo', etc.
# 2011-04-05: Written by Steven J. DeRose.
#
use strict;
use Getopt::Long;
use Encode;
use XmlTuples;
use sjdUtils;

our %metadata = (
    'title'        => "macFinderInfo",
    'description'  => "Extract and diplay Mac 'finderInfo', etc.",
    'rightsHolder' => "Steven J. DeRose",
    'creator'      => "http://viaf.org/viaf/50334488",
    'type'         => "http://purl.org/dc/dcmitype/Software",
    'language'     => "Perl 5.18",
    'created'      => "2011-04-05",
    'modified'     => "2021-06-14",
    'publisher'    => "http://github.com/sderose",
    'license'      => "https://creativecommons.org/licenses/by-sa/3.0/"
);
our $VERSION_DATE = $metadata{'modified'};

use Cwd 'abs_path';
(my $thisPath = abs_path($0)) =~ s|/[^/]*$||;

=pod

=head1 Usage

finderInfo [options] files

Extract and diplay the 'finderInfo' for a given file, mostly using C<xattr>.
Intended to be more readable than the usual.
Also shows UUID for the partition, volume, and host.


=head1 Options

(prefix 'no' to negate where applicable)

=over

=item * B<--listKeys>

Show a list of common information items. For more details, see C<spotlite> or
L[https://developer.apple.com/documentation/coreservices/file_metadata/mditem/file_system_metadata_attribute_keys].

=item * B<--quiet> OR B<-q>

Suppress most messages.

=item * B<--toHex>

Try to make hex values more readable.

=item * B<--verbose> OR B<-v>

Add more messages (repeatable).

=item * B<--version>

Show version info and exit.

=item * B<--visible>

Translate unusual characters to visible representation.


=back


=head1 Known Bugs and Limitations

Doesn't split out and report individual finderFlags yet (though info is here).


=head1 Related Commands and Files

PyPI package `xattr` gives direct access to get and set these attrs.

F<macOsxSpotlightKeys.xsv>, C<XmlTuples.pm>.
C<whereFrom>, C<pdfinfo>, C<file>, C<xattr>.


=head1 To do

Finish adding PartitionID, VolumeID, getHostID, inode, etc.

Option to get *all* xattr data, and/or to check kMDItemWhereFroms (see xattr -l,
but chop trailing nulls, decode dates, etc.

Do something smarter with (Unicode?) strings.

Parse the internals.

See e.g. https://eclecticlight.co/2017/12/19/xattr-com-apple-finderinfo-information-for-the-finder/
"It’s a FileInfo structure followed by a ExtendedFileInfo structure. These are
located in the CoreServices Framework (CarbonCore>Finder.h>)."
https://opensource.apple.com/source/CarbonHeaders/CarbonHeaders-8A428/Finder.h

struct FileInfo {
  OSType      fileType;               /* The type of the file (4 bytes) */
  OSType      fileCreator;            /* The file's creator */
  UInt16      finderFlags;            /* ex: kHasBundle, kIsInvisible... */
  Point       location;               /* File's location in the folder */
      /* If set to {0, 0}, the Finder will place the item automatically */
  UInt16      reservedField;          /* (set to 0) */
};
typedef struct FileInfo                 FileInfo;

struct FolderInfo {
  Rect        windowBounds;           /* The position and dimension of the folder's window */
  UInt16      finderFlags;            /* ex. kIsInvisible, kNameLocked, etc.*/
  Point       location;               /* Folder's location in the parent folder */
      /* If set to {0, 0}, the Finder will place the item automatically */
  UInt16      reservedField;          /* (set to 0) */
};
typedef struct FolderInfo               FolderInfo;

struct ExtendedFileInfo {
  SInt16      reserved1[4];           /* Reserved (set to 0) */
  UInt16      extendedFinderFlags;    /* Extended flags (custom badge, routing info...) */
  SInt16      reserved2;              /* Reserved (set to 0). Comment ID if high-bit is clear */
  SInt32      putAwayFolderID;        /* Put away folder ID */
};
typedef struct ExtendedFileInfo         ExtendedFileInfo;

struct ExtendedFolderInfo {
  Point       scrollPosition;         /* Scroll position (for icon views) */
  SInt32      reserved1;              /* Reserved (set to 0) */
  UInt16      extendedFinderFlags;    /* Extended flags (custom badge, routing info...) */
  SInt16      reserved2;              /* Reserved (set to 0). Comment ID if high-bit is clear */
  SInt32      putAwayFolderID;        /* Put away folder ID */
};

/* Finder flags and Extended flags -- see below */


=head1 History

  2011-04-05: Written by Steven J. DeRose.
  2018-09-20: Handles paths containing spaces etc.
  2020-07-13: New layout.
  2020-08-11: Fix decoding/display of utf-8 value, ";"-delimited list values.
  2021-06-14: Add --visible.


=head1 Ownership

Copyright 2011-04-05 by Steven J. DeRose. This work is licensed under a
Creative Commons Attribution-Share Alike 3.0 Unported License.
For further information on this license, see
L<https://creativecommons.org/licenses/by-sa/3.0>.

For the most recent version, see L<http://www.derose.net/steve/utilities> or
L<https://github.com/sderose>.


=cut


###############################################################################
#
my %finderFlags = (
    kIsOnDesk       => 0x0001,
    kColor          => 0x000E,
    kIsShared       => 0x0040,
    kHasNoINITs     => 0x0080,
    kHasBeenInited  => 0x0100,
    kHasCustomIcon  => 0x0400,
    kIsStationery   => 0x0800,
    kNameLocked     => 0x1000,
    kHasBundle      => 0x2000,
    kIsInvisible    => 0x4000,
    kIsAlias        => 0x8000,
    );

my %extendedFinderFlags = (
    kExtendedFlagsAreInvalid => 0x8000,
    kExtendedFlagHasCustomBadge => 0x0100,
    kExtendedFlagObjectIsBusy => 0x0080,
    kExtendedFlagHasRoutingInfo => 0x0004,
    );

my @defaultColors = (
    "none", "red", "orange", "yellow", "green", "blue", "purple", "gray"
);

my %cAliasFile = (
    cAliasFile => 'alia',
    cApplicationFile => 'appf',
    cControlPanelFile => 'ccdv',
    cDeskAccessoryFile => 'dafi',
    cDocumentFile => 'docf',
    cFontFile => 'fntf',
    cSoundFile => 'sndf',
    cClippingFile => 'clpf',
    cContainer => 'ctnr',
    cDesktop => 'cdsk',
    cSharableContainer => 'sctr',
    cDisk => 'cdis',
    cFolder => 'cfol',
    cSuitcase => 'stcs',
    cAccessorySuitcase => 'dsut',
    cFontSuitcase => 'fsut',
    cTrash => 'ctrs',
    cDesktopPrinter => 'dskp',
    cPackage => 'pack',
    cContentSpace => 'dwnd',
    cContainerWindow => 'cwnd',
    cInfoWindow => 'iwnd',
    cSharingWindow => 'swnd',
    cStatusWindow => 'qwnd',
    cClippingWindow => 'lwnd',
    cPreferencesWindow => 'pwnd',
    cDTPWindow => 'dtpw',
    cProcess => 'prcs',
    cAccessoryProcess => 'pcda',
    cApplicationProcess => 'pcap',
    cGroup => 'sgrp',
    cUser => 'cuse',
    cSharingPrivileges => 'priv',
    cPreferences => 'cprf',
    cLabel => 'clbl',
    cSound => 'snd ',
    cAliasList => 'alst',
    cSpecialFolders => 'spfl',
    cOnlineDisk => 'cods',
    cOnlineLocalDisk => 'clds',
    cOnlineRemoteDisk => 'crds',
    cEntireContents => 'ects',
    cIconFamily => 'ifam',
    );

# These appear as 'com.apple.metadata:'...
my %others = (
    kMDItemDownloadedDate => 1,
    kMDItemWhereFroms => 1,
);

my $fmt = "  %-16s = '%s'\n";


###############################################################################
# Options
#
my $quiet         = 0;
my $keyFile       = "$thisPath/macOsxSpotLightKeys.xsv";
my $listKeys      = 0;
my $toHex         = 0;
my $verbose       = 0;
my $visible       = 1;

Getopt::Long::Configure ("ignore_case");
my $result = GetOptions(
    "h|help"      => sub { system "perldoc $0"; exit; },
    "listKeys!"   => \$listKeys,
    "q!"          => \$quiet,
    "toHex!"      => \$toHex,
    "v+"          => \$verbose,
    "version"     => sub {
        die "Version of $VERSION_DATE, by Steven J. DeRose.\n";
    },
    "visible!"    => \$visible,
    );

($result) || die "Bad options.\n";


###############################################################################
# Main
#
if ($listKeys) {
    listKeys();
    exit;
}

(scalar(@ARGV)) || die "No file(s) specified.\n";

while (my $file = shift) {
    (!$quiet) && warn "\n*** Starting file '$file'\n";
    doOneFile($file);
}

exit;


###############################################################################
#
sub listKeys {
    my $foo = new XmlTuples();
    $foo->open($keyFile) || die
        "Couldn't open list of Spotlight keys from '$keyFile'.\n"; # FIX
    my $keysRef = $foo->getAllAsHash("Key"); # FIX

    warn("\nKey names start with 'kMDItem' (not shown below). Key file: \n");
    warn("  $keyFile\n");
    for my $k (sort(keys(%{$keysRef}))) {
        (my $shortKey = $k) =~ s/^kMDItem//;
        warn(sprintf("%-24s", $shortKey) .
            " " . $keysRef->{$k}->{"Typ"} .
            "\n" . wrap($keysRef->{$k}->{"Dsc"}, 4));
    }
    warn("Total keys known: " . scalar(keys(%{$keysRef})) . ".\n");
}


sub doOneFile {
    my ($file) = @_;
    my @attrNames = `xattr '$file'`;  # Typically returns 'com.apple.FinderInfo'

    for my $name (@attrNames) {
        #($verbose) && warn "Fetching xattr '$name'.\n";
        chomp $name;
        my $cmd = "xattr -p $name '$file'";
        my $val = `$cmd`;
        print "  '$name'\n";
        if ($val =~ m/;.*;/) {
            print "    =(array?): [\n";
            chomp $val;
            my @entries = split /;/, $val;
            print "      " . join(";\n      ", @entries) . "\n    ]\n";
        }
        elsif (" $val" =~ m/^(\s[0-9A-F][0-9A-F])+\s*$/s) {
            print "    =(raw string): ###$val###\n";
            (length($val)/3 == 32) || warn
                sprintf("Length is %d, not 32.\n", length($val)/3);
            print "    =(hex string): '" . x2str($val) . "'\n";
        }
        else {
            print "    =(raw string): ###$val###\n";
        }
    }

    print("Partition UUID: %s", getPartitionID($file));
    print("Volume UUID: %s", getVolumeID($file));
    print("Host UUID: %s", getHostID($file));
}

sub getPartitionID {
    my ($file) = @_;
    return "???";
}

sub getVolumeID {
    my ($file) = @_;
    return "???";
}

sub getHostID {
    my ($file) = @_;
    return "???";
}


###############################################################################
#
BEGIN {
    my $theString = undef;
    my $theOffset = 0;

    sub setHexString {
        my ($s) = @_;
        $theString = $s;
        $theOffset = 0;
    }
    sub nextN {
        my ($n) = @_;
        my $buf = substr($theString, $theOffset, $n);
        $theOffset += $n;
        return($buf);
    }
} # END

# Convert a string like this to characters:
#     00 00 00 00 00 00 00 00 40 00 00 00...
# Doesn't handle utf8 or ucs2.
#
sub x2str {
    my ($s) = @_;
    my $buf = "";
    Encode::decode('utf8', $s);
    if ($toHex) {
        while ($s =~ m/\s*([0-9a-f][0-9a-f])/ig) {
            my $x = hex("0x".$1);
            my $c = chr($x);
	        $buf .= $c;
        }
    }
    if ($visible) { $buf = sjdUtils::showInvisibles($buf); }
    return($buf);
}

sub x2int {
    my ($s) = @_;
    return(hex("0x".$s));
}