hal/WindowIdentifier.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set sw=2 ts=8 et ft=cpp : */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_hal_WindowIdentifier_h
   8 #define mozilla_hal_WindowIdentifier_h
   9
  10 #include "mozilla/Types.h"
  11 #include "nsTArray.h"
  12 #include "nsCOMPtr.h"
  13 #include "nsIDOMWindow.h"
  14
  15 namespace mozilla {
  16 namespace hal {
  17
  18 /**
  19  * This class serves two purposes.
  20  *
  21  * First, this class wraps a pointer to a window.
  22  *
  23  * Second, WindowIdentifier lets us uniquely identify a window across
  24  * processes.  A window exposes an ID which is unique only within its
  25  * process.  Thus to identify a window, we need to know the ID of the
  26  * process which contains it.  But the scope of a process's ID is its
  27  * parent; that is, two processes with different parents might have
  28  * the same ID.
  29  *
  30  * So to identify a window, we need its ID plus the IDs of all the
  31  * processes in the path from the window's process to the root
  32  * process.  We throw in the IDs of the intermediate windows (a
  33  * content window is contained in a window at each level of the
  34  * process tree) for good measures.
  35  *
  36  * You can access this list of IDs by calling AsArray().
  37  */
  38 class WindowIdentifier
  39 {
  40 public:
  41   /**
  42    * Create an empty WindowIdentifier.  Calls to any of this object's
  43    * public methods will assert -- an empty WindowIdentifier may be
  44    * used only as a placeholder to code which promises not to touch
  45    * the object.
  46    */
  47   WindowIdentifier();
  48
  49   /**
  50    * Copy constructor.
  51    */
  52   WindowIdentifier(const WindowIdentifier& other);
  53
  54   /**
  55    * Wrap the given window in a WindowIdentifier.  These two
  56    * constructors automatically grab the window's ID and append it to
  57    * the array of IDs.
  58    *
  59    * Note that these constructors allow an implicit conversion to a
  60    * WindowIdentifier.
  61    */
  62   explicit WindowIdentifier(nsIDOMWindow* window);
  63
  64   /**
  65    * Create a new WindowIdentifier with the given id array and window.
  66    * This automatically grabs the window's ID and appends it to the
  67    * array.
  68    */
  69   WindowIdentifier(const nsTArray<uint64_t>& id, nsIDOMWindow* window);
  70
  71   /**
  72    * Get the list of window and process IDs we contain.
  73    */
  74   typedef InfallibleTArray<uint64_t> IDArrayType;
  75   const IDArrayType& AsArray() const;
  76
  77   /**
  78    * Append the ID of the ContentChild singleton to our array of
  79    * window/process IDs.
  80    */
  81   void AppendProcessID();
  82
  83   /**
  84    * Does this WindowIdentifier identify both a window and the process
  85    * containing that window?  If so, we say it has traveled through
  86    * IPC.
  87    */
  88   bool HasTraveledThroughIPC() const;
  89
  90   /**
  91    * Get the window this object wraps.
  92    */
  93   nsIDOMWindow* GetWindow() const;
  94
  95 private:
  96   /**
  97    * Get the ID of the window object we wrap.
  98    */
  99   uint64_t GetWindowID() const;
 100
 101   AutoInfallibleTArray<uint64_t, 3> mID;
 102   nsCOMPtr<nsIDOMWindow> mWindow;
 103   bool mIsEmpty;
 104 };
 105
 106 } // namespace hal
 107 } // namespace mozilla
 108
 109 #endif // mozilla_hal_WindowIdentifier_h