markbase/docs/FSKIT_QUICK_REFERENCE.md

# FSKit API Quick Reference ⭐⭐⭐⭐⭐

## 修正后的 API（基于 FSKitSample）

### 1. Entry Point

```swift
struct MyFSExtension: FSKitExtension {
    func filesystem() -> FSFileSystem {
        return MyFS()
    }
}
```

### 2. Filesystem

```swift
class MyFS: FSFileSystem {
    func probeResource(
        resource: FSResource,
        replyHandler: @escaping (FSProbeResult?) -> Void
    ) {
        // Check if resource is usable
        let result = FSProbeResult.usable(
            resource: resource,
            identifier: FSResourceIdentifier(uuid: UUID()),
            userInfo: nil
        )
        replyHandler(result)
    }
    
    func loadResource(
        resource: FSResource,
        options: FSTaskOptions,
        replyHandler: @escaping (Error?) -> Void
    ) {
        // Load resource (block device, etc)
        replyHandler(nil)
    }
    
    func unloadResource(
        resource: FSResource,
        options: FSTaskOptions,
        replyHandler: @escaping (Error?) -> Void
    ) {
        // Unload resource
        replyHandler(nil)
    }
}
```

### 3. Volume

```swift
class MyFSVolume: FSVolume {
    init(resource: FSResource) {
        super.init(resource: resource)
    }
}

// Required protocols (13+):
extension MyFSVolume: FSVolume.PathConfOperations { }
extension MyFSVolume: FSVolume.OpenCloseOperations { }
extension MyFSVolume: FSVolume.IOOperations { }
extension MyFSVolume: FSVolume.DirectoryOperations { }
extension MyFSVolume: FSVolume.AttributeOperations { }
extension MyFSVolume: FSVolume.XattrOperations { }
```

### 4. File Item

```swift
class MyFSItem: FSItem {
    var name: FSFileName
    var id: UInt64
    var attributes: FSItem.Attributes
    var xattrs: [String: Data]
    var children: [MyFSItem]
    var content: Data?
    
    init(name: FSFileName) {
        self.name = name
        self.id = UInt64.random()
        self.attributes = FSItem.Attributes()
        super.init()
    }
}
```

### 5. Key Protocol Methods

**PathConfOperations**：
```swift
func pathconf(_ item: FSItem, conf: FSPathConf) throws -> Int32
```

**OpenCloseOperations**：
```swift
func open(_ item: FSItem, options: FSTaskOptions) throws -> FSFileHandle
func close(_ handle: FSFileHandle) throws
```

**IOOperations**：
```swift
func read(_ handle: FSFileHandle, buffer: UnsafeMutableRawBufferPointer, options: FSTaskOptions) throws -> Int
func write(_ handle: FSFileHandle, buffer: UnsafeRawBufferPointer, options: FSTaskOptions) throws -> Int
```

**DirectoryOperations**：
```swift
func enumerateDirectory(_ item: FSItem, verifier: inout FSItemVerifier, options: FSTaskOptions) throws -> FSItemEnumerator
```

**AttributeOperations**：
```swift
func attributes(_ item: FSItem) throws -> FSItem.Attributes
func attributes(_ item: FSItem, named: FSFileName) throws -> FSItem.Attributes
func setAttributes(_ item: FSItem, attributes: FSItem.Attributes, options: FSTaskOptions) throws
```

**XattrOperations**：
```swift
func getXattr(_ item: FSItem, name: String) throws -> Data
func setXattr(_ item: FSItem, name: String, value: Data, options: FSTaskOptions) throws
func listXattrs(_ item: FSItem) throws -> [String]
func removeXattr(_ item: FSItem, name: String, options: FSTaskOptions) throws
```

---

## Info.plist Template

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>FSExtension</key>
    <dict>
        <key>FSExtensionPersonality</key>
        <string>HelloFS</string>
        
        <key>FSShortName</key>
        <string>HelloFS</string>
        
        <key>FSObjectsAreCaseSensitive</key>
        <false/>
        
        <key>FSSupportsBlockDevices</key>
        <true/>
        
        <key>FSPrimaryClass</key>
        <string>HelloFS</string>
    </dict>
    
    <key>NSExtension</key>
    <dict>
        <key>NSExtensionPointIdentifier</key>
        <string>com.apple.fskit</string>
        
        <key>NSExtensionPrincipalClass</key>
        <string>$(PRODUCT_MODULE_NAME).HelloFSExtension</string>
    </dict>
</dict>
</plist>
```

---

## Entitlements Template

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    
    <key>com.apple.security.files.user-selected.read-write</key>
    <true/>
</dict>
</plist>
```

---

## Testing Commands

**Create block device**：
```bash
mkfile -n 100m dummy
hdiutil attach -imagekey diskimage-class=CRawDiskImage -nomount dummy
# Output: disk18 (or diskN)
```

**Mount**：
```bash
mkdir /tmp/TestVol
mount -t HelloFS disk18 /tmp/TestVol
```

**Unmount**：
```bash
umount /tmp/TestVol
```

---