Skip to content

Commit abc08f4

Browse files
leonhslleonhsl
authored
Update MultiProfile.md
1 parent f9b83cd commit abc08f4

1 file changed

Lines changed: 75 additions & 137 deletions

File tree

‎specs/MultiProfile.md‎

Lines changed: 75 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,16 @@
1-
<!--
2-
Before submitting, delete all "<!-- TEMPLATE" marked comments in this file,
3-
and the following quote banner:
4-
-->
5-
> See comments in Markdown for how to use this spec template
6-
7-
<!-- TEMPLATE
8-
The purpose of this spec is to describe new APIs, in a way
9-
that will transfer to docs.microsoft.com (https://docs.microsoft.com/en-us/microsoft-edge/webview2/).
10-
11-
There are two audiences for the spec. The first are people that want to evaluate and
12-
give feedback on the API, as part of the submission process.
13-
So the second audience is everyone that reads there to learn how and why to use this API.
14-
Some of this text also shows up in Visual Studio Intellisense.
15-
When the PR is complete, the content within the 'Conceptual Pages' section of the review spec will be incorporated into the public documentation at
16-
http://docs.microsoft.com (DMC).
17-
18-
For example, much of the examples and descriptions in the `RadialGradientBrush` API spec
19-
(https://github.com/microsoft/microsoft-ui-xaml-specs/blob/master/active/RadialGradientBrush/RadialGradientBrush.md)
20-
were carried over to the public API page on DMC
21-
(https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.media.radialgradientbrush?view=winui-2.5)
22-
23-
Once the API is on DMC, that becomes the official copy, and this spec becomes an archive.
24-
For example if the description is updated, that only needs to happen on DMC and needn't
25-
be duplicated here.
26-
27-
Examples:
28-
* New set of classes and APIs (Custom Downloads):
29-
https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/CustomDownload.md
30-
* New member on an existing class (BackgroundColor):
31-
https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/BackgroundColor.md
32-
33-
Style guide:
34-
* Use second person; speak to the developer who will be learning/using this API.
35-
(For example "you use this to..." rather than "the developer uses this to...")
36-
* Use hard returns to keep the page width within ~100 columns.
37-
(Otherwise it's more difficult to leave comments in a GitHub PR.)
38-
* Talk about an API's behavior, not its implementation.
39-
(Speak to the developer using this API, not to the team implementing it.)
40-
* A picture is worth a thousand words.
41-
* An example is worth a million words.
42-
* Keep examples realistic but simple; don't add unrelated complications.
43-
(An example that passes a stream needn't show the process of launching the File-Open dialog.)
44-
* Use GitHub flavored Markdown: https://guides.github.com/features/mastering-markdown/
45-
46-
-->
47-
48-
Title
1+
API spec for multiple profile support
492
===
503

514
# Background
52-
<!-- TEMPLATE
53-
Use this section to provide background context for the new API(s)
54-
in this spec. Try to briefly provide enough information to be able to read
55-
the rest of the document.
56-
57-
This section and the appendix are the only sections that likely
58-
do not get copied into any official documentation, they're just an aid
59-
to reading this spec. If you find useful information in the background
60-
or appendix consider moving it to documentation.
61-
62-
If you're modifying an existing API, included a link here to the
63-
existing page(s) or spec documentation.
64-
65-
For example, this section is a place to explain why you're adding this
66-
API rather than modifying an existing API.
675

68-
For example, this is a place to provide a brief explanation of some dependent
69-
area, just explanation enough to understand this new API, rather than telling
70-
the reader "go read 100 pages of background information posted at ...".
71-
-->
72-
73-
# Conceptual pages (How To)
74-
75-
_(This is conceptual documentation that will go to docs.microsoft.com "how to" page)_
76-
77-
<!-- TEMPLATE
78-
(Optional)
79-
80-
All APIs have reference docs, but some APIs or groups of APIs have an additional high level,
81-
conceptual page (called a "how-to" page). This section can be used for that content.
82-
83-
For example, there are several navigation events each with their own reference doc, but then
84-
there's also a concept doc on navigation
85-
(https://docs.microsoft.com/en-us/microsoft-edge/webview2/concepts/navigation-events).
86-
87-
Sometimes it's difficult to decide if text belongs on a how-to page or an API page.
88-
Because our API reference documentation is automatically turned into reference docs you can
89-
lean towards including text in the API documentation below instead of in this conceptual
90-
section.
91-
-->
6+
Currently, all WebView2s can only use one fixed Edge profile in the browser process, which is
7+
normally the **Default** profile or the profile specified by the **--profile-directory** command
8+
line switch. Regarding this we have got a bunch of requests to support multiple profiles, so we're
9+
adding these new APIs.
9210

11+
With this you can have different WebView2s running with separate profiles under a given user data
12+
directory, which means separate cookies, user preference settings, and various data storage etc.,
13+
to enable you to build a more wonderful experience for your application.
9314

9415
# Examples
9516
<!-- TEMPLATE
@@ -145,64 +66,81 @@ _(This is conceptual documentation that will go to docs.microsoft.com "how to" p
14566
-->
14667

14768
# API Details
148-
<!-- TEMPLATE
149-
The exact API, in IDL format for our COM API and
150-
in MIDL3 format (https://docs.microsoft.com/en-us/uwp/midl-3/)
151-
when possible.
15269

153-
Include every new or modified type but use // ... to remove any methods,
154-
properties, or events that are unchanged.
70+
## Win32 C++
15571

156-
For the MIDL3 parts, after running build-apiwriter, open the generated
157-
`Microsoft.Web.WebView2.Core.idl` and find the new or modified portions
158-
generated from your modifications to the COM IDL.
72+
```IDL
73+
interface ICoreWebView2Staging6;
74+
interface ICoreWebView2StagingCreateControllerOptions;
75+
interface ICoreWebView2StagingEnvironment4;
76+
interface ICoreWebView2StagingProfile;
15977
160-
(GitHub's markdown syntax formatter does not (yet) know about MIDL3, so
161-
use ```c# instead even when writing MIDL3.)
78+
[uuid(57FD205C-39D5-4BA1-8E7B-3E53C323EA87), object, pointer_default(unique)]
79+
interface ICoreWebView2StagingEnvironment4 : IUnknown
80+
{
81+
/// Create a new ICoreWebView2StagingCreateControllerOptions to be passed as a parameter of
82+
/// CreateCoreWebView2ControllerWithOptions and CreateCoreWebView2CompositionControllerWithOptions.
83+
HRESULT CreateCoreWebView2CreateControllerOptions(
84+
[in] LPCWSTR profileName,
85+
[in] BOOL inPrivateModeEnabled,
86+
[out, retval] ICoreWebView2StagingCreateControllerOptions** options);
87+
88+
/// Create a new WebView with options.
89+
HRESULT CreateCoreWebView2ControllerWithOptions(
90+
[in] HWND parentWindow,
91+
[in] ICoreWebView2StagingCreateControllerOptions* options,
92+
[in] ICoreWebView2CreateCoreWebView2ControllerCompletedHandler* handler);
93+
94+
/// Create a new WebView in visual hosting mode with options.
95+
HRESULT CreateCoreWebView2CompositionControllerWithOptions(
96+
[in] HWND parentWindow,
97+
[in] ICoreWebView2StagingCreateControllerOptions* options,
98+
[in] ICoreWebView2CreateCoreWebView2CompositionControllerCompletedHandler* handler);
99+
}
162100
163-
Example:
164-
165-
```
166-
[uuid(B625A89E-368F-43F5-BCBA-39AA6234CCF8), object, pointer_default(unique)]
167-
interface ICoreWebView2Settings4 : ICoreWebView2Settings3 {
168-
/// The IsPinchZoomEnabled property enables or disables the ability of
169-
/// the end user to use a pinching motion on touch input enabled devices
170-
/// to scale the web content in the WebView2. It defaults to TRUE.
171-
/// When set to FALSE, the end user cannot pinch zoom.
172-
/// This API only affects the Page Scale zoom and has no effect on the
173-
/// existing browser zoom properties (IsZoomControlEnabled and ZoomFactor)
174-
/// or other end user mechanisms for zooming.
175-
///
176-
/// \snippet SettingsComponent.cpp TogglePinchZooomEnabled
177-
[propget] HRESULT IsPinchZoomEnabled([out, retval] BOOL* enabled);
178-
/// Set the IsPinchZoomEnabled property
179-
[propput] HRESULT IsPinchZoomEnabled([in] BOOL enabled);
101+
[uuid(C2669A3A-03A9-45E9-97EA-03CD55E5DC03), object, pointer_default(unique)]
102+
interface ICoreWebView2StagingCreateControllerOptions : IUnknown {
103+
/// `ProfileName` property is to specify a profile name, which is only allowed to contain
104+
/// the following ASCII characters with the maximum length as 64 and will be treated in a
105+
/// case insensitive way.
106+
/// alphabet characters: a-z and A-Z
107+
/// digit characters: 0-9
108+
/// and '#', '@', '$', '(', ')', '+', '-', '_', '~', '.', ' ' (space).
109+
/// Note: the text must not end with a period '.' or ' ' (space). And, although upper case letters are
110+
/// allowed, they're treated just as lower case couterparts because the profile name will be mapped to
111+
/// the real profile directory path on disk and Windows file system handles path names in a case-insensitive way.
112+
[propget] HRESULT ProfileName([out, retval] LPWSTR* value);
113+
/// Sets the `ProfileName` property.
114+
[propput] HRESULT ProfileName([in] LPCWSTR value);
115+
116+
/// `InPrivateModeEnabled` property is to enable/disable InPrivate mode.
117+
[propget] HRESULT InPrivateModeEnabled([out, retval] BOOL* enabled);
118+
/// Sets the `InPrivateModeEnabled` property.
119+
[propput] HRESULT InPrivateModeEnabled([in] BOOL enabled);
180120
}
181-
```
182121
183-
```c# (but really MIDL3)
184-
namespace Microsoft.Web.WebView2.Core
185-
{
186-
runtimeclass CoreWebView2Settings
187-
{
188-
// ...
122+
[uuid(6E5CE5F0-16E6-4A05-97D8-4E256B3EB609), object, pointer_default(unique)]
123+
interface ICoreWebView2Staging6 : IUnknown {
124+
/// The associated `ICoreWebView2StagingProfile` object.
125+
[propget] HRESULT Profile([out, retval] ICoreWebView2StagingProfile** profile);
126+
}
189127
190-
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings5")]
191-
{
192-
Boolean IsPinchZoomEnabled { get; set; };
193-
}
194-
}
128+
[uuid(3B9A2AF2-E703-4C81-9D25-FCE44312E960), object, pointer_default(unique)]
129+
interface ICoreWebView2StagingProfile : IUnknown {
130+
/// Name of the profile.
131+
[propget] HRESULT ProfileName([out, retval] LPWSTR* value);
132+
133+
/// InPrivate mode is enabled or not.
134+
[propget] HRESULT InPrivateModeEnabled([out, retval] BOOL* enabled);
135+
136+
/// Full path of the profile directory.
137+
[propget] HRESULT ProfilePath([out, retval] LPWSTR* value);
138+
139+
/// TODO: All profile-wide operations/settings will be put below.
195140
}
196141
```
197-
-->
198-
199142

200143
# Appendix
201-
<!-- TEMPLATE
202-
Anything else that you want to write down about implementation notes and for posterity,
203-
but that isn't necessary to understand the purpose and usage of the API.
204-
205-
This or the Background section are a good place to describe alternative designs
206-
and why they were rejected, any relevant implementation details, or links to other
207-
resources.
208-
-->
144+
145+
Next we'll consolidate all profile-wide operations/settings into the interface
146+
`ICoreWebView2StagingProfile`, and will also add support for erasing a profile completely.

0 commit comments

Comments
 (0)