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

Update the VDM documentation.

Browse Source 
- Add top level docs to VDM
 - Add docs to the aidl files
 - Document the differences between the two VirtualDevice classes
 - Extend VirtualSensorDirectChannelWriter docs
 - Fix minor inconsistencies, formatting and wording.

Fix: 269078018
Fix: 257449173
Test: n/a
Change-Id: Icb5f818f234f5eba03d7f685f58385aee8631000
This commit is contained in:
Vladimir Komsiyski
2023-03-31 10:28:55 +02:00
parent c3550fca47
commit c29a2c966b
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
*/