0
# JNA Platform
1

2
JNA Platform provides comprehensive cross-platform native API access for Java applications. It extends the core Java Native Access (JNA) library with platform-specific functionality and utilities, offering developers a complete abstraction layer for native system calls across Windows, macOS, and Linux platforms without requiring JNI code.
3

4
## Package Information
5

6
- **Package Name**: jna-platform
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Maven Group**: net.java.dev.jna
10
- **Installation**: 
11
  ```xml
12
  <dependency>
13
    <groupId>net.java.dev.jna</groupId>
14
    <artifactId>jna-platform</artifactId>
15
    <version>5.17.0</version>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
import com.sun.jna.platform.FileUtils;
23
import com.sun.jna.platform.WindowUtils;
24
import com.sun.jna.platform.KeyboardUtils;
25
import com.sun.jna.platform.EnumUtils;
26
import com.sun.jna.platform.dnd.DragHandler;
27
import com.sun.jna.platform.dnd.DropHandler;
28
import com.sun.jna.platform.win32.Kernel32;
29
import com.sun.jna.platform.win32.User32;
30
import com.sun.jna.platform.unix.LibC;
31
import com.sun.jna.platform.mac.CoreFoundation;
32
```
33

34
## Basic Usage
35

36
```java
37
import com.sun.jna.platform.FileUtils;
38
import com.sun.jna.platform.WindowUtils;
39
import com.sun.jna.platform.win32.Kernel32;
40
import com.sun.jna.platform.win32.User32;
41
import com.sun.jna.platform.win32.WinDef.HWND;
42

43
// Cross-platform file operations
44
FileUtils fileUtils = FileUtils.getInstance();
45
fileUtils.moveToTrash(new File("temp.txt"));
46

47
// Cross-platform window manipulation  
48
WindowUtils.setWindowAlpha(window, 0.5f); // 50% transparency
49

50
// Windows-specific system calls (when on Windows)
51
if (Platform.isWindows()) {
52
    HWND hwnd = User32.INSTANCE.FindWindow(null, "Calculator");
53
    if (hwnd != null) {
54
        User32.INSTANCE.ShowWindow(hwnd, User32.SW_MAXIMIZE);
55
    }
56
    
57
    // Get system information
58
    int processId = Kernel32.INSTANCE.GetCurrentProcessId();
59
    System.out.println("Current PID: " + processId);
60
}
61
```
62

63
## Architecture
64

65
JNA Platform is organized around several key architectural components:
66

67
- **Cross-Platform Abstractions**: Base classes like `FileUtils` and `WindowUtils` provide unified APIs with platform-specific implementations
68
- **Platform-Specific Libraries**: Direct bindings to native APIs (Win32, POSIX, etc.) accessed through singleton instances
69
- **Utility Wrappers**: High-level wrapper classes (*Util classes) that simplify common operations and provide better error handling
70
- **Type Definitions**: Complete data structure definitions matching native types (HWND, DWORD, RECT, etc.)
71
- **COM Integration**: Comprehensive Component Object Model support for Windows automation
72

73
## Capabilities
74

75
### Cross-Platform Utilities
76

77
Core utilities that work across Windows, macOS, and Linux platforms, providing unified APIs for file management, window manipulation, keyboard input, and utility functions.
78

79
```java { .api }
80
// File operations
81
public abstract class FileUtils {
82
    public static FileUtils getInstance();
83
    public abstract void moveToTrash(File... files) throws IOException;
84
    public abstract boolean hasTrash();
85
}
86

87
// Window manipulation and effects
88
public class WindowUtils {
89
    public static void setWindowMask(Window w, Shape mask);
90
    public static void setWindowAlpha(Window w, float alpha);
91
    public static void setWindowTransparent(Window w, boolean transparent);
92
    public static List<DesktopWindow> getAllWindows(boolean onlyVisible);
93
    public static BufferedImage getWindowIcon(HWND hwnd);
94
    public static String getWindowTitle(HWND hwnd);
95
}
96

97
// Keyboard state access
98
public class KeyboardUtils {
99
    public static boolean isPressed(int keycode);
100
    public static boolean isPressed(int keycode, int location);
101
}
102

103
// Enum conversion utilities
104
public class EnumUtils {
105
    public static <E extends Enum<E>> int toInteger(E val);
106
    public static <E extends Enum<E>> E fromInteger(int idx, Class<E> clazz);
107
    public static <T extends FlagEnum> Set<T> setFromInteger(int flags, Class<T> clazz);
108
    public static <T extends FlagEnum> int setToInteger(Set<T> set);
109
}
110
```
111

