1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
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 file,
5  * You can obtain one at http://mozilla.org/MPL/2.0/. */
6 
7 #ifndef TabGroup_h
8 #define TabGroup_h
9 
10 #include "nsISupports.h"
11 #include "nsISupportsImpl.h"
12 #include "nsIPrincipal.h"
13 #include "nsTHashtable.h"
14 #include "nsString.h"
15 
16 #include "mozilla/RefPtr.h"
17 
18 namespace mozilla {
19 class ThrottledEventQueue;
20 namespace dom {
21 
22 // Two browsing contexts are considered "related" if they are reachable from one
23 // another through window.opener, window.parent, or window.frames. This is the
24 // spec concept of a "unit of related browsing contexts"
25 //
26 // Two browsing contexts are considered "similar-origin" if they can be made to
27 // have the same origin by setting document.domain. This is the spec concept of
28 // a "unit of similar-origin related browsing contexts"
29 //
30 // A TabGroup is a set of browsing contexts which are all "related". Within a
31 // TabGroup, browsing contexts are broken into "similar-origin" DocGroups. In
32 // more detail, a DocGroup is actually a collection of documents, and a
33 // TabGroup is a collection of DocGroups. A TabGroup typically will contain
34 // (through its DocGroups) the documents from one or more tabs related by
35 // window.opener. A DocGroup is a member of exactly one TabGroup.
36 
37 class DocGroup;
38 
39 class TabGroup final : public nsISupports
40 {
41 private:
42   class HashEntry : public nsCStringHashKey
43   {
44   public:
45     // NOTE: Weak reference. The DocGroup destructor removes itself from its
46     // owning TabGroup.
47     DocGroup* mDocGroup;
48     explicit HashEntry(const nsACString* aKey);
49   };
50 
51   typedef nsTHashtable<HashEntry> DocGroupMap;
52 public:
53   typedef DocGroupMap::Iterator Iterator;
54 
55   friend class DocGroup;
56 
57   NS_DECL_THREADSAFE_ISUPPORTS
58 
59   static TabGroup*
60   GetChromeTabGroup();
61 
62   explicit TabGroup(bool aIsChrome = false);
63 
64   // Get the docgroup for the corresponding doc group key.
65   // Returns null if the given key hasn't been seen yet.
66   already_AddRefed<DocGroup>
67   GetDocGroup(const nsACString& aKey);
68 
69   already_AddRefed<DocGroup>
70   AddDocument(const nsACString& aKey, nsIDocument* aDocument);
71 
72   // Join the specified TabGroup, returning a reference to it. If aTabGroup is
73   // nullptr, create a new tabgroup to join.
74   static already_AddRefed<TabGroup>
75   Join(nsPIDOMWindowOuter* aWindow, TabGroup* aTabGroup);
76 
77   void Leave(nsPIDOMWindowOuter* aWindow);
78 
Iter()79   Iterator Iter()
80   {
81     return mDocGroups.Iter();
82   }
83 
84 
85   // Returns the nsIDocShellTreeItem with the given name, searching each of the
86   // docShell trees which are within this TabGroup. It will pass itself as
87   // aRequestor to each docShellTreeItem which it asks to search for the name,
88   // and will not search the docShellTreeItem which is passed as aRequestor.
89   //
90   // This method is used in order to correctly namespace named windows based on
91   // their unit of related browsing contexts.
92   //
93   // It is illegal to pass in the special case-insensitive names "_blank",
94   // "_self", "_parent" or "_top", as those should be handled elsewhere.
95   nsresult
96   FindItemWithName(const nsAString& aName,
97                    nsIDocShellTreeItem* aRequestor,
98                    nsIDocShellTreeItem* aOriginalRequestor,
99                    nsIDocShellTreeItem** aFoundItem);
100 
101   nsTArray<nsPIDOMWindowOuter*> GetTopLevelWindows();
102 
103   // Get the event queue that associated windows can use to issue runnables to
104   // the main thread.  This may return nullptr during browser shutdown.
105   ThrottledEventQueue*
106   GetThrottledEventQueue() const;
107 
108 private:
109   ~TabGroup();
110   DocGroupMap mDocGroups;
111   nsTArray<nsPIDOMWindowOuter*> mWindows;
112   RefPtr<ThrottledEventQueue> mThrottledEventQueue;
113 };
114 
115 } // namespace dom
116 } // namespace mozilla
117 
118 #endif // defined(TabGroup_h)
119