Merge "Expose Circle and Polygon as SystemApi"

api/system-current.txt

@@ -7937,6 +7937,13 @@ package android.telephony {
   public class CbGeoUtils {
   }
 
+  public static class CbGeoUtils.Circle implements android.telephony.CbGeoUtils.Geometry {
+    ctor public CbGeoUtils.Circle(@NonNull android.telephony.CbGeoUtils.LatLng, double);
+    method public boolean contains(@NonNull android.telephony.CbGeoUtils.LatLng);
+    method @NonNull public android.telephony.CbGeoUtils.LatLng getCenter();
+    method public double getRadius();
+  }
+
   public static interface CbGeoUtils.Geometry {
     method public boolean contains(@NonNull android.telephony.CbGeoUtils.LatLng);
   }
@@ -7949,6 +7956,12 @@ package android.telephony {
     field public final double lng;
   }
 
+  public static class CbGeoUtils.Polygon implements android.telephony.CbGeoUtils.Geometry {
+    ctor public CbGeoUtils.Polygon(@NonNull java.util.List<android.telephony.CbGeoUtils.LatLng>);
+    method public boolean contains(@NonNull android.telephony.CbGeoUtils.LatLng);
+    method @NonNull public java.util.List<android.telephony.CbGeoUtils.LatLng> getVertices();
+  }
+
   public class CellBroadcastIntents {
     method public static void sendOrderedBroadcastForBackgroundReceivers(@NonNull android.content.Context, @Nullable android.os.UserHandle, @NonNull android.content.Intent, @Nullable String, @Nullable String, @Nullable android.content.BroadcastReceiver, @Nullable android.os.Handler, int, @Nullable String, @Nullable android.os.Bundle);
   }

telephony/java/android/telephony/CbGeoUtils.java

@@ -27,10 +27,15 @@ import java.util.stream.Collectors;
 
 
 /**
- * This utils class is specifically used for geo-targeting of CellBroadcast messages.
+ * This utils class is used for geo-fencing of CellBroadcast messages and is used by the cell
+ * broadcast module.
+ *
  * The coordinates used by this utils class are latitude and longitude, but some algorithms in this
  * class only use them as coordinates on plane, so the calculation will be inaccurate. So don't use
  * this class for anything other then geo-targeting of cellbroadcast messages.
+ *
+ * More information regarding cell broadcast geo-fencing logic is laid out in 3GPP TS 23.041 and
+ * ATIS-0700041.
  * @hide
  */
 @SystemApi
@@ -81,7 +86,7 @@ public class CbGeoUtils {
     /** @hide */
     private static final String POLYGON_SYMBOL = "polygon";
 
-    /** Point represent by (latitude, longitude). */
+    /** A point represented by (latitude, longitude). */
     public static class LatLng {
         public final double lat;
         public final double lng;
@@ -97,8 +102,8 @@ public class CbGeoUtils {
         }
 
         /**
-         * @param p the point use to calculate the subtraction result.
-         * @return the result of this point subtract the given point {@code p}.
+         * @param p the point to subtract
+         * @return the result of the subtraction
          */
         @NonNull
         public LatLng subtract(@NonNull LatLng p) {
@@ -106,9 +111,9 @@ public class CbGeoUtils {
         }
 
         /**
-         * Calculate the distance in meter between this point and the given point {@code p}.
-         * @param p the point use to calculate the distance.
-         * @return the distance in meter.
+         * Calculate the distance in meters between this point and the given point {@code p}.
+         * @param p the point used to calculate the distance.
+         * @return the distance in meters.
          */
         public double distance(@NonNull LatLng p) {
             double dlat = Math.sin(0.5 * Math.toRadians(lat - p.lat));
@@ -125,8 +130,9 @@ public class CbGeoUtils {
     }
 
     /**
-     * The class represents a simple polygon with at least 3 points.
-     * @hide
+     * A class representing a simple polygon with at least 3 points. This is used for geo-fencing
+     * logic with cell broadcasts. More information regarding cell broadcast geo-fencing logic is
+     * laid out in 3GPP TS 23.041 and ATIS-0700041.
      */
     public static class Polygon implements Geometry {
         /**
@@ -145,7 +151,7 @@ public class CbGeoUtils {
          * connected to form an edge of the polygon. The polygon has at least 3 vertices, and the
          * last vertices and the first vertices must be adjacent.
          *
-         * The longitude difference in the vertices should be less than 180 degree.
+         * The longitude difference in the vertices should be less than 180 degrees.
          */
         public Polygon(@NonNull List<LatLng> vertices) {
             mVertices = vertices;
@@ -164,19 +170,24 @@ public class CbGeoUtils {
                     .collect(Collectors.toList());
         }
 
-        public List<LatLng> getVertices() {
+        /**
+         * Return the list of vertices which compose the polygon.
+         */
+        public @NonNull List<LatLng> getVertices() {
             return mVertices;
         }
 
         /**
-         * Check if the given point {@code p} is inside the polygon. This method counts the number
-         * of times the polygon winds around the point P, A.K.A "winding number". The point is
-         * outside only when this "winding number" is 0.
+         * Check if the given LatLng is inside the polygon.
          *
-         * If a point is on the edge of the polygon, it is also considered to be inside the polygon.
+         * If a LatLng is on the edge of the polygon, it is also considered to be inside the
+         * polygon.
          */
         @Override
-        public boolean contains(LatLng latLng) {
+        public boolean contains(@NonNull LatLng latLng) {
+            // This method counts the number of times the polygon winds around the point P, A.K.A
+            // "winding number". The point is outside only when this "winding number" is 0.
+
             Point p = convertAndScaleLatLng(latLng);
 
             int n = mScaledVertices.size();
@@ -245,6 +256,7 @@ public class CbGeoUtils {
             return a.x * b.y - a.y * b.x;
         }
 
+        /** @hide */
         static final class Point {
             public final double x;
             public final double y;
@@ -270,29 +282,47 @@ public class CbGeoUtils {
     }
 
     /**
-     * The class represents a circle.
-     * @hide
+     * A class represents a {@link Geometry} in the shape of a Circle. This is used for handling
+     * geo-fenced cell broadcasts. More information regarding cell broadcast geo-fencing logic is
+     * laid out in 3GPP TS 23.041 and ATIS-0700041.
      */
     public static class Circle implements Geometry {
         private final LatLng mCenter;
         private final double mRadiusMeter;
 
-        public Circle(LatLng center, double radiusMeter) {
+        /**
+         * Construct a Circle given a center point and a radius in meters.
+         *
+         * @param center the latitude and longitude of the center of the circle
+         * @param radiusInMeters the radius of the circle in meters
+         */
+        public Circle(@NonNull LatLng center, double radiusInMeters) {
             this.mCenter = center;
-            this.mRadiusMeter = radiusMeter;
+            this.mRadiusMeter = radiusInMeters;
         }
 
-        public LatLng getCenter() {
+        /**
+         * Return the latitude and longitude of the center of the circle;
+         */
+        public @NonNull LatLng getCenter() {
             return mCenter;
         }
 
+        /**
+         * Return the radius of the circle in meters.
+         */
         public double getRadius() {
             return mRadiusMeter;
         }
 
+        /**
+         * Check if the given LatLng is inside the circle.
+         *
+         * If a LatLng is on the edge of the circle, it is also considered to be inside the circle.
+         */
         @Override
-        public boolean contains(LatLng p) {
-            return mCenter.distance(p) <= mRadiusMeter;
+        public boolean contains(@NonNull LatLng latLng) {
+            return mCenter.distance(latLng) <= mRadiusMeter;
         }
 
         @Override