From c559adfda37bc07904e3846c0a7464d01d8240ae Mon Sep 17 00:00:00 2001
From: brunoais <brunoaiss@gmail.com>
Date: Sat, 19 Jun 2021 18:23:41 +0100
Subject: [PATCH] Update documentation to include the socket intnt

---
 README.md     | 26 +++++++++++++++++++-------
 app/src/cli.c |  9 ++++++++-
 2 files changed, 27 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index a073987d..eea7d8cc 100644
--- a/README.md
+++ b/README.md
@@ -735,11 +735,12 @@ If no value is provided with this argument, all intents are turned on.
 
 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 
+ | Option    | Description                                       | [Intent Action]                  | [Intent Extras]
+ | ----------|:----------------------------------------------    |:---------------------------------|:---------------
+ | `start`   | scrcpy starts                                     |  `com.genymobile.scrcpy.START`   | STARTUP: true
+ | `socket`  | a socket for the duration of scrcpy's run created |  `com.genymobile.scrcpy.SOCKET`  | SOCKET: int
+ | `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)
@@ -748,11 +749,13 @@ Currently, the only events that exist are:
 **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 
+2. The only guaranteed way to know if scrcpy has exited is by listening for a connection reset on
+   the socket
+3. 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
+4. 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].
 
@@ -770,9 +773,18 @@ Additionally, there are two boolean fields (that may not be present) in the extr
 
 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.
+3. `com.genymobile.scrcpy.SOCKET` if present and an int, scrcpy has created a socket on the specified
+   port and you can listen to it to confirm when scrcpy exits
 
 More extra fields will be present in the future.
 
+In case you listen to the socket provided by `com.genymobile.scrcpy.SOCKET`, note that **no information will
+be exchanged through it**. Even though bytes will be transmitted through it, they are only a test to
+ensure the connection is still alive and have no meaning.  
+A connection reset followed by connection refused when trying to reestablish the connection is the
+only infallible way to ensure that scrcpy has turned off.
+
+
 For convinience with automation tools such as [Tasker], scrcpy also writes to the data field of the intents.
 The scheme is `scrcpy-status`.
 
diff --git a/app/src/cli.c b/app/src/cli.c
index b2814421..30b6a580 100644
--- a/app/src/cli.c
+++ b/app/src/cli.c
@@ -31,9 +31,10 @@ scrcpy_print_usage(const char *arg0) {
         "    --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"
+        "        options are: start, socket, stop, cleaned\n"
         "        Each of these will arm the corresponding intent\n"
         "        start: announce finished setting up\n"
+        "        socket: announce isAlive server port\n"
         "        stop: announce shut down started (best effort)\n"
         "        cleaned: announce cleanup finished (best effort)\n"
         "        \n"
@@ -51,6 +52,12 @@ scrcpy_print_usage(const char *arg0) {
         "           scrcpy is starting up.\n"
         "        2. com.genymobile.scrcpy.SHUTDOWN if present and true,\n"
         "           scrcpy is shutting down.\n"
+        "\n"
+        "        socket has a different extra\n"
+        "        com.genymobile.scrcpy.SOCKET which is the port where the socket\n"
+        "        listens to.\n"
+        "        Listening for a connection reset on the socket is the only\n"
+        "        guaranteed way to know when scrcpy disconnects or crashes\n"
         "        \n"
         "        Notes:\n"
         "        1. stop and cleaned may not happen in specific cases. For example, \n"