Java tutorial
/* * Copyright (C) 2006 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.content; import android.annotation.UnsupportedAppUsage; import android.app.ActivityManager; import android.os.Bundle; import android.os.RemoteException; import android.os.Handler; import android.os.IBinder; import android.os.Parcel; import android.os.Parcelable; import android.os.UserHandle; import android.util.AndroidException; /** * A description of an Intent and target action to perform with it. * The returned object can be * handed to other applications so that they can perform the action you * described on your behalf at a later time. * * <p>By giving a IntentSender to another application, * you are granting it the right to perform the operation you have specified * as if the other application was yourself (with the same permissions and * identity). As such, you should be careful about how you build the IntentSender: * often, for example, the base Intent you supply will have the component * name explicitly set to one of your own components, to ensure it is ultimately * sent there and nowhere else. * * <p>A IntentSender itself is simply a reference to a token maintained by * the system describing the original data used to retrieve it. This means * that, even if its owning application's process is killed, the * IntentSender itself will remain usable from other processes that * have been given it. If the creating application later re-retrieves the * same kind of IntentSender (same operation, same Intent action, data, * categories, and components, and same flags), it will receive a IntentSender * representing the same token if that is still valid. * * <p>Instances of this class can not be made directly, but rather must be * created from an existing {@link android.app.PendingIntent} with * {@link android.app.PendingIntent#getIntentSender() PendingIntent.getIntentSender()}. */ public class IntentSender implements Parcelable { @UnsupportedAppUsage private final IIntentSender mTarget; IBinder mWhitelistToken; /** * Exception thrown when trying to send through a PendingIntent that * has been canceled or is otherwise no longer able to execute the request. */ public static class SendIntentException extends AndroidException { public SendIntentException() { } public SendIntentException(String name) { super(name); } public SendIntentException(Exception cause) { super(cause); } } /** * Callback interface for discovering when a send operation has * completed. Primarily for use with a IntentSender that is * performing a broadcast, this provides the same information as * calling {@link Context#sendOrderedBroadcast(Intent, String, * android.content.BroadcastReceiver, Handler, int, String, Bundle) * Context.sendBroadcast()} with a final BroadcastReceiver. */ public interface OnFinished { /** * Called when a send operation as completed. * * @param IntentSender The IntentSender this operation was sent through. * @param intent The original Intent that was sent. * @param resultCode The final result code determined by the send. * @param resultData The final data collected by a broadcast. * @param resultExtras The final extras collected by a broadcast. */ void onSendFinished(IntentSender IntentSender, Intent intent, int resultCode, String resultData, Bundle resultExtras); } private static class FinishedDispatcher extends IIntentReceiver.Stub implements Runnable { private final IntentSender mIntentSender; private final OnFinished mWho; private final Handler mHandler; private Intent mIntent; private int mResultCode; private String mResultData; private Bundle mResultExtras; FinishedDispatcher(IntentSender pi, OnFinished who, Handler handler) { mIntentSender = pi; mWho = who; mHandler = handler; } public void performReceive(Intent intent, int resultCode, String data, Bundle extras, boolean serialized, boolean sticky, int sendingUser) { mIntent = intent; mResultCode = resultCode; mResultData = data; mResultExtras = extras; if (mHandler == null) { run(); } else { mHandler.post(this); } } public void run() { mWho.onSendFinished(mIntentSender, mIntent, mResultCode, mResultData, mResultExtras); } } /** * Perform the operation associated with this IntentSender, allowing the * caller to specify information about the Intent to use and be notified * when the send has completed. * * @param context The Context of the caller. This may be null if * <var>intent</var> is also null. * @param code Result code to supply back to the IntentSender's target. * @param intent Additional Intent data. See {@link Intent#fillIn * Intent.fillIn()} for information on how this is applied to the * original Intent. Use null to not modify the original Intent. * @param onFinished The object to call back on when the send has * completed, or null for no callback. * @param handler Handler identifying the thread on which the callback * should happen. If null, the callback will happen from the thread * pool of the process. * * * @throws SendIntentException Throws CanceledIntentException if the IntentSender * is no longer allowing more intents to be sent through it. */ public void sendIntent(Context context, int code, Intent intent, OnFinished onFinished, Handler handler) throws SendIntentException { sendIntent(context, code, intent, onFinished, handler, null); } /** * Perform the operation associated with this IntentSender, allowing the * caller to specify information about the Intent to use and be notified * when the send has completed. * * @param context The Context of the caller. This may be null if * <var>intent</var> is also null. * @param code Result code to supply back to the IntentSender's target. * @param intent Additional Intent data. See {@link Intent#fillIn * Intent.fillIn()} for information on how this is applied to the * original Intent. Use null to not modify the original Intent. * @param onFinished The object to call back on when the send has * completed, or null for no callback. * @param handler Handler identifying the thread on which the callback * should happen. If null, the callback will happen from the thread * pool of the process. * @param requiredPermission Name of permission that a recipient of the PendingIntent * is required to hold. This is only valid for broadcast intents, and * corresponds to the permission argument in * {@link Context#sendBroadcast(Intent, String) Context.sendOrderedBroadcast(Intent, String)}. * If null, no permission is required. * * * @throws SendIntentException Throws CanceledIntentException if the IntentSender * is no longer allowing more intents to be sent through it. */ public void sendIntent(Context context, int code, Intent intent, OnFinished onFinished, Handler handler, String requiredPermission) throws SendIntentException { try { String resolvedType = intent != null ? intent.resolveTypeIfNeeded(context.getContentResolver()) : null; int res = ActivityManager.getService().sendIntentSender(mTarget, mWhitelistToken, code, intent, resolvedType, onFinished != null ? new FinishedDispatcher(this, onFinished, handler) : null, requiredPermission, null); if (res < 0) { throw new SendIntentException(); } } catch (RemoteException e) { throw new SendIntentException(); } } /** * @deprecated Renamed to {@link #getCreatorPackage()}. */ @Deprecated public String getTargetPackage() { try { return ActivityManager.getService().getPackageForIntentSender(mTarget); } catch (RemoteException e) { // Should never happen. return null; } } /** * Return the package name of the application that created this * IntentSender, that is the identity under which you will actually be * sending the Intent. The returned string is supplied by the system, so * that an application can not spoof its package. * * @return The package name of the PendingIntent, or null if there is * none associated with it. */ public String getCreatorPackage() { try { return ActivityManager.getService().getPackageForIntentSender(mTarget); } catch (RemoteException e) { // Should never happen. return null; } } /** * Return the uid of the application that created this * PendingIntent, that is the identity under which you will actually be * sending the Intent. The returned integer is supplied by the system, so * that an application can not spoof its uid. * * @return The uid of the PendingIntent, or -1 if there is * none associated with it. */ public int getCreatorUid() { try { return ActivityManager.getService().getUidForIntentSender(mTarget); } catch (RemoteException e) { // Should never happen. return -1; } } /** * Return the user handle of the application that created this * PendingIntent, that is the user under which you will actually be * sending the Intent. The returned UserHandle is supplied by the system, so * that an application can not spoof its user. See * {@link android.os.Process#myUserHandle() Process.myUserHandle()} for * more explanation of user handles. * * @return The user handle of the PendingIntent, or null if there is * none associated with it. */ public UserHandle getCreatorUserHandle() { try { int uid = ActivityManager.getService().getUidForIntentSender(mTarget); return uid > 0 ? new UserHandle(UserHandle.getUserId(uid)) : null; } catch (RemoteException e) { // Should never happen. return null; } } /** * Comparison operator on two IntentSender objects, such that true * is returned then they both represent the same operation from the * same package. */ @Override public boolean equals(Object otherObj) { if (otherObj instanceof IntentSender) { return mTarget.asBinder().equals(((IntentSender) otherObj).mTarget.asBinder()); } return false; } @Override public int hashCode() { return mTarget.asBinder().hashCode(); } @Override public String toString() { StringBuilder sb = new StringBuilder(128); sb.append("IntentSender{"); sb.append(Integer.toHexString(System.identityHashCode(this))); sb.append(": "); sb.append(mTarget != null ? mTarget.asBinder() : null); sb.append('}'); return sb.toString(); } public int describeContents() { return 0; } public void writeToParcel(Parcel out, int flags) { out.writeStrongBinder(mTarget.asBinder()); } public static final Parcelable.Creator<IntentSender> CREATOR = new Parcelable.Creator<IntentSender>() { public IntentSender createFromParcel(Parcel in) { IBinder target = in.readStrongBinder(); return target != null ? new IntentSender(target) : null; } public IntentSender[] newArray(int size) { return new IntentSender[size]; } }; /** * Convenience function for writing either a IntentSender or null pointer to * a Parcel. You must use this with {@link #readIntentSenderOrNullFromParcel} * for later reading it. * * @param sender The IntentSender to write, or null. * @param out Where to write the IntentSender. */ public static void writeIntentSenderOrNullToParcel(IntentSender sender, Parcel out) { out.writeStrongBinder(sender != null ? sender.mTarget.asBinder() : null); } /** * Convenience function for reading either a Messenger or null pointer from * a Parcel. You must have previously written the Messenger with * {@link #writeIntentSenderOrNullToParcel}. * * @param in The Parcel containing the written Messenger. * * @return Returns the Messenger read from the Parcel, or null if null had * been written. */ public static IntentSender readIntentSenderOrNullFromParcel(Parcel in) { IBinder b = in.readStrongBinder(); return b != null ? new IntentSender(b) : null; } /** @hide */ @UnsupportedAppUsage public IIntentSender getTarget() { return mTarget; } /** @hide */ public IBinder getWhitelistToken() { return mWhitelistToken; } /** @hide */ @UnsupportedAppUsage public IntentSender(IIntentSender target) { mTarget = target; } /** @hide */ public IntentSender(IIntentSender target, IBinder whitelistToken) { mTarget = target; mWhitelistToken = whitelistToken; } /** @hide */ public IntentSender(IBinder target) { mTarget = IIntentSender.Stub.asInterface(target); } }