Code Beach: Show

NDAlias

Language: Objective-C, Author: Nathan Day
License: Public domain

NDAlias is a wrapper for Apples Alias Records, there is and optional category that add methods for initialising NDAliases from alias files and writing NDAliases to alias files but this is not it's main function of NDAlias.

NDAlias source preview

/*
 *  NDAlias+AliasFile.m category
 *  NDAliasProject
 *
 *  Created by Nathan Day on Tue Dec 03 2002.
 *  Copyright (c) 2002 Nathan Day. All rights reserved.
 */

#import "NDAlias+AliasFile.h"
#import "NDResourceFork.h"
#import "NSURL+NDCarbonUtilities.h"
#import "NDResourceFork+OtherSorces.h"

//const ResType  aliasResourceType = 'alis';
const OSType  finderCreatorCode = 'MACS';
const short    aliasRecordId = 0;
//          customIconID = -16496;

@implementation NDAlias (AliasFile)

OSType aliasOSTypeFor( NSURL * aURL );

+ (id)aliasWithContentsOfFile:(NSString *)aPath
{
  return [[[self alloc] initWithContentsOfFile:aPath] autorelease];
}

+ (id)aliasWithContentsOfURL:(NSURL *)aURL
{
  return [[[self alloc] initWithContentsOfURL:aURL] autorelease];
}

- (id)initWithContentsOfFile:(NSString *)aPath
{
  NDResourceFork    * theResourcFork;
  theResourcFork = [[NDResourceFork alloc] initForReadingAtPath:aPath];

  self = [self initWithData:[theResourcFork dataForType:formAlias Id:aliasRecordId]];

  [theResourcFork release];

  return self;
}

- (id)initWithContentsOfURL:(NSURL *)aURL
{
  NDResourceFork    * theResourcFork;
  theResourcFork = [[NDResourceFork alloc] initForReadingAtURL:aURL];

  self = [self initWithData:[theResourcFork dataForType:formAlias Id:aliasRecordId]];

  [theResourcFork release];

  return self;
}

- (BOOL)writeToFile:(NSString *)aPath
{
  return [self writeToURL:[NSURL fileURLWithPath:aPath]];
}

- (BOOL)writeToURL:(NSURL *)aURL
{
  BOOL          theSuccess;
  NDResourceFork    * theResourcFork;
  
  theResourcFork = [[NDResourceFork alloc] initForWritingAtURL:aURL];
  theSuccess = [theResourcFork addData:[self data] type:formAlias Id:aliasRecordId name:@"created by NDAlias"];

  if( theSuccess )
  {
    UInt16    theFlags;
    OSType    theAliasType,
            theAliasCreator,
            theTargetType,
            theTargetCreator;
    NSURL      * theTargetURL;

    theTargetURL = [self url];

    [[self url] finderInfoFlags:&theFlags type:&theTargetType creator:&theTargetCreator];

    theAliasType = aliasOSTypeFor( theTargetURL );  // get the alias type

    if( theAliasType == 0 )  // 0 alias type means doc which just takes the targets type
    {
      theAliasCreator = theTargetCreator;
      theAliasType = theTargetType;
    }
    else  // special alias types take the finder creator code
    {
      theAliasCreator = finderCreatorCode;
    }

    // item with custom icon as well as apps need to have a custoime icon for the alias
    if( (theAliasType == 0 ) || (theFlags & kHasCustomIcon) || (theAliasType == kAppPackageAliasType) || (theAliasType == kApplicationAliasType) )
    {
      NSData    * theIconFamilyData;
      
      theIconFamilyData = [NDResourceFork iconFamilyDataForURL:theTargetURL];
      
      if( [theResourcFork addData:theIconFamilyData type:kIconFamilyType Id:kCustomIconResource name:@""] )
        [aURL setFinderInfoFlags:kIsAlias | kHasCustomIcon mask:kIsAlias | kHasCustomIcon type:theAliasType creator:theAliasCreator];
    }
    else
    {
      [aURL setFinderInfoFlags:kIsAlias mask:kIsAlias | kHasCustomIcon type:theAliasType creator:theAliasCreator];
    }
  }

  [theResourcFork release];
  return theSuccess;
}