112
[Cross-Platform Utilities](./cross-platform.md)
113

114
### Windows Platform APIs
115

116
Comprehensive Windows API bindings including core system functions, user interface operations, graphics, networking, and COM automation.
117

118
```java { .api }
119
// Core Windows APIs
120
public interface Kernel32 extends StdCallLibrary, WinNT, Wincon {
121
    Kernel32 INSTANCE = Native.load("kernel32", Kernel32.class, W32APIOptions.DEFAULT_OPTIONS);
122
    
123
    boolean CreateProcess(String lpApplicationName, String lpCommandLine, 
124
                         WinBase.SECURITY_ATTRIBUTES lpProcessAttributes,
125
                         WinBase.SECURITY_ATTRIBUTES lpThreadAttributes,
126
                         boolean bInheritHandles, DWORD dwCreationFlags,
127
                         Pointer lpEnvironment, String lpCurrentDirectory,
128
                         WinBase.STARTUPINFO lpStartupInfo,
129
                         WinBase.PROCESS_INFORMATION lpProcessInformation);
130
    
131
    HANDLE OpenProcess(DWORD dwDesiredAccess, boolean bInheritHandle, DWORD dwProcessId);
132
    DWORD GetCurrentProcessId();
133
    DWORD GetLastError();
134
}
135

136
public interface User32 extends StdCallLibrary, WinUser, WinNT {
137
    User32 INSTANCE = Native.load("user32", User32.class, W32APIOptions.DEFAULT_OPTIONS);
138
    
139
    HWND FindWindow(String lpClassName, String lpWindowName);
140
    int GetWindowText(HWND hWnd, char[] lpString, int nMaxCount);
141
    LRESULT SendMessage(HWND hWnd, int Msg, WPARAM wParam, LPARAM lParam);
142
    boolean ShowWindow(HWND hWnd, int nCmdShow);
143
}
144
```
145

146
[Windows Platform](./windows.md)
147

148
### Unix/Linux Platform APIs
149

150
POSIX-compliant system calls and Linux-specific functionality including X11 graphics, device management, and file system operations.
151

152
```java { .api }
153
// Unix/Linux system calls
154
public interface LibC extends Library {
155
    LibC INSTANCE = Native.load("c", LibC.class);
156
    
157
    int open(String path, int flags);
158
    int close(int fd);
159
    int read(int fd, Buffer buffer, int count);
160
    int write(int fd, Buffer buffer, int count);
161
    int chmod(String path, int mode);
162
}
163

164
// X Window System
165
public interface X11 extends Library {
166
    X11 INSTANCE = Native.load("X11", X11.class);
167
    
168
    Display XOpenDisplay(String display_name);
169
    int XCloseDisplay(Display display);
170
    Window XCreateSimpleWindow(Display display, Window parent, int x, int y, 
171
                              int width, int height, int border_width, 
172
                              long border, long background);
173
}
174
```
175

176
[Unix/Linux Platform](./unix-linux.md)
177

178
### Mac Platform APIs
179

180
macOS-specific frameworks including Core Foundation, IOKit for hardware access, and Carbon for system events.
181

182
```java { .api }
183
// Core Foundation framework
184
public interface CoreFoundation extends Library {
185
    CoreFoundation INSTANCE = Native.load("CoreFoundation", CoreFoundation.class);
186
    
187
    CFStringRef CFStringCreateWithCString(CFAllocatorRef alloc, String cStr, int encoding);
188
    void CFRelease(CFTypeRef cf);
189
    CFTypeID CFGetTypeID(CFTypeRef cf);
190
}
191

192
// I/O Kit framework
193
public interface IOKit extends Library {
194
    IOKit INSTANCE = Native.load("IOKit", IOKit.class);
195
    
196
    CFMutableDictionaryRef IOServiceMatching(String name);
197
    int IOServiceGetMatchingServices(int masterPort, CFDictionaryRef matching, 
198
                                   Pointer existing);
199
}
200
```
201

202
[Mac Platform](./mac.md)
203

204
### COM Automation (Windows)
205

