Commit 34387bb1 authored by Mygod's avatar Mygod

Update doc

parent 3c6d5a89
......@@ -136,8 +136,8 @@ Every native mode plugin MUST have a content provider to provide the native exec
* MUST implement `query` that returns the file list which MUST include `$PLUGIN_ID` when having
these as arguments:
- `uri = "content://$authority_of_your_provider`;
- `projection = ["path", "mode"]`; (relative path, for example `obfs-local`; file mode, for
example `755`)
- `projection = ["path", "mode"]`; (relative path, for example `obfs-local`; file mode as integer, for
example `0b110100100`)
- `selection = null`;
- `selectionArgs = null`;
- `sortOrder = null`;
......@@ -186,10 +186,19 @@ If your plugin binary executable can run in place, you can support native mode w
`com.github.shadowsocks.plugin.EXTRA_ENTRY` when having `method = "shadowsocks:getExecutable"`;
(`com.github.shadowsocks.plugin.EXTRA_OPTIONS` is provided in extras as well just in case you
need them)
* SHOULD define `android:installLocation="internalOnly"` for `<manifest>` in AndroidManifest.xml;
* SHOULD define `android:extractNativeLibs="true"` for `<application>` in AndroidManifest.xml;
If you don't plan to support this mode, you can just throw `UnsupportedOperationException` when
being invoked. It will fallback to the slow routine automatically.
### Native mode without binary copying and setup
Additionally, if your plugin only needs to supply the path of your executable without doing any extra setup work,
you can use an additional `meta-data` with name `com.github.shadowsocks.plugin.executable_path`
to supply executable path to your native binary.
This allows the host app to launch your plugin without ever launching your app.
## JVM mode
This feature hasn't been implemented yet.
......@@ -229,7 +238,7 @@ Plugin app must include this in their application tag: (which should be automati
```
<meta-data android:name="com.github.shadowsocks.plugin.version"
android:value="0.0.2"/>
android:value="1.0.0"/>
```
# Android TV
......
......@@ -69,7 +69,11 @@ abstract class NativePluginProvider : ContentProvider() {
}
/**
* Returns executable entry absolute path. This is used if plugin is sharing UID with the host.
* Returns executable entry absolute path.
* This is used for fast mode initialization where ss-local launches your native binary at the path given directly.
* In order for this to work, plugin app is encouraged to have the following in its AndroidManifest.xml:
* - android:installLocation="internalOnly" for <manifest>
* - android:extractNativeLibs="true" for <application>
*
* Default behavior is throwing UnsupportedOperationException. If you don't wish to use this feature, use the
* default behavior.
......
......@@ -88,7 +88,11 @@ object PluginContract {
* The metadata key to retrieve executable path to your native binary.
* This path should be relative to your application's nativeLibraryDir.
*
* If this is set, the host app will prefer this value and (probably) not launch your app at all.
* If this is set, the host app will prefer this value and (probably) not launch your app at all (aka faster mode).
* In order for this to work, plugin app is encouraged to have the following in its AndroidManifest.xml:
* - android:installLocation="internalOnly" for <manifest>
* - android:extractNativeLibs="true" for <application>
*
* Do not use this if you plan to do some setup work before giving away your binary path,
* or your native binary is not at a fixed location relative to your application's nativeLibraryDir.
*
......@@ -112,11 +116,11 @@ object PluginContract {
*/
const val COLUMN_PATH = "path"
/**
* File mode bits. Default value is "644".
* File mode bits. Default value is 644 in octal.
*
* Example: "755"
* Example: 0b110100100 (for 755 in octal)
*
* Type: String
* Type: Int or String (deprecated)
*/
const val COLUMN_MODE = "mode"
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment