edl/API_README.md

API usage guide

This API was developed to provide a native Python integration with all EDL features.

API setup

Before anything, you should import it and instance the API with:

from edlclient.Library.api import *

e = edl_api()

After that, you should set your desired EDL options (those who starts with --), e.g. --debugmode. For this, you should use the set_arg() method, like this:

e.set_arg("--debugmode", True)

Be aware that, by default, the set_arg() method returns the full arguments dictionary, but, if the passed option doesn't exist, it'll return Invalid key!. This should be useful to avoid future errors.

Also, you can use the reset_arg() method to set back any option to its default value. This method's return is the same as the set_arg(), because it's actually just a wrapper to set_arg(key, None, True).

That said, now you should initialize the API with the init() method. However, note that:

1. The API initialization should be done after you set the -- options

2. To change any -- option after the API initialization, you should reinitialize the API with the reinit() method (which is equivalent to deinit() + init())

3. You can use the deinit() method to "free" the API. This will happen automatically when the API instance (i.e. the Python object) gets destroyed or the program exits

4. Every init()/reinit()/deinit() calls will return the API status attribute, which stores a code that can be useful to check if any errors occurred. The stored value will be 1 for error or 0 for success

And, finally, the API is ready to be used!

EDL commands

In summary, all EDL commands are API methods and they follow this same structure: command([arg1[, arg2[, arg3]]]). To a better understanding, we're going to take the peek command as an example: we know that peek requires <offset>, <length> and <filename> as its arguments, respectively. This way, considering the <offset> as 0x100000, <length> as 80 and <filename> as output.bin, we should have this API call:

e.peek(0x100000, 80, "output.bin")

And that's it for all the EDL commands! Simple, isn't it?

For the full command list and their arguments, refer to EDL's documentation (i.e. edl --help or README.md)

Basic usage example

This example covers the basic (and probably most common) API usage, so check it out:

from edlclient.Library.api import *

# Step 1
e = edl_api()
e.set_arg("--debugmode", True)
if (e.init() == 1):
	exit(1)

# Step 2
e.peek(0x100000, 80, "peek1.bin")

# Step 3
e.reset_arg("--debugmode")
if (e.reinit() == 1):
	exit(1)

# Step 4
e.peek(0x100080, 80, "peek2.bin")

# Step 5
e.reset()

Steps explanation:

1. The API is instanced and initialized with the --debugmode option enabled

2. A peek command is executed

3. The --debugmode option is disabled and, in order to take effect, the API is reinitialized

4. Another peek command is executed

5. The Android device is restarted with the reset command

For a more contextualized and robust example, check the Examples/api_example.py