206
Complete Component Object Model support for Windows automation, including interfaces, utilities, and type library importing.
207

208
```java { .api }
209
// Base COM interface
210
public interface IUnknown {
211
    HRESULT QueryInterface(REFIID riid, PointerByReference ppvObject);
212
    int AddRef();
213
    int Release();
214
}
215

216
// COM automation interface  
217
public interface IDispatch extends IUnknown {
218
    HRESULT GetTypeInfoCount(IntByReference pctinfo);
219
    HRESULT GetTypeInfo(int iTInfo, LCID lcid, PointerByReference ppTInfo);
220
    HRESULT Invoke(DISPID dispIdMember, REFIID riid, LCID lcid, WORD wFlags,
221
                   DISPPARAMS.ByReference pDispParams, VARIANT.ByReference pVarResult,
222
                   EXCEPINFO.ByReference pExcepInfo, IntByReference puArgErr);
223
}
224
```
225

226
[COM Automation](./com.md)
227

228
### Drag and Drop Support
229

230
Enhanced drag and drop functionality with cross-platform ghosted images and simplified APIs that extend Java's built-in support.
231

232
```java { .api }
233
// Drag handling with ghosted images
234
public abstract class DragHandler {
235
    protected DragHandler(Component dragSource, int actions);
236
    public static Transferable getTransferable(DropTargetEvent e);
237
}
238

239
// Drop handling with visual feedback
240
public abstract class DropHandler implements DropTargetListener {
241
    public DropHandler(Component dropTarget, int actions);
242
    public boolean isActive();
243
    public void setActive(boolean active);
244
}
245

246
// Ghosted drag images
247
public class GhostedDragImage {
248
    public GhostedDragImage(Component dragSource, Icon icon, Point initialScreenLoc, Point cursorOffset);
249
    public void setAlpha(float alpha);
250
    public void move(Point screenLocation);
251
    public void dispose();
252
}
253
```
254

255
[Drag and Drop Support](./drag-drop.md)
256

257
## Entry Points by Platform
258

259
### Cross-Platform Entry Points
260
- `FileUtils.getInstance()` - Platform-specific file operations
261
- `WindowUtils` static methods - Window manipulation and effects
262
- `KeyboardUtils` static methods - Keyboard state access
263
- `EnumUtils` static methods - Enum conversion utilities
264
- `DragHandler`, `DropHandler` - Enhanced drag and drop functionality
265

266
### Windows Entry Points
267
- `Kernel32.INSTANCE` - Core Windows system functions
268
- `User32.INSTANCE` - Windows UI and message handling
269
- `Advapi32.INSTANCE` - Advanced Windows services and registry
270
- `COM.ObjectFactory` - COM object creation and automation
271

272
### Unix/Linux Entry Points  
273
- `LibC.INSTANCE` - POSIX system calls
274
- `X11.INSTANCE` - X Window System operations
275
- `Udev.INSTANCE` - Linux device management (Linux only)
276

277
### Mac Entry Points
278
- `CoreFoundation.INSTANCE` - Core Foundation operations
279
- `IOKit.INSTANCE` - Hardware and device access
280
- `Carbon.INSTANCE` - Legacy Carbon framework events
281

282
## Error Handling
283

284
JNA Platform provides several mechanisms for error handling:
285

286
- **Win32Exception**: Windows-specific errors with GetLastError() integration
287
- **IOReturnException**: macOS IOKit operation errors  
288
- **Native errno**: Unix/Linux system call error codes
289
- **COM exceptions**: Automated error handling for COM operations
290

291
## Common Types
292

293
```java { .api }
294
// Windows types
295
public class WinDef {
296
    public static class HWND extends HANDLE { }
297
    public static class DWORD extends IntegerType { }
298
    public static class WORD extends IntegerType { }
299
    public static class LRESULT extends IntegerType { }
300
    public static class WPARAM extends IntegerType { }
301
    public static class LPARAM extends IntegerType { }
302
    public static class RECT extends Structure {
303
        public int left, top, right, bottom;
304
    }
305
    public static class POINT extends Structure {
306
        public int x, y;
307
    }
308
}
309

310
// Cross-platform window information
311
public class DesktopWindow {
312
    private HWND hwnd;
313
    private String title;
314
    private String filePath;
315
    private Rectangle bounds;
316
}
317
```