Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Update the VDM documentation." into udc-dev

Browse Source
This commit is contained in:
Vladimir Komsiyski
2023-03-31 11:49:44 +00:00
committed by Android (Google) Code Review
parent 6a47399c9f c29a2c966b
commit 8b3f7da4a3
15 changed files with 256 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
core/java/android/companion/virtual/IVirtualDevice.aidl
View File

@@ -39,21 +39,22 @@ import android.hardware.input.VirtualNavigationTouchpadConfig;
import android.os.ResultReceiver;
/**
* Interface for a virtual device.
* Interface for a virtual device for communication between the system server and the process of
* the owner of the virtual device.
*
* @hide
*/
interface IVirtualDevice {
/**
* Returns the association ID for this virtual device.
* Returns the CDM association ID of this virtual device.
*
* @see AssociationInfo#getId()
*/
int getAssociationId();
/**
* Returns the unique device ID for this virtual device.
* Returns the unique ID of this virtual device.
*/
int getDeviceId();
@@ -64,55 +65,99 @@ interface IVirtualDevice {
void close();
/**
* Notifies of an audio session being started.
* Notifies that an audio session being started.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
void onAudioSessionStarting(
int displayId,
IAudioRoutingCallback routingCallback,
void onAudioSessionStarting(int displayId, IAudioRoutingCallback routingCallback,
IAudioConfigChangedCallback configChangedCallback);
/**
* Notifies that an audio session has ended.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
void onAudioSessionEnded();
/**
* Creates a new dpad and registers it with the input framework with the given token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
void createVirtualDpad(
in VirtualDpadConfig config,
IBinder token);
void createVirtualDpad(in VirtualDpadConfig config, IBinder token);
/**
* Creates a new keyboard and registers it with the input framework with the given token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
void createVirtualKeyboard(
in VirtualKeyboardConfig config,
IBinder token);
void createVirtualKeyboard(in VirtualKeyboardConfig config, IBinder token);
/**
* Creates a new mouse and registers it with the input framework with the given token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
void createVirtualMouse(
in VirtualMouseConfig config,
IBinder token);
void createVirtualMouse(in VirtualMouseConfig config, IBinder token);
/**
* Creates a new touchscreen and registers it with the input framework with the given token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
void createVirtualTouchscreen(
in VirtualTouchscreenConfig config,
IBinder token);
void createVirtualTouchscreen(in VirtualTouchscreenConfig config, IBinder token);
/**
* Creates a new navigation touchpad and registers it with the input framework with the given
* token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
void createVirtualNavigationTouchpad(
in VirtualNavigationTouchpadConfig config,
IBinder token);
void createVirtualNavigationTouchpad(in VirtualNavigationTouchpadConfig config, IBinder token);
/**
* Removes the input device corresponding to the given token from the framework.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
void unregisterInputDevice(IBinder token);
/**
* Returns the ID of the device corresponding to the given token, as registered with the input
* framework.
*/
int getInputDeviceId(IBinder token);
/**
* Injects a key event to the virtual dpad corresponding to the given token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
boolean sendDpadKeyEvent(IBinder token, in VirtualKeyEvent event);
/**
* Injects a key event to the virtual keyboard corresponding to the given token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
boolean sendKeyEvent(IBinder token, in VirtualKeyEvent event);
/**
* Injects a button event to the virtual mouse corresponding to the given token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
boolean sendButtonEvent(IBinder token, in VirtualMouseButtonEvent event);
/**
* Injects a relative event to the virtual mouse corresponding to the given token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
boolean sendRelativeEvent(IBinder token, in VirtualMouseRelativeEvent event);
/**
* Injects a scroll event to the virtual mouse corresponding to the given token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
boolean sendScrollEvent(IBinder token, in VirtualMouseScrollEvent event);
/**
* Injects a touch event to the virtual touch input device corresponding to the given token.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
boolean sendTouchEvent(IBinder token, in VirtualTouchEvent event);
/**
* Returns all virtual sensors for this device.
* Returns all virtual sensors created for this device.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
List<VirtualSensor> getVirtualSensorList();
@@ -126,8 +171,13 @@ interface IVirtualDevice {
/**
* Launches a pending intent on the given display that is owned by this virtual device.
*/
void launchPendingIntent(
int displayId, in PendingIntent pendingIntent, in ResultReceiver resultReceiver);
void launchPendingIntent(int displayId, in PendingIntent pendingIntent,
in ResultReceiver resultReceiver);
/**
* Returns the current cursor position of the mouse corresponding to the given token, in x and y
* coordinates.
*/
PointF getCursorPosition(IBinder token);
/** Sets whether to show or hide the cursor while this virtual device is active. */
@@ -140,8 +190,12 @@ interface IVirtualDevice {
* intent.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
void registerIntentInterceptor(
in IVirtualDeviceIntentInterceptor intentInterceptor, in IntentFilter filter);
void registerIntentInterceptor(in IVirtualDeviceIntentInterceptor intentInterceptor,
in IntentFilter filter);
/**
* Unregisters a previously registered intent interceptor.
*/
@EnforcePermission("CREATE_VIRTUAL_DEVICE")
void unregisterIntentInterceptor(in IVirtualDeviceIntentInterceptor intentInterceptor);
}

2
core/java/android/companion/virtual/IVirtualDeviceManager.aidl
View File

@@ -101,7 +101,7 @@ interface IVirtualDeviceManager {
*
* @param deviceId id of the virtual device.
* @param sound effect type corresponding to
* {@code android.media.AudioManager.SystemSoundEffect}
* {@code android.media.AudioManager.SystemSoundEffect}
*/
void playSoundEffect(int deviceId, int effectType);
}

2
core/java/android/companion/virtual/IVirtualDeviceSoundEffectListener.aidl
View File

@@ -28,7 +28,7 @@ oneway interface IVirtualDeviceSoundEffectListener {
* Called when there's sound effect to be played on Virtual Device.
*
* @param sound effect type corresponding to
* {@code android.media.AudioManager.SystemSoundEffect}
* {@code android.media.AudioManager.SystemSoundEffect}
*/
void onPlaySoundEffect(int effectType);
}

5
core/java/android/companion/virtual/VirtualDevice.java
View File

@@ -26,6 +26,11 @@ import java.util.Objects;
/**
* Details of a particular virtual device.
*
* <p>Read-only device representation exposing the properties of an existing virtual device.
*
* <p class="note">Not to be confused with {@link VirtualDeviceManager.VirtualDevice}, which is used
* by the virtual device creator and allows them to manage the device.
*/
public final class VirtualDevice implements Parcelable {

146
core/java/android/companion/virtual/VirtualDeviceManager.java
View File

@@ -68,7 +68,13 @@ import java.util.concurrent.Executor;
import java.util.function.IntConsumer;
/**
* System level service for managing virtual devices.
* System level service for creation and management of virtual devices.
*
* <p>VirtualDeviceManager enables interactive sharing of capabilities between the host Android
* device and a remote device.
*
* <p class="note">Not to be confused with the Android Studio's Virtual Device Manager, which allows
* for device emulation.
*/
@SystemService(Context.VIRTUAL_DEVICE_SERVICE)
public final class VirtualDeviceManager {
@@ -174,6 +180,9 @@ public final class VirtualDeviceManager {
/**
* Returns the details of all available virtual devices.
*
* <p>The returned objects are read-only representations that expose the properties of all
* existing virtual devices.
*/
@NonNull
public List<android.companion.virtual.VirtualDevice> getVirtualDevices() {
@@ -252,11 +261,12 @@ public final class VirtualDeviceManager {
*
* @param deviceId - id of the virtual audio device
* @return Device specific session id to be used for audio playback (see
* {@link android.media.AudioManager.generateAudioSessionId}) if virtual device has
* {@link VirtualDeviceParams.POLICY_TYPE_AUDIO} set to
* {@link VirtualDeviceParams.DEVICE_POLICY_CUSTOM} and Virtual Audio Device
* is configured in context-aware mode.
* Otherwise {@link AUDIO_SESSION_ID_GENERATE} constant is returned.
* {@link AudioManager#generateAudioSessionId}) if virtual device has
* {@link VirtualDeviceParams#POLICY_TYPE_AUDIO} set to
* {@link VirtualDeviceParams#DEVICE_POLICY_CUSTOM} and Virtual Audio Device
* is configured in context-aware mode. Otherwise
* {@link AudioManager#AUDIO_SESSION_ID_GENERATE} constant is returned.
*
* @hide
*/
public int getAudioPlaybackSessionId(int deviceId) {
@@ -275,11 +285,12 @@ public final class VirtualDeviceManager {
*
* @param deviceId - id of the virtual audio device
* @return Device specific session id to be used for audio recording (see
* {@link android.media.AudioManager.generateAudioSessionId}) if virtual device has
* {@link VirtualDeviceParams.POLICY_TYPE_AUDIO} set to
* {@link VirtualDeviceParams.DEVICE_POLICY_CUSTOM} and Virtual Audio Device
* is configured in context-aware mode.
* Otherwise {@link AUDIO_SESSION_ID_GENERATE} constant is returned.
* {@link AudioManager#generateAudioSessionId}) if virtual device has
* {@link VirtualDeviceParams#POLICY_TYPE_AUDIO} set to
* {@link VirtualDeviceParams#DEVICE_POLICY_CUSTOM} and Virtual Audio Device
* is configured in context-aware mode. Otherwise
* {@link AudioManager#AUDIO_SESSION_ID_GENERATE} constant is returned.
*
* @hide
*/
public int getAudioRecordingSessionId(int deviceId) {
@@ -296,10 +307,11 @@ public final class VirtualDeviceManager {
/**
* Requests sound effect to be played on virtual device.
*
* @see android.media.AudioManager#playSoundEffect(int)
* @see AudioManager#playSoundEffect(int)
*
* @param deviceId - id of the virtual audio device
* @param effectType the type of sound effect
*
* @hide
*/
public void playSoundEffect(int deviceId, @AudioManager.SystemSoundEffect int effectType) {
@@ -315,11 +327,18 @@ public final class VirtualDeviceManager {
}
/**
* A virtual device has its own virtual display, audio output, microphone, sensors, etc. The
* creator of a virtual device can take the output from the virtual display and stream it over
* to another device, and inject input events that are received from the remote device.
* A representation of a virtual device.
*
* TODO(b/204081582): Consider using a builder pattern for the input APIs.
* <p>A virtual device can have its own virtual displays, audio input/output, sensors, etc.
* The creator of a virtual device can take the output from the virtual display and stream it
* over to another device, and inject input and sensor events that are received from the remote
* device.
*
* <p>This object is only used by the virtual device creator and allows them to manage the
* device's behavior, peripherals, and the user interaction with that device.
*
* <p class="note">Not to be confused with {@link android.companion.virtual.VirtualDevice},
* which is a read-only representation exposing the properties of an existing virtual device.
*
* @hide
*/
@@ -346,8 +365,10 @@ public final class VirtualDeviceManager {
}
/**
* @return A new Context bound to this device. This is a convenience method equivalent to
* calling {@link Context#createDeviceContext(int)} with the device id of this device.
* Returns a new context bound to this device.
*
* <p>This is a convenience method equivalent to calling
* {@link Context#createDeviceContext(int)} with the id of this device.
*/
public @NonNull Context createContext() {
return mVirtualDeviceInternal.createContext();
@@ -400,20 +421,19 @@ public final class VirtualDeviceManager {
* @param height The height of the virtual display in pixels, must be greater than 0.
* @param densityDpi The density of the virtual display in dpi, must be greater than 0.
* @param surface The surface to which the content of the virtual display should
* be rendered, or null if there is none initially. The surface can also be set later using
* {@link VirtualDisplay#setSurface(Surface)}.
* be rendered, or null if there is none initially. The surface can also be set later
* using {@link VirtualDisplay#setSurface(Surface)}.
* @param flags A combination of virtual display flags accepted by
* {@link DisplayManager#createVirtualDisplay}. In addition, the following flags are
* automatically set for all virtual devices:
* {@link DisplayManager#VIRTUAL_DISPLAY_FLAG_PUBLIC VIRTUAL_DISPLAY_FLAG_PUBLIC} and
* {@link DisplayManager#VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY
* VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY}.
* {@link DisplayManager#createVirtualDisplay}. In addition, the following flags are
* automatically set for all virtual devices:
* {@link DisplayManager#VIRTUAL_DISPLAY_FLAG_PUBLIC} and
* {@link DisplayManager#VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY}.
* @param executor The executor on which {@code callback} will be invoked. This is ignored
* if {@code callback} is {@code null}. If {@code callback} is specified, this executor must
* not be null.
* if {@code callback} is {@code null}. If {@code callback} is specified, this executor
* must not be null.
* @param callback Callback to call when the state of the {@link VirtualDisplay} changes
* @return The newly created virtual display, or {@code null} if the application could
* not create the virtual display.
* not create the virtual display.
*
* @see DisplayManager#createVirtualDisplay
*
@@ -450,11 +470,11 @@ public final class VirtualDeviceManager {
*
* @param config The configuration of the display.
* @param executor The executor on which {@code callback} will be invoked. This is ignored
* if {@code callback} is {@code null}. If {@code callback} is specified, this executor must
* not be null.
* if {@code callback} is {@code null}. If {@code callback} is specified, this executor
* must not be null.
* @param callback Callback to call when the state of the {@link VirtualDisplay} changes
* @return The newly created virtual display, or {@code null} if the application could
* not create the virtual display.
* not create the virtual display.
*
* @see DisplayManager#createVirtualDisplay
*/
@@ -478,7 +498,7 @@ public final class VirtualDeviceManager {
/**
* Creates a virtual dpad.
*
* @param config the configurations of the virtual Dpad.
* @param config the configurations of the virtual dpad.
*/
@RequiresPermission(android.Manifest.permission.CREATE_VIRTUAL_DEVICE)
@NonNull
@@ -500,11 +520,10 @@ public final class VirtualDeviceManager {
/**
* Creates a virtual keyboard.
*
* @param display the display that the events inputted through this device should
* target
* @param inputDeviceName the name to call this input device
* @param vendorId the PCI vendor id
* @param productId the product id, as defined by the vendor
* @param display the display that the events inputted through this device should target.
* @param inputDeviceName the name of this keyboard device.
* @param vendorId the PCI vendor id.
* @param productId the product id, as defined by the vendor.
* @see #createVirtualKeyboard(VirtualKeyboardConfig config)
* @deprecated Use {@link #createVirtualKeyboard(VirtualKeyboardConfig config)} instead
*/
@@ -537,14 +556,12 @@ public final class VirtualDeviceManager {
/**
* Creates a virtual mouse.
*
* @param display the display that the events inputted through this device should
* target
* @param inputDeviceName the name to call this input device
* @param vendorId the PCI vendor id
* @param productId the product id, as defined by the vendor
* @param display the display that the events inputted through this device should target.
* @param inputDeviceName the name of this mouse.
* @param vendorId the PCI vendor id.
* @param productId the product id, as defined by the vendor.
* @see #createVirtualMouse(VirtualMouseConfig config)
* @deprecated Use {@link #createVirtualMouse(VirtualMouseConfig config)} instead
* *
*/
@Deprecated
@RequiresPermission(android.Manifest.permission.CREATE_VIRTUAL_DEVICE)
@@ -576,11 +593,10 @@ public final class VirtualDeviceManager {
/**
* Creates a virtual touchscreen.
*
* @param display the display that the events inputted through this device should
* target
* @param inputDeviceName the name to call this input device
* @param vendorId the PCI vendor id
* @param productId the product id, as defined by the vendor
* @param display the display that the events inputted through this device should target.
* @param inputDeviceName the name of this touchscreen device.
* @param vendorId the PCI vendor id.
* @param productId the product id, as defined by the vendor.
* @see #createVirtualTouchscreen(VirtualTouchscreenConfig config)
* @deprecated Use {@link #createVirtualTouchscreen(VirtualTouchscreenConfig config)}
* instead
@@ -605,11 +621,13 @@ public final class VirtualDeviceManager {
/**
* Creates a virtual touchpad in navigation mode.
*
* A touchpad in navigation mode means that its events are interpreted as navigation events
* (up, down, etc) instead of using them to update a cursor's absolute position. If the
* events are not consumed they are converted to DPAD events.
* <p>A touchpad in navigation mode means that its events are interpreted as navigation
* events (up, down, etc) instead of using them to update a cursor's absolute position. If
* the events are not consumed they are converted to DPAD events and delivered to the target
* again.
*
* @param config the configurations of the virtual navigation touchpad.
* @see android.view.InputDevice#SOURCE_TOUCH_NAVIGATION
*/
@RequiresPermission(android.Manifest.permission.CREATE_VIRTUAL_DEVICE)
@NonNull
@@ -629,10 +647,10 @@ public final class VirtualDeviceManager {
*
* @param display The target virtual display to capture from and inject into.
* @param executor The {@link Executor} object for the thread on which to execute
* the callback. If <code>null</code>, the {@link Executor} associated with
* the main {@link Looper} will be used.
* the callback. If <code>null</code>, the {@link Executor} associated with the main
* {@link Looper} will be used.
* @param callback Interface to be notified when playback or recording configuration of
* applications running on virtual display is changed.
* applications running on virtual display is changed.
* @return A {@link VirtualAudioDevice} instance.
*/
@RequiresPermission(android.Manifest.permission.CREATE_VIRTUAL_DEVICE)
@@ -648,7 +666,7 @@ public final class VirtualDeviceManager {
* Sets the visibility of the pointer icon for this VirtualDevice's associated displays.
*
* @param showPointerIcon True if the pointer should be shown; false otherwise. The default
* visibility is true.
* visibility is true.
*/
@RequiresPermission(android.Manifest.permission.CREATE_VIRTUAL_DEVICE)
@NonNull
@@ -670,8 +688,7 @@ public final class VirtualDeviceManager {
}
/**
* Removes an activity listener previously added with
* {@link #addActivityListener}.
* Removes an activity listener previously added with {@link #addActivityListener}.
*
* @param listener The listener to remove.
* @see #addActivityListener(Executor, ActivityListener)
@@ -693,10 +710,10 @@ public final class VirtualDeviceManager {
}
/**
* Removes a sound effect listener previously added with {@link #addActivityListener}.
* Removes a sound effect listener previously added with {@link #addSoundEffectListener}.
*
* @param soundEffectListener The listener to remove.
* @see #addActivityListener(Executor, ActivityListener)
* @see #addSoundEffectListener(Executor, SoundEffectListener)
*/
public void removeSoundEffectListener(@NonNull SoundEffectListener soundEffectListener) {
mVirtualDeviceInternal.removeSoundEffectListener(soundEffectListener);
@@ -723,7 +740,7 @@ public final class VirtualDeviceManager {
}
/**
* Unregisters the intent interceptorCallback previously registered with
* Unregisters the intent interceptor previously registered with
* {@link #registerIntentInterceptor}.
*/
@RequiresPermission(android.Manifest.permission.CREATE_VIRTUAL_DEVICE)
@@ -761,9 +778,9 @@ public final class VirtualDeviceManager {
* {@link #onDisplayEmpty(int)} will be called. If the value topActivity is cached, it
* should be cleared when {@link #onDisplayEmpty(int)} is called.
*
* @param displayId The display ID on which the activity change happened.
* @param displayId The display ID on which the activity change happened.
* @param topActivity The component name of the top activity.
* @param userId The user ID associated with the top activity.
* @param userId The user ID associated with the top activity.
*/
default void onTopActivityChanged(int displayId, @NonNull ComponentName topActivity,
@UserIdInt int userId) {}
@@ -800,6 +817,7 @@ public final class VirtualDeviceManager {
/**
* Listener for system sound effect playback on virtual device.
*
* @hide
*/
@SystemApi
@@ -808,8 +826,8 @@ public final class VirtualDeviceManager {
/**
* Called when there's a system sound effect to be played on virtual device.
*
* @param effectType - system sound effect type, see
* {@code android.media.AudioManager.SystemSoundEffect}
* @param effectType - system sound effect type
* @see android.media.AudioManager.SystemSoundEffect
*/
void onPlaySoundEffect(@AudioManager.SystemSoundEffect int effectType);
}

15
core/java/android/companion/virtual/VirtualDeviceParams.java
View File

@@ -34,6 +34,7 @@ import android.companion.virtual.sensor.VirtualSensorCallback;
import android.companion.virtual.sensor.VirtualSensorConfig;
import android.companion.virtual.sensor.VirtualSensorDirectChannelCallback;
import android.content.ComponentName;
import android.content.Context;
import android.os.Parcel;
import android.os.Parcelable;
import android.os.SharedMemory;
@@ -680,7 +681,7 @@ public final class VirtualDeviceParams implements Parcelable {
* {@link #NAVIGATION_POLICY_DEFAULT_ALLOWED}, meaning activities are allowed to launch
* unless they are in {@code blockedCrossTaskNavigations}.
*
* <p> This method must not be called if {@link #setAllowedCrossTaskNavigations(Set)} has
* <p>This method must not be called if {@link #setAllowedCrossTaskNavigations(Set)} has
* been called.
*
* @throws IllegalArgumentException if {@link #setAllowedCrossTaskNavigations(Set)} has
@@ -847,11 +848,11 @@ public final class VirtualDeviceParams implements Parcelable {
* <p>Requires {@link #DEVICE_POLICY_CUSTOM} to be set for {@link #POLICY_TYPE_AUDIO},
* otherwise {@link #build()} method will throw {@link IllegalArgumentException} if
* the playback session id is set to value other than
* {@link android.media.AudioManager.AUDIO_SESSION_ID_GENERATE}.
* {@link android.media.AudioManager#AUDIO_SESSION_ID_GENERATE}.
*
* @param playbackSessionId requested device-specific audio session id for playback
* @see android.media.AudioManager.generateAudioSessionId()
* @see android.media.AudioTrack.Builder.setContext(Context)
* @see android.media.AudioManager#generateAudioSessionId()
* @see android.media.AudioTrack.Builder#setContext(Context)
*/
@NonNull
public Builder setAudioPlaybackSessionId(int playbackSessionId) {
@@ -871,11 +872,11 @@ public final class VirtualDeviceParams implements Parcelable {
* <p>Requires {@link #DEVICE_POLICY_CUSTOM} to be set for {@link #POLICY_TYPE_AUDIO},
* otherwise {@link #build()} method will throw {@link IllegalArgumentException} if
* the recording session id is set to value other than
* {@link android.media.AudioManager.AUDIO_SESSION_ID_GENERATE}.
* {@link android.media.AudioManager#AUDIO_SESSION_ID_GENERATE}.
*
* @param recordingSessionId requested device-specific audio session id for playback
* @see android.media.AudioManager.generateAudioSessionId()
* @see android.media.AudioRecord.Builder.setContext(Context)
* @see android.media.AudioManager#generateAudioSessionId()
* @see android.media.AudioRecord.Builder#setContext(Context)
*/
@NonNull
public Builder setAudioRecordingSessionId(int recordingSessionId) {

10
core/java/android/companion/virtual/audio/AudioCapture.java
View File

@@ -56,12 +56,12 @@ public final class AudioCapture {
/**
* Sets the {@link AudioRecord} to handle audio capturing.
* Callers may call this multiple times with different audio records to change
* the underlying {@link AudioRecord} without stopping and re-starting recording.
*
* @param audioRecord The underlying {@link AudioRecord} to use for capture,
* or null if no audio (i.e. silence) should be captured while still keeping the
* record in a recording state.
* <p>Callers may call this multiple times with different audio records to change the underlying
* {@link AudioRecord} without stopping and re-starting recording.
*
* @param audioRecord The underlying {@link AudioRecord} to use for capture, or null if no audio
* (i.e. silence) should be captured while still keeping the record in a recording state.
*/
void setAudioRecord(@Nullable AudioRecord audioRecord) {
Log.d(TAG, "set AudioRecord with " + audioRecord);

10
core/java/android/companion/virtual/audio/AudioInjection.java
View File

@@ -65,12 +65,12 @@ public final class AudioInjection {
/**
* Sets the {@link AudioTrack} to handle audio injection.
* Callers may call this multiple times with different audio tracks to change
* the underlying {@link AudioTrack} without stopping and re-starting injection.
*
* @param audioTrack The underlying {@link AudioTrack} to use for injection,
* or null if no audio (i.e. silence) should be injected while still keeping the
* record in a playing state.
* <p>Callers may call this multiple times with different audio tracks to change the underlying
* {@link AudioTrack} without stopping and re-starting injection.
*
* @param audioTrack The underlying {@link AudioTrack} to use for injection, or null if no audio
* (i.e. silence) should be injected while still keeping the record in a playing state.
*/
void setAudioTrack(@Nullable AudioTrack audioTrack) {
Log.d(TAG, "set AudioTrack with " + audioTrack);

4
core/java/android/companion/virtual/sensor/IVirtualSensorCallback.aidl
View File

@@ -33,7 +33,7 @@ oneway interface IVirtualSensorCallback {
* @param enabled Whether the sensor is enabled.
* @param samplingPeriodMicros The requested sensor's sampling period in microseconds.
* @param batchReportingLatencyMicros The requested maximum time interval in microseconds
* between the delivery of two batches of sensor events.
* between the delivery of two batches of sensor events.
*/
void onConfigurationChanged(in VirtualSensor sensor, boolean enabled, int samplingPeriodMicros,
int batchReportLatencyMicros);
@@ -60,7 +60,7 @@ oneway interface IVirtualSensorCallback {
* @param sensor The sensor, for which the channel was configured.
* @param rateLevel The rate level used to configure the direct sensor channel.
* @param reportToken A positive sensor report token, used to differentiate between events from
* different sensors within the same channel.
* different sensors within the same channel.
*/
void onDirectChannelConfigured(int channelHandle, in VirtualSensor sensor, int rateLevel,
int reportToken);

2
core/java/android/companion/virtual/sensor/VirtualSensor.java
View File

@@ -30,7 +30,7 @@ import android.os.RemoteException;
* Representation of a sensor on a remote device, capable of sending events, such as an
* accelerometer or a gyroscope.
*
* This registers the sensor device with the sensor framework as a runtime sensor.
* <p>A virtual sensor device is registered with the sensor framework as a runtime sensor.
*
* @hide
*/

4
core/java/android/companion/virtual/sensor/VirtualSensorCallback.java
View File

@@ -45,10 +45,10 @@ public interface VirtualSensorCallback {
*
* @param sensor The sensor whose requested injection parameters have changed.
* @param enabled Whether the sensor is enabled. True if any listeners are currently registered,
* and false otherwise.
* and false otherwise.
* @param samplingPeriod The requested sampling period of the sensor.
* @param batchReportLatency The requested maximum time interval between the delivery of two
* batches of sensor events.
* batches of sensor events.
*/
void onConfigurationChanged(@NonNull VirtualSensor sensor, boolean enabled,
@NonNull Duration samplingPeriod, @NonNull Duration batchReportLatency);

34
core/java/android/companion/virtual/sensor/VirtualSensorConfig.java
View File

@@ -31,7 +31,9 @@ import java.util.Objects;
/**
* Configuration for creation of a virtual sensor.
*
* @see VirtualSensor
*
* @hide
*/
@SystemApi
@@ -122,6 +124,7 @@ public final class VirtualSensorConfig implements Parcelable {
/**
* Returns the vendor string of the sensor.
*
* @see Builder#setVendor
*/
@Nullable
@@ -130,7 +133,8 @@ public final class VirtualSensorConfig implements Parcelable {
}
/**
* Returns maximum range of the sensor in the sensor's unit.
* Returns the maximum range of the sensor in the sensor's unit.
*
* @see Sensor#getMaximumRange
*/
public float getMaximumRange() {
@@ -138,7 +142,8 @@ public final class VirtualSensorConfig implements Parcelable {
}
/**
* Returns The resolution of the sensor in the sensor's unit.
* Returns the resolution of the sensor in the sensor's unit.
*
* @see Sensor#getResolution
*/
public float getResolution() {
@@ -146,7 +151,8 @@ public final class VirtualSensorConfig implements Parcelable {
}
/**
* Returns The power in mA used by this sensor while in use.
* Returns the power in mA used by this sensor while in use.
*
* @see Sensor#getPower
*/
public float getPower() {
@@ -154,8 +160,9 @@ public final class VirtualSensorConfig implements Parcelable {
}
/**
* Returns The minimum delay allowed between two events in microseconds, or zero depending on
* Returns the minimum delay allowed between two events in microseconds, or zero depending on
* the sensor type.
*
* @see Sensor#getMinDelay
*/
public int getMinDelay() {
@@ -163,7 +170,8 @@ public final class VirtualSensorConfig implements Parcelable {
}
/**
* Returns The maximum delay between two sensor events in microseconds.
* Returns the maximum delay between two sensor events in microseconds.
*
* @see Sensor#getMaxDelay
*/
public int getMaxDelay() {
@@ -201,6 +209,7 @@ public final class VirtualSensorConfig implements Parcelable {
/**
* Returns the sensor flags.
*
* @hide
*/
public int getFlags() {
@@ -233,7 +242,7 @@ public final class VirtualSensorConfig implements Parcelable {
*
* @param type The type of the sensor, matching {@link Sensor#getType}.
* @param name The name of the sensor. Must be unique among all sensors with the same type
* that belong to the same virtual device.
* that belong to the same virtual device.
*/
public Builder(@IntRange(from = 1) int type, @NonNull String name) {
if (type <= 0) {
@@ -275,6 +284,7 @@ public final class VirtualSensorConfig implements Parcelable {
/**
* Sets the maximum range of the sensor in the sensor's unit.
*
* @see Sensor#getMaximumRange
*/
@NonNull
@@ -285,6 +295,7 @@ public final class VirtualSensorConfig implements Parcelable {
/**
* Sets the resolution of the sensor in the sensor's unit.
*
* @see Sensor#getResolution
*/
@NonNull
@@ -295,6 +306,7 @@ public final class VirtualSensorConfig implements Parcelable {
/**
* Sets the power in mA used by this sensor while in use.
*
* @see Sensor#getPower
*/
@NonNull
@@ -305,6 +317,7 @@ public final class VirtualSensorConfig implements Parcelable {
/**
* Sets the minimum delay allowed between two events in microseconds.
*
* @see Sensor#getMinDelay
*/
@NonNull
@@ -315,6 +328,7 @@ public final class VirtualSensorConfig implements Parcelable {
/**
* Sets the maximum delay between two sensor events in microseconds.
*
* @see Sensor#getMaxDelay
*/
@NonNull
@@ -339,11 +353,11 @@ public final class VirtualSensorConfig implements Parcelable {
* Sets whether direct sensor channel of the given types is supported.
*
* @param memoryTypes A combination of {@link SensorDirectChannel.MemoryType} flags
* indicating the types of shared memory supported for creating direct channels. Only
* {@link SensorDirectChannel#TYPE_MEMORY_FILE} direct channels may be supported for virtual
* sensors.
* indicating the types of shared memory supported for creating direct channels. Only
* {@link SensorDirectChannel#TYPE_MEMORY_FILE} direct channels may be supported for
* virtual sensors.
* @throws IllegalArgumentException if {@link SensorDirectChannel#TYPE_HARDWARE_BUFFER} is
* set to be supported.
* set to be supported.
*/
@NonNull
public VirtualSensorConfig.Builder setDirectChannelTypesSupported(

4
core/java/android/companion/virtual/sensor/VirtualSensorDirectChannelCallback.java
View File

@@ -45,6 +45,8 @@ import android.os.SharedMemory;
* <p>The callback is tied to the VirtualDevice's lifetime as the virtual sensors are created when
* the device is created and destroyed when the device is destroyed.
*
* @see VirtualSensorDirectChannelWriter
*
* @hide
*/
@SystemApi
@@ -94,7 +96,7 @@ public interface VirtualSensorDirectChannelCallback {
* @param sensor The sensor, for which the channel was configured.
* @param rateLevel The rate level used to configure the direct sensor channel.
* @param reportToken A positive sensor report token, used to differentiate between events from
* different sensors within the same channel.
* different sensors within the same channel.
*
* @see VirtualSensorConfig.Builder#setHighestDirectReportRateLevel(int)
* @see VirtualSensorConfig.Builder#setDirectChannelTypesSupported(int)

35
core/java/android/companion/virtual/sensor/VirtualSensorDirectChannelWriter.java
View File

@@ -41,6 +41,41 @@ import java.util.concurrent.atomic.AtomicLong;
* write the events from the relevant sensors directly to the shared memory regions of the
* corresponding {@link SensorDirectChannel} instances.
*
* <p>Example:
* <p>During sensor and virtual device creation:
* <pre>
* VirtualSensorDirectChannelWriter writer = new VirtualSensorDirectChannelWriter();
* VirtualSensorDirectChannelCallback callback = new VirtualSensorDirectChannelCallback() {
* @Override
* public void onDirectChannelCreated(int channelHandle, SharedMemory sharedMemory) {
* writer.addChannel(channelHandle, sharedMemory);
* }
* @Override
* public void onDirectChannelDestroyed(int channelHandle);
* writer.removeChannel(channelHandle);
* }
* @Override
* public void onDirectChannelConfigured(int channelHandle, VirtualSensor sensor, int rateLevel,
* int reportToken)
* if (!writer.configureChannel(channelHandle, sensor, rateLevel, reportToken)) {
* // handle error
* }
* }
* }
* </pre>
* <p>During the virtual device lifetime:
* <pre>
* VirtualSensor sensor = ...
* while (shouldInjectEvents(sensor)) {
* if (!writer.writeSensorEvent(sensor, event)) {
* // handle error
* }
* }
* writer.close();
* </pre>
* <p>Note that the virtual device owner should take the currently configured rate level into
* account when deciding whether and how often to inject events for a particular sensor.
*
* @see android.hardware.SensorDirectChannel#configure
* @see VirtualSensorDirectChannelCallback
*

2
core/java/android/companion/virtual/sensor/VirtualSensorEvent.java
View File

@@ -121,7 +121,7 @@ public final class VirtualSensorEvent implements Parcelable {
* monotonically increasing using the same time base as
* {@link android.os.SystemClock#elapsedRealtimeNanos()}.
*
* If not explicitly set, the current timestamp is used for the sensor event.
* <p>If not explicitly set, the current timestamp is used for the sensor event.
*
* @see android.hardware.SensorEvent#timestamp
*/