jpkdll API

# jpkdll

The jpkdll name come from Java Process Killer DLL (where Java Process Killer is the Java interface implemented by the DLL at the beginning). Now, jpkdll is implementing mainly 3 interfaces, corresponding to three main directions of use:

1. Task Manager API called TM API from now on;
2. Service Control Manager API - called SCM API from now on;
3. Access Control Manager API called ACM API from now on;

The SCM API is the programmatic implementation of services offered by the Services applet in Windows NT/2000, the TM API is the programmatic implementation of services offered by the Task Manager applet in Windows NT/2000, and the ACM API is the programmatic implementation of consulting, enabling and disabling the debug programs privilege in the Local Security Settings (previously assigned to the current user via Security Settings/Local Policies/User Rights Assignment.

## Version warning

The programmatic implementation is generally working correctly and therefore applicable on both NT and 2000 versions of Windows (as stated in MSDN for specific Win32 API used). BUT, due to large version of Windows NT available (if we include various patches and services packs), the current version warning apply: "The DLL was developed on Windows 2000 Professional SP0 (i.e. no services pack), reported version by ver command "Microsoft Windows 2000 [Version 5.00.2195]", using Visual C++ v6.0, and Microsoft Platform SDK August 2001 for Windows 2000". Currently the developer is aware of the following limitations:

- finding the process id for a service related API is not available on Windows versions previous to 2000, therefore the API work correctly and the dll load without problems for Windows 2000 only;

## Error reporting

Each of the three API report the error the same way, as stated in the java interface bellow. Generally each API throw an java.io.IOException carrying a string in the following format "<code>|<code>|<code>" with the following meaning:

- 1st code is the API specific error code (each of the three APIs define a specific set of errors);
- 2nd code is the Win32 reported code for the offending Win32 API call (reported by the GetLastError() Win32 API);
- 3rd code is the Dll source line where the error occured.

The string carried inside the thrown exception is for informative purposes only (logging it, reporting to user, etc), no specific action beeing implied by particular values (retry is possible for specific APIs).

A detailed explanation of each API specific error code (1st code) is give for each of the three APIs. Also errors are cross references against each API call bellow. The code is specific for each of the three APIs (i.e. the value of n have different meaning for API1 and API2). It;s true that all the three APIs share the value of 0 = no_error code.

Particular values for the 2nd code are shown in the error table extracted from MSDN (MSDN January 2000 Release).

The 3rd code is for internal use only.

API return value is used generally to report the correct execution results. In some special cases the return value is used to report errors too, as stated for that particular API (the common one is that each API test jni environment, and return 0 cast to the return value (0 for int, false for boolean, null for []) when jni related parameters are invalid).

## jpkdll interface

    	/* task manager */
    	public native String[] applications() throws java.io.IOException;
    	public native String[] processes() throws java.io.IOException;
    	public native int app2pid(String app) throws java.io.IOException;
    	public native String pid2exename(int pid) throws java.io.IOException;
    	public native boolean exist_pid(int pid) throws java.io.IOException;
    	public native boolean kill(int pid) throws java.io.IOException;
    	public native int[] kill_tree(int pid) throws java.io.IOException;
    	public native int[] get_tree(int pid) throws java.io.IOException;

    	/* service manager */
    	public native boolean startService(String servicename) throws java.io.IOException;
    	public native boolean stopService(String servicename) throws java.io.IOException;
    	public native boolean isRunningService(String servicename) throws java.io.IOException;
    	public native boolean isConfiguredService(String servicename) throws java.io.IOException;
    	public native String[] listServices() throws java.io.IOException;
    	public native int service2pid(String servicename) throws java.io.IOException;
    	public native int getServiceState(String servicename) throws java.io.IOException;
    	public native int getServiceControls(String servicename) throws java.io.IOException;
    	public native boolean isServiceDBLocked() throws java.io.IOException;
    	public native String serviceName2DisplayName(String servicename) throws java.io.IOException;
    	public native String displayName2ServiceName(String servicename) throws java.io.IOException;

    	/* access control manager */
    	public native boolean isDebugPrivilegeEnabled() throws java.io.IOException;
    	public native void enableDebugPrivilege(boolean bEnable) throws java.io.IOException;

## TM API

### TM API Errors

The following specific error codes (1st code) are generally reported by TM API:

ok | 0
internal_error | 1
param_errors | 2
can_not_enumerate_windows | 3
can_not_enumerate_processes | 4
no_window_for_app_name | 5
can_not_open_process_for_pid | 6
can_not_kill | 7
can_not_start_snapshot | 8
can_not_iterate_snapshot | 9
not_enough_memory | 10
can_not_create_array | 11

### public native String[] applications() throws java.io.IOException;

Goal | Return the title (window text) of all top-level windows
Remarks | No particular order (like the lexicographic order) is guaranteed. Top-level windows are windows that have desktop as parent or no parent at all. Generally these windows appear in the taskbar. The same result in show in the "Applications" tab in Task Manager applet.
Parameters | none
Return value | String []
No throw returns | non-null string[] with each top-level window title.
Specific thrown code | can_not_enumerate_windows | window enumation process failed.
internal_error | severe internal error conditions occured
can_not_create_array | jni create string[] failed

### public native String[] processes() throws java.io.IOException;

Goal |
Remarks |
Parameters |
Return value |
No throw returns |
Specific thrown code |  |

##

### public native int app2pid(String app) throws java.io.IOException;

Goal |
Remarks |
Parameters |
Return value |
No throw returns |
Specific thrown code |  |

### public native String pid2exename(int pid) throws java.io.IOException;

Goal |
Remarks |
Parameters |
Return value |
No throw returns |
Specific thrown code |  |

### public native boolean exist_pid(int pid) throws java.io.IOException;

Goal |
Remarks |
Parameters |
Return value |
No throw returns |
Specific thrown code |  |

### public native boolean kill(int pid) throws java.io.IOException;

Goal |
Remarks |
Parameters |
Return value |
No throw returns |
Specific thrown code |  |

### public native int[] kill_tree(int pid) throws java.io.IOException;

Goal |
Remarks |
Parameters |
Return value |
No throw returns |
Specific thrown code |  |

### public native int[] get_tree(int pid) throws java.io.IOException;

Goal |
Remarks |
Parameters |
Return value |
No throw returns |
Specific thrown code |  |