Add postMessage APIs to the support lib

customtabs/src/android/support/customtabs/CustomTabsService.java

Index: customtabs/src/android/support/customtabs/CustomTabsService.java
diff --git a/customtabs/src/android/support/customtabs/CustomTabsService.java b/customtabs/src/android/support/customtabs/CustomTabsService.java
index 25697c5e3bdb35c3e411e670ee4456a16a5dcd46..3061a6986d3735489e946ebfa474b6c27676442a 100644
--- a/customtabs/src/android/support/customtabs/CustomTabsService.java
+++ b/customtabs/src/android/support/customtabs/CustomTabsService.java
@@ -23,6 +23,7 @@ import android.os.Bundle;
 import android.os.IBinder;
 import android.os.IBinder.DeathRecipient;
 import android.os.RemoteException;
+import android.support.annotation.IntDef;
 import android.support.v4.util.ArrayMap;
 
 import java.util.List;
@@ -50,6 +51,14 @@ import java.util.NoSuchElementException;
      public static final String KEY_URL =
              "android.support.customtabs.otherurls.URL";
 
+     @IntDef({RESULT_SUCCESS, RESULT_FAILURE_DISALLOWED,
+         RESULT_FAILURE_REMOTE_ERROR, RESULT_FAILURE_MESSAGING_ERROR})
+     public @interface Result {}
+     public static final int RESULT_SUCCESS = 0;
+     public static final int RESULT_FAILURE_DISALLOWED = -1;
+     public static final int RESULT_FAILURE_REMOTE_ERROR = -2;
+     public static final int RESULT_FAILURE_MESSAGING_ERROR = -3;
+
      private final Map<IBinder, DeathRecipient> mDeathRecipientMap = new ArrayMap<>();
 
      private ICustomTabsService.Stub mBinder = new ICustomTabsService.Stub() {
@@ -96,6 +105,18 @@ import java.util.NoSuchElementException;
              return CustomTabsService.this.updateVisuals(
                      new CustomTabsSessionToken(callback), bundle);
          }
+
+         @Override
+         public boolean validatePostMessageOrigin(ICustomTabsCallback callback) {

[Benoit L, 2016/11/08 16:27:07]

nit: This is likely for a future CL, but it would be nice to avoid having to
create a new CustomTabsSessionToken for each message, and more generally for
each service call.

Since the Binder objects are comparable, we could perhaps cache the
CustomTabsSessionToken objects. Or perhaps even just keep the most recent one,
since we suspect that the majority of clients will have only one session.

This is not important for correctness and only concerns the browser side, so I
think we can safely defer that to a future CL.

What do you think?

[Yusuf, 2016/11/08 18:59:10]

Makes sense, and yeah since it is kind of gonna be a non-trivial change on the
mechanism here, let's defer it.

+             return CustomTabsService.this.validatePostMessageOrigin(
+                     new CustomTabsSessionToken(callback));
+         }
+
+         @Override
+         public int postMessage(ICustomTabsCallback callback, String message, Bundle extras) {
+             return CustomTabsService.this.postMessage(
+                     new CustomTabsSessionToken(callback), message, extras);
+         }
      };
 
      @Override
@@ -193,4 +214,32 @@ import java.util.NoSuchElementException;
      */
      protected abstract boolean updateVisuals(CustomTabsSessionToken sessionToken,
              Bundle bundle);
+
+     /**
+      * Sends a request to the implementation to validate and assign a postMessage origin for the
+      * related {@link CustomTabsSession}.
+      *
+      * <p>This also acts a trigger to setup a postMessage communication channel.

[Benoit L, 2016/11/08 16:27:07]

nit: s/a trigger/as a trigger/

[Yusuf, 2016/11/08 18:59:10]

Done.

+      *
+      * @param sessionToken The unique identifier for the session. Can not be null.
+      * @return Whether the implementation accepted the validation request. Note that returning true
+      *         here doesn't mean an origin has already been assigned as the validation is
+      *         asynchronous.
+      */
+     protected abstract boolean validatePostMessageOrigin(CustomTabsSessionToken sessionToken);
+
+     /**
+      * Sends a postMessage request using the origin that has been validated and communicated via
+      * {@link CustomTabsCallback#onMessageChannelReady(Uri, Bundle)}. Returns false when called

[Benoit L, 2016/11/08 16:27:06]

nit: This does not return a boolean, what is the error code in this case?

[Yusuf, 2016/11/08 18:59:10]

CustomTabsService.Result (annotated below) is the return value. So it is the
same error code that CustomTabsService returns. See line 117 up above.

[Benoit L, 2016/11/09 10:11:00]

The Javadoc is not correct then, "Returns false when". Sorry, the comment was
not really clear.

[Yusuf, 2016/11/09 18:29:21]

Done.

+      * without a preceding
+      * {@link CustomTabsService#validatePostMessageOrigin(CustomTabsSessionToken)}.
+      *
+      * @param sessionToken The unique identifier for the session. Can not be null.
+      * @param message The message that is being sent.
+      * @param extras Reserved for future use.
+      * @return An integer constant about the postMessage request result.
+      */
+     @Result
+     protected abstract int postMessage(
+             CustomTabsSessionToken sessionToken, String message, Bundle extras);
  }