STPrivilegedTask 技术文档

本文档将详细介绍如何安装和使用 STPrivilegedTask 项目，该项目是一个围绕 macOS 安全 API 中的 AuthorizationExecuteWithPrivileges() 函数实现的 Objective-C 封装类，用于以 root 权限运行 shell 命令。

1. 安装指南

通过 CocoaPods 安装

将以下内容添加到您的 Podfile 文件中：

pod 'STPrivilegedTask', '~> 1.0.8'

然后运行以下命令进行安装：

pod install

手动安装

1. 下载项目中的 STPrivilegedTask.h 和 STPrivilegedTask.m 文件。
2. 将这些文件直接包含到您的项目中。

2. 项目使用说明

引入头文件

在您的代码中引入 STPrivilegedTask.h：

#import "STPrivilegedTask.h"

创建并启动任务

创建一个 STPrivilegedTask 对象，设置要执行的路径和参数，然后启动任务：

STPrivilegedTask *privilegedTask = [STPrivilegedTask new];
[privilegedTask setLaunchPath:@"/usr/bin/touch"];
[privilegedTask setArguments:@[@"/etc/my_test_file"]];

// 可选设置工作目录
// [privilegedTask setCurrentDirectoryPath:@"目录路径"];

// 启动任务，用户将被提示输入密码（阻塞）
OSStatus err = [privilegedTask launch];
if (err == errAuthorizationSuccess) {
    NSLog(@"任务成功启动");
} else if (err == errAuthorizationCanceled) {
    NSLog(@"用户取消");
} else {
    NSLog(@"发生错误，错误代码：%d", err);
}

获取任务输出

// ... 启动任务

[privilegedTask waitUntilExit]; // 阻塞直到任务结束

// 读取输出文件句柄中的数据
NSData *outputData = [[privilegedTask outputFileHandle] readDataToEndOfFile];
NSString *outputString = [[NSString alloc] initWithData:outputData encoding:NSUTF8StringEncoding];

任务在后台运行时获取输出

// ... 启动 privilegedTask

NSFileHandle *readHandle = [privilegedTask outputFileHandle];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(getOutputData:)
                                             name:NSFileHandleReadCompletionNotification
                                           object:readHandle];
[readHandle readInBackgroundAndNotify];

// ...

- (void)getOutputData:(NSNotification *)aNotification {
    // 从通知中获取数据
   NSData *data = [[aNotification userInfo] objectForKey:NSFileHandleNotificationDataItem];
    
    // 确保实际有数据
    if ([data length]) {
        // 处理数据
        NSString *outputString = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
        NSLog(@"%@", outputString);
        
        // 在后台读取更多数据
        [[aNotification object] readInBackgroundAndNotify];
    } else {
        // 执行其他操作
    }
}

任务终止

您可以观察 STPrivilegedTaskDidTerminateNotification：

[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(privilegedTaskFinished:)
                                             name:STPrivilegedTaskDidTerminateNotification
                                           object:nil];

- (void)privilegedTaskFinished:(NSNotification *)aNotification {
    // 执行操作
}

或者，设置一个终止处理程序块：

privilegedTask.terminationHandler = ^(STPrivilegedTask *privilegedTask) {
    NSLog(@"终止任务：%@", [privilegedTask description]);
};

使用外部 AuthorizationRef 启动任务

// ... 创建您的 AuthorizationRef

[STPrivilegedTask launchedPrivilegedTaskWithLaunchPath:@"/bin/sh"
                                             arguments:@"/path/to/script"
                                      currentDirectory:@"/"
                                         authorization:authRef]

检查 AuthorizationExecuteWithPrivileges() 是否可用

AuthorizationExecuteWithPrivileges() 自 macOS 10.7 起已被弃用，但在 macOS 13 "Ventura" 中仍然可用。如果您想确保未来兼容性，可以检查 STPrivilegedTask 是否在当前版本的 macOS 中工作：

// ... 创建 privilegedTask 对象

OSStatus err = [privilegedTask launch];
if (err == errAuthorizationFnNoLongerExists) {
    NSLog(@"AuthorizationExecuteWithPrivileges 不可用");
    // 执行一些操作以处理这种情况
}

如果您需要在启动任务之前检查 STPrivilegedTask 是否工作：

BOOL works = [STPrivilegedTask authorizationFunctionAvailable];

3. 项目 API 使用文档

请参考项目中的 STPrivilegedTask.h 头文件以获取详细的 API 文档。

4. 项目安装方式

项目的安装方式已在“安装指南”部分进行了说明。您可以选择通过 CocoaPods 进行安装或手动安装。