OSType aliasOSTypeFor( NSURL * aURL )
{
  LSItemInfoRecord  theItemInfo;
  OSType        theType = kContainerFolderAliasType;
    
  /*
  * alias files to documents take on the targets type and creator
  * alias files to others take on special types and finder creator
  */
  if( LSCopyItemInfoForURL( (CFURLRef)aURL, kLSRequestBasicFlagsOnly, &theItemInfo) == noErr)
  {
    if( (theItemInfo.flags & kLSItemInfoIsApplication) && (theItemInfo.flags & kLSItemInfoIsPackage) )  // package app
    {
      theType = kAppPackageAliasType;
    }
    else if( theItemInfo.flags & kLSItemInfoIsApplication )  // straight app
    {
      theType = kApplicationAliasType;
    }
    else if( theItemInfo.flags & kLSItemInfoIsPlainFile )  // document
    {
      theType = 0;    // straight documents don't have a special alias type
    }
    else if( theItemInfo.flags & kLSItemInfoIsPackage )  // package
    {
      theType = kPackageAliasType;
    }
    else if( theItemInfo.flags & kLSItemInfoIsVolume )  // disk
    {
      theType = kContainerHardDiskAliasType;
    }
  }

  return theType;
}

@end

NDAlias header preview

/*!
  @header NDAlias
  @abstract Declare the interface for the class NDAlias.
  @discussion <tt>NDAlias</tt> is a wrapper class for Apples Alias Manager.

  @created Wed Dec 05 2001
  @copyright &#169; 2001 Nathan Day. All rights reserved.
 */

#import <Foundation/Foundation.h>

/*!
  @class NDAlias
  @abstract A class to access the Alias Manager from Cocoa 
  @discussion Your application can use a <tt>NDAlias</tt> to refere to file system objects (that is, files, directories, and volumes) in a way that does expect the file system objects path to be maintained. The user then can move or rename the file system object with out your program lossing track of it. This behaviour is not always desirable, for intance with library resources. But for file system objects like documents of user folders, it is what Mac OS users have come to expect.
  @version 1.1
 */
@interface NDAlias : NSObject <NSCoding>
{
  AliasHandle    aliasHandle;
  Boolean      changed;
  unsigned long  mountFlags;
}

/*!
  @functiongroup Creating an alias
 */

/*!
  @method aliasWithURL:
  @abstract Creates and initalises a <tt>NDAlias</tt>.
  @discussion The method <tt>aliasWithURL:</tt> creates an <tt>NDAlias</tt> that contains only the minimum information necessary to describe the target: the target name, the parent directory ID, the volume name and creation date, and the volume mounting information. The <tt>aliasWithURL:</tt> method uses the standard alias record data structure, but it fills in only parts of the record.
  <p>The methods <tt>url</tt> and <tt>path</tt> never update a minimal alias record.</p>
  @param URL the file url for the target of the alias.
  @result A <tt>NDAlias</tt> instance, returns <tt>nil</tt> if <tt>NDAlias</tt> creation fails.
  */
+ (id)aliasWithURL:(NSURL *)URL;
/*!
  @method aliasWithURL:fromURL:
   @abstract Creates and initalises a <tt>NDAlias</tt>.
   @discussion  The method <tt>aliasWithURL:fromURL:</tt> creates a <tt>NDAlias</tt> that describes the specified target. <tt>aliasWithURL:fromURL:</tt> always records the name and file or directory ID of the target, its creation date, the parent directory name and ID, and the volume name and creation date. It also records the full pathname of the target and a collection of other information relevant to locating the target, verifying the target, and mounting the target's volume, if necessary. <tt>aliasWithURL:fromURL:</tt> also stores relative path information as well by supplying a starting point for a relative path.
  @param URL the file url for the target of the alias.
  @param fromURL The starting point for a relative path, to be used later in a relative search. The two file or directory url's, <tt>fromURL</tt> and <tt>URL</tt>, must reside on the same volume.
  @result A <tt>NDAlias</tt> instance, returns <tt>nil</tt> if <tt>NDAlias</tt> creation fails.
 */
+ (id)aliasWithURL:(NSURL *)URL fromURL:(NSURL *)fromURL;
/*!
  @method aliasWithPath:
  @abstract Creates and initalises a <tt>NDAlias</tt>.
  @discussion The method <tt>aliasWithPath:</tt> creates an <tt>NDAlias</tt> that contains only the minimum information necessary to describe the target: the target name, the parent directory ID, the volume name and creation date, and the volume mounting information. The <tt>aliasWithPath:</tt> method uses the standard alias record data structure, but it fills in only parts of the record.
  <p>The methods <tt>url</tt> and <tt>path</tt> never update a minimal alias record.</p>
  @param path the path for the target of the alias.
  @result A <tt>NDAlias</tt> instance, returns <tt>nil</tt> if <tt>NDAlias</tt> creation fails.
 */
