refactor(jna): 更新设备和图像接口为指针类型- 将 HGLibDeviceScanEventFunc 和 HGLibDeviceScanImageFunc 回调中的设备参数改为 Pointer 类型
- 修改所有图像相关函数的参数和返回值为 Pointer 类型- 修改所有设备相关函数的参数和返回值为 Pointer 类型- 在 HGScannerWrapper 中适配新的 Pointer 类型接口- 更新 openDevice、loadImage 和 cloneImage 方法以处理 Pointer 类型- 添加空的 CLAUDE.md 文件提供项目指导信息
This commit is contained in:
93
CLAUDE.md
Normal file
93
CLAUDE.md
Normal file
@ -0,0 +1,93 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
HuaGoScanner-SDK is a Java library providing scanner functionality through JNA (Java Native Access) wrapper around the native HGScannerLib DLL. The SDK enables Java applications to control HuaGo scanners, perform scanning operations, and process scanned images.
|
||||
|
||||
## Build Commands
|
||||
|
||||
### Basic Build Operations
|
||||
```bash
|
||||
# Clean and compile the project
|
||||
mvn clean compile
|
||||
|
||||
# Run tests (if any exist)
|
||||
mvn test
|
||||
|
||||
# Build JAR package
|
||||
mvn package
|
||||
|
||||
# Verify build (compile + test + package)
|
||||
mvn clean verify
|
||||
```
|
||||
|
||||
### Maven Publishing
|
||||
```bash
|
||||
# Deploy to snapshot repository
|
||||
mvn clean deploy
|
||||
|
||||
# Deploy to release repository (with source and javadoc)
|
||||
mvn clean deploy -P release
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
1. **HGDef.java** - Basic type definitions and mappings from native C types to JNA types
|
||||
2. **HGScannerLib.java** - Main JNA interface mapping to the native HGScannerLib DLL
|
||||
3. **HGScannerConstants.java** - Comprehensive constant definitions for error codes, device parameters, and configuration options
|
||||
4. **HGScannerWrapper.java** - High-level Java wrapper providing simplified, user-friendly API methods
|
||||
|
||||
### Key Architectural Patterns
|
||||
|
||||
- **JNA Layer**: Low-level native library interface using JNA `Structure` and `Callback` mappings
|
||||
- **Wrapper Layer**: Simplified Java API that handles memory management, string encoding, and error handling
|
||||
- **Static Factory**: The library uses static initialization to load the native DLL from a fixed Windows path
|
||||
|
||||
### Native Library Dependencies
|
||||
|
||||
The SDK depends on:
|
||||
- JNA (Java Native Access) library v5.17.0
|
||||
- JNA Platform library v5.17.0
|
||||
- Native HGScannerLib.dll (expected at `C:/Program Files (x86)/HuaGoScannerLib/bin/x64`)
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Adding New Scanner Features
|
||||
|
||||
1. **Native Interface**: Add new constants and method signatures to `HGScannerLib.java`
|
||||
2. **Constants**: Define any new constant values in `HGScannerConstants.java`
|
||||
3. **Wrapper Implementation**: Implement high-level wrapper methods in `HGScannerWrapper.java` with proper error handling and memory management
|
||||
|
||||
### Memory Management
|
||||
|
||||
- Always release native resources using the corresponding release methods
|
||||
- Use `try-finally` blocks to ensure cleanup
|
||||
- Pay attention to pointer management in JNA Structure mappings
|
||||
|
||||
### String Handling
|
||||
|
||||
- Use UTF-8 encoding for all string operations between Java and native code
|
||||
- Buffer sizes are defined as `STRING_BUFFER_SIZE = 256` in the wrapper
|
||||
- Handle null-terminated C strings properly when reading from native buffers
|
||||
|
||||
## Testing
|
||||
|
||||
Test files should be placed in `src/test/java/`. The Main.java class is currently empty and can be used for manual testing of scanner functionality.
|
||||
|
||||
## Release Process
|
||||
|
||||
The project is configured for Maven Central publishing with GPG signing. See DEPLOY.md for detailed release instructions, including:
|
||||
- GPG key setup and requirements
|
||||
- Maven settings configuration
|
||||
- Release deployment commands
|
||||
|
||||
## Important Notes
|
||||
|
||||
- The SDK currently only supports Windows (due to native DLL dependency)
|
||||
- Native library path is hardcoded in `HGScannerWrapper.java` static block
|
||||
- All native library calls use the stdcall calling convention
|
||||
- Error codes are categorized into software errors (0x1xx), USB errors (0x5Bxx), and hardware errors (0xDExx)
|
||||
@ -239,11 +239,11 @@ public interface HGScannerLib extends HGDef, StdCallLibrary {
|
||||
}
|
||||
|
||||
interface HGLibDeviceScanEventFunc extends Callback {
|
||||
void invoke(HGLibDevice device, int event, int operateCode, String info, Pointer param);
|
||||
void invoke(Pointer device, int event, int operateCode, String info, Pointer param);
|
||||
}
|
||||
|
||||
interface HGLibDeviceScanImageFunc extends Callback {
|
||||
void invoke(HGLibDevice device, HGLibImage image, Pointer param);
|
||||
void invoke(Pointer device, Pointer image, Pointer param);
|
||||
}
|
||||
|
||||
// ==================== 函数接口定义 ====================
|
||||
@ -252,21 +252,21 @@ public interface HGScannerLib extends HGDef, StdCallLibrary {
|
||||
boolean HGLib_MemoryCopy(Pointer dest, Pointer src, int size);
|
||||
|
||||
// 图像相关函数
|
||||
HGLibImage HGLib_LoadImage(String filePath);
|
||||
Pointer HGLib_LoadImage(String filePath);
|
||||
|
||||
HGLibImage HGLib_CloneImage(HGLibImage image, int type, int origin);
|
||||
Pointer HGLib_CloneImage(Pointer image, int type, int origin);
|
||||
|
||||
Pointer HGLib_GetImageData(HGLibImage image);
|
||||
Pointer HGLib_GetImageData(Pointer image);
|
||||
|
||||
boolean HGLib_GetImageInfo(HGLibImage image, HGLibImageInfo.ByReference imageInfo);
|
||||
boolean HGLib_GetImageInfo(Pointer image, HGLibImageInfo.ByReference imageInfo);
|
||||
|
||||
boolean HGLib_GetImageDpi(HGLibImage image, IntByReference xDpi, IntByReference yDpi);
|
||||
boolean HGLib_GetImageDpi(Pointer image, IntByReference xDpi, IntByReference yDpi);
|
||||
|
||||
boolean HGLib_SaveImage(HGLibImage image, String savePath, HGLibSaveImageParam saveParam);
|
||||
boolean HGLib_SaveImage(Pointer image, String savePath, HGLibSaveImageParam saveParam);
|
||||
|
||||
boolean HGLib_ReleaseImage(HGLibImage image);
|
||||
boolean HGLib_ReleaseImage(Pointer image);
|
||||
|
||||
String HGLib_GetOcrText(HGLibImage image);
|
||||
String HGLib_GetOcrText(Pointer image);
|
||||
|
||||
boolean HGLib_ReleaseOcrText(String ocrText);
|
||||
|
||||
@ -279,65 +279,65 @@ public interface HGScannerLib extends HGDef, StdCallLibrary {
|
||||
|
||||
boolean HGLib_ReleaseDeviceNameList(Pointer deviceNameList);
|
||||
|
||||
HGLibDevice HGLib_OpenDevice(String deviceName);
|
||||
Pointer HGLib_OpenDevice(String deviceName);
|
||||
|
||||
boolean HGLib_CloseDevice(HGLibDevice device);
|
||||
boolean HGLib_CloseDevice(Pointer device);
|
||||
|
||||
boolean HGLib_GetDeviceType(HGLibDevice device, byte[] type, int maxLen);
|
||||
boolean HGLib_GetDeviceType(Pointer device, byte[] type, int maxLen);
|
||||
|
||||
boolean HGLib_GetDeviceSN(HGLibDevice device, byte[] sn, int maxLen);
|
||||
boolean HGLib_GetDeviceSN(Pointer device, byte[] sn, int maxLen);
|
||||
|
||||
boolean HGLib_GetDeviceFWVersion(HGLibDevice device, byte[] fwVersion, int maxLen);
|
||||
boolean HGLib_GetDeviceFWVersion(Pointer device, byte[] fwVersion, int maxLen);
|
||||
|
||||
boolean HGLib_GetDevicePD(HGLibDevice device, byte[] pd, int maxLen);
|
||||
boolean HGLib_GetDevicePD(Pointer device, byte[] pd, int maxLen);
|
||||
|
||||
boolean HGLib_GetDevicePatchId(HGLibDevice device, byte[] patchId, int maxLen);
|
||||
boolean HGLib_GetDevicePatchId(Pointer device, byte[] patchId, int maxLen);
|
||||
|
||||
int HGLib_GetDeviceRollerCount(HGLibDevice device);
|
||||
int HGLib_GetDeviceRollerCount(Pointer device);
|
||||
|
||||
int HGLib_GetDeviceTotalCount(HGLibDevice device);
|
||||
int HGLib_GetDeviceTotalCount(Pointer device);
|
||||
|
||||
boolean HGLib_ClearDeviceRollerCount(HGLibDevice device);
|
||||
boolean HGLib_ClearDeviceRollerCount(Pointer device);
|
||||
|
||||
boolean HGLib_SetDeviceToken(HGLibDevice device, String code);
|
||||
boolean HGLib_SetDeviceToken(Pointer device, String code);
|
||||
|
||||
boolean HGLib_SetOriginalImage(HGLibDevice device, int isOriginal);
|
||||
boolean HGLib_SetOriginalImage(Pointer device, int isOriginal);
|
||||
|
||||
// 设备参数相关函数
|
||||
boolean HGLib_SetDeviceParam(HGLibDevice device, int option, Pointer data);
|
||||
boolean HGLib_SetDeviceParam(Pointer device, int option, Pointer data);
|
||||
|
||||
Pointer HGLib_GetDeviceParamGroupList(HGLibDevice device, IntByReference count);
|
||||
Pointer HGLib_GetDeviceParamGroupList(Pointer device, IntByReference count);
|
||||
|
||||
Pointer HGLib_GetDeviceParam(HGLibDevice device, int option);
|
||||
Pointer HGLib_GetDeviceParam(Pointer device, int option);
|
||||
|
||||
boolean HGLib_ReleaseDeviceParamGroupList(Pointer paramGroup, int count);
|
||||
|
||||
boolean HGLib_ReleaseDeviceParam(Pointer param);
|
||||
|
||||
boolean HGLib_ResetDeviceParam(HGLibDevice device);
|
||||
boolean HGLib_ResetDeviceParam(Pointer device);
|
||||
|
||||
// 设备状态相关函数
|
||||
boolean HGLib_DeviceIsPaperOn(HGLibDevice device);
|
||||
boolean HGLib_DeviceIsPaperOn(Pointer device);
|
||||
|
||||
int HGLib_GetDeviceStatus(HGLibDevice device);
|
||||
int HGLib_GetDeviceStatus(Pointer device);
|
||||
|
||||
boolean HGLib_GetDeviceIsOnline(HGLibDevice device);
|
||||
boolean HGLib_GetDeviceIsOnline(Pointer device);
|
||||
|
||||
boolean HGLib_DeviceRestart(HGLibDevice device);
|
||||
boolean HGLib_DeviceRestart(Pointer device);
|
||||
|
||||
boolean HGLib_DeviceShutDown(HGLibDevice device);
|
||||
boolean HGLib_DeviceShutDown(Pointer device);
|
||||
|
||||
// 扫描相关函数
|
||||
boolean HGLib_StartDeviceScan(HGLibDevice device, HGLibDeviceScanEventFunc eventFunc, Pointer eventParam,
|
||||
boolean HGLib_StartDeviceScan(Pointer device, HGLibDeviceScanEventFunc eventFunc, Pointer eventParam,
|
||||
HGLibDeviceScanImageFunc imageFunc, Pointer imageParam);
|
||||
|
||||
boolean HGLib_StopDeviceScan(HGLibDevice device);
|
||||
boolean HGLib_StopDeviceScan(Pointer device);
|
||||
|
||||
boolean HGLib_StopDeviceScanAsyn(HGLibDevice device);
|
||||
boolean HGLib_StopDeviceScanAsyn(Pointer device);
|
||||
|
||||
int HGLib_GetDeviceOperateCode(HGLibDevice device);
|
||||
int HGLib_GetDeviceOperateCode(Pointer device);
|
||||
|
||||
int HGLib_GetDevicePageId(HGLibDevice device);
|
||||
int HGLib_GetDevicePageId(Pointer device);
|
||||
|
||||
// ==================== 工厂方法 ====================
|
||||
|
||||
|
||||
@ -81,7 +81,8 @@ public class HGScannerWrapper {
|
||||
* @return 设备句柄
|
||||
*/
|
||||
public static HGScannerLib.HGLibDevice openDevice(String deviceName) {
|
||||
return scannerLib.HGLib_OpenDevice(deviceName);
|
||||
Pointer devicePtr = scannerLib.HGLib_OpenDevice(deviceName);
|
||||
return devicePtr != null ? new HGScannerLib.HGLibDevice(Pointer.nativeValue(devicePtr)) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
@ -161,7 +162,8 @@ public class HGScannerWrapper {
|
||||
* @return 图像句柄
|
||||
*/
|
||||
public static HGScannerLib.HGLibImage loadImage(String filePath) {
|
||||
return scannerLib.HGLib_LoadImage(filePath);
|
||||
Pointer imagePtr = scannerLib.HGLib_LoadImage(filePath);
|
||||
return imagePtr != null ? new HGScannerLib.HGLibImage(Pointer.nativeValue(imagePtr)) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
@ -342,7 +344,8 @@ public class HGScannerWrapper {
|
||||
* @return 克隆后的图像句柄
|
||||
*/
|
||||
public static HGScannerLib.HGLibImage cloneImage(HGScannerLib.HGLibImage image, int type, int origin) {
|
||||
return scannerLib.HGLib_CloneImage(image, type, origin);
|
||||
Pointer imagePtr = scannerLib.HGLib_CloneImage(image, type, origin);
|
||||
return imagePtr != null ? new HGScannerLib.HGLibImage(Pointer.nativeValue(imagePtr)) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
Reference in New Issue
Block a user