react-native-kookit 0.3.0 → 0.3.1

package/ANDROID_SMB_LIBRARY_COMPARISON.md

@@ -0,0 +1,170 @@
+# Android SMB库对比分析与推荐
+
+## 当前使用的库：SMBJ
+
+### 优点
+
+- ✅ 轻量级，专注SMB2/3协议
+- ✅ 现代化设计，良好的性能
+- ✅ 活跃维护，最新版本0.13.0 (2023)
+- ✅ 支持SMB2/3的高级功能
+
+### 缺点
+
+- ❌ **不支持share枚举** - 这是我们当前的问题
+- ❌ 没有NetShareEnum API
+- ❌ 需要手动测试常见share名称
+
+## 备选方案1：JCIFS (CodeLibs版本)
+
+### 基本信息
+
+```gradle
+implementation 'org.codelibs:jcifs:2.1.39'
+```
+
+### 优点
+
+- ✅ **完整的SMB协议支持** (SMB1/2/3)
+- ✅ **支持网络浏览** - 可能包括share枚举
+- ✅ 成熟的库，有长期历史
+- ✅ 支持Java 17+
+- ✅ 现代化API设计
+
+### 缺点
+
+- ❌ 体积较大
+- ❌ 需要额外学习新API
+- ❌ 依赖Bouncy Castle加密库
+
+### Share枚举支持
+
+基于文档分析，JCIFS应该支持类似这样的用法：
+
+```java
+// 可能的API (需要验证)
+SmbFile server = new SmbFile("smb://192.168.1.100/", context);
+SmbFile[] shares = server.listFiles(); // 列出所有shares
+```
+
+## 备选方案2：JCIFS-NG (AgNO3版本)
+
+### 基本信息
+
+```gradle
+implementation 'eu.agno3.jcifs:jcifs-ng:2.1.9'
+```
+
+### 优点
+
+- ✅ **支持SMB2支持** (2.02协议级别)
+- ✅ 基于原始JCIFS但经过清理和改进
+- ✅ 移除了全局状态，线程安全
+
+### 缺点
+
+- ❌ **明确弃用了server browsing功能** (2.1版本)
+- ❌ 不再支持share枚举
+- ❌ API与原始JCIFS有差异
+
+## 备选方案3：SMB4J
+
+### 基本信息
+
+```gradle
+implementation 'com.github.smb4j:smb4j:1.0.0'
+```
+
+### 优点
+
+- ✅ 现代化设计
+- ✅ 支持SMB2/3
+
+### 缺点
+
+- ❌ 相对较新，生态不够成熟
+- ❌ 文档不够完整
+
+## 推荐方案：尝试JCIFS (CodeLibs)
+
+### 理由
+
+1. **完整功能支持** - 作为最全面的SMB库，很可能支持share枚举
+2. **现代维护** - CodeLibs版本是维护最积极的JCIFS分支
+3. **向后兼容** - 支持所有SMB版本，兼容性最好
+
+### 实施建议
+
+#### 第一步：添加依赖测试
+
+```gradle
+dependencies {
+    // 当前SMBJ
+    implementation 'com.hierynomus:smbj:0.13.0'
+
+    // 添加JCIFS测试
+    implementation 'org.codelibs:jcifs:2.1.39'
+    implementation 'org.slf4j:slf4j-nop:2.0.13'
+}
+```
+
+#### 第二步：创建JCIFS实现的listShares
+
+```kotlin
+import org.codelibs.jcifs.smb.CIFSContext
+import org.codelibs.jcifs.smb.context.SingletonContext
+import org.codelibs.jcifs.smb.impl.SmbFile
+import org.codelibs.jcifs.smb.impl.NtlmPasswordAuthenticator
+
+class JcifsShareEnumerator {
+    fun listShares(host: String, username: String, password: String, domain: String? = null): List<String> {
+        val context = SingletonContext.getInstance()
+        val auth = NtlmPasswordAuthenticator(domain, username, password)
+        val authContext = context.withCredentials(auth)
+
+        return try {
+            val serverUrl = "smb://$host/"
+            val server = SmbFile(serverUrl, authContext)
+
+            server.listFiles()?.map { share ->
+                share.name.removeSuffix("/")
+            } ?: emptyList()
+        } catch (e: Exception) {
+            emptyList()
+        }
+    }
+}
+```
+
+#### 第三步：集成到现有API
+
+```kotlin
+// 在SmbClient.kt中添加
+@Synchronized
+fun listSharesJcifs(): List<String> {
+    // 使用JCIFS实现
+    return JcifsShareEnumerator().listShares(host, username, password, domain)
+}
+
+@Synchronized
+fun listShares(): List<String> {
+    // 首先尝试JCIFS方法
+    val jcifsShares = listSharesJcifs()
+    if (jcifsShares.isNotEmpty()) {
+        return jcifsShares
+    }
+
+    // 如果失败，回退到当前的测试方法
+    return listSharesViaTesting()
+}
+```
+
+## 总结
+
+**推荐采用JCIFS (CodeLibs版本)** 作为share枚举的补充方案：
+
+1. **混合策略** - 保留SMBJ作为主要SMB客户端，仅使用JCIFS进行share枚举
+2. **向后兼容** - 如果JCIFS枚举失败，回退到当前的测试方法
+3. **最小改动** - 只需要添加一个枚举方法，不需要重写整个SMB客户端
+
+这样既能解决share枚举问题，又能保持现有代码的稳定性。