+ (id)aliasWithPath:(NSString *)path;
/*!
  @method aliasWithPath:fromPath:
   @abstract Creates and initalises a <tt>NDAlias</tt>.
   @discussion  The method <tt>aliasWithPath:fromPath:</tt> creates a <tt>NDAlias</tt> that describes the specified target. <tt>aliasWithPath:fromPath:</tt> always records the name and file or directory ID of the target, its creation date, the parent directory name and ID, and the volume name and creation date. It also records the full pathname of the target and a collection of other information relevant to locating the target, verifying the target, and mounting the target's volume, if necessary. <tt>aliasWithPath:fromPath:</tt> also stores relative path information as well by supplying a starting point for a relative path.
   @param URL the file url for the target of the alias.
   @param fromPath The starting point for a relative path, to be used later in a relative search. The two file or directory url's, <tt>fromPath</tt> and <tt>URL</tt>, must reside on the same volume.
   @result A NDAlias instance, returns <tt>nil</tt> if <tt>NDAlias</tt> creation fails.
 */
+ (id)aliasWithPath:(NSString *)path fromPath:(NSString *)fromPath;

/*!
  @method aliasWithData:
  @abstract Creates and initalises a <tt>NDAlias</tt>.
  @discussion The method <tt>aliasWithData:</tt> creates a <tt>NDAlias</tt> that describes the specified target. <tt>aliasWithData:</tt> creates the <tt>NDAlias</tt> from the data that was returned from the method <tt>data</tt>
  @param data The <tt>NSData</tt> instaqnces that contains the data returned previously from the method <tt>data</tt>.
  @result A NDAlias instance, returns <tt>nil</tt> if <tt>NDAlias</tt> creation fails.
  */
+ (id)aliasWithData:(NSData *)data;

/*!
  @method initWithURL:
  @abstract Initalises a <tt>NDAlias</tt>.
  @discussion The method <tt>initWithURL:</tt> initalises an <tt>NDAlias</tt> that contains only the minimum information necessary to describe the target: the target name, the parent directory ID, the volume name and creation date, and the volume mounting information. The <tt>initWithURL:</tt> method uses the standard alias record data structure, but it fills in only parts of the record.
   <p>The methods <tt>url</tt> and <tt>path</tt> never update a minimal alias record.</p>
  @param URL the file url for the target of the alias.
  @result A <tt>NDAlias</tt> instance, returns <tt>nil</tt> if <tt>NDAlias</tt> creation fails.
 */
- (id)initWithURL:(NSURL *)URL;
/*!
  @method initWithPath:fromURL:
   @abstract Initalises a <tt>NDAlias</tt>.
   @discussion  The method <tt>initWithPath:fromURL:</tt> initalises a <tt>NDAlias</tt> that describes the specified target. <tt>initWithPath:fromURL:</tt> always records the name and file or directory ID of the target, its creation date, the parent directory name and ID, and the volume name and creation date. It also records the full pathname of the target and a collection of other information relevant to locating the target, verifying the target, and mounting the target's volume, if necessary. <tt>initWithPath:fromURL:</tt> also stores relative path information as well by supplying a starting point for a relative path.
   @param URL the file url for the target of the alias.
   @param fromURL The starting point for a relative path, to be used later in a relative search. The two file or directory url's, <tt>fromURL</tt> and <tt>URL</tt>, must reside on the same volume.
  @result An initalises <tt>NDAlias</tt>, returns <tt>nil</tt> if initalises fails.
 */
- (id)initWithURL:(NSURL *)URL fromURL:(NSURL *)fromURL;
/*!
  @method initWithPath:
   @abstract Initalises a <tt>NDAlias</tt>.
   @discussion The method <tt>initWithPath:</tt> initalises an <tt>NDAlias</tt> that contains only the minimum information necessary to describe the target: the target name, the parent directory ID, the volume name and creation date, and the volume mounting information. The <tt>initWithPath:</tt> method uses the standard alias record data structure, but it fills in only parts of the record.
   <p>The methods <tt>url</tt> and <tt>path</tt> never update a minimal alias record.</p>
   @param path the path for the target of the alias.
  @result An initalises <tt>NDAlias</tt>, returns <tt>nil</tt> if initalises fails.
 */
