diff options
Diffstat (limited to 'location')
| -rw-r--r-- | location/java/android/location/Country.aidl | 19 | ||||
| -rwxr-xr-x | location/java/android/location/Country.java | 161 | ||||
| -rw-r--r-- | location/java/android/location/CountryDetector.java | 152 | ||||
| -rw-r--r-- | location/java/android/location/CountryListener.java | 30 | ||||
| -rw-r--r-- | location/java/android/location/ICountryDetector.aidl | 44 | ||||
| -rw-r--r-- | location/java/android/location/ICountryListener.aidl | 26 | ||||
| -rw-r--r-- | location/java/android/location/LocationManager.java | 48 | ||||
| -rw-r--r-- | location/java/android/location/package.html | 9 | ||||
| -rw-r--r-- | location/tests/locationtests/src/android/location/CountryTester.java | 33 |
9 files changed, 495 insertions, 27 deletions
diff --git a/location/java/android/location/Country.aidl b/location/java/android/location/Country.aidl new file mode 100644 index 0000000..c83d645 --- /dev/null +++ b/location/java/android/location/Country.aidl @@ -0,0 +1,19 @@ +/* + * Copyright (C) 2010, The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package android.location; + +parcelable Country;
\ No newline at end of file diff --git a/location/java/android/location/Country.java b/location/java/android/location/Country.java new file mode 100755 index 0000000..3c05403 --- /dev/null +++ b/location/java/android/location/Country.java @@ -0,0 +1,161 @@ +/* + * Copyright (C) 2010 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ + +package android.location; + +import android.os.Parcel; +import android.os.Parcelable; + +/** + * This class wraps the country information. + * + * @hide + */ +public class Country implements Parcelable { + /** + * The country code came from the mobile network + */ + public static final int COUNTRY_SOURCE_NETWORK = 0; + + /** + * The country code came from the location service + */ + public static final int COUNTRY_SOURCE_LOCATION = 1; + + /** + * The country code was read from the SIM card + */ + public static final int COUNTRY_SOURCE_SIM = 2; + + /** + * The country code came from the system locale setting + */ + public static final int COUNTRY_SOURCE_LOCALE = 3; + + /** + * The ISO 3166-1 two letters country code. + */ + private final String mCountryIso; + + /** + * Where the country code came from. + */ + private final int mSource; + + private int mHashCode; + /** + * + * @param countryIso the ISO 3166-1 two letters country code. + * @param source where the countryIso came from, could be one of below + * values + * <p> + * <ul> + * <li>{@link #COUNTRY_SOURCE_NETWORK}</li> + * <li>{@link #COUNTRY_SOURCE_LOCATION}</li> + * <li>{@link #COUNTRY_SOURCE_SIM}</li> + * <li>{@link #COUNTRY_SOURCE_LOCALE}</li> + * </ul> + */ + public Country(final String countryIso, final int source) { + if (countryIso == null || source < COUNTRY_SOURCE_NETWORK + || source > COUNTRY_SOURCE_LOCALE) { + throw new IllegalArgumentException(); + } + mCountryIso = countryIso.toLowerCase(); + mSource = source; + } + + public Country(Country country) { + mCountryIso = country.mCountryIso; + mSource = country.mSource; + } + + /** + * @return the ISO 3166-1 two letters country code + */ + public final String getCountryIso() { + return mCountryIso; + } + + /** + * @return where the country code came from, could be one of below values + * <p> + * <ul> + * <li>{@link #COUNTRY_SOURCE_NETWORK}</li> + * <li>{@link #COUNTRY_SOURCE_LOCATION}</li> + * <li>{@link #COUNTRY_SOURCE_SIM}</li> + * <li>{@link #COUNTRY_SOURCE_LOCALE}</li> + * </ul> + */ + public final int getSource() { + return mSource; + } + + public static final Parcelable.Creator<Country> CREATOR = new Parcelable.Creator<Country>() { + public Country createFromParcel(Parcel in) { + return new Country(in.readString(), in.readInt()); + } + + public Country[] newArray(int size) { + return new Country[size]; + } + }; + + public int describeContents() { + return 0; + } + + public void writeToParcel(Parcel parcel, int flags) { + parcel.writeString(mCountryIso); + parcel.writeInt(mSource); + } + + @Override + public boolean equals(Object object) { + if (object == this) { + return true; + } + if (object instanceof Country) { + Country c = (Country) object; + return mCountryIso.equals(c.getCountryIso()) && mSource == c.getSource(); + } + return false; + } + + @Override + public int hashCode() { + int hash = mHashCode; + if (hash == 0) { + hash = 17; + hash = hash * 13 + mCountryIso.hashCode(); + hash = hash * 13 + mSource; + mHashCode = hash; + } + return mHashCode; + } + + /** + * Compare the specified country to this country object ignoring the mSource + * field, return true if the countryIso fields are equal + * + * @param country the country to compare + * @return true if the specified country's countryIso field is equal to this + * country's, false otherwise. + */ + public boolean equalsIgnoreSource(Country country) { + return country != null && mCountryIso.equals(country.getCountryIso()); + } +} diff --git a/location/java/android/location/CountryDetector.java b/location/java/android/location/CountryDetector.java new file mode 100644 index 0000000..0b780ce --- /dev/null +++ b/location/java/android/location/CountryDetector.java @@ -0,0 +1,152 @@ +/* + * Copyright (C) 2010 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations under + * the License. + */ + +package android.location; + +import java.util.HashMap; + +import android.os.Handler; +import android.os.Looper; +import android.os.RemoteException; +import android.util.Log; + +/** + * This class provides access to the system country detector service. This + * service allows applications to obtain the country that the user is in. + * <p> + * The country will be detected in order of reliability, like + * <ul> + * <li>Mobile network</li> + * <li>Location</li> + * <li>SIM's country</li> + * <li>Phone's locale</li> + * </ul> + * <p> + * Call the {@link #detectCountry()} to get the available country immediately. + * <p> + * To be notified of the future country change, use the + * {@link #addCountryListener} + * <p> + * <p> + * You do not instantiate this class directly; instead, retrieve it through + * {@link android.content.Context#getSystemService + * Context.getSystemService(Context.COUNTRY_DETECTOR)}. + * <p> + * Both ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION permissions are needed. + * + * @hide + */ +public class CountryDetector { + + /** + * The class to wrap the ICountryListener.Stub and CountryListener objects + * together. The CountryListener will be notified through the specific + * looper once the country changed and detected. + */ + private final static class ListenerTransport extends ICountryListener.Stub { + + private final CountryListener mListener; + + private final Handler mHandler; + + public ListenerTransport(CountryListener listener, Looper looper) { + mListener = listener; + if (looper != null) { + mHandler = new Handler(looper); + } else { + mHandler = new Handler(); + } + } + + public void onCountryDetected(final Country country) { + mHandler.post(new Runnable() { + public void run() { + mListener.onCountryDetected(country); + } + }); + } + } + + private final static String TAG = "CountryDetector"; + private final ICountryDetector mService; + private final HashMap<CountryListener, ListenerTransport> mListeners; + + /** + * @hide - hide this constructor because it has a parameter of type + * ICountryDetector, which is a system private class. The right way to + * create an instance of this class is using the factory + * Context.getSystemService. + */ + public CountryDetector(ICountryDetector service) { + mService = service; + mListeners = new HashMap<CountryListener, ListenerTransport>(); + } + + /** + * Start detecting the country that the user is in. + * + * @return the country if it is available immediately, otherwise null will + * be returned. + */ + public Country detectCountry() { + try { + return mService.detectCountry(); + } catch (RemoteException e) { + Log.e(TAG, "detectCountry: RemoteException", e); + return null; + } + } + + /** + * Add a listener to receive the notification when the country is detected + * or changed. + * + * @param listener will be called when the country is detected or changed. + * @param looper a Looper object whose message queue will be used to + * implement the callback mechanism. If looper is null then the + * callbacks will be called on the main thread. + */ + public void addCountryListener(CountryListener listener, Looper looper) { + synchronized (mListeners) { + if (!mListeners.containsKey(listener)) { + ListenerTransport transport = new ListenerTransport(listener, looper); + try { + mService.addCountryListener(transport); + mListeners.put(listener, transport); + } catch (RemoteException e) { + Log.e(TAG, "addCountryListener: RemoteException", e); + } + } + } + } + + /** + * Remove the listener + */ + public void removeCountryListener(CountryListener listener) { + synchronized (mListeners) { + ListenerTransport transport = mListeners.get(listener); + if (transport != null) { + try { + mListeners.remove(listener); + mService.removeCountryListener(transport); + } catch (RemoteException e) { + Log.e(TAG, "removeCountryListener: RemoteException", e); + } + } + } + } +} diff --git a/location/java/android/location/CountryListener.java b/location/java/android/location/CountryListener.java new file mode 100644 index 0000000..e36db41 --- /dev/null +++ b/location/java/android/location/CountryListener.java @@ -0,0 +1,30 @@ +/* + * Copyright (C) 2010 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ + +package android.location; + +/** + * The listener for receiving the notification when the country is detected or + * changed + * + * @hide + */ +public interface CountryListener { + /** + * @param country the changed or detected country. + */ + void onCountryDetected(Country country); +} diff --git a/location/java/android/location/ICountryDetector.aidl b/location/java/android/location/ICountryDetector.aidl new file mode 100644 index 0000000..6eaf07c --- /dev/null +++ b/location/java/android/location/ICountryDetector.aidl @@ -0,0 +1,44 @@ +/* + * Copyright (C) 2010, The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package android.location; + +import android.location.Country; +import android.location.ICountryListener; + +/** + * The API for detecting the country where the user is. + * + * {@hide} + */ +interface ICountryDetector +{ + /** + * Start detecting the country that the user is in. + * @return the country if it is available immediately, otherwise null will be returned. + */ + Country detectCountry(); + + /** + * Add a listener to receive the notification when the country is detected or changed. + */ + void addCountryListener(in ICountryListener listener); + + /** + * Remove the listener + */ + void removeCountryListener(in ICountryListener listener); +}
\ No newline at end of file diff --git a/location/java/android/location/ICountryListener.aidl b/location/java/android/location/ICountryListener.aidl new file mode 100644 index 0000000..76ecb13 --- /dev/null +++ b/location/java/android/location/ICountryListener.aidl @@ -0,0 +1,26 @@ +/* + * Copyright (C) 2010, The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package android.location; + +import android.location.Country; +/** + * {@hide} + */ +oneway interface ICountryListener +{ + void onCountryDetected(in Country country); +} diff --git a/location/java/android/location/LocationManager.java b/location/java/android/location/LocationManager.java index 9aa84a03..cc689bb 100644 --- a/location/java/android/location/LocationManager.java +++ b/location/java/android/location/LocationManager.java @@ -715,15 +715,13 @@ public class LocationManager { } /** - * Registers the current activity to be notified periodically by - * the named provider. Periodically, the supplied LocationListener will - * be called with the current Location or with status updates. + * Requests a single location update from the named provider. * * <p> It may take a while to receive the most recent location. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * - * <p> In case the provider is disabled by the user, updates will stop, + * <p> In case the provider is disabled by the user, the update will not be received, * and the {@link LocationListener#onProviderDisabled(String)} * method will be called. As soon as the provider is enabled again, * the {@link LocationListener#onProviderEnabled(String)} method will @@ -733,8 +731,8 @@ public class LocationManager { * * @param provider the name of the provider with which to register * @param listener a {#link LocationListener} whose - * {@link LocationListener#onLocationChanged} method will be called for - * each location update + * {@link LocationListener#onLocationChanged} method will be called when + * the location update is available * @param looper a Looper object whose message queue will be used to * implement the callback mechanism. * If looper is null then the callbacks will be called on the main thread. @@ -754,15 +752,13 @@ public class LocationManager { } /** - * Registers the current activity to be notified periodically based on - * the specified criteria. Periodically, the supplied LocationListener will - * be called with the current Location or with status updates. + * Requests a single location update based on the specified criteria. * * <p> It may take a while to receive the most recent location. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * - * <p> In case the provider is disabled by the user, updates will stop, + * <p> In case the provider is disabled by the user, the update will not be received, * and the {@link LocationListener#onProviderDisabled(String)} * method will be called. As soon as the provider is enabled again, * the {@link LocationListener#onProviderEnabled(String)} method will @@ -773,8 +769,8 @@ public class LocationManager { * @param criteria contains parameters for the location manager to choose the * appropriate provider and parameters to compute the location * @param listener a {#link LocationListener} whose - * {@link LocationListener#onLocationChanged} method will be called for - * each location update + * {@link LocationListener#onLocationChanged} method will be called when + * the location update is available * @param looper a Looper object whose message queue will be used to * implement the callback mechanism. * If looper is null then the callbacks will be called on the current thread. @@ -795,16 +791,20 @@ public class LocationManager { } /** - * Registers the current activity to be notified periodically by - * the named provider. Periodically, the supplied PendingIntent will - * be broadcast with the current Location or with status updates. - * - * <p> Location updates are sent with a key of KEY_LOCATION_CHANGED and a Location value. + * Requests a single location update from the named provider. * * <p> It may take a while to receive the most recent location. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * + * <p> Location updates are sent with a key of KEY_LOCATION_CHANGED and a Location value. + * + * <p> In case the provider is disabled by the user, the update will not be received, + * and the {@link LocationListener#onProviderDisabled(String)} + * method will be called. As soon as the provider is enabled again, + * the {@link LocationListener#onProviderEnabled(String)} method will + * be called and location updates will start again. + * * @param provider the name of the provider with which to register * @param intent a {#link PendingIntent} to be sent for the location update * @@ -823,16 +823,20 @@ public class LocationManager { } /** - * Registers the current activity to be notified periodically based on - * the specified criteria. Periodically, the supplied PendingIntent will - * be broadcast with the current Location or with status updates. - * - * <p> Location updates are sent with a key of KEY_LOCATION_CHANGED and a Location value. + * Requests a single location update based on the specified criteria. * * <p> It may take a while to receive the most recent location. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * + * <p> Location updates are sent with a key of KEY_LOCATION_CHANGED and a Location value. + * + * <p> In case the provider is disabled by the user, the update will not be received, + * and the {@link LocationListener#onProviderDisabled(String)} + * method will be called. As soon as the provider is enabled again, + * the {@link LocationListener#onProviderEnabled(String)} method will + * be called and location updates will start again. + * * @param criteria contains parameters for the location manager to choose the * appropriate provider and parameters to compute the location * @param intent a {#link PendingIntent} to be sent for the location update diff --git a/location/java/android/location/package.html b/location/java/android/location/package.html index bbaeb42..be34774 100644 --- a/location/java/android/location/package.html +++ b/location/java/android/location/package.html @@ -1,12 +1,11 @@ <html> -<head> -<script type="text/javascript" src="http://www.corp.google.com/style/prettify.js"></script> -<script src="http://www.corp.google.com/eng/techpubs/include/navbar.js" type="text/javascript"></script> -</head> <body> -<p>Classes defining Android location-based and related services.</p> +<p>Contains classes that define Android location-based and related services.</p> +<p>For more information about location services, see the documentation for <a +href="{@docRoot}guide/topics/location/obtaining-user-location.html">Obtaining User Location</a>.</p> +{@more} </body> </html> diff --git a/location/tests/locationtests/src/android/location/CountryTester.java b/location/tests/locationtests/src/android/location/CountryTester.java new file mode 100644 index 0000000..9802d5a --- /dev/null +++ b/location/tests/locationtests/src/android/location/CountryTester.java @@ -0,0 +1,33 @@ +/* + * Copyright (C) 2010 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package android.location; + +import android.test.AndroidTestCase; + +public class CountryTester extends AndroidTestCase { + public void testCountryEquals() { + Country countryA = new Country("US", Country.COUNTRY_SOURCE_NETWORK); + Country countryB = new Country("US", Country.COUNTRY_SOURCE_LOCALE); + Country countryC = new Country("CN", Country.COUNTRY_SOURCE_LOCALE); + Country countryD = new Country("us", Country.COUNTRY_SOURCE_NETWORK); + assertTrue(countryA.equalsIgnoreSource(countryB)); + assertFalse(countryA.equalsIgnoreSource(countryC)); + assertFalse(countryA.equals(countryC)); + assertTrue(countryA.equals(countryD)); + assertTrue(countryA.hashCode() == countryD.hashCode()); + } +} |