env_create_options.go 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276
  1. //go:build windows && !native_webview2loader
  2. package webviewloader
  3. import (
  4. "unicode/utf16"
  5. "unsafe"
  6. "github.com/wailsapp/go-webview2/pkg/combridge"
  7. "golang.org/x/sys/windows"
  8. )
  9. // WithBrowserExecutableFolder to specify whether WebView2 controls use a fixed or installed version
  10. // of the WebView2 Runtime that exists on a user machine.
  11. //
  12. // To use a fixed version of the WebView2 Runtime,
  13. // pass the folder path that contains the fixed version of the WebView2 Runtime.
  14. // BrowserExecutableFolder supports both relative (to the application's executable) and absolute files paths.
  15. // To create WebView2 controls that use the installed version of the WebView2 Runtime that exists on user
  16. // machines, pass a empty string to WithBrowserExecutableFolder. In this scenario, the API tries to find a
  17. // compatible version of the WebView2 Runtime that is installed on the user machine (first at the machine level,
  18. // and then per user) using the selected channel preference. The path of fixed version of the WebView2 Runtime
  19. // should not contain \Edge\Application\. When such a path is used, the API fails with HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).
  20. func WithBrowserExecutableFolder(folder string) option {
  21. return func(wvep *environmentOptions) {
  22. wvep.browserExecutableFolder = folder
  23. }
  24. }
  25. // WithUserDataFolder specifies to user data folder location for WebView2
  26. //
  27. // You may specify the userDataFolder to change the default user data folder location for WebView2.
  28. // The path is either an absolute file path or a relative file path that is interpreted as relative
  29. // to the compiled code for the current process.
  30. // Dhe default user data ({Executable File Name}.WebView2) folder is created in the same directory
  31. // next to the compiled code for the app. WebView2 creation fails if the compiled code is running
  32. // in a directory in which the process does not have permission to create a new directory.
  33. // The app is responsible to clean up the associated user data folder when it is done.
  34. func WithUserDataFolder(folder string) option {
  35. return func(wvep *environmentOptions) {
  36. wvep.userDataFolder = folder
  37. }
  38. }
  39. // WithAdditionalBrowserArguments changes the behavior of the WebView.
  40. //
  41. // The arguments are passed to the
  42. // browser process as part of the command. For more information about
  43. // using command-line switches with Chromium browser processes, navigate to
  44. // [Run Chromium with Flags][ChromiumDevelopersHowTosRunWithFlags].
  45. // The value appended to a switch is appended to the browser process, for
  46. // example, in `--edge-webview-switches=xxx` the value is `xxx`. If you
  47. // specify a switch that is important to WebView functionality, it is
  48. // ignored, for example, `--user-data-dir`. Specific features are disabled
  49. // internally and blocked from being enabled. If a switch is specified
  50. // multiple times, only the last instance is used.
  51. //
  52. // \> [!NOTE]\n\> A merge of the different values of the same switch is not attempted,
  53. // except for disabled and enabled features. The features specified by
  54. // `--enable-features` and `--disable-features` are merged with simple
  55. // logic.\n\> * The features is the union of the specified features
  56. // and built-in features. If a feature is disabled, it is removed from the
  57. // enabled features list.
  58. //
  59. // If you specify command-line switches and use the
  60. // `additionalBrowserArguments` parameter, the `--edge-webview-switches`
  61. // value takes precedence and is processed last. If a switch fails to
  62. // parse, the switch is ignored. The default state for the operation is
  63. // to run the browser process with no extra flags.
  64. //
  65. // [ChromiumDevelopersHowTosRunWithFlags]: https://www.chromium.org/developers/how-tos/run-chromium-with-flags "Run Chromium with flags | The Chromium Projects"
  66. func WithAdditionalBrowserArguments(args string) option {
  67. return func(wvep *environmentOptions) {
  68. wvep.additionalBrowserArguments = args
  69. }
  70. }
  71. // WithLanguage sets the default display language for WebView.
  72. //
  73. // It applies to browser UI such as
  74. // context menu and dialogs. It also applies to the `accept-languages` HTTP
  75. // header that WebView sends to websites. It is in the format of
  76. //
  77. // `language[-country]` where `language` is the 2-letter code from
  78. // [ISO 639][ISO639LanguageCodesHtml]
  79. // and `country` is the
  80. // 2-letter code from
  81. // [ISO 3166][ISOStandard72482Html].
  82. //
  83. // [ISO639LanguageCodesHtml]: https://www.iso.org/iso-639-language-codes.html "ISO 639 | ISO"
  84. // [ISOStandard72482Html]: https://www.iso.org/standard/72482.html "ISO 3166-1:2020 | ISO"
  85. func WithLanguage(lang string) option {
  86. return func(wvep *environmentOptions) {
  87. wvep.language = lang
  88. }
  89. }
  90. // WithTargetCompatibleBrowserVersion secifies the version of the WebView2 Runtime binaries required to be
  91. // compatible with your app.
  92. //
  93. // This defaults to the WebView2 Runtime version
  94. // that corresponds with the version of the SDK the app is using. The
  95. // format of this value is the same as the format of the
  96. // `BrowserVersionString` property and other `BrowserVersion` values. Only
  97. // the version part of the `BrowserVersion` value is respected. The channel
  98. // suffix, if it exists, is ignored. The version of the WebView2 Runtime
  99. // binaries actually used may be different from the specified
  100. // `TargetCompatibleBrowserVersion`. The binaries are only guaranteed to be
  101. // compatible. Verify the actual version on the `BrowserVersionString`
  102. // property on the `ICoreWebView2Environment`.
  103. func WithTargetCompatibleBrowserVersion(version string) option {
  104. return func(wvep *environmentOptions) {
  105. wvep.targetCompatibleBrowserVersion = version
  106. }
  107. }
  108. // WithAllowSingleSignOnUsingOSPrimaryAccount is used to enable
  109. // single sign on with Azure Active Directory (AAD) and personal Microsoft
  110. // Account (MSA) resources inside WebView. All AAD accounts, connected to
  111. // Windows and shared for all apps, are supported. For MSA, SSO is only enabled
  112. // for the account associated for Windows account login, if any.
  113. // Default is disabled. Universal Windows Platform apps must also declare
  114. // `enterpriseCloudSSO`
  115. // [Restricted capabilities][WindowsUwpPackagingAppCapabilityDeclarationsRestrictedCapabilities]
  116. // for the single sign on (SSO) to work.
  117. //
  118. // [WindowsUwpPackagingAppCapabilityDeclarationsRestrictedCapabilities]: /windows/uwp/packaging/app-capability-declarations\#restricted-capabilities "Restricted capabilities - App capability declarations | Microsoft Docs"
  119. func WithAllowSingleSignOnUsingOSPrimaryAccount(allow bool) option {
  120. return func(wvep *environmentOptions) {
  121. wvep.allowSingleSignOnUsingOSPrimaryAccount = allow
  122. }
  123. }
  124. // WithExclusiveUserDataFolderAccess specifies that the WebView environment
  125. // obtains exclusive access to the user data folder.
  126. //
  127. // If the user data folder is already being used by another WebView environment with a
  128. // different value for `ExclusiveUserDataFolderAccess` property, the creation of a WebView2Controller
  129. // using the environment object will fail with `HRESULT_FROM_WIN32(ERROR_INVALID_STATE)`.
  130. // When set as TRUE, no other WebView can be created from other processes using WebView2Environment
  131. // objects with the same UserDataFolder. This prevents other processes from creating WebViews
  132. // which share the same browser process instance, since sharing is performed among
  133. // WebViews that have the same UserDataFolder. When another process tries to create a
  134. // WebView2Controller from an WebView2Environment object created with the same user data folder,
  135. // it will fail with `HRESULT_FROM_WIN32(ERROR_INVALID_STATE)`.
  136. func WithExclusiveUserDataFolderAccess(exclusive bool) option {
  137. return func(wvep *environmentOptions) {
  138. wvep.exclusiveUserDataFolderAccess = exclusive
  139. }
  140. }
  141. type option func(*environmentOptions)
  142. var _ iCoreWebView2EnvironmentOptions = &environmentOptions{}
  143. var _ iCoreWebView2EnvironmentOptions2 = &environmentOptions{}
  144. type environmentOptions struct {
  145. browserExecutableFolder string
  146. userDataFolder string
  147. preferCanary bool
  148. additionalBrowserArguments string
  149. language string
  150. targetCompatibleBrowserVersion string
  151. allowSingleSignOnUsingOSPrimaryAccount bool
  152. exclusiveUserDataFolderAccess bool
  153. }
  154. func (o *environmentOptions) AdditionalBrowserArguments() string {
  155. return o.additionalBrowserArguments
  156. }
  157. func (o *environmentOptions) Language() string {
  158. return o.language
  159. }
  160. func (o *environmentOptions) TargetCompatibleBrowserVersion() string {
  161. v := o.targetCompatibleBrowserVersion
  162. if v == "" {
  163. v = kMinimumCompatibleVersion
  164. }
  165. return v
  166. }
  167. func (o *environmentOptions) AllowSingleSignOnUsingOSPrimaryAccount() bool {
  168. return o.allowSingleSignOnUsingOSPrimaryAccount
  169. }
  170. func (o *environmentOptions) ExclusiveUserDataFolderAccess() bool {
  171. return o.exclusiveUserDataFolderAccess
  172. }
  173. type iCoreWebView2EnvironmentOptions interface {
  174. combridge.IUnknown
  175. AdditionalBrowserArguments() string
  176. Language() string
  177. TargetCompatibleBrowserVersion() string
  178. AllowSingleSignOnUsingOSPrimaryAccount() bool
  179. }
  180. type iCoreWebView2EnvironmentOptions2 interface {
  181. combridge.IUnknown
  182. ExclusiveUserDataFolderAccess() bool
  183. }
  184. func init() {
  185. combridge.RegisterVTable[combridge.IUnknown, iCoreWebView2EnvironmentOptions](
  186. "{2fde08a8-1e9a-4766-8c05-95a9ceb9d1c5}",
  187. _iCoreWebView2EnvironmentOptionsAdditionalBrowserArguments,
  188. _iCoreWebView2EnvironmentOptionsNOP,
  189. _iCoreWebView2EnvironmentOptionsLanguage,
  190. _iCoreWebView2EnvironmentOptionsNOP,
  191. _iCoreWebView2EnvironmentTargetCompatibleBrowserVersion,
  192. _iCoreWebView2EnvironmentOptionsNOP,
  193. _iCoreWebView2EnvironmentOptionsAllowSingleSignOnUsingOSPrimaryAccount,
  194. _iCoreWebView2EnvironmentOptionsNOP,
  195. )
  196. combridge.RegisterVTable[combridge.IUnknown, iCoreWebView2EnvironmentOptions2](
  197. "{ff85c98a-1ba7-4a6b-90c8-2b752c89e9e2}",
  198. _iCoreWebView2EnvironmentOptions2ExclusiveUserDataFolderAccess,
  199. _iCoreWebView2EnvironmentOptionsNOP,
  200. )
  201. }
  202. func _iCoreWebView2EnvironmentOptionsNOP(this uintptr) uintptr {
  203. return uintptr(windows.S_FALSE)
  204. }
  205. func _iCoreWebView2EnvironmentOptionsAdditionalBrowserArguments(this uintptr, value **uint16) uintptr {
  206. v := combridge.Resolve[iCoreWebView2EnvironmentOptions](this).AdditionalBrowserArguments()
  207. *value = stringToOleString(v)
  208. return uintptr(windows.S_OK)
  209. }
  210. func _iCoreWebView2EnvironmentOptionsLanguage(this uintptr, value **uint16) uintptr {
  211. args := combridge.Resolve[iCoreWebView2EnvironmentOptions](this).Language()
  212. *value = stringToOleString(args)
  213. return uintptr(windows.S_OK)
  214. }
  215. func _iCoreWebView2EnvironmentTargetCompatibleBrowserVersion(this uintptr, value **uint16) uintptr {
  216. args := combridge.Resolve[iCoreWebView2EnvironmentOptions](this).TargetCompatibleBrowserVersion()
  217. *value = stringToOleString(args)
  218. return uintptr(windows.S_OK)
  219. }
  220. func _iCoreWebView2EnvironmentOptionsAllowSingleSignOnUsingOSPrimaryAccount(this uintptr, value *int32) uintptr {
  221. v := combridge.Resolve[iCoreWebView2EnvironmentOptions](this).AllowSingleSignOnUsingOSPrimaryAccount()
  222. *value = boolToInt(v)
  223. return uintptr(windows.S_OK)
  224. }
  225. func _iCoreWebView2EnvironmentOptions2ExclusiveUserDataFolderAccess(this uintptr, value *int32) uintptr {
  226. v := combridge.Resolve[iCoreWebView2EnvironmentOptions2](this).ExclusiveUserDataFolderAccess()
  227. *value = boolToInt(v)
  228. return uintptr(windows.S_OK)
  229. }
  230. func stringToOleString(v string) *uint16 {
  231. wstr := utf16.Encode([]rune(v + "\x00"))
  232. lwstr := len(wstr)
  233. ptr := (*uint16)(coTaskMemAlloc(2 * lwstr))
  234. copy(unsafe.Slice(ptr, lwstr), wstr)
  235. return ptr
  236. }
  237. func boolToInt(v bool) int32 {
  238. if v {
  239. return 1
  240. }
  241. return 0
  242. }