HuaGoScanner-SDK/CLAUDE.md

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

# 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

# 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)