- (id)initWithPath:(NSString *)path;
/*!
  @method initWithPath:fromPath:
   @abstract Initalises a <tt>NDAlias</tt>.
   @discussion  The method <tt>initWithPath:fromPath:</tt> initalises a <tt>NDAlias</tt> that describes the specified target. <tt>initWithPath:fromPath:</tt> always records the name and file or directory ID of the target, its creation date, the parent directory name and ID, and the volume name and creation date. It also records the full pathname of the target and a collection of other information relevant to locating the target, verifying the target, and mounting the target's volume, if necessary. <tt>initWithPath:fromPath:</tt> also stores relative path information as well by supplying a starting point for a relative path.
   @param path the file url for the target of the alias.
   @param fromPath The starting point for a relative path, to be used later in a relative search. The two file or directory url's, <tt>fromPath</tt> and <tt>path</tt>, must reside on the same volume.
  @result An initalises <tt>NDAlias</tt>, returns <tt>nil</tt> if initalises fails.
 */
- (id)initWithPath:(NSString *)path fromPath:(NSString *)fromPath;

  /*!
  @method initWithData:
   @abstract Initalises a <tt>NDAlias</tt>.
   @discussion The method <tt>initWithData:</tt> initalises a <tt>NDAlias</tt> that describes the specified target. <tt>initWithData:</tt> creates the <tt>NDAlias</tt> from the data that was returned from the method <tt>data</tt>
   @param data The <tt>NSData</tt> instaqnces that contains the data returned previously from the method <tt>data</tt>.
   @result An initalises <tt>NDAlias</tt>, returns <tt>nil</tt> if initalises fails.
   */
- (id)initWithData:(NSData *)data;

/*!
  @functiongroup Setting the way the alias is resolved
*/

/*!
  @method setAllowUserInteraction:
  @abstract Option controls how the alias is resolved
  @discussion Sets resolve the alias, presenting a user interface if necessary. By default user interaction is allowed.
  @param flag <tt>YES</tt> to stop any user interaction.
 */
- (void)setAllowUserInteraction:(BOOL)flag;

/*!
  @method setTryFileIDFirst:
  @abstract Option controls how the alias is resolved
  @discussion Search for the alias target using file IDs before searching using the path. By default search by path occurs first.
  @param flag <tt>YES</tt> to resolve the alias by trying file ID first, <tt>NO</tt> to try path first.
 */
- (void)setTryFileIDFirst:(BOOL)flag;

/*!
  @functiongroup Information about an alias
 */

/*!
  @method allowUserInteraction
  @abstract Option controls how the alias is resolved
  @discussion Resolve the alias, presenting a user interface if necessary. By default user interaction is allowed.
  @result Returns <tt>YES</tt> if user interaction is allowed.
 */
- (BOOL)allowUserInteraction;

/*!
  @method tryFileIDFirst
  @abstract Option controls how the alias is resolved
  @discussion Search for the alias target using file IDs before searching using the path. By default search by path occurs first.
  @result <tt>YES</tt> to resolve the alias by trying file ID first, <tt>NO</tt> to try path first.
 */
- (BOOL)tryFileIDFirst;

/*!
  @method changed
  @abstract Reports whether the receiver was updated.
  @discussion The method <tt>changed</tt> indicates whether the receiver was updated because it contained some outdated information about the target. If it the receiver is updated, <tt>YES</tt> is returned. Otherwise, it return <tt>NO</tt>. (<tt>url</tt> and <tt>path</tt> never update a <tt>NDAlias</tt> that was created with no relative path.) 
  @result <tt>YES</tt> if the receiver was updated, <tt>NO</tt> if it was not updated.
  */
- (BOOL)changed;

/*!
  @functiongroup Obtain the path the alias points to.
 */

/*!
  @method url
  @abstract Returns the single most likely target for the receiver.
  @discussion  The <tt>url</tt> method performs a fast search for the target of the receiver. If the resolution is successful, <tt>url</tt> returns a file <tt>NSURL</tt> for the target file system object, updates the receiver if necessary, and reports (through the method <tt>changed</tt>) whether the receiver was updated. If the target is on an unmounted AppleShare volume, <tt>url</tt> automatically mounts the volume. If the target is on an unmounted ejectable volume, <tt>url</tt> asks the user to insert the volume.
  <p>After it identifies a target, <tt>url</tt> compares some key information about the target with the information in the receiver. If the information differs, <tt>url</tt> updates the receiver to match the target.</p>
  <p>The <tt>url</tt> method displays the standard dialog boxes when it needs input from the user, such as a name and password for mounting a remote volume. The user can cancel the resolution through these dialog boxes.</p>
  @result A file <tt>NSURL</tt> to the target of the receiver. <tt>nil</tt> is returned if no target could be found. 
  */
