Bug 1697647 - Add screen orientation lock api r=ipc-reviewers,mccr8,agi,smaug,jonalmeida

Previously, the screenOrientation.lock API was for Fennec and not supported for Fenix and multi-process use. The overall idea is to now allow apps to use the API through a delegate and make asynchronous calls to LockDeviceOrientation. This required replacing the existing code that returned a default false bool to calls that perform the requested orientation change and instead return a promise that contained either an allow or deny value.

Returning a promise instead of a bool involved changing the API calls from the C++ side to Java. The new general control flow of screenOrientation lock follows: an app calls C++ ScreenOrientation.lock() which eventually dispatches LockOrientationTask to resolve the pending orientation promise. Hal.cpp sends an IPC call to the content process and RecvLockScreenOrientation retrieves the current instance of geckoRuntime and calls the java side LockScreenOrientation. Apps must create a delegate and override onOrientationLock to set the requested orientation. In geckoview's testing, this is done with the android API setRequestedOrientation. Once a device orientation change has been triggered, native OnOrientationChange calls to NotifyScreenConfigurationChange, which notifies all observers and dispatches a change event to resolve the pending orientation promise.

Testing:
I used a demo on the GeckoView Example (https://usefulangle.com/demos/105/screen.html) to test locking to landscape orientation. This required a change to the GVE to show the app from recreating the whole thing on orientation change. In the example AndroidManifest xml file, `orientation` prevents restart when orientation changes.

The Junit/Kotlin tests were to verify that the expected orientation delegate was called with the expected new orientation value, in an orientation change, if the new orientation was the same as the current, and if the pre-lock conditions such as being fullscreen were not met.

A static preference `dom.screenorientation.allow-lock` was added to the dom group, since it affects the ui dom) and is currently turned off. C++ can access it through its mirrored variable dom_screenorientation_allow_lock (same name but with underscores). The junit tests turn the preference on and test the lock feature.

Reference:
Orientation constant values:
    C++
        1 ScreenOrientation_PortraitPrimary); - vertical with button at bottom
        2 ScreenOrientation_PortraitSecondary); - vertical with button at top
        4 ScreenOrientation_LandscapePrimary); - horizational w button right
        8 ScreenOrientation_LandscapeSecondary); - horization button left
        16 ScreenOrientation_Default);
    Java
        1 GeckoScreenOrientation.ScreenOrientation.PORTRAIT_PRIMARY.value
        2 GeckoScreenOrientation.ScreenOrientation.PORTRAIT_SECONDARY.value
        4 GeckoScreenOrientation.ScreenOrientation.LANDSCAPE_PRIMARY.value
        8 GeckoScreenOrientation.ScreenOrientation.LANDSCAPE_SECONDARY.value

    Java public API
        0 ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE
        1 Activitynfo.SCREEN_ORIENTATION_PORTRAIT

    Android
        1 ORIENTATION_PORTRAIT
        2 ORIENTATION_LANDSCAPE

Differential Revision: https://phabricator.services.mozilla.com/D129427

Author: calumozilla

dom/base/ScreenOrientation.cpp

@@ -18,6 +18,7 @@
 #include "mozilla/dom/ContentChild.h"
 #include "mozilla/dom/Event.h"
 #include "mozilla/dom/Promise.h"
+#include "mozilla/StaticPrefs_browser.h"
 #include "nsContentUtils.h"
 
 using namespace mozilla;
