topjohnwu/libsu
1
0
Fork 0
mirror of https://github.com/topjohnwu/libsu.git synced 2024-10-07 01:03:22 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update Javadoc

Browse Source
This commit is contained in:
topjohnwu 2022-04-29 00:39:22 -07:00
parent bef6098d2f
commit e7a5594ef1
2 changed files with 38 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
nio/src/main/java/com/topjohnwu/superuser/nio/ExtendedFile.java
View File

@ -29,6 +29,25 @@ import java.io.InputStream;
import java.io.OutputStream;
import java.net.URI;
/**
* {@link File} API with extended features.
* <p>
* The goal of this class is to extend missing features in the {@link File} API that are available
* in the NIO package but not possible to be re-implemented without low-level file system access.
* For instance, detecting file types other than regular files and directories, handling and
* creating hard links and symbolic links.
* <p>
* Another goal of this class is to provide a generalized API interface for custom file system
* backends. The library includes backends for accessing files locally, accessing files remotely
* via IPC, and accessing files through shell commands (by using {@code SuFile}, included in the
* {@code io} module). The developer can get instances of this class through several APIs in
* {@link FileSystemManager}.
* <p>
* Implementations of this class is required to return the same type of {@link ExtendedFile} in
* all of its APIs returning {@link File}s. This means that, for example, if the developer is
* getting a list of files in a directory using a remote file system with {@link #listFiles()},
* all files returned in the array will also be using the same remote file system backend.
*/
public abstract class ExtendedFile extends File {
/**

24
nio/src/main/java/com/topjohnwu/superuser/nio/FileSystemManager.java
View File

@ -41,16 +41,16 @@ public abstract class FileSystemManager {
private static final FileSystemManager LOCAL = NIOFactory.createLocal();
/**
* Get the service that exposes file system APIs over Binder IPC.
* Get the service that exports the file system of the current process over Binder IPC.
* <p>
* Sending the {@link Binder} obtained from this method to a client process enables
* the calling process to perform file system operations on behalf of the client.
* the current process to perform file system operations on behalf of the client.
* This allows a client process to access files normally denied by its permissions.
* <p>
* You can pass this {@link Binder} object in many different ways, such as returning it in the
* {@code onBind()} method of (root) services, passing it around with a {@link Bundle},
* {@code onBind()} method of (root) services, passing it around in a {@link Bundle},
* or returning it in an AIDL interface method. The receiving end will get an {@link IBinder},
* which should be passed to {@link #getRemote(IBinder)} for usage.
* which the developer should then pass to {@link #getRemote(IBinder)} for usage.
*/
@NonNull
public synchronized static Binder getService() {
@ -59,13 +59,27 @@ public abstract class FileSystemManager {
return fsService;
}
/**
* Create a {@link FileSystemManager} to access the file system of the current local process.
*/
@NonNull
public static FileSystemManager getLocal() {
return LOCAL;
}
/**
* Create a {@link FileSystemManager} to access file system APIs of a remote process.
* Create a {@link FileSystemManager} to access the file system of a remote process.
* <p>
* Several APIs are not supported through a remote process:
* <ul>
* <li>{@link File#deleteOnExit()}</li>
* <li>{@link FileChannel#map(FileChannel.MapMode, long, long)}</li>
* <li>{@link FileChannel#lock()}</li>
* <li>{@link FileChannel#lock(long, long, boolean)}</li>
* <li>{@link FileChannel#tryLock()}</li>
* <li>{@link FileChannel#tryLock(long, long, boolean)}</li>
* </ul>
* Calling these APIs will throw {@link UnsupportedOperationException}.
* @param binder a remote proxy of the {@link Binder} obtained from {@link #getService()}
*/
@NonNull