diff --git a/OpenPGP-API.md b/OpenPGP-API.md index 2bbb5c0..b44d9e4 100644 --- a/OpenPGP-API.md +++ b/OpenPGP-API.md @@ -4,7 +4,7 @@ To get an idea how this API works from a user's perspective install [OpenKeychai ## 1. Add the API library to your project -Copy the directory [OpenPGP-Keychain-API/libraries/openpgp-api-library](https://github.com/openpgp-keychain/openpgp-keychain/tree/master/OpenPGP-Keychain-API/libraries/openpgp-api-library) from this git repository into a subfolder of your projects directory. +Copy the directory [OpenKeychain-API/libraries/openpgp-api-library](https://github.com/open-keychain/open-keychain/tree/master/OpenKeychain-API/libraries/openpgp-api-library) from this git repository into a subfolder of your projects directory. ### Gradle/Android Studio 1. Reference the library by including the library project in your ``settings.gradle`` file (adjust the path to your folder layout): @@ -23,13 +23,13 @@ Please read ["Referencing a library project"](http://developer.android.com/tools ## 2. Understand the basic design of the OpenPGP API -The API is **not** designed around ``Intents`` which are started via ``startActivityForResult``. These Intent actions typically start an activity for user interaction, so they are not suitable for background tasks. Most API design decisions are explained at [the bottom of this wiki page](https://github.com/openpgp-keychain/openpgp-keychain/wiki/OpenPGP-API#internal-design-decisions). +The API is **not** designed around ``Intents`` which are started via ``startActivityForResult``. These Intent actions typically start an activity for user interaction, so they are not suitable for background tasks. Most API design decisions are explained at [the bottom of this wiki page](https://github.com/open-keychain/open-keychain/wiki/OpenPGP-API#internal-design-decisions). We will go through the basic steps to understand how this API works, following this (greatly simplified) sequence diagram: -![](https://github.com/openpgp-keychain/openpgp-keychain/raw/master/Resources/docs/openpgp_api_1.jpg) +![](https://github.com/open-keychain/open-keychain/raw/master/Resources/docs/openpgp_api_1.jpg) In this diagram the client app is depicted on the left side, the OpenPGP provider (in this case OpenKeychain) is depicted on the right. -The remote service is defined via the [AIDL](http://developer.android.com/guide/components/aidl.html) file [``IOpenPgpService``](https://github.com/openpgp-keychain/openpgp-keychain/blob/master/OpenPGP-Keychain-API/libraries/openpgp-api-library/src/org/openintents/openpgp/IOpenPgpService.aidl). +The remote service is defined via the [AIDL](http://developer.android.com/guide/components/aidl.html) file [``IOpenPgpService``](https://github.com/open-keychain/open-keychain/blob/master/OpenKeychain-API/libraries/openpgp-api-library/src/org/openintents/openpgp/IOpenPgpService.aidl). It contains only one exposed method which can be invoked remotely: ```java interface IOpenPgpService { @@ -143,17 +143,17 @@ Intent result = api.executeApi(data, is, os); ## 3. Tipps * ``api.executeApi(data, is, os);`` is a blocking call. If you want a convenient asynchronous call, use ``api.executeApiAsync(data, is, os, new MyCallback([... ]));``, where ``MyCallback`` is an private class implementing ``OpenPgpApi.IOpenPgpCallback``. - See [``OpenPgpProviderActivity.java``](https://github.com/openpgp-keychain/openpgp-keychain/blob/master/OpenPGP-Keychain-API/example-app/src/main/java/org/sufficientlysecure/keychain/demo/OpenPgpProviderActivity.java) for an example. + See [``OpenPgpProviderActivity.java``](https://github.com/open-keychain/open-keychain/blob/master/OpenKeychain-API/example-app/src/main/java/org/sufficientlysecure/keychain/demo/OpenPgpProviderActivity.java) for an example. * Using ```java mServiceConnection = new OpenPgpServiceConnection(this, "org.sufficientlysecure.keychain"); ``` connects to OpenKeychain directly. - If you want to let the user choose between OpenPGP providers, you can implement the [``OpenPgpListPreference.java``](https://github.com/openpgp-keychain/openpgp-keychain/blob/master/OpenPGP-Keychain-API/libraries/openpgp-api-library/src/org/openintents/openpgp/util/OpenPgpListPreference.java) like done in the example app. + If you want to let the user choose between OpenPGP providers, you can implement the [``OpenPgpListPreference.java``](https://github.com/open-keychain/open-keychain/blob/master/OpenKeychain-API/libraries/openpgp-api-library/src/org/openintents/openpgp/util/OpenPgpListPreference.java) like done in the example app. ## 4. Complete example -A complete example can be found in the demo application's [``OpenPgpProviderActivity.java``](https://github.com/openpgp-keychain/openpgp-keychain/blob/master/OpenPGP-Keychain-API/example-app/src/main/java/org/sufficientlysecure/keychain/demo/OpenPgpProviderActivity.java). +A complete example can be found in the demo application's [``OpenPgpProviderActivity.java``](https://github.com/open-keychain/open-keychain/blob/master/OpenKeychain-API/example-app/src/main/java/org/sufficientlysecure/keychain/demo/OpenPgpProviderActivity.java). ## Internal Design Decisions * The API does not use the Android permission system due to [its problems](http://commonsware.com/blog/2014/02/12/vulnerabilities-custom-permissions.html) ([details](https://github.com/commonsguy/cwac-security/blob/master/PERMS.md)). Instead OpenKeychain stores its own table of granted applications.