react-native-kookit 0.3.5 → 0.3.7

package/SMB_CLIENT_STATIC_METHODS.md

@@ -1,175 +0,0 @@
-# SMB Client 静态方法使用示例
-
-SmbClient新增了多个静态方法来管理多个客户端实例：
-
-## 新增的静态方法
-
-### 1. `SmbClient.disposeClient(clientId: string)`
-
-销毁指定客户端ID的客户端实例
-
-```typescript
-// 销毁特定的客户端
-const disposed = await SmbClient.disposeClient("my_client_id");
-console.log("Client disposed:", disposed); // true/false
-```
-
-### 2. `SmbClient.getClientStatus(clientId: string)`
-
-获取指定客户端ID的状态信息
-
-```typescript
-// 获取客户端状态
-const status = SmbClient.getClientStatus("my_client_id");
-console.log("Client status:", status);
-// 返回: {
-//   exists: true,
-//   isConnected: true,
-//   currentShare: 'C$',
-//   isDisposed: false
-// }
-```
-
-### 3. `SmbClient.getAllClientsStatus()`
-
-获取所有活跃客户端的状态
-
-```typescript
-// 获取所有客户端状态
-const allStatus = SmbClient.getAllClientsStatus();
-allStatus.forEach((status, clientId) => {
-  console.log(`Client ${clientId}:`, status);
-});
-```
-
-### 4. `SmbClient.getInstance(clientId: string)`
-
-获取指定客户端ID的实例对象
-
-```typescript
-// 获取现有的客户端实例
-const existingClient = SmbClient.getInstance("my_client_id");
-if (existingClient) {
-  await existingClient.listFiles("/");
-}
-```
-
-### 5. `SmbClient.disposeAllClients()`
-
-销毁所有客户端实例
-
-```typescript
-// 清理所有客户端
-const disposedCount = await SmbClient.disposeAllClients();
-console.log(`Disposed ${disposedCount} clients`);
-```
-
-## 使用示例
-
-```typescript
-import SmbClient from "react-native-kookit";
-
-export class SmbManager {
-  private clients: Map<string, SmbClient> = new Map();
-
-  // 创建命名客户端
-  async createNamedClient(
-    name: string,
-    config: SmbConnectionConfig
-  ): Promise<SmbClient> {
-    const client = await SmbClient.create(name);
-    await client.connect(config);
-    this.clients.set(name, client);
-    return client;
-  }
-
-  // 检查客户端是否存在且连接
-  isClientReady(name: string): boolean {
-    const status = SmbClient.getClientStatus(name);
-    return status.exists && status.isConnected && !status.isDisposed;
-  }
-
-  // 安全获取客户端
-  getClient(name: string): SmbClient | null {
-    if (this.isClientReady(name)) {
-      return SmbClient.getInstance(name);
-    }
-    return null;
-  }
-
-  // 销毁指定客户端
-  async removeClient(name: string): Promise<boolean> {
-    this.clients.delete(name);
-    return await SmbClient.disposeClient(name);
-  }
-
-  // 获取所有客户端状态报告
-  getStatusReport(): Record<string, any> {
-    const report: Record<string, any> = {};
-    const allStatus = SmbClient.getAllClientsStatus();
-
-    allStatus.forEach((status, clientId) => {
-      report[clientId] = {
-        ...status,
-        managed: this.clients.has(clientId),
-      };
-    });
-
-    return report;
-  }
-
-  // 清理所有资源
-  async cleanup(): Promise<void> {
-    this.clients.clear();
-    await SmbClient.disposeAllClients();
-  }
-}
-
-// 使用示例
-const smbManager = new SmbManager();
-
-// 创建多个客户端
-const client1 = await smbManager.createNamedClient("server1", {
-  host: "192.168.1.100",
-  username: "user1",
-  password: "pass1",
-});
-
-const client2 = await smbManager.createNamedClient("server2", {
-  host: "192.168.1.101",
-  username: "user2",
-  password: "pass2",
-});
-
-// 检查状态
-console.log("Status report:", smbManager.getStatusReport());
-
-// 使用特定客户端
-const client = smbManager.getClient("server1");
-if (client) {
-  const files = await client.listFiles("/");
-  console.log("Files:", files);
-}
-
-// 清理资源
-await smbManager.cleanup();
-```
-
-## 类型定义
-
-```typescript
-export interface SmbClientStatus {
-  exists: boolean;
-  isConnected: boolean;
-  currentShare: string | null;
-  isDisposed: boolean;
-}
-
-export interface SmbClientInfo {
-  isConnected: boolean;
-  currentShare: string | null;
-  isDisposed: boolean;
-}
-```
-
-这些静态方法使得SmbClient的多实例管理变得更加简单和安全。

package/SMB_COMPLETE_GUIDE.md

@@ -1,308 +0,0 @@
-# SMB Client Implementation
-
-This document provides comprehensive documentation for the SMB client functionality in react-native-kookit.
-
-## Overview
-
-The SMB client provides object-oriented access to SMB/CIFS file shares, supporting both Android and iOS platforms with a unified API.
-
-## Features
-
-- **Object-oriented design**: Create multiple SMB client instances
-- **Cross-platform**: Works on both Android and iOS
-- **Progress tracking**: Real-time upload/download progress events
-- **Full file operations**: List, download, upload, delete, create directories
-- **Authentication**: Supports username/password and domain authentication
-- **Share management**: Connect to different shares on the same server
-
-## Platform Support
-
-### Android
-
-- Uses SMBJ library (version 0.13.0)
-- Supports SMB2/3 protocols
-- Full authentication and file operations
-
-### iOS
-
-- Uses SMBClient library (version 0.3.1)
-- Supports SMB2 protocol
-- Async/await Swift implementation
-
-## API Reference
-
-### Creating an SMB Client
-
-```typescript
-import { SmbClient } from "react-native-kookit";
-
-// Create and initialize a new SMB client
-const client = await SmbClient.create();
-
-// Or create with custom client ID
-const client = await SmbClient.create("my-smb-client");
-```
-
-### Connection Configuration
-
-```typescript
-interface SmbConnectionConfig {
-  host: string; // SMB server IP or hostname
-  port?: number; // Port (default: 445)
-  username: string; // Username for authentication
-  password: string; // Password for authentication
-  domain?: string; // Domain name (optional)
-  share?: string; // Share name to connect to (optional)
-  timeout?: number; // Connection timeout in milliseconds (default: 10000)
-}
-```
-
-### Event Handlers
-
-```typescript
-client.setEventHandlers({
-  onProgress: (progress: {
-    transferred: number;
-    total: number;
-    percentage: number;
-  }) => {
-    console.log(`Progress: ${progress.percentage}%`);
-  },
-  onComplete: () => {
-    console.log("Operation completed");
-  },
-  onError: (error: Error) => {
-    console.error("SMB error:", error.message);
-  },
-});
-```
-
-### Connection Methods
-
-```typescript
-// Connect to SMB server
-await client.connect({
-  host: "192.168.1.100",
-  username: "admin",
-  password: "password",
-  domain: "WORKGROUP",
-  share: "shared",
-  timeout: 15000,
-});
-
-// Connect to a different share on the same server
-await client.connectShare("documents");
-
-// Disconnect from server
-await client.disconnect();
-
-// Dispose of the client (cleanup resources)
-await client.dispose();
-```
-
-### File Operations
-
-```typescript
-// List files and directories
-const files = await client.list("/path/to/directory");
-console.log(files); // Array of SmbFileInfo objects
-
-// Download a file
-await client.download("/remote/file.txt", "/local/path/file.txt");
-
-// Upload a file
-await client.upload("/local/path/file.txt", "/remote/file.txt");
-
-// Delete a file
-await client.delete("/remote/file.txt");
-
-// Delete a directory
-await client.delete("/remote/directory", true);
-
-// Create a directory
-await client.createDirectory("/remote/new_directory");
-```
-
-### File Information Structure
-
-```typescript
-interface SmbFileInfo {
-  name: string; // File/directory name
-  isDirectory: boolean; // Whether it's a directory
-  size: number; // File size in bytes
-  lastModified: string; // Last modification date
-  attributes?: string; // File attributes (platform-specific)
-}
-```
-
-### Client Management
-
-```typescript
-// Get client status
-const status = await SmbClient.getClientStatus("client-id");
-console.log(status); // { exists: boolean, connected: boolean }
-
-// List all clients
-const clients = await SmbClient.listClients();
-console.log(clients); // { clients: Record<string, { connected: boolean }>, count: number }
-```
-
-## Usage Examples
-
-### Basic Connection and File Listing
-
-```typescript
-import { SmbClient } from "react-native-kookit";
-
-async function basicExample() {
-  const client = await SmbClient.create();
-
-  try {
-    await client.connect({
-      host: "192.168.1.100",
-      username: "admin",
-      password: "password",
-      share: "shared",
-    });
-
-    const files = await client.list();
-    files.forEach((file) => {
-      console.log(
-        `${file.isDirectory ? "📁" : "📄"} ${file.name} (${file.size} bytes)`
-      );
-    });
-  } catch (error) {
-    console.error("Error:", error.message);
-  } finally {
-    await client.dispose();
-  }
-}
-```
-
-### File Upload with Progress
-
-```typescript
-async function uploadWithProgress() {
-  const client = await SmbClient.create();
-
-  client.setEventHandlers({
-    onProgress: (progress) => {
-      console.log(`Upload progress: ${progress.percentage}%`);
-    },
-    onComplete: () => {
-      console.log("Upload completed!");
-    },
-    onError: (error) => {
-      console.error("Upload failed:", error.message);
-    },
-  });
-
-  try {
-    await client.connect({
-      host: "192.168.1.100",
-      username: "admin",
-      password: "password",
-      share: "uploads",
-    });
-
-    await client.upload("/local/document.pdf", "/remote/backup/document.pdf");
-  } finally {
-    await client.dispose();
-  }
-}
-```
-
-### Multiple Share Access
-
-```typescript
-async function multiShareExample() {
-  const client = await SmbClient.create();
-
-  try {
-    // Connect to server
-    await client.connect({
-      host: "192.168.1.100",
-      username: "admin",
-      password: "password",
-    });
-
-    // Connect to documents share
-    await client.connectShare("documents");
-    const docFiles = await client.list();
-    console.log("Documents:", docFiles.length, "files");
-
-    // Switch to media share
-    await client.connectShare("media");
-    const mediaFiles = await client.list();
-    console.log("Media:", mediaFiles.length, "files");
-  } finally {
-    await client.dispose();
-  }
-}
-```
-
-## Error Handling
-
-The SMB client throws specific errors for different scenarios:
-
-```typescript
-try {
-  await client.connect(config);
-} catch (error) {
-  if (error.message.includes("SMB_CONNECT_ERROR")) {
-    // Handle connection errors
-  } else if (error.message.includes("SMB_AUTH_ERROR")) {
-    // Handle authentication errors
-  } else {
-    // Handle other errors
-  }
-}
-```
-
-## Common Error Codes
-
-- `SMB_CLIENT_EXISTS`: Client with the same ID already exists
-- `SMB_CLIENT_NOT_FOUND`: Client ID not found
-- `SMB_CONNECT_ERROR`: Connection failed
-- `SMB_LIST_ERROR`: Failed to list directory
-- `SMB_DOWNLOAD_ERROR`: Download operation failed
-- `SMB_UPLOAD_ERROR`: Upload operation failed
-- `SMB_DELETE_ERROR`: Delete operation failed
-- `SMB_CREATE_DIR_ERROR`: Directory creation failed
-
-## Best Practices
-
-1. **Always dispose clients**: Use `try/finally` blocks to ensure proper cleanup
-2. **Handle connection timeouts**: Set appropriate timeout values based on network conditions
-3. **Use progress events**: Provide user feedback for long-running operations
-4. **Error handling**: Implement comprehensive error handling for network operations
-5. **Connection pooling**: Reuse client instances when possible to reduce overhead
-
-## Troubleshooting
-
-### Connection Issues
-
-- Verify SMB server is accessible and SMB service is running
-- Check firewall settings (default port 445)
-- Ensure correct username/password credentials
-- Try connecting without specifying a share first
-
-### Authentication Problems
-
-- Verify domain name is correct (or omit if not using domain)
-- Check user permissions on the target share
-- Some servers require specific SMB protocol versions
-
-### File Operation Errors
-
-- Ensure the share is properly connected before file operations
-- Check file/directory permissions
-- Verify paths use forward slashes (/) as separators
-- Some special characters in filenames may cause issues
-
-## Performance Considerations
-
-- File operations are async and don't block the UI thread
-- Large file transfers will trigger progress events for better UX
-- Multiple concurrent operations on the same client are queued
-- Consider using separate clients for parallel operations on different shares

package/SMB_HYBRID_IMPLEMENTATION.md

@@ -1,160 +0,0 @@
-# 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名称