本文详解 SMBJ 库中设置文件权限（如 755）失败（STATUS_INVALID_PARAMETER）的根本原因，指出 FileModeInformation 不适用于普通文件、仅限目录创建场景，并提供基于 FileAllInformation 的标准解决方案及完整可运行代码。
本文详解 smbj 库中设置文件权限（如 755）失败（status_invalid_parameter）的根本原因，指出 `filemodeinformation` 不适用于普通文件、仅限目录创建场景，并提供基于 `fileallinformation` 的标准解决方案及完整可运行代码。
在使用 SMBJ 操作 Windows 或 Samba 共享文件系统时，开发者常误以为可通过 f.setFileInformation(new FileModeInformation(755)) 直接修改远程文件的 Unix 权限（如 rwxr-xr-x）。但该调用会触发 STATUS_INVALID_PARAMETER (0xc000000d) 错误——根本原因在于：FileModeInformation 是 SMB 协议中专用于目录创建（CREATE）阶段的临时属性，不能用于已打开文件的 SET_INFO 操作。SMB 协议本身不原生支持对普通文件动态设置 mode；Unix 权限映射需通过更底层的 FileAllInformation 结构完成，且依赖服务端配置（如 Samba 启用 vfs_fruit 或 unix extensions = yes）。
✅ 正确做法是：使用 FileAllInformation 替代 FileModeInformation，并在打开文件/目录时确保访问掩码与操作语义匹配。以下为推荐实现流程：
- 优先使用 openDirectory() 处理目录权限（因 FileModeInformation 仅在目录创建上下文中有效）；
- 对普通文件设置权限，应通过 setFileInformation(FileAllInformation) 并显式填充 FileBasicInformation 中的 fileAttributes 字段（注意：SMB 的 fileAttributes 与 Unix mode 并非一一对应，需服务端支持 Unix 扩展）；
- 确保连接协商启用了 Unix 扩展（Samba 需配置 unix extensions = yes，Windows Server 需启用 SMB 3.1.1+ 及相关 VFS 模块）。
✅ 正确示例：安全设置目录权限（推荐场景）
DiskShare share = getSmbSession(); // 获取已认证的 DiskShare 实例
// 1. 显式声明共享级访问权限（READ/WRITE/DELETE）
Set<SMB2ShareAccess> shareAccess = EnumSet.of(
SMB2ShareAccess.FILE_SHARE_READ,
SMB2ShareAccess.FILE_SHARE_WRITE,
SMB2ShareAccess.FILE_SHARE_DELETE
);
// 2. 使用 FILE_ATTRIBUTE_NORMAL（避免混用 DIRECTORY 导致语义冲突）
Set<FileAttributes> fileAttrs = EnumSet.of(FileAttributes.FILE_ATTRIBUTE_NORMAL);
// 3. 创建选项：仅当创建新目录时添加 FILE_DIRECTORY_FILE
Set<SMB2CreateOptions> createOptions = EnumSet.of(SMB2CreateOptions.FILE_DIRECTORY_FILE);
// 4. 以 MAXIMUM_ALLOWED 打开目录（兼容性最佳）
Directory dir = share.openDirectory(
"folder01",
EnumSet.of(AccessMask.MAXIMUM_ALLOWED),
fileAttrs,
shareAccess,
SMB2CreateDisposition.FILE_OPEN_IF,
createOptions
);
// 5. 设置目录权限：使用 FileAllInformation（含基础属性 + 时间戳 + Unix mode）
FileAllInformation allInfo = new FileAllInformation();
allInfo.setBasicInformation(new FileBasicInformation()
.setFileAttributes(FileAttributes.FILE_ATTRIBUTE_DIRECTORY)
.setCreationTime(0L)
.setLastAccessTime(0L)
.setLastWriteTime(0L)
.setChangeTime(0L)
);
// ⚠️ 注意：mode 字段仅在服务端支持 Unix extensions 时生效
allInfo.setStandardInformation(new FileStandardInformation());
allInfo.setInternalInformation(new FileInternalInformation());
allInfo.setEaInformation(new FileEaInformation());
allInfo.setAccessInformation(new FileAccessInformation());
allInfo.setPositionInformation(new FilePositionInformation());
allInfo.setModeInformation(new FileModeInformation(0755)); // 此处才合法（目录上下文）
dir.setFileInformation(allInfo);⚠️ 关键注意事项
- FileModeInformation 无效场景：对已打开的普通文件（share.openFile()）调用 setFileInformation(FileModeInformation) 必然失败，协议层不支持；
- 服务端依赖：mode 字段写入生效需 Samba 配置 vfs objects = unixuid, unixext 且 unix extensions = yes；Windows SMB 默认忽略该字段；
- 权限掩码建议：生产环境避免使用 AccessMask.GENERIC_ALL，应按最小权限原则选用 AccessMask.FILE_WRITE_ATTRIBUTES 或 AccessMask.FILE_READ_ATTRIBUTES；
- 错误诊断：若仍报 STATUS_INVALID_PARAMETER，请启用 SMBJ 日志（logging.level.com.hierynomus.smbj=DEBUG）检查 Negotiate Response 中是否包含 CAP_UNIX 标志。
✅ 总结
SMBJ 中设置远程文件权限的核心原则是：区分“创建时设定”与“运行时修改”，并严格匹配协议能力边界。FileModeInformation 仅适用于 openDirectory(..., FILE_DIRECTORY_FILE) 创建路径的上下文；通用方案应采用 FileAllInformation 封装完整元数据，并确保服务端开启 Unix 扩展支持。忽视此约束将导致不可恢复的协议级参数错误——理解 SMB 协议语义，比盲目调用 API 更重要。
