ios/chrome/browser/web/dom_altering_lock.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef IOS_CHROME_BROWSER_WEB_DOM_ALTERING_LOCK_H_
   6 #define IOS_CHROME_BROWSER_WEB_DOM_ALTERING_LOCK_H_
   7
   8 #include "base/ios/block_types.h"
   9 #import "base/ios/weak_nsobject.h"
  10 #include "ios/web/public/web_state/web_state_user_data.h"
  11
  12 namespace web {
  13 class WebState;
  14 }
  15
  16 typedef void (^ProceduralBlockWithBool)(BOOL);
  17
  18 // This protocol must be implemented by all classes which may alter the DOM tree
  19 // of a web page. Before altering the DOM, the class must call
  20 // DOMAlteringLock::Acquire() and can only proceed if the lock is really
  21 // acquired.
  22 // After restoring the DOM tree, the class must call DOMAlteringLock::Release().
  23 @protocol DOMAltering<NSObject>
  24
  25 // Method called when another class wants to acquire the lock.
  26 // Return YES if the class is ready to restore the DOM tree to its initial state
  27 // and release the lock. A call to |releaseDOMLockWithCompletionHandler:|
  28 // will follow to do the actual cleaning.
  29 // Return NO if the class wants to keep an exclusive access to the DOM tree.
  30 // Other features must account for the fact that they may not be able to acquire
  31 // a lock on the DOM and behave accordingly.
  32 - (BOOL)canReleaseDOMLock;
  33
  34 // Method called when another class wants to acquire the lock.
  35 // The class must restore the DOM tree, call DOMAlteringLock::Release() and then
  36 // |completionHandler|.
  37 - (void)releaseDOMLockWithCompletionHandler:(ProceduralBlock)completionHandler;
  38
  39 @end
  40
  41 class DOMAlteringLock : public web::WebStateUserData<DOMAlteringLock> {
  42  public:
  43   DOMAlteringLock(web::WebState* web_state);
  44
  45   // This method must be called before altering the DOM of the page. This will
  46   // ensure that only one class tries to alter the page at a time.
  47   // The completion handler is called with YES if the lock was acquired, or NO
  48   // if it could not.
  49   // This method must be called on the UI thread.
  50   void Acquire(id<DOMAltering> feature, ProceduralBlockWithBool lockAction);
  51
  52   // Releases the lock on the DOM tree.
  53   // The lock is always released, even if it was acquired multiple times.
  54   // This method must be called on the UI thread.
  55   void Release(id<DOMAltering> feature);
  56
  57  private:
  58   // DOMAltering object currently having the lock.
  59   base::WeakNSProtocol<id<DOMAltering>> current_dom_altering_feature_;
  60
  61   ~DOMAlteringLock() override;
  62 };
  63
  64 #endif  // IOS_CHROME_BROWSER_WEB_DOM_ALTERING_LOCK_H_