Foundation-XAttr

Foundation-XAttr makes working with Extended Attributes a natural part of Foundation. Both NSURL and NSFileHandle objects gain the ability to read and write extended attributes using an API that fits right in with Cocoa. Add the power of metadata to your app!

Works with iOS, macOS, and tvOS.

For more info on Darwin's extended attribute APIs – which underlie this module – see Apple's man pages for listxattr, getxattr, setxattr, and removexattr.

Example

Here's a simple example of working with extended attributes using a file URL:

let myURL = NSURL(fileURLWithPath: "/path/to/file")

let data = "value".dataUsingEncoding(NSUTF8StringEncoding)!

// Set an attribute
try myURL.setExtendedAttribute(name: "com.example.attribute", value: data)
// List attributes
let names = try myURL.extendedAttributeNames()
// Get an attribute's value
let value = try myURL.extendedAttributeValue(forName: "com.example.attribute")
// Remove an attribute
try myURL.removeExtendedAttribute(forName: "com.example.attribute")

// Set multiple attributes
try myURL.setExtendedAttributes(["com.example.attribute1": data, "com.example.attribute2": data])
// Get multiple attributes' values (all available)
let attrs = try myURL.extendedAttributeValues(forNames: nil)
// Remove multiple attributes (all)
try myURL.removeExtendedAttributes(forNames: nil)

Installation

Requires Swift 2.2.

Swift Package Manager

Add Foundation-XAttr as a dependency to your project:

// Package.swift

import PackageDescription

let package = Package(
    name: "YourProjectName",
    dependencies: [
        .Package(url: "https://github.com/overbuilt/foundation-xattr.git", majorVersion: 1),
    ]
)

Source

If you cannot use the Swift Package Manager, just copy the source file Foundation-XAttr.swift from the Sources directory into your project.

Usage

Foundation-XAttr is easy to use. This section contains the all the basic information required. Be sure to check out the Quick Help in Xcode for more detail.

Methods

The following methods are available to both NSURL and NSFileHandle objects:

Retrieving an Attribute's Value

extendedAttributeValue(forName: String, options: XAttrOptions = []) throws -> NSData

Retrieving Multiple Attributes' Values

extendedAttributeValues(forNames: [String]?, options: XAttrOptions = []) throws -> [String: NSData]

Supply a list of names to retrieve, or nil to retrieve all available attributes.

Setting an Attribute's Value

setExtendedAttribute(name: String, value: NSData, options: XAttrOptions = []) throws

Setting Multiple Attributes' Values

setExtendedAttributes(_: [String: NSData], options: XAttrOptions = []) throws

Supply a dictionary of name:value pairs to be set on the target.

Listing Attribute Names

extendedAttributeNames(options: XAttrOptions = []) throws -> [String]

Removing an Extended Attribute

removeExtendedAttribute(forName: String, options: XAttrOptions = []) throws

Removing Multiple Extended Attributes

removeExtendedAttributes(forNames: [String]?, options: XAttrOptions = []) throws

Supply a list of names to remove, or nil to remove all existing attributes.

Options

XAttrOptions provides the following options:

Note: If neither CreateOnly nor ReplaceOnly are specified, the attribute will be created/updated regardless of its current status.

Errors

An NSError will be thrown if the system is not able to get/set/list/remove an extended attribute. The error will have the Foundation built-in domain NSPOSIXErrorDomain. The error's code property will represent the POSIX error code reported by the system, and the error's localizedDescription property will contain an explanation of the error.

Additionally, if the system was able to retrieve an attribute's name, but was not able to decode it, an NSError with the Foundation built-in domain NSCocoaErrorDomain and code NSFileReadInapplicableStringEncodingError will be thrown.

Finally, if an error is encountered while getting/setting/removing multiple extended attributes, the specific attribute that caused the error will be named in the error's userInfo dictionary, at the key ExtendedAttributeNameKey.

License

Foundation-XAttr is licensed under the permissive ISC License.