public interface

CallbackReceiver<T>

 androidx.remotecallback.CallbackReceiver<T>

Subclasses:

SliceProviderWithCallbacks<T>, BroadcastReceiverWithCallbacks<T>, AppWidgetProviderWithCallbacks<T>, ContentProviderWithCallbacks<T>

Gradle dependencies

compile group: 'androidx.remotecallback', name: 'remotecallback', version: '1.0.0-alpha02'

  • groupId: androidx.remotecallback
  • artifactId: remotecallback
  • version: 1.0.0-alpha02

Artifact androidx.remotecallback:remotecallback:1.0.0-alpha02 it located at Google repository (https://maven.google.com/)

Overview

An objects that can receive remote callbacks.

Remote callbacks provide an easy way to bundle arguments and pass them directly into a method rather than managing PendingIntents manually.

Example:

public class MyReceiver extends BroadcastReceiverWithCallbacks {
   public PendingIntent getPendingIntent(Context context, int value1, int value2) {
     return createRemoteCallback().doMyAction(value1, value2)
         .toPendingIntent(context);
   }

   \@RemoteCallable
   public MyReceiver doMyAction(int value1, int value2) {
     ...
     return this;
   }
 }

The following types are supported as parameter types for methods tagged with RemoteCallable.

  • byte/Byte/byte[]
  • char/Character/char[]
  • short/Short/short[]
  • int/Integer/int[]
  • long/Long/long[]
  • float/Float/float[]
  • double/Double/double[]
  • boolean/Boolean/boolean[]
  • String/String[]
  • Uri
  • Context *
* Context is a special kind of parameter, in that it cannot be specified during createRemoteCallback, it instead is passed directly through to provide a valid context at the time of the callback in case no other one is available.

This interface shouldn't be implemented in apps, instead extend one of the implementations of it provided.

Just like PendingIntents, Remote Callbacks don't require components be exported. They also ensure that all parameters always have a value in the PendingIntent generated, which ensures that the caller cannot inject new values except when explicitly requested by the receiving app. They also generate the intent Uris to ensure that the callbacks stay separate and don't collide with each other.

Summary

Methods
public java.lang.ObjectcreateRemoteCallback(Context context)

Creates a RemoteCallback that will call the method with method specified with the arguments specified when triggered.

Methods

public java.lang.Object createRemoteCallback(Context context)

Creates a RemoteCallback that will call the method with method specified with the arguments specified when triggered. Only methods tagged with RemoteCallable can be used here. This method returns a stub implementation of the class calling it to record the arguments/method being used. This should only be used in a chain of 2 calls, starting with createRemoteCallback(), then followed up with a call to any method tagged with RemoteCallable.

     createRemoteCallback().callMyMethod("My arguments", 43, 2.4)
              .toPendingIntent(context);
 
     \@RemoteCallable
     public RemoteCallback callMyMethod(String argStr, int argInt, double argDouble) {
         ...
         return RemoteCallback.LOCAL;
     }
 

Source

/*
 * Copyright 2018 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 androidx.remotecallback;

import android.content.Context;

/**
 * An objects that can receive remote callbacks.
 * <p>
 * Remote callbacks provide an easy way to bundle arguments and pass them
 * directly into a method rather than managing PendingIntents manually.
 * <p>
 * Example:
 * <pre>public class MyReceiver extends BroadcastReceiverWithCallbacks {
 *   public PendingIntent getPendingIntent(Context context, int value1, int value2) {
 *     return createRemoteCallback().doMyAction(value1, value2)
 *         .toPendingIntent(context);
 *   }
 *
 *   \@RemoteCallable
 *   public MyReceiver doMyAction(int value1, int value2) {
 *     ...
 *     return this;
 *   }
 * }</pre>
 * <p>
 * The following types are supported as parameter types for methods tagged
 * with {@link RemoteCallable}.
 * <ul>
 * <li>byte/Byte/byte[]</li>
 * <li>char/Character/char[]</li>
 * <li>short/Short/short[]</li>
 * <li>int/Integer/int[]</li>
 * <li>long/Long/long[]</li>
 * <li>float/Float/float[]</li>
 * <li>double/Double/double[]</li>
 * <li>boolean/Boolean/boolean[]</li>
 * <li>String/String[]</li>
 * <li>Uri</li>
 * <li>Context *</li>
 * </ul>
 * * Context is a special kind of parameter, in that it cannot be specified
 *   during createRemoteCallback, it instead is passed directly through to
 *   provide a valid context at the time of the callback in case no other one
 *   is available.
 * <p>
 * This interface shouldn't be implemented in apps, instead extend one of
 * the implementations of it provided.
 * <ul>
 * <li>{@link BroadcastReceiverWithCallbacks}</li>
 * <li>{@link AppWidgetProviderWithCallbacks}</li>
 * <li>{@link ContentProviderWithCallbacks}</li>
 * </ul>
 * <p>
 * Just like PendingIntents, Remote Callbacks don't require components be
 * exported. They also ensure that all parameters always have a value in the
 * PendingIntent generated, which ensures that the caller cannot inject new values
 * except when explicitly requested by the receiving app. They also generate the
 * intent Uris to ensure that the callbacks stay separate and don't collide with
 * each other.
 *
 * @param <T> Should be specified as the root class (e.g. class X extends
 *           CallbackReceiver\<X>)
 *
 * @see RemoteCallable
 * @see ExternalInput
 */
public interface CallbackReceiver<T> {

    /**
     * Creates a {@link RemoteCallback} that will call the method with method
     * specified with the arguments specified when triggered. Only methods
     * tagged with {@link RemoteCallable} can be used here.
     *
     * This method returns a stub implementation of the class calling it to
     * record the arguments/method being used. This should only be used in a
     * chain of 2 calls, starting with createRemoteCallback(), then followed
     * up with a call to any method tagged with {@link RemoteCallable}.
     *
     * <pre>
     *     createRemoteCallback().callMyMethod("My arguments", 43, 2.4)
     *              .toPendingIntent(context);
     * </pre>
     *
     * <pre>
     *     \@RemoteCallable
     *     public RemoteCallback callMyMethod(String argStr, int argInt, double argDouble) {
     *         ...
     *         return RemoteCallback.LOCAL;
     *     }
     * </pre>
     */
    T createRemoteCallback(Context context);
}