package/SMB_HYBRID_IMPLEMENTATION.md

@@ -0,0 +1,160 @@
+# SMB 混合实现方案
+
+## 概述
+
+为了解决SMB share枚举的问题，我们实现了一个混合方案：
+
+- 主要SMB客户端使用SMBJ（可靠性高）
+- Share枚举使用JCIFS（功能更完整）
+
+## 实现细节
+
+### 1. 依赖库
+
+- **SMBJ**: 主要SMB客户端操作（连接、文件操作等）
+- **JCIFS**: Share枚举和发现（org.codelibs:jcifs:2.1.39）
+
+### 2. 架构设计
+
+#### SmbClient.kt 主类
+
+- 保留SMBJ作为主要SMB客户端
+- 添加JcifsShareEnumerator辅助类
+- 存储连接凭据以供JCIFS使用
+
+#### JcifsShareEnumerator.kt 辅助类
+
+- 专门用于Share枚举
+- 使用JCIFS进行完整的Share发现
+- 提供连接测试功能
+
+### 3. listShares() 方法流程
+
+```kotlin
+fun listShares(): List<String> {
+    // 1. 尝试使用JCIFS进行完整Share枚举
+    try {
+        val shares = jcifsEnumerator.listShares(host, username, password, domain)
+        if (shares.isNotEmpty()) {
+            return shares
+        }
+    } catch (e: Exception) {
+        // 继续到fallback方法
+    }
+
+    // 2. Fallback: 使用SMBJ测试常见Share名称
+    try {
+        // 测试常见Windows和用户定义的Share
+        val commonShares = listOf("C$", "D$", "shared", "public", ...)
+        // 返回可访问的Share
+    } catch (e: Exception) {
+        // 最终fallback: 返回常见Share名称
+    }
+}
+```
+
+### 4. 优势
+
+1. **可靠性**: SMBJ作为主要客户端，稳定性高
+2. **完整性**: JCIFS提供完整的Share枚举
+3. **容错性**: 多层fallback机制
+4. **性能**: JCIFS仅用于Share枚举，不影响主要操作
+
+### 5. Share参数说明
+
+#### 对于列出SMB根目录（Share根目录）：
+
+```typescript
+// 连接到具体Share
+await smbClient.connect({
+  host: "192.168.1.100",
+  username: "user",
+  password: "pass",
+  share: "C$", // 指定具体的Share
+});
+
+// 列出Share根目录
+const files = await smbClient.listFiles(""); // 空字符串表示Share根目录
+```
+
+#### 对于列出所有可用Share：
+
+```typescript
+// 只需要认证，不指定share
+await smbClient.connect({
+  host: "192.168.1.100",
+  username: "user",
+  password: "pass",
+  // 不指定share参数
+});
+
+// 获取所有可用Share
+const shares = await smbClient.listShares();
+```
+
+### 6. 常见Share类型
+
+#### Windows系统Share：
+
+- `C$`, `D$`, `E$`: 驱动器共享（需要管理员权限）
+- `ADMIN$`: 管理共享
+- `IPC$`: 进程间通信共享
+
+#### 用户定义Share：
+
+- `shared`, `public`, `data`: 常见的用户共享文件夹
+- `home`, `Users`: 用户目录共享
+- `documents`, `media`: 媒体和文档共享
+
+## 使用示例
+
+```typescript
+const smbClient = new SmbClient();
+
+// 1. 连接到服务器
+await smbClient.connect({
+  host: "192.168.1.100",
+  username: "myuser",
+  password: "mypass",
+});
+
+// 2. 获取所有可用Share
+const shares = await smbClient.listShares();
+console.log("Available shares:", shares);
+// 输出: ['C$', 'shared', 'public', 'documents']
+
+// 3. 连接到具体Share
+await smbClient.openShare("shared");
+
+// 4. 列出Share根目录
+const files = await smbClient.listFiles("");
+
+// 5. 列出子目录
+const subFiles = await smbClient.listFiles("subfolder");
+```
+
+## 故障排除
+
+### 如果JCIFS枚举失败：
+
+- 自动fallback到SMBJ测试方法
+- 返回测试可访问的常见Share
+
+### 如果所有方法都失败：
+
+- 返回最常见的Share名称列表
+- 用户可以手动尝试连接
+
+## 技术细节
+
+### JCIFS配置：
+
+- 使用NtlmPasswordAuthenticator进行认证
+- 通过SmbFile访问服务器根目录
+- 枚举所有可用的Share
+
+### SMBJ fallback：
+
+- 测试常见Share名称的可访问性
+- 短暂连接后立即关闭以测试可用性
+- 收集所有可访问的Share名称

