react-native-kookit 0.2.7 → 0.2.9

package/SMB_USAGE.md

@@ -0,0 +1,275 @@
+# SMB Client 完整功能使用指南
+
+React Native Kookit 现在提供了完整的 SMB (Server Message Block) 客户端功能，支持 Android 和 iOS 平台。
+
+## 特性
+
+✅ **OOP 面向对象设计** - 与 FTP 客户端 API 一致的设计模式  
+✅ **多客户端管理** - 支持同时创建和管理多个 SMB 连接  
+✅ **完整文件操作** - 连接、列目录、下载、上传、删除、创建目录  
+✅ **进度事件** - 下载/上传进度回调和完成/错误事件  
+✅ **跨平台支持** - Android (SMBJ) 和 iOS (SMBClient) 原生实现
+
+## 基本用法
+
+### 1. 创建和连接
+
+```typescript
+import { SmbClient } from "react-native-kookit";
+
+// 创建 SMB 客户端实例
+const client = await SmbClient.create();
+
+// 设置事件监听器（可选）
+client.setEventHandlers({
+  onProgress: (progress) => {
+    console.log(
+      `Progress: ${progress.percentage}% (${progress.transferred}/${progress.total})`
+    );
+  },
+  onComplete: () => {
+    console.log("操作完成");
+  },
+  onError: (error) => {
+    console.error("SMB 错误:", error.message);
+  },
+});
+
+// 连接到 SMB 服务器
+await client.connect({
+  host: "192.168.1.100",
+  port: 445, // 可选，默认 445
+  username: "myuser",
+  password: "mypassword",
+  domain: "WORKGROUP", // 可选，Windows 域
+  share: "Public", // 可选，默认共享
+  timeout: 10000, // 可选，超时时间(毫秒)
+});
+```
+
+### 2. 文件和目录操作
+
+```typescript
+// 列出文件和目录
+const files = await client.list("Documents");
+files.forEach((file) => {
+  console.log(
+    `${file.isDirectory ? "📁" : "📄"} ${file.name} (${file.size} bytes)`
+  );
+});
+
+// 下载文件
+await client.download(
+  "Documents/report.pdf", // 远程路径
+  "/storage/emulated/0/Download/report.pdf" // 本地路径
+);
+
+// 上传文件
+await client.upload(
+  "/storage/emulated/0/Pictures/photo.jpg", // 本地路径
+  "Photos/photo.jpg" // 远程路径
+);
+
+// 创建目录
+await client.createDirectory("NewFolder");
+
+// 删除文件
+await client.delete("OldFile.txt");
+
+// 删除目录
+await client.delete("OldFolder", true);
+```
+
+### 3. 连接管理
+
+```typescript
+// 检查连接状态
+const isConnected = await client.isConnected();
+
+// 获取客户端状态
+const status = await client.getStatus();
+console.log(
+  `Client ${status.clientId}: exists=${status.exists}, connected=${status.connected}`
+);
+
+// 断开连接
+await client.disconnect();
+
+// 释放资源
+await client.dispose();
+```
+
+### 4. 多客户端管理
+
+```typescript
+// 创建多个客户端
+const client1 = await SmbClient.create("server1");
+const client2 = await SmbClient.create("server2");
+
+// 分别连接到不同服务器
+await client1.connect({
+  host: "192.168.1.100",
+  username: "user1",
+  password: "pass1",
+  share: "Share1",
+});
+await client2.connect({
+  host: "192.168.1.101",
+  username: "user2",
+  password: "pass2",
+  share: "Share2",
+});
+
+// 列出所有客户端
+const allClients = await SmbClient.listClients();
+console.log(`管理中的客户端数量: ${allClients.count}`);
+
+// 清理资源
+await client1.dispose();
+await client2.dispose();
+```
+
+## React Native 组件示例
+
+```tsx
+import React, { useState, useEffect } from "react";
+import { View, Text, Button, FlatList } from "react-native";
+import { SmbClient, SmbFileInfo } from "react-native-kookit";
+
+export function SmbBrowser() {
+  const [client, setClient] = useState<SmbClient | null>(null);
+  const [files, setFiles] = useState<SmbFileInfo[]>([]);
+  const [currentPath, setCurrentPath] = useState("");
+
+  const connect = async () => {
+    const smbClient = await SmbClient.create();
+
+    smbClient.setEventHandlers({
+      onProgress: (p) => console.log(`进度: ${p.percentage}%`),
+      onComplete: () => console.log("操作完成"),
+      onError: (e) => console.error("SMB 错误:", e.message),
+    });
+
+    await smbClient.connect({
+      host: "192.168.1.100",
+      username: "user",
+      password: "password",
+      share: "Public",
+    });
+
+    setClient(smbClient);
+    await listFiles("");
+  };
+
+  const listFiles = async (path: string) => {
+    if (!client) return;
+    const fileList = await client.list(path);
+    setFiles(fileList);
+    setCurrentPath(path);
+  };
+
+  const downloadFile = async (fileName: string) => {
+    if (!client) return;
+    const remotePath = currentPath ? `${currentPath}/${fileName}` : fileName;
+    const localPath = `/storage/emulated/0/Download/${fileName}`;
+    await client.download(remotePath, localPath);
+    alert(`文件已下载到: ${localPath}`);
+  };
+
+  useEffect(() => {
+    return () => {
+      client?.dispose();
+    };
+  }, [client]);
+
+  return (
+    <View style={{ flex: 1, padding: 16 }}>
+      <Text style={{ fontSize: 18, marginBottom: 16 }}>SMB 文件浏览器</Text>
+
+      {!client ? (
+        <Button title="连接 SMB 服务器" onPress={connect} />
+      ) : (
+        <>
+          <Text>当前路径: /{currentPath}</Text>
+          <Button title="返回上级" onPress={() => listFiles("")} />
+
+          <FlatList
+            data={files}
+            keyExtractor={(item, index) => index.toString()}
+            renderItem={({ item }) => (
+              <View
+                style={{
+                  padding: 8,
+                  borderBottomWidth: 1,
+                  borderColor: "#eee",
+                }}
+              >
+                <Text
+                  style={{ fontWeight: item.isDirectory ? "bold" : "normal" }}
+                >
+                  {item.isDirectory ? "📁" : "📄"} {item.name}
+                </Text>
+                <Text style={{ fontSize: 12, color: "#666" }}>
+                  大小: {item.size} | 修改时间: {item.lastModified}
+                </Text>
+                {!item.isDirectory && (
+                  <Button
+                    title="下载"
+                    onPress={() => downloadFile(item.name)}
+                  />
+                )}
+              </View>
+            )}
+          />
+        </>
+      )}
+    </View>
+  );
+}
+```
+
+## 平台特定说明
+
+### Android
+
+- 基于 **SMBJ** 库实现
+- 支持完整的 SMB2/3 协议
+- 包含文件上传/下载进度回调
+- 自动处理认证和会话管理
+
+### iOS
+
+- 基于 **SMBClient** (kishikawakatsumi) 库实现
+- 支持 SMB2 协议
+- 完整的文件操作和进度事件
+- 自动处理连接和共享管理
+
+## 错误处理
+
+```typescript
+try {
+  await client.connect(config);
+} catch (error) {
+  if (error.message.includes("authentication")) {
+    console.error("认证失败，请检查用户名和密码");
+  } else if (error.message.includes("timeout")) {
+    console.error("连接超时，请检查网络和主机地址");
+  } else {
+    console.error("连接错误:", error.message);
+  }
+}
+```
+
+## 性能和最佳实践
+
+1. **连接管理**: 不用时及时调用 `disconnect()` 和 `dispose()`
+2. **批量操作**: 对于多个文件操作，复用同一个客户端连接
+3. **进度监听**: 对大文件操作使用进度事件提升用户体验
+4. **错误处理**: 始终包装 SMB 操作在 try-catch 块中
+5. **内存管理**: 在组件卸载时清理客户端资源
+
+## 许可和依赖
+
+- **Android**: SMBJ (Apache License 2.0)
+- **iOS**: SMBClient (MIT License)
+- 该模块遵循 MIT 许可证

