diff options
Diffstat (limited to 'taskerlocaleapi/src/main/java/com/twofortyfouram')
4 files changed, 456 insertions, 0 deletions
diff --git a/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/BreadCrumber.java b/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/BreadCrumber.java new file mode 100644 index 00000000..6363982f --- /dev/null +++ b/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/BreadCrumber.java @@ -0,0 +1,90 @@ +/* + * Copyright 2013 two forty four a.m. LLC <http://www.twofortyfouram.com> + * + * 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 com.twofortyfouram.locale; + +import android.content.Context; +import android.content.Intent; +import android.util.Log; + +import com.twofortyfouram.locale.api.R; + +/** + * Utility class to generate a breadcrumb title string for {@code Activity} instances in Locale. + * <p> + * This class cannot be instantiated. + */ +public final class BreadCrumber +{ + /** + * Static helper method to generate bread crumbs. Bread crumb strings will be properly formatted for the + * current language, including right-to-left languages, as long as the proper + * {@link com.twofortyfouram.locale.platform.R.string#twofortyfouram_locale_breadcrumb_format} string + * resources have been created. + * + * @param context {@code Context} for loading platform resources. Cannot be null. + * @param intent {@code Intent} to extract the bread crumb from. + * @param currentCrumb The last element of the bread crumb path. + * @return {@code String} presentation of the bread crumb. If the intent parameter is null, then this + * method returns currentCrumb. If currentCrumb is null, then this method returns the empty string + * "". If intent contains a private Serializable instances as an extra, then this method returns + * the empty string "". + * @throws IllegalArgumentException if {@code context} is null. + */ + public static CharSequence generateBreadcrumb(final Context context, final Intent intent, + final String currentCrumb) + { + if (null == context) + { + throw new IllegalArgumentException("context cannot be null"); //$NON-NLS-1$ + } + + try + { + if (null == currentCrumb) + { + Log.w(Constants.LOG_TAG, "currentCrumb cannot be null"); //$NON-NLS-1$ + return ""; //$NON-NLS-1$ + } + if (null == intent) + { + Log.w(Constants.LOG_TAG, "intent cannot be null"); //$NON-NLS-1$ + return currentCrumb; + } + + /* + * Note: this is vulnerable to a private serializable attack, but the try-catch will solve that. + */ + final String breadcrumbString = intent.getStringExtra(com.twofortyfouram.locale.Intent.EXTRA_STRING_BREADCRUMB); + if (null != breadcrumbString) + { + return context.getString(R.string.twofortyfouram_locale_breadcrumb_format, breadcrumbString, context.getString(R.string.twofortyfouram_locale_breadcrumb_separator), currentCrumb); + } + return currentCrumb; + } + catch (final Exception e) + { + Log.e(Constants.LOG_TAG, "Encountered error generating breadcrumb", e); //$NON-NLS-1$ + return ""; //$NON-NLS-1$ + } + } + + /** + * Private constructor prevents instantiation. + * + * @throws UnsupportedOperationException because this class cannot be instantiated. + */ + private BreadCrumber() + { + throw new UnsupportedOperationException("This class is non-instantiable"); //$NON-NLS-1$ + } +}
\ No newline at end of file diff --git a/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/Constants.java b/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/Constants.java new file mode 100644 index 00000000..7e22c518 --- /dev/null +++ b/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/Constants.java @@ -0,0 +1,48 @@ +/* + * Copyright 2013 two forty four a.m. LLC <http://www.twofortyfouram.com> + * + * 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 com.twofortyfouram.locale; + +/** + * Utility class containing constants for the Locale Developer Platform. + */ +/* + * This class is NOT part of the public API. + */ +/* package */final class Constants +{ + /** + * Log tag for logcat messages generated by the Locale Developer Platform + */ + /* + * This is NOT a public API. Third party apps should NOT use this log tag for their own log messages. + */ + /* package */static final String LOG_TAG = "LocaleApiLibrary"; //$NON-NLS-1$ + + /** + * String package name for Locale. + */ + /* + * This is NOT a public API. Third parties should NOT rely on this being the only package name for Locale. + */ + /* package */static final String LOCALE_PACKAGE = "com.twofortyfouram.locale"; //$NON-NLS-1$ + + /** + * Private constructor prevents instantiation + * + * @throws UnsupportedOperationException because this class cannot be instantiated. + */ + private Constants() + { + throw new UnsupportedOperationException("This class is non-instantiable"); //$NON-NLS-1$ + } +}
\ No newline at end of file diff --git a/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/Intent.java b/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/Intent.java new file mode 100644 index 00000000..79716041 --- /dev/null +++ b/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/Intent.java @@ -0,0 +1,195 @@ +/* + * Copyright 2013 two forty four a.m. LLC <http://www.twofortyfouram.com> + * + * 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 com.twofortyfouram.locale; + +import android.os.Parcelable; + +/** + * Contains Intent constants necessary for interacting with the Locale Developer Platform. + */ +public final class Intent +{ + /** + * Private constructor prevents instantiation. + * + * @throws UnsupportedOperationException because this class cannot be instantiated. + */ + private Intent() + { + throw new UnsupportedOperationException("This class is non-instantiable"); //$NON-NLS-1$ + } + + /** + * Ordered broadcast result code indicating that a plug-in condition's state is satisfied (true). + * + * @see Intent#ACTION_QUERY_CONDITION + */ + public static final int RESULT_CONDITION_SATISFIED = 16; + + /** + * Ordered broadcast result code indicating that a plug-in condition's state is not satisfied (false). + * + * @see Intent#ACTION_QUERY_CONDITION + */ + public static final int RESULT_CONDITION_UNSATISFIED = 17; + + /** + * Ordered broadcast result code indicating that a plug-in condition's state is unknown (neither true nor + * false). + * <p> + * If a condition returns UNKNOWN, then Locale will use the last known return value on a best-effort + * basis. Best-effort means that Locale may not persist known values forever (e.g. last known values could + * hypothetically be cleared after a device reboot or a restart of the Locale process. If + * there is no last known return value, then unknown is treated as not satisfied (false). + * <p> + * The purpose of an UNKNOWN result is to allow a plug-in condition more than 10 seconds to process a + * requery. A {@code BroadcastReceiver} must return within 10 seconds, otherwise it will be killed by + * Android. A plug-in that needs more than 10 seconds might initially return + * {@link #RESULT_CONDITION_UNKNOWN}, subsequently request a requery, and then return either + * {@link #RESULT_CONDITION_SATISFIED} or {@link #RESULT_CONDITION_UNSATISFIED}. + * + * @see Intent#ACTION_QUERY_CONDITION + */ + public static final int RESULT_CONDITION_UNKNOWN = 18; + + /** + * {@code Intent} action {@code String} broadcast by Locale to create or edit a plug-in setting. When + * Locale broadcasts this {@code Intent}, it will be sent directly to the package and class of the + * plug-in's {@code Activity}. The {@code Intent} may contain a {@link #EXTRA_BUNDLE} that was previously + * set by the {@code Activity} result of {@link #ACTION_EDIT_SETTING}. + * <p> + * There SHOULD be only one {@code Activity} per APK that implements this {@code Intent}. If a single APK + * wishes to export multiple plug-ins, it MAY implement multiple Activity instances that implement this + * {@code Intent}, however there must only be a single {@link #ACTION_FIRE_SETTING} receiver. In this + * scenario, it is the responsibility of the Activities to store enough data in {@link #EXTRA_BUNDLE} to + * allow this receiver to disambiguate which "plug-in" is being fired. To avoid user confusion, it is + * recommended that only a single plug-in be implemented per APK. + * + * @see Intent#EXTRA_BUNDLE + * @see Intent#EXTRA_STRING_BREADCRUMB + */ + public static final String ACTION_EDIT_SETTING = "com.twofortyfouram.locale.intent.action.EDIT_SETTING"; //$NON-NLS-1$ + + /** + * {@code Intent} action {@code String} broadcast by Locale to fire a plug-in setting. When Locale + * broadcasts this {@code Intent}, it will be sent directly to the package and class of the plug-in's + * {@code BroadcastReceiver}. The {@code Intent} will contain a {@link #EXTRA_BUNDLE} that was previously + * set by the {@code Activity} result of {@link #ACTION_EDIT_SETTING}. + * <p> + * There MUST be only one {@code BroadcastReceiver} per APK that implements this {@code Intent}. + * + * @see Intent#EXTRA_BUNDLE + */ + public static final String ACTION_FIRE_SETTING = "com.twofortyfouram.locale.intent.action.FIRE_SETTING"; //$NON-NLS-1$ + + /** + * {@code Intent} action {@code String} broadcast by Locale to create or edit a plug-in condition. When + * Locale broadcasts this {@code Intent}, it will be sent directly to the package and class of the + * plug-in's {@code Activity}. The {@code Intent} may contain a store-and-forward {@link #EXTRA_BUNDLE} + * that was previously set by the {@code Activity} result of {@link #ACTION_EDIT_CONDITION}. + * <p> + * There SHOULD be only one {@code Activity} per APK that implements this {@code Intent}. If a single APK + * wishes to export multiple plug-ins, it MAY implement multiple Activity instances that implement this + * {@code Intent}, however there must only be a single {@link #ACTION_QUERY_CONDITION} receiver. In this + * scenario, it is the responsibility of the Activities to store enough data in {@link #EXTRA_BUNDLE} to + * allow this receiver to disambiguate which "plug-in" is being queried. To avoid user confusion, it is + * recommended that only a single plug-in be implemented per APK. + * + * @see Intent#EXTRA_BUNDLE + * @see Intent#EXTRA_STRING_BREADCRUMB + */ + public static final String ACTION_EDIT_CONDITION = "com.twofortyfouram.locale.intent.action.EDIT_CONDITION"; //$NON-NLS-1$ + + /** + * Ordered {@code Intent} action {@code String} broadcast by Locale to query a plug-in condition. When + * Locale broadcasts this {@code Intent}, it will be sent directly to the package and class of the + * plug-in's {@code BroadcastReceiver}. The {@code Intent} will contain a {@link #EXTRA_BUNDLE} that was + * previously set by the {@code Activity} result of {@link #ACTION_EDIT_CONDITION}. + * <p> + * Since this is an ordered broadcast, the receiver is expected to set an appropriate result code from + * {@link #RESULT_CONDITION_SATISFIED}, {@link #RESULT_CONDITION_UNSATISFIED}, and + * {@link #RESULT_CONDITION_UNKNOWN}. + * <p> + * There MUST be only one {@code BroadcastReceiver} per APK that implements this {@code Intent}. + * + * @see Intent#EXTRA_BUNDLE + * @see Intent#RESULT_CONDITION_SATISFIED + * @see Intent#RESULT_CONDITION_UNSATISFIED + * @see Intent#RESULT_CONDITION_UNKNOWN + */ + public static final String ACTION_QUERY_CONDITION = "com.twofortyfouram.locale.intent.action.QUERY_CONDITION"; //$NON-NLS-1$ + + /** + * {@code Intent} action {@code String} to notify Locale that a plug-in condition is requesting that + * Locale query it via {@link #ACTION_QUERY_CONDITION}. This merely serves as a hint to Locale that a + * condition wants to be queried. There is no guarantee as to when or if the plug-in will be queried after + * this {@code Intent} is broadcast. If Locale does not respond to the plug-in condition after a + * {@link #ACTION_REQUEST_QUERY} Intent is sent, the plug-in SHOULD shut itself down and stop requesting + * requeries. A lack of response from Locale indicates that Locale is not currently interested in this + * plug-in. When Locale becomes interested in the plug-in again, Locale will send + * {@link #ACTION_QUERY_CONDITION}. + * <p> + * The extra {@link #EXTRA_ACTIVITY} MUST be included, otherwise Locale will ignore this {@code Intent}. + * <p> + * Plug-in conditions SHOULD NOT use this unless there is some sort of asynchronous event that has + * occurred, such as a broadcast {@code Intent} being received by the plug-in. Plug-ins SHOULD NOT + * periodically request a requery as a way of implementing polling behavior. + * + * @see Intent#EXTRA_ACTIVITY + */ + public static final String ACTION_REQUEST_QUERY = "com.twofortyfouram.locale.intent.action.REQUEST_QUERY"; //$NON-NLS-1$ + + /** + * Type: {@code String}. + * <p> + * Maps to a {@code String} that represents the {@code Activity} bread crumb path. + * + * @see BreadCrumber + */ + public static final String EXTRA_STRING_BREADCRUMB = "com.twofortyfouram.locale.intent.extra.BREADCRUMB"; //$NON-NLS-1$ + + /** + * Type: {@code String}. + * <p> + * Maps to a {@code String} that represents a blurb. This is returned as an {@code Activity} result extra + * from {@link #ACTION_EDIT_CONDITION} or {@link #ACTION_EDIT_SETTING}. + * <p> + * The blurb is a concise description displayed to the user of what the plug-in is configured to do. + */ + public static final String EXTRA_STRING_BLURB = "com.twofortyfouram.locale.intent.extra.BLURB"; //$NON-NLS-1$ + + /** + * Type: {@code Bundle}. + * <p> + * Maps to a {@code Bundle} that contains all of a plug-in's extras. + * <p> + * Plug-ins MUST NOT store {@link Parcelable} objects in this {@code Bundle}, because {@code Parcelable} + * is not a long-term storage format. Also, plug-ins MUST NOT store any serializable object that is not + * exposed by the Android SDK. + * <p> + * The maximum size of a Bundle that can be sent across process boundaries is on the order of 500 + * kilobytes (base-10), while Locale further limits plug-in Bundles to about 100 kilobytes (base-10). + * Although the maximum size is about 100 kilobytes, plug-ins SHOULD keep Bundles much smaller for + * performance and memory usage reasons. + */ + public static final String EXTRA_BUNDLE = "com.twofortyfouram.locale.intent.extra.BUNDLE"; //$NON-NLS-1$ + + /** + * Type: {@code String}. + * <p> + * Maps to a {@code String} that represents the name of a plug-in's {@code Activity}. + * + * @see Intent#ACTION_REQUEST_QUERY + */ + public static final String EXTRA_ACTIVITY = "com.twofortyfouram.locale.intent.extra.ACTIVITY"; //$NON-NLS-1$ +}
\ No newline at end of file diff --git a/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/PackageUtilities.java b/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/PackageUtilities.java new file mode 100644 index 00000000..a4b623ce --- /dev/null +++ b/taskerlocaleapi/src/main/java/com/twofortyfouram/locale/PackageUtilities.java @@ -0,0 +1,123 @@ +/* + * Copyright 2013 two forty four a.m. LLC <http://www.twofortyfouram.com> + * + * 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 com.twofortyfouram.locale; + +import android.content.pm.PackageInfo; +import android.content.pm.PackageManager; + +import java.util.Collections; +import java.util.HashSet; +import java.util.List; +import java.util.Set; + +/** + * A simple utility class to find a package that is compatible with hosting the Locale Developer Platform. + */ +/* + * This class is NOT part of the public Locale Developer Platform API + */ +public final class PackageUtilities +{ + /** + * A hard-coded set of Android packages that support the Locale Developer Platform. + */ + /* + * This is NOT a public field and is subject to change in future releases of the Developer Platform. A + * conscious design decision was made to use hard-coded package names, rather than dynamic discovery of + * packages that might be compatible with hosting the Locale Developer Platform API. This is for two + * reasons: to ensure the host is implemented correctly (hosts must pass the extensive Locale Platform + * Host compatibility test suite) and to prevent malicious applications from crashing plug-ins by + * providing bad values. As additional apps implement the Locale Developer Platform, their package names + * will also be added to this list. + */ + /* + * Note: this is implemented as a Set<String> rather than a String[], in order to enforce immutability. + */ + private static final Set<String> COMPATIBLE_PACKAGES = constructPackageSet(); + + /** + * @return a list wrapped in {@link Collections#unmodifiableList(List)} that represents the set of + * Locale-compatible packages. + */ + private static Set<String> constructPackageSet() + { + final HashSet<String> packages = new HashSet<String>(); + + packages.add(Constants.LOCALE_PACKAGE); + + /* + * Note: Tasker is not 100% compatible with Locale's plug-in API, but it is close enough that these + * packages are enabled. Tasker's known incompatibilities are documented on the Tasker website. + */ + packages.add("net.dinglisch.android.taskerm"); //$NON-NLS-1$ + packages.add("net.dinglisch.android.tasker"); //$NON-NLS-1$ + packages.add("net.dinglisch.android.taskercupcake"); //$NON-NLS-1$ + + return Collections.unmodifiableSet(packages); + } + + /** + * Obtains the {@code String} package name of a currently-installed package which implements the host + * component of the Locale Developer Platform. + * <p> + * Note: A TOCTOU error exists, due to the fact that the package could be uninstalled at any time. + * <p> + * Note: If there are multiple hosts, this method will return one of them. The interface of this method + * makes no guarantee which host will returned, nor whether that host will be consistently returned. + * + * @param manager an instance of {@code PackageManager}. Cannot be null. + * @param packageHint hint as to which package should take precedence. This parameter may be null. + * @return {@code String} package name of a host for the Locale Developer Platform, such as + * "com.twofortyfouram.locale". If no such package is found, returns null. + */ + public static String getCompatiblePackage(final PackageManager manager, final String packageHint) + { + /* + * The interface for this method makes no guarantees as to which host will be returned. However the + * implementation is more predictable. + */ + + final List<PackageInfo> installedPackages = manager.getInstalledPackages(0); + + if (COMPATIBLE_PACKAGES.contains(packageHint)) + { + for (final PackageInfo packageInfo : installedPackages) + { + final String temp = packageInfo.packageName; + if (packageHint.equals(temp)) + { + return temp; + } + } + } + + for (final String compatiblePackageName : COMPATIBLE_PACKAGES) + { + if (compatiblePackageName.equals(packageHint)) + { + continue; + } + + for (final PackageInfo packageInfo : installedPackages) + { + final String temp = packageInfo.packageName; + if (compatiblePackageName.equals(temp)) + { + return temp; + } + } + } + + return null; + } +}
\ No newline at end of file |