@@ -158,8 +159,11 @@ bool ScreenOrientation::LockOrientationTask::OrientationLockContains(
 
 NS_IMETHODIMP
 ScreenOrientation::LockOrientationTask::Run() {
-  // Step to lock the orientation as defined in the spec.
+  if (!mPromise) {
+    return NS_OK;
+  }
 
+  // Step to lock the orientation as defined in the spec.
   if (mDocument->GetOrientationPendingPromise() != mPromise) {
     // The document's pending promise is not associated with this task
     // to lock orientation. There has since been another request to
@@ -182,19 +186,29 @@ ScreenOrientation::LockOrientationTask::Run() {
     return NS_OK;
   }
 
-  ErrorResult rv;
-  bool result = mScreenOrientation->LockDeviceOrientation(mOrientationLock,
-                                                          mIsFullscreen, rv);
-  if (NS_WARN_IF(rv.Failed())) {
-    return rv.StealNSResult();
-  }
+  RefPtr<MozPromise<bool, bool, false>> lockOrientationPromise =
+      mScreenOrientation->LockDeviceOrientation(mOrientationLock,
+                                                mIsFullscreen);
 
-  if (NS_WARN_IF(!result)) {
+  if (NS_WARN_IF(!lockOrientationPromise)) {
     mPromise->MaybeReject(NS_ERROR_UNEXPECTED);
     mDocument->ClearOrientationPendingPromise();
     return NS_OK;
   }
 
+  lockOrientationPromise->Then(
+      GetCurrentSerialEventTarget(), __func__,
+      [self = RefPtr{this}](
+          const mozilla::MozPromise<bool, bool, false>::ResolveOrRejectValue&
+              aValue) {
+        if (aValue.IsResolve()) {
+          return NS_OK;
+        }
+        self->mPromise->MaybeReject(NS_ERROR_DOM_ABORT_ERR);
+        self->mDocument->ClearOrientationPendingPromise();
+        return NS_OK;
+      });
+
   BrowsingContext* bc = mDocument->GetBrowsingContext();
   if (OrientationLockContains(bc->GetCurrentOrientationType()) ||
       (mOrientationLock == hal::eScreenOrientation_Default &&
@@ -304,6 +318,12 @@ already_AddRefed<Promise> ScreenOrientation::LockInternal(
   p->MaybeReject(NS_ERROR_DOM_NOT_SUPPORTED_ERR);
   return p.forget();
 #else
+  // Bypass locking screen orientation if preference is false
+  if (!StaticPrefs::dom_screenorientation_allow_lock()) {
+    p->MaybeReject(NS_ERROR_DOM_NOT_SUPPORTED_ERR);
+    return p.forget();
+  }
+
   LockPermission perm = GetLockOrientationPermission(true);
   if (perm == LOCK_DENIED) {
     p->MaybeReject(NS_ERROR_DOM_SECURITY_ERR);
@@ -342,11 +362,10 @@ already_AddRefed<Promise> ScreenOrientation::LockInternal(
 #endif
 }
 
-bool ScreenOrientation::LockDeviceOrientation(
-    hal::ScreenOrientation aOrientation, bool aIsFullscreen, ErrorResult& aRv) {
+RefPtr<MozPromise<bool, bool, false>> ScreenOrientation::LockDeviceOrientation(
+    hal::ScreenOrientation aOrientation, bool aIsFullscreen) {
   if (!GetOwner()) {
-    aRv.Throw(NS_ERROR_UNEXPECTED);
-    return false;
+    return MozPromise<bool, bool, false>::CreateAndReject(false, __func__);
   }
 
   nsCOMPtr<EventTarget> target = GetOwner()->GetDoc();
@@ -355,11 +374,7 @@ bool ScreenOrientation::LockDeviceOrientation(
   // This needs to be done before LockScreenOrientation call to make sure
   // the locking can be unlocked.
   if (aIsFullscreen && !target) {
-    return false;
-  }
-
-  if (NS_WARN_IF(!hal::LockScreenOrientation(aOrientation))) {
-    return false;
+    return MozPromise<bool, bool, false>::CreateAndReject(false, __func__);
   }
 
   // We are fullscreen and lock has been accepted.
@@ -368,15 +383,21 @@ bool ScreenOrientation::LockDeviceOrientation(
       mFullscreenListener = new FullscreenEventListener();
     }
 
-    aRv = target->AddSystemEventListener(u"fullscreenchange"_ns,
-                                         mFullscreenListener,
-                                         /* useCapture = */ true);
-    if (NS_WARN_IF(aRv.Failed())) {
-      return false;
+    nsresult rv = target->AddSystemEventListener(u"fullscreenchange"_ns,
+                                                 mFullscreenListener,
+                                                 /* aUseCapture = */ true);
+    if (NS_WARN_IF(NS_FAILED(rv))) {
+      return MozPromise<bool, bool, false>::CreateAndReject(false, __func__);
     }
   }
 
-  return true;
+  RefPtr<MozPromise<bool, bool, false>> halPromise =
+      hal::LockScreenOrientation(aOrientation);
+  if (halPromise == nullptr) {
+    return MozPromise<bool, bool, false>::CreateAndReject(false, __func__);
+  }
+
+  return halPromise;
 }
 
 void ScreenOrientation::Unlock(ErrorResult& aRv) {
@@ -521,7 +542,7 @@ void ScreenOrientation::Notify(const hal::ScreenConfiguration& aConfiguration) {
   if (doc->Hidden() && !mVisibleListener) {
     mVisibleListener = new VisibleEventListener();
     rv = doc->AddSystemEventListener(u"visibilitychange"_ns, mVisibleListener,
-                                     /* useCapture = */ true);
+                                     /* aUseCapture = */ true);
     NS_WARNING_ASSERTION(NS_SUCCEEDED(rv), "AddSystemEventListener failed");
     return;
   }
@@ -541,8 +562,14 @@ void ScreenOrientation::UpdateActiveOrientationLock(
   if (aOrientation == hal::eScreenOrientation_None) {
     hal::UnlockScreenOrientation();
   } else {
-    DebugOnly<bool> ok = hal::LockScreenOrientation(aOrientation);
-    NS_WARNING_ASSERTION(ok, "hal::LockScreenOrientation failed");
+    hal::LockScreenOrientation(aOrientation)
+        ->Then(
+            GetMainThreadSerialEventTarget(), __func__,
+            [](const mozilla::MozPromise<bool, bool,
+                                         false>::ResolveOrRejectValue& aValue) {
+              NS_WARNING_ASSERTION(aValue.IsResolve(),
+                                   "hal::LockScreenOrientation failed");
+            });
   }
 }
 

dom/base/ScreenOrientation.h

@@ -11,6 +11,7 @@
 #include "mozilla/dom/BindingDeclarations.h"
 #include "mozilla/dom/ScreenOrientationBinding.h"
 #include "mozilla/HalScreenConfiguration.h"
+#include "mozilla/MozPromise.h"
 
 class nsScreen;
 
@@ -74,8 +75,8 @@ class ScreenOrientation final
 
   // This method calls into the HAL to lock the device and sets
   // up listeners for full screen change.
-  bool LockDeviceOrientation(hal::ScreenOrientation aOrientation,
-                             bool aIsFullscreen, ErrorResult& aRv);
+  RefPtr<MozPromise<bool, bool, false>> LockDeviceOrientation(
+      hal::ScreenOrientation aOrientation, bool aIsFullscreen);
 
   // This method calls in to the HAL to unlock the device and removes
   // full screen change listener.

dom/base/nsScreen.cpp

@@ -195,27 +195,6 @@ void nsScreen::GetMozOrientation(nsString& aOrientation,
   }
 }
 
-static void UpdateDocShellOrientationLock(nsPIDOMWindowInner* aWindow,
-                                          hal::ScreenOrientation aOrientation) {
-  if (!aWindow) {
-    return;
-  }
-
-  nsCOMPtr<nsIDocShell> docShell = aWindow->GetDocShell();
-  if (!docShell) {
-    return;
-  }
-
-  RefPtr<BrowsingContext> bc = docShell->GetBrowsingContext();
-  bc = bc ? bc->Top() : nullptr;
-  if (!bc) {
-    return;
-  }
-
-  // Setting orientation lock on a discarded context has no effect.
-  Unused << bc->SetOrientationLock(aOrientation);
-}
-
 bool nsScreen::MozLockOrientation(const nsAString& aOrientation,
                                   ErrorResult& aRv) {
   nsString orientation(aOrientation);
@@ -227,62 +206,13 @@ bool nsScreen::MozLockOrientation(const nsAString& aOrientation,
   return MozLockOrientation(orientations, aRv);
 }
 
+// This function is deprecated, use ScreenOrientation API instead.
 bool nsScreen::MozLockOrientation(const Sequence<nsString>& aOrientations,
                                   ErrorResult& aRv) {
-  if (ShouldResistFingerprinting()) {
-    return false;
-  }
-  hal::ScreenOrientation orientation = hal::eScreenOrientation_None;
-
-  for (uint32_t i = 0; i < aOrientations.Length(); ++i) {
-    const nsString& item = aOrientations[i];
-
-    if (item.EqualsLiteral("portrait")) {
-      orientation |= hal::eScreenOrientation_PortraitPrimary |
-                     hal::eScreenOrientation_PortraitSecondary;
-    } else if (item.EqualsLiteral("portrait-primary")) {
-      orientation |= hal::eScreenOrientation_PortraitPrimary;
-    } else if (item.EqualsLiteral("portrait-secondary")) {
-      orientation |= hal::eScreenOrientation_PortraitSecondary;
-    } else if (item.EqualsLiteral("landscape")) {
-      orientation |= hal::eScreenOrientation_LandscapePrimary |
-                     hal::eScreenOrientation_LandscapeSecondary;
-    } else if (item.EqualsLiteral("landscape-primary")) {
-      orientation |= hal::eScreenOrientation_LandscapePrimary;
-    } else if (item.EqualsLiteral("landscape-secondary")) {
-      orientation |= hal::eScreenOrientation_LandscapeSecondary;
-    } else if (item.EqualsLiteral("default")) {
-      orientation |= hal::eScreenOrientation_Default;
-    } else {
-      // If we don't recognize the token, we should just return 'false'
-      // without throwing.
-      return false;
-    }
-  }
-
-  switch (mScreenOrientation->GetLockOrientationPermission(false)) {
-    case ScreenOrientation::LOCK_DENIED:
-      return false;
-    case ScreenOrientation::LOCK_ALLOWED:
-      UpdateDocShellOrientationLock(GetOwner(), orientation);
-      return mScreenOrientation->LockDeviceOrientation(orientation, false, aRv);
-    case ScreenOrientation::FULLSCREEN_LOCK_ALLOWED:
-      UpdateDocShellOrientationLock(GetOwner(), orientation);
-      return mScreenOrientation->LockDeviceOrientation(orientation, true, aRv);
-  }
-
-  // This is only for compilers that don't understand that the previous switch
-  // will always return.
-  MOZ_CRASH("unexpected lock orientation permission value");
+  return false;
 }
 
-void nsScreen::MozUnlockOrientation() {
-  if (ShouldResistFingerprinting()) {
-    return;
-  }
-  UpdateDocShellOrientationLock(GetOwner(), hal::eScreenOrientation_None);
-  mScreenOrientation->UnlockDeviceOrientation();
-}
+void nsScreen::MozUnlockOrientation() {}
 
 /* virtual */
 JSObject* nsScreen::WrapObject(JSContext* aCx,

hal/Hal.cpp

@@ -407,9 +407,10 @@ void NotifyScreenConfigurationChange(
   ScreenConfigurationObservers()->BroadcastCachedInformation();
 }
 
-bool LockScreenOrientation(const ScreenOrientation& aOrientation) {
+RefPtr<mozilla::MozPromise<bool, bool, false>> LockScreenOrientation(
+    const ScreenOrientation& aOrientation) {
   AssertMainThread();
-  RETURN_PROXY_IF_SANDBOXED(LockScreenOrientation(aOrientation), false);
+  RETURN_PROXY_IF_SANDBOXED(LockScreenOrientation(aOrientation), nullptr);
 }
 
 void UnlockScreenOrientation() {

hal/Hal.h

@@ -17,6 +17,7 @@
 #include "mozilla/HalWakeLockInformation.h"
 #include "mozilla/HalTypes.h"
 #include "mozilla/Types.h"
+#include "mozilla/MozPromise.h"
 
 /*
  * Hal.h contains the public Hal API.
@@ -232,10 +233,10 @@ void NotifyScreenConfigurationChange(
 
 /**
  * Lock the screen orientation to the specific orientation.
- * @return Whether the lock has been accepted.
+ * @return A promise indicating that the screen orientation has been locked.
  */
-[[nodiscard]] bool LockScreenOrientation(
-    const hal::ScreenOrientation& aOrientation);
+[[nodiscard]] RefPtr<mozilla::MozPromise<bool, bool, false>>
+LockScreenOrientation(const hal::ScreenOrientation& aOrientation);
 
 /**
  * Unlock the screen orientation.

hal/android/AndroidHal.cpp

@@ -9,6 +9,7 @@
 #include "AndroidBridge.h"
 #include "mozilla/dom/network/Constants.h"
 #include "mozilla/java/GeckoAppShellWrappers.h"
+#include "mozilla/java/GeckoRuntimeWrappers.h"
 #include "nsIScreenManager.h"
 #include "nsPIDOMWindow.h"
 #include "nsServiceManagerUtils.h"
@@ -123,8 +124,40 @@ void GetCurrentScreenConfiguration(ScreenConfiguration* aScreenConfiguration) {
                                orientation, angle, colorDepth, pixelDepth);
 }
 
-bool LockScreenOrientation(const hal::ScreenOrientation& aOrientation) {
-  return false;
+RefPtr<MozPromise<bool, bool, false>> LockScreenOrientation(
+    const hal::ScreenOrientation& aOrientation) {
+  // Force the default orientation to be portrait-primary.
+  hal::ScreenOrientation orientation =
+      aOrientation == eScreenOrientation_Default
+          ? eScreenOrientation_PortraitPrimary
+          : aOrientation;
+
+  switch (orientation) {
+    // The Android backend only supports these orientations.
+    case eScreenOrientation_PortraitPrimary:
+    case eScreenOrientation_PortraitSecondary:
+    case eScreenOrientation_PortraitPrimary |
+        eScreenOrientation_PortraitSecondary:
+    case eScreenOrientation_LandscapePrimary:
+    case eScreenOrientation_LandscapeSecondary:
+    case eScreenOrientation_LandscapePrimary |
+        eScreenOrientation_LandscapeSecondary:
+    case eScreenOrientation_Default: {
+      java::GeckoRuntime::LocalRef runtime = java::GeckoRuntime::GetInstance();
+      if (runtime != NULL) {
+        auto result = runtime->LockScreenOrientation(orientation);
+        auto geckoResult = java::GeckoResult::LocalRef(std::move(result));
+        return geckoResult
+                   ? MozPromise<bool, bool, false>::FromGeckoResult(geckoResult)
+                   : MozPromise<bool, bool, false>::CreateAndReject(false,
+                                                                    __func__);
+      } else {
+        return MozPromise<bool, bool, false>::CreateAndReject(false, __func__);
+      }
+    }
+    default:
+      return nullptr;
+  }
 }
 
 void UnlockScreenOrientation() {}

hal/fallback/FallbackScreenConfiguration.cpp

@@ -16,8 +16,10 @@ void GetCurrentScreenConfiguration(
   fallback::GetCurrentScreenConfiguration(aScreenConfiguration);
 }
 
-bool LockScreenOrientation(const hal::ScreenOrientation& aOrientation) {
-  return false;
+RefPtr<mozilla::MozPromise<bool, bool, false>> LockScreenOrientation(
+    const hal::ScreenOrientation& aOrientation) {
+  return mozilla::MozPromise<bool, bool, false>::CreateAndReject(false,
+                                                                 __func__);
 }
 
 void UnlockScreenOrientation() {}

hal/sandbox/PHal.ipdl

@@ -91,7 +91,7 @@ parent:
 
     async EnableScreenConfigurationNotifications();
     async DisableScreenConfigurationNotifications();
-    sync LockScreenOrientation(ScreenOrientation aOrientation)
+    async LockScreenOrientation(ScreenOrientation aOrientation)
       returns (bool allowed);
     async UnlockScreenOrientation();