package/android/build.gradle

@@ -41,3 +41,10 @@ android {
     abortOnError false
   }
 }
+
+dependencies {
+  // SMB client library
+  implementation 'com.hierynomus:smbj:0.13.0'
+  // Suppress SLF4J binding warnings
+  implementation 'org.slf4j:slf4j-nop:2.0.13'
+}

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

@@ -18,6 +18,7 @@ class ReactNativeKookitModule : Module() {
   private var originalStreamVolume: Int = 0
   private var ftpClient: FtpClient? = null
   private val ftpClients = mutableMapOf<String, FtpClient>()
+  private val smbClients = mutableMapOf<String, SmbClient>()
   private val moduleScope = CoroutineScope(Dispatchers.Main + SupervisorJob())
 
   // Each module class must implement the definition function. The definition consists of components
@@ -35,7 +36,11 @@ class ReactNativeKookitModule : Module() {
     )
 
     // Defines event names that the module can send to JavaScript.
-    Events("onChange", "onVolumeButtonPressed", "onFtpProgress", "onFtpComplete", "onFtpError")
+    Events(
+      "onChange", "onVolumeButtonPressed",
+      "onFtpProgress", "onFtpComplete", "onFtpError",
+      "onSmbProgress", "onSmbComplete", "onSmbError"
+    )
 
     // Function to enable volume key interception
     Function("enableVolumeKeyInterception") {
@@ -470,6 +475,224 @@ class ReactNativeKookitModule : Module() {
       }
     }
 
+    // SMB Client API
+    AsyncFunction("createSmbClient") { clientId: String, promise: Promise ->
+      moduleScope.launch {
+        try {
+          if (smbClients.containsKey(clientId)) {
+            promise.reject("SMB_CLIENT_EXISTS", "SMB client with ID '$clientId' already exists", null)
+            return@launch
+          }
+          smbClients[clientId] = SmbClient()
+          promise.resolve(mapOf("clientId" to clientId))
+        } catch (e: Exception) {
+          promise.reject("SMB_CREATE_CLIENT_ERROR", e.message, e)
+        }
+      }
+    }
+
+    AsyncFunction("disposeSmbClient") { clientId: String, promise: Promise ->
+      moduleScope.launch {
+        try {
+          smbClients[clientId]?.disconnect()
+          smbClients.remove(clientId)
+          promise.resolve(null)
+        } catch (e: Exception) {
+          promise.reject("SMB_DISPOSE_CLIENT_ERROR", e.message, e)
+        }
+      }
+    }
+
+    AsyncFunction("getSmbClientStatus") { clientId: String, promise: Promise ->
+      moduleScope.launch {
+        try {
+          val client = smbClients[clientId]
+          val status = mapOf(
+            "exists" to (client != null),
+            "connected" to (client?.isConnected() ?: false)
+          )
+          promise.resolve(status)
+        } catch (e: Exception) {
+          promise.reject("SMB_CLIENT_STATUS_ERROR", e.message, e)
+        }
+      }
+    }
+
+    AsyncFunction("listSmbClients") { promise: Promise ->
+      moduleScope.launch {
+        try {
+          val clients = mutableMapOf<String, Map<String, Any>>()
+          smbClients.forEach { (id, client) ->
+            clients[id] = mapOf("connected" to client.isConnected())
+          }
+          val result = mapOf(
+            "clients" to clients,
+            "count" to smbClients.size
+          )
+          promise.resolve(result)
+        } catch (e: Exception) {
+          promise.reject("SMB_LIST_CLIENTS_ERROR", e.message, e)
+        }
+      }
+    }
+
+    AsyncFunction("smbClientConnect") { clientId: String, config: Map<String, Any>, promise: Promise ->
+      moduleScope.launch(Dispatchers.IO) {
+        try {
+          val client = smbClients[clientId]
+            ?: throw Exception("SMB client with ID '$clientId' not found")
+          val cfg = SmbConnectionConfig(
+            host = config["host"] as String,
+            port = (config["port"] as? Double)?.toInt() ?: 445,
+            username = config["username"] as String,
+            password = config["password"] as String,
+            domain = config["domain"] as? String,
+            share = config["share"] as? String,
+            timeoutMs = (config["timeout"] as? Double)?.toInt() ?: 10000
+          )
+          client.connect(cfg)
+          // If share not provided in connect, allow later openShare via list/upload APIs
+          withContext(Dispatchers.Main) { promise.resolve(null) }
+        } catch (e: Exception) {
+          withContext(Dispatchers.Main) { promise.reject("SMB_CLIENT_CONNECT_ERROR", e.message, e) }
+        }
+      }
+    }
+
+    AsyncFunction("smbClientDisconnect") { clientId: String, promise: Promise ->
+      moduleScope.launch {
+        try {
+          val client = smbClients[clientId]
+            ?: throw Exception("SMB client with ID '$clientId' not found")
+          client.disconnect()
+          promise.resolve(null)
+        } catch (e: Exception) {
+          promise.reject("SMB_CLIENT_DISCONNECT_ERROR", e.message, e)
+        }
+      }
+    }
+
+    AsyncFunction("smbClientConnectShare") { clientId: String, shareName: String, promise: Promise ->
+      moduleScope.launch(Dispatchers.IO) {
+        try {
+          val client = smbClients[clientId]
+            ?: throw Exception("SMB client with ID '$clientId' not found")
+          client.openShare(shareName)
+          withContext(Dispatchers.Main) { 
+            promise.resolve(mapOf(
+              "clientId" to clientId,
+              "share" to shareName,
+              "connected" to true
+            ))
+          }
+        } catch (e: Exception) {
+          withContext(Dispatchers.Main) { 
+            promise.reject("SMB_CONNECT_SHARE_ERROR", e.message, e) 
+          }
+        }
+      }
+    }
+
+    AsyncFunction("smbClientList") { clientId: String, path: String?, promise: Promise ->
+      moduleScope.launch(Dispatchers.IO) {
+        try {
+          val client = smbClients[clientId]
+            ?: throw Exception("SMB client with ID '$clientId' not found")
+          val items = client.list(path)
+          val mapped = items.map {
+            mapOf(
+              "name" to it.name,
+              "isDirectory" to it.isDirectory,
+              "size" to it.size,
+              "lastModified" to it.lastModified,
+              "attributes" to it.attributes
+            )
+          }
+          withContext(Dispatchers.Main) { promise.resolve(mapped) }
+        } catch (e: Exception) {
+          withContext(Dispatchers.Main) { promise.reject("SMB_CLIENT_LIST_ERROR", e.message, e) }
+        }
+      }
+    }
+
+    AsyncFunction("smbClientDownload") { clientId: String, remotePath: String, localPath: String, promise: Promise ->
+      moduleScope.launch(Dispatchers.IO) {
+        try {
+          val client = smbClients[clientId]
+            ?: throw Exception("SMB client with ID '$clientId' not found")
+          client.download(remotePath, localPath) { transferred, total ->
+            val percentage = if (total > 0) ((transferred * 100) / total).toInt() else 0
+            sendEvent("onSmbProgress", mapOf(
+              "clientId" to clientId,
+              "transferred" to transferred,
+              "total" to total,
+              "percentage" to percentage
+            ))
+          }
+          sendEvent("onSmbComplete", mapOf("clientId" to clientId))
+          withContext(Dispatchers.Main) { promise.resolve(null) }
+        } catch (e: Exception) {
+          sendEvent("onSmbError", mapOf(
+            "clientId" to clientId,
+            "error" to (e.message ?: "SMB download error")
+          ))
+          withContext(Dispatchers.Main) { promise.reject("SMB_CLIENT_DOWNLOAD_ERROR", e.message, e) }
+        }
+      }
+    }
+
+    AsyncFunction("smbClientUpload") { clientId: String, localPath: String, remotePath: String, promise: Promise ->
+      moduleScope.launch(Dispatchers.IO) {
+        try {
+          val client = smbClients[clientId]
+            ?: throw Exception("SMB client with ID '$clientId' not found")
+          client.upload(localPath, remotePath) { transferred, total ->
+            val percentage = if (total > 0) ((transferred * 100) / total).toInt() else 0
+            sendEvent("onSmbProgress", mapOf(
+              "clientId" to clientId,
+              "transferred" to transferred,
+              "total" to total,
+              "percentage" to percentage
+            ))
+          }
+          sendEvent("onSmbComplete", mapOf("clientId" to clientId))
+          withContext(Dispatchers.Main) { promise.resolve(null) }
+        } catch (e: Exception) {
+          sendEvent("onSmbError", mapOf(
+            "clientId" to clientId,
+            "error" to (e.message ?: "SMB upload error")
+          ))
+          withContext(Dispatchers.Main) { promise.reject("SMB_CLIENT_UPLOAD_ERROR", e.message, e) }
+        }
+      }
+    }
+
+    AsyncFunction("smbClientDelete") { clientId: String, remotePath: String, isDirectory: Boolean?, promise: Promise ->
+      moduleScope.launch(Dispatchers.IO) {
+        try {
+          val client = smbClients[clientId]
+            ?: throw Exception("SMB client with ID '$clientId' not found")
+          client.delete(remotePath, isDirectory ?: false)
+          withContext(Dispatchers.Main) { promise.resolve(null) }
+        } catch (e: Exception) {
+          withContext(Dispatchers.Main) { promise.reject("SMB_CLIENT_DELETE_ERROR", e.message, e) }
+        }
+      }
+    }
+
+    AsyncFunction("smbClientCreateDirectory") { clientId: String, remotePath: String, promise: Promise ->
+      moduleScope.launch(Dispatchers.IO) {
+        try {
+          val client = smbClients[clientId]
+            ?: throw Exception("SMB client with ID '$clientId' not found")
+          client.mkdir(remotePath)
+          withContext(Dispatchers.Main) { promise.resolve(null) }
+        } catch (e: Exception) {
+          withContext(Dispatchers.Main) { promise.reject("SMB_CLIENT_CREATE_DIR_ERROR", e.message, e) }
+        }
+      }
+    }
+
     // Enables the module to be used as a native view. Definition components that are accepted as part of
     // the view definition: Prop, Events.
     View(ReactNativeKookitView::class) {