package/android/build.gradle

@@ -43,8 +43,10 @@ android {
 }
 
 dependencies {
-  // SMB client library
+  // SMB client library (primary)
   implementation 'com.hierynomus:smbj:0.13.0'
+  // JCIFS library for share enumeration
+  implementation 'org.codelibs:jcifs:2.1.39'
   // Suppress SLF4J binding warnings
   implementation 'org.slf4j:slf4j-nop:2.0.13'
 }

package/android/src/main/java/expo/modules/kookit/JcifsShareEnumerator.kt

@@ -0,0 +1,75 @@
+package expo.modules.kookit
+
+import jcifs.CIFSContext
+import jcifs.context.SingletonContext
+import jcifs.smb.SmbFile
+import jcifs.smb.NtlmPasswordAuthenticator
+import java.util.*
+
+/**
+ * JCIFS-based SMB share enumerator
+ * Used as a supplement to SMBJ for share enumeration functionality
+ */
+class JcifsShareEnumerator {
+    
+    /**
+     * List all available shares on an SMB server using JCIFS
+     * @param host SMB server hostname or IP
+     * @param username Username for authentication
+     * @param password Password for authentication
+     * @param domain Domain name (optional)
+     * @return List of share names, empty if enumeration fails
+     */
+    fun listShares(host: String, username: String, password: String, domain: String? = null): List<String> {
+        return try {
+            // Create JCIFS context with authentication
+            val context = SingletonContext.getInstance()
+            val auth = NtlmPasswordAuthenticator(domain, username, password)
+            val authContext = context.withCredentials(auth)
+            
+            // Connect to server root to enumerate shares
+            val serverUrl = "smb://$host/"
+            val server = SmbFile(serverUrl, authContext)
+            
+            // List all shares
+            val shares = server.listFiles()
+            shares?.mapNotNull { shareFile ->
+                val shareName = shareFile.name.removeSuffix("/")
+                // Filter out hidden/administrative shares if needed
+                if (shareName.isNotBlank() && !shareName.startsWith(".")) {
+                    shareName
+                } else null
+            } ?: emptyList()
+            
+        } catch (e: Exception) {
+            // If JCIFS enumeration fails, return empty list
+            // The caller can fall back to other methods
+            emptyList()
+        }
+    }
+    
+    /**
+     * Test if JCIFS can connect to the server
+     * @param host SMB server hostname or IP
+     * @param username Username for authentication
+     * @param password Password for authentication
+     * @param domain Domain name (optional)
+     * @return true if connection successful, false otherwise
+     */
+    fun testConnection(host: String, username: String, password: String, domain: String? = null): Boolean {
+        return try {
+            val context = SingletonContext.getInstance()
+            val auth = NtlmPasswordAuthenticator(domain, username, password)
+            val authContext = context.withCredentials(auth)
+            
+            val serverUrl = "smb://$host/"
+            val server = SmbFile(serverUrl, authContext)
+            
+            // Test if we can access the server
+            server.exists()
+            true
+        } catch (e: Exception) {
+            false
+        }
+    }
+}

package/android/src/main/java/expo/modules/kookit/SmbClient.kt

@@ -41,11 +41,23 @@ class SmbClient {
   private var session: Session? = null
   private var share: DiskShare? = null
   private var connected = false
+  private val jcifsEnumerator = JcifsShareEnumerator()
+  private var lastHost: String? = null
+  private var lastUsername: String? = null
+  private var lastPassword: String? = null
+  private var lastDomain: String? = null
 
   @Synchronized
   @Throws(IOException::class)
   fun connect(config: SmbConnectionConfig) {
     disconnect()
+    
+    // Store connection parameters for share enumeration
+    lastHost = config.host
+    lastUsername = config.username
+    lastPassword = config.password
+    lastDomain = config.domain
+    
     val conn = smb.connect(config.host)
     connection = conn
     val auth = AuthenticationContext(
@@ -70,9 +82,26 @@ class SmbClient {
   @Synchronized
   fun listShares(): List<String> {
     val s = session ?: throw IOException("Not authenticated")
+    
+    // First try JCIFS for more complete share enumeration
+    if (lastHost != null && lastUsername != null && lastPassword != null) {
+      try {
+        val shares = jcifsEnumerator.listShares(
+          lastHost!!,
+          lastUsername!!,
+          lastPassword!!,
+          lastDomain ?: ""
+        )
+        if (shares.isNotEmpty()) {
+          return shares
+        }
+      } catch (e: Exception) {
+        // JCIFS failed, fall back to SMBJ testing approach
+      }
+    }
+    
     return try {
-      // SMBJ doesn't provide direct share enumeration API
-      // We implement a practical approach by testing common share names
+      // Fallback: SMBJ testing approach
       val availableShares = mutableListOf<String>()
       
       // Common Windows shares
@@ -95,12 +124,12 @@ class SmbClient {
       
       // If no shares found, suggest some common ones
       if (availableShares.isEmpty()) {
-        return listOf("C$", "shared", "public")
+        listOf("C$", "shared", "public")
+      } else {
+        availableShares
       }
-      
-      availableShares
     } catch (e: Exception) {
-      // Fallback to common share names if enumeration fails
+      // Final fallback to common share names if all enumeration methods fail
       listOf("C$", "shared", "public", "data")
     }
   }
@@ -114,6 +143,12 @@ class SmbClient {
     session = null
     connection = null
     connected = false
+    
+    // Clear stored credentials
+    lastHost = null
+    lastUsername = null
+    lastPassword = null
+    lastDomain = null
   }
 
   @Synchronized

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-kookit",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "React Native module for intercepting volume button presses on iOS and Android, with FTP client functionality",
   "main": "build/index.js",
   "types": "build/index.d.ts",