Clive Darke > Win32-StreamNames-1.04 > Win32::StreamNames

Download:
Win32-StreamNames-1.04.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.04   Source  

NAME ^

Win32::StreamNames - Perl extension for reading Windows ADS names

SYNOPSIS ^

  use Win32::StreamNames;
  @streams = StreamNames( $file );
  
  if (@streams)
  {
     ...
  }
  else
  {
     # No Additional Data Stream names
     ...
  }

DESCRIPTION ^

Data Streams have always been a feature of Windows, but support for them was reinforced with NTFS 5 on Windows 2000. With an additional data stream, a simple file can be 'extended' to include other data, and Windows Explorer does just that with its Summary Information (from the file Properties dialog). The stream itself is seen by Perl as a separate file for I/O purposes, but is invisible when scanning a directory using glob or readdir.

To get at the stream names associated with a file requires calls to the BackupRead Win32 API (and a few other bits and pieces), This module provides a simple wrapper to the API calls.

The only external function, StreamNames, takes a file or directory name as an argument, and returns a list of stream names. These may be appended to the original filename to get a fully qualified name, which may be opened using the usual Perl functions.

If the specified file or directory cannot be opened then $^E ($EXTENDED_OS_ERROR) is set and an empty list is returned. Note that an empty list is not necessarily an error, since a file need not have any additional streams.

For example:

   for $file ( glob("*.txt") ) 
   {
      @list = StreamNames($file);
   
      if (!@list && $^E)
      {
         print STDERR "Unable to open $file: $^E\n";
         next
      }
   
      for $stream (@list)
      {
         open (HANDLE, $file.$stream) || 
               die "Unable to open $file$stream: $!";
            
         binmode HANDLE;
         while (<HANDLE>)
         {
            # Do some stuff

         }

         close HANDLE;
      }
   
   }

NOTES

The SummaryInformation stream names used by Windows Explorer contain a non-ASCII character (0x05). Perl can happily open a file with such a name but it might surprise you (it is displayed as a playing card 'spade' symbol).

Microsoft Office applications such as Word do no use additional data streams, but store their summary information in internal fields.

The module now supports directory names, as well as files.

EXPORT

StreamNames

SEE ALSO ^

Win32::API provides a generic interface to APIs in kernel32.dll

BUGS ^

Versions prior to 1.03 had a bug where empty ADS files were not listed. Versions prior to 1.04 had a bug where empty ADS files terminated the list. Thanks to Frederic Medico for reporting these.

AUTHOR ^

Clive Darke, <clive.darke @ talk21.com> With thanks to Geert VAN ACKER for the directory suggestion

COPYRIGHT AND LICENSE ^

Copyright (C) 2005, 2007, 2008, 2009 by Clive Darke

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.0 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: