Add new api ClipDescription.getTimestamp.

ClipDescription.getTimestamp can be used to know the time
at which the associated ClipData is copied to global clipboard.

Bug: 30873580
Test: cts-tradefed run singleCommand cts-dev --module CtsContentTestCases -t \
      android.content.cts.ClipDescriptionTest
Change-Id: I9486ab3fe0696959d42f6b4c98e40f5becee3019

api/current.txt

@@ -8054,6 +8054,7 @@ package android.content {
     method public java.lang.CharSequence getLabel();
     method public java.lang.String getMimeType(int);
     method public int getMimeTypeCount();
+    method public long getTimestamp();
     method public boolean hasMimeType(java.lang.String);
     method public void setExtras(android.os.PersistableBundle);
     method public void writeToParcel(android.os.Parcel, int);

api/system-current.txt

@@ -8439,6 +8439,7 @@ package android.content {
     method public java.lang.CharSequence getLabel();
     method public java.lang.String getMimeType(int);
     method public int getMimeTypeCount();
+    method public long getTimestamp();
     method public boolean hasMimeType(java.lang.String);
     method public void setExtras(android.os.PersistableBundle);
     method public void writeToParcel(android.os.Parcel, int);

api/test-current.txt

@@ -8077,6 +8077,7 @@ package android.content {
     method public java.lang.CharSequence getLabel();
     method public java.lang.String getMimeType(int);
     method public int getMimeTypeCount();
+    method public long getTimestamp();
     method public boolean hasMimeType(java.lang.String);
     method public void setExtras(android.os.PersistableBundle);
     method public void writeToParcel(android.os.Parcel, int);

core/java/android/content/ClipDescription.java

@@ -19,7 +19,9 @@ package android.content;
 import android.os.Parcel;
 import android.os.Parcelable;
 import android.os.PersistableBundle;
+import android.os.SystemClock;
 import android.text.TextUtils;
+import android.util.TimeUtils;
 
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -92,6 +94,7 @@ public class ClipDescription implements Parcelable {
     final CharSequence mLabel;
     private final ArrayList<String> mMimeTypes;
     private PersistableBundle mExtras;
+    private long mTimeStamp;
 
     /**
      * Create a new clip.
@@ -113,6 +116,7 @@ public class ClipDescription implements Parcelable {
     public ClipDescription(ClipDescription o) {
         mLabel = o.mLabel;
         mMimeTypes = new ArrayList<String>(o.mMimeTypes);
+        mTimeStamp = o.mTimeStamp;
     }
 
     /**
@@ -141,6 +145,29 @@ public class ClipDescription implements Parcelable {
         return false;
     }
 
+    /**
+     * Used for setting the timestamp at which the associated {@link ClipData} is copied to
+     * global clipboard.
+     *
+     * @param timeStamp at which the associated {@link ClipData} is copeid to clipboard in
+     *                  {@link SystemClock#elapsedRealtime()} time base.
+     * @hide
+     */
+    public void setTimestamp(long timeStamp) {
+        mTimeStamp = timeStamp;
+    }
+
+    /**
+     * Return the timestamp at which the associated {@link ClipData} is copied to global clipboard
+     * in the {@link SystemClock#elapsedRealtime()} time base.
+     *
+     * @return timestamp at which the associated {@link ClipData} is copied to global clipboard
+     *         or {@code 0} if it is not copied to clipboard.
+     */
+    public long getTimestamp() {
+        return mTimeStamp;
+    }
+
     /**
      * Return the label for this clip.
      */
@@ -285,6 +312,13 @@ public class ClipDescription implements Parcelable {
             first = false;
             b.append(mExtras.toString());
         }
+        if (mTimeStamp > 0) {
+            if (!first) {
+                b.append(' ');
+            }
+            first = false;
+            TimeUtils.formatDuration(mTimeStamp, b);
+        }
         return !first;
     }
 
@@ -312,12 +346,14 @@ public class ClipDescription implements Parcelable {
         TextUtils.writeToParcel(mLabel, dest, flags);
         dest.writeStringList(mMimeTypes);
         dest.writePersistableBundle(mExtras);
+        dest.writeLong(mTimeStamp);
     }
 
     ClipDescription(Parcel in) {
         mLabel = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in);
         mMimeTypes = in.createStringArrayList();
         mExtras = in.readPersistableBundle();
+        mTimeStamp = in.readLong();
     }
 
     public static final Parcelable.Creator<ClipDescription> CREATOR =

services/core/java/com/android/server/clipboard/ClipboardService.java

@@ -41,6 +41,7 @@ import android.os.RemoteCallbackList;
 import android.os.RemoteException;
 import android.os.ServiceManager;
 import android.os.SystemProperties;
+import android.os.SystemClock;
 import android.os.UserHandle;
 import android.os.UserManager;
 import android.util.Slog;
@@ -403,6 +404,10 @@ public class ClipboardService extends SystemService {
             return;
         }
         clipboard.primaryClip = clip;
+        final ClipDescription description = clipboard.primaryClip.getDescription();
+        if (description != null) {
+            description.setTimestamp(SystemClock.elapsedRealtime());
+        }
         final long ident = Binder.clearCallingIdentity();
         final int n = clipboard.primaryClipListeners.beginBroadcast();
         try {