- (NSURL *)url;
/*!
  @method path
   @abstract Returns the single most likely target for the receiver.
   @discussion  The method <tt>path</tt> performs a fast search for the target of the receiver. If the resolution is successful, <tt>path</tt> returns a path <tt>NSString</tt> for the target file system object, updates the receiver if necessary, and reports (through the method <tt>changed</tt>) whether the receiver was updated. If the target is on an unmounted AppleShare volume, <tt>path</tt> automatically mounts the volume. If the target is on an unmounted ejectable volume, <tt>path</tt> asks the user to insert the volume.
   <p>After it identifies a target, <tt>path</tt> compares some key information about the target with the information in the receiver. If the information differs, <tt>path</tt> updates the receiver to match the target.</p>
   <p>The <tt>path</tt> method displays the standard dialog boxes when it needs input from the user, such as a name and password for mounting a remote volume. The user can cancel the resolution through these dialog boxes.</p>
   @result A path <tt>NSString</tt> to the target of the receiver. <tt>nil</tt> is returned if no target could be found.
 */
- (NSString *)path;

/*!
  @functiongroup Update the path of the alias
 */

/*!
  @method setURL:
   @abstract Updates an the reciever with a new target.
   @discussion The method <tt>setURL:</tt> rebuilds the entire recievers alias record .
   @param URL the file url for the target of the alias.
   @result Returns <tt>YES</tt> if setting the target succeeded, otherwise returns <tt>NO</tt>.
 */
- (BOOL)setURL:(NSURL *)URL;
/*!
  @method setURL:fromURL:
  @abstract Updates an the reciever with a new target.
  @discussion The method <tt>setURL:fromURL:</tt> rebuilds the entire recievers alias record .
  <p>The <tt>setURL:fromURL:</tt> function always creates a complete alias record. When you use <tt>setURL:fromURL:</tt> to update a minimal alias record, you convert the minimal record to a complete record.</p>
  @param URL the file url for the target of the reciever.
  @param fromURL The starting point for a relative path, to be used later in a relative search. The two file or directory url's, <tt>fromURL</tt> and <tt>URL</tt>, must reside on the same volume.
  @result Returns <tt>YES</tt> if setting the target succeeded, otherwise returns <tt>NO</tt>.
  */
- (BOOL)setURL:(NSURL *)URL fromURL:(NSURL *)fromURL;
/*!
  @method setPath:
  @abstract Updates an the reciever with a new target.
  @discussion The method <tt>setPath:</tt> rebuilds the entire recievers alias record .
  @param path the path for the target of the reciever.
  @result Returns <tt>YES</tt> if setting the target succeeded, otherwise returns <tt>NO</tt>.
 */
- (BOOL)setPath:(NSString *)path;
/*!
  @method setURL:fromURL:
   @abstract Updates an the reciever with a new target.
   @discussion The method <tt>setURL:fromURL:</tt> rebuilds the entire recievers alias record .
   <p>The <tt>setURL:fromURL:</tt> function always creates a complete alias record. When you use <tt>setURL:fromURL:</tt> to update a minimal alias record, you convert the minimal record to a complete record.</p>
   @param path the path for the target of the reciever.
   @param fromPath The starting point for a relative path, to be used later in a relative search. The two file or directory paths, <tt>fromPath</tt> and <tt>path</tt>, must reside on the same volume.
   @result Returns <tt>YES</tt> if setting the target succeeded, otherwise returns <tt>NO</tt>.
 */
- (BOOL)setPath:(NSString *)path fromPath:(NSString *)fromPath;

/*!
  @functiongroup Obtain the aliases data
 */

/*!
  @method data
  @abstract Returns a <tt>NSData</tt> instance for the reciever.
  @discussion The method <tt>data</tt> returns the contents of the recievers as an <tt>NSData</tt>, this can be used for archiving perposes though <tt>NDAlias</tt> does implement the <tt>NSCoding</tt> protocol.
  @result Returns an <tt>NSData</tt> instance.
  */
- (NSData *)data;

@end

Download Archive

Compatible with:

Mac OS X 10.0
Mac OS X 10.1
Mac OS X 10.2
Mac OS X 10.3
Mac OS X 10.4 PPC
Mac OS X 10.4 Intel

Comments

Comment feed