From 6c53b258c25bd248bfcb5fdb24ae9b3bfa78a703 Mon Sep 17 00:00:00 2001
From: brunoais <brunoaiss@gmail.com>
Date: Sat, 19 Jun 2021 16:24:27 +0100
Subject: [PATCH] Documentation for broadcast-intents

---
 README.md     | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++
 app/src/cli.c | 32 +++++++++++++++++++++++
 2 files changed, 103 insertions(+)

diff --git a/README.md b/README.md
index ba68dfb1..a073987d 100644
--- a/README.md
+++ b/README.md
@@ -721,6 +721,77 @@ The target directory can be changed on start:
 scrcpy --push-target=/sdcard/Download/
 ```
 
+### Android features
+
+#### Announce scrcpy state of execution
+
+**(Advanced feature)**
+
+Turn on the announcement of scrcpy current status.  
+Those announcements are done using the [broadcast intents] feature of Android.  
+If no value is provided with this argument, all intents are turned on.
+
+[broadcast intents]: https://developer.android.com/reference/android/content/Intent
+
+Currently, the only events that exist are:
+
+ | Option    | Description                                   | [Intent Action]                           | [Intent Extras]
+ | ----------|:----------------------------------------------|:---------------------------------|:-----------------------------
+ | `start`   | scrcpy starts                                 |  `com.genymobile.scrcpy.START`   | STARTUP: true
+ | `stop`    | scrcpy stops (best effort)                    |  `com.genymobile.scrcpy.STOP`    | SHUTDOWN: true
+ | `cleaned` | scrcpy has finished cleaning up (best effort) |  `com.genymobile.scrcpy.CLEANED` | SHUTDOWN: true 
+
+[Intent Action]: https://developer.android.com/reference/android/content/Intent#setAction(java.lang.String)
+[Intent Extras]: https://developer.android.com/reference/android/content/Intent#putExtra(java.lang.String,%20android.os.Parcelable)
+
+
+**Important:**
+1. `stop` and `cleaned` **may not happen** in specific cases. For example, 
+   if debugging is turned off, scrcpy process is immediately killed without a chance to cleanup.
+2. This option is intended for advanced users. By using this 
+   feature, all apps on your phone will know scrcpy has connected
+   Unless that is what you want, and you know what that means
+   do not use this feature
+3. In order for this argument to produce visible results you must create
+   some automation to listen to android broadcast intents. 
+   Such as with your own app or with automation apps such as [Tasker].
+
+
+Following [Android intent rules], all intents fields/keys prefixed with: 
+`com.genymobile.scrcpy.`
+In case of Actions, it is followed by the intent name in caps. For example,
+the 'start' intent has the action:  
+`com.genymobile.scrcpy.START`
+
+
+[Android intent rules]: https://developer.android.com/reference/android/content/Intent#setAction(java.lang.String)
+
+Additionally, there are two boolean fields (that may not be present) in the extra data section of the intents:
+
+1. `com.genymobile.scrcpy.STARTUP` if present and `true`, scrcpy is starting up.
+2. `com.genymobile.scrcpy.SHUTDOWN` if present and `true`, scrcpy is shutting down.
+
+More extra fields will be present in the future.
+
+For convinience with automation tools such as [Tasker], scrcpy also writes to the data field of the intents.
+The scheme is `scrcpy-status`.
+
+[Tasker]: https://tasker.joaoapps.com/
+
+**Example usages:**
+
+```bash
+scrcpy --broadcast-intents
+```
+
+```bash
+scrcpy --broadcast-intents=start
+```
+
+```bash
+scrcpy --broadcast-intents start,cleaned
+```
+
 
 ### Audio forwarding
 
diff --git a/app/src/cli.c b/app/src/cli.c
index 462d2ea3..adf424c5 100644
--- a/app/src/cli.c
+++ b/app/src/cli.c
@@ -28,6 +28,38 @@ scrcpy_print_usage(const char *arg0) {
         "        Unit suffixes are supported: 'K' (x1000) and 'M' (x1000000).\n"
         "        Default is " STR(DEFAULT_BIT_RATE) ".\n"
         "\n"
+        "    --broadcast-intents [value[, ...]]\n"
+        "        (Advanced feature)\n"
+        "        Turn on the broadcast of intents with the status of scrcpy \n"
+        "        options are: start, stop, cleaned\n"
+        "        Each of these will arm the corresponding intent\n"
+        "        start: announce finished setting up\n"
+        "        stop: announce shut down started (best effort)\n"
+        "        cleaned: announce cleanup finished (best effort)\n"
+        "        \n"
+        "        If you ommit the value, all intents are turned on\n"
+        "        \n"
+        "        All intents have the action and extra fields prefixed with: \n"
+        "        com.genymobile.scrcpy.\n"
+        "        Which is then followed by the intent name in caps. For example,\n"
+        "        the 'start' intent has the action:\n"
+        "        com.genymobile.scrcpy.START\n"
+        "\n"
+        "        There are two boolean extras use to ease\n"
+        "        the parsing process of the intents:\n"
+        "        1. com.genymobile.scrcpy.STARTUP if present and true,\n"
+        "           scrcpy is starting up.\n"
+        "        2. com.genymobile.scrcpy.SHUTDOWN if present and true,\n"
+        "           scrcpy is shutting down.\n"
+        "        \n"
+        "        Notes:\n"
+        "        1. stop and cleaned may not happen in specific cases. For example, \n"
+        "           if debugging is turned off, scrcpy process is immediately killed \n"
+        "        2. This option is intended for advanced users. By using this \n"
+        "           feature, all apps on your phone will know scrcpy has connected\n"
+        "           Unless that is what you want, and you know what that means\n"
+        "           do not use this feature\n"
+        "\n"
         "    --codec-options key[:type]=value[,...]\n"
         "        Set a list of comma-separated key:type=value options for the\n"
         "        device encoder.\n"