Struct WKWebExtensionContext

#[repr(C)]
pub struct WKWebExtensionContext { /* private fields */ }

Available on crate feature WKWebExtensionContext only.

A WKWebExtensionContext object represents the runtime environment for a web extension.

This class provides methods for managing the extension’s permissions, allowing it to inject content, run background logic, show popovers, and display other web-based UI to the user.

See also Apple’s documentation

Implementations

impl WKWebExtensionContext

pub unsafe fn new(mtm: MainThreadMarker) -> Retained<Self>

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn contextForExtension(extension: &WKWebExtension) -> Retained<Self>

Available on crate feature WKWebExtension only.

Returns a web extension context initialized with the specified extension.

Parameter extension: The extension to use for the new web extension context.

Returns: An initialized web extension context.

pub unsafe fn initForExtension( this: Allocated<Self>, extension: &WKWebExtension, ) -> Retained<Self>

Available on crate feature WKWebExtension only.

Returns a web extension context initialized with a specified extension.

Parameter extension: The extension to use for the new web extension context.

Returns: An initialized web extension context.

This is a designated initializer.

pub unsafe fn webExtension(&self) -> Retained<WKWebExtension>

Available on crate feature WKWebExtension only.

The extension this context represents.

pub unsafe fn webExtensionController( &self, ) -> Option<Retained<WKWebExtensionController>>

Available on crate feature WKWebExtensionController only.

The extension controller this context is loaded in, otherwise nil if it isn’t loaded.

pub unsafe fn isLoaded(&self) -> bool

A Boolean value indicating if this context is loaded in an extension controller.

pub unsafe fn errors(&self) -> Retained<NSArray<NSError>>

All errors that occurred in the extension context.

Provides an array of all parse-time and runtime errors for the extension and extension context, with repeat errors consolidated into a single entry for the original occurrence. If no errors occurred, an empty array is returned.

pub unsafe fn baseURL(&self) -> Retained<NSURL>

The base URL the context uses for loading extension resources or injecting content into webpages.

The default value is a unique URL using the webkit-extension scheme. The base URL can be set to any URL, but only the scheme and host will be used. The scheme cannot be a scheme that is already supported by WKWebView (e.g. http, https, etc.) Setting is only allowed when the context is not loaded.

pub unsafe fn setBaseURL(&self, base_url: &NSURL)

Setter for baseURL.

pub unsafe fn uniqueIdentifier(&self) -> Retained<NSString>

A unique identifier used to distinguish the extension from other extensions and target it for messages.

The default value is a unique value that matches the host in the default base URL. The identifier can be any value that is unique. Setting is only allowed when the context is not loaded. This value is accessible by the extension via browser.runtime.id and is used for messaging the extension via browser.runtime.sendMessage().

pub unsafe fn setUniqueIdentifier(&self, unique_identifier: &NSString)

Setter for uniqueIdentifier.

pub unsafe fn isInspectable(&self) -> bool

Determines whether Web Inspector can inspect the WKWebView instances for this context.

A context can control multiple WKWebView instances, from the background content, to the popover. You should set this to YES when needed for debugging purposes. The default value is NO.

pub unsafe fn setInspectable(&self, inspectable: bool)

Setter for isInspectable.

pub unsafe fn inspectionName(&self) -> Option<Retained<NSString>>

The name shown when inspecting the background web view.

This is the text that will appear when inspecting the background web view.

pub unsafe fn setInspectionName(&self, inspection_name: Option<&NSString>)

Setter for inspectionName.

pub unsafe fn unsupportedAPIs(&self) -> Retained<NSSet<NSString>>

Specifies unsupported APIs for this extension, making them undefined in JavaScript.

This property allows the app to specify a subset of web extension APIs that it chooses not to support, effectively making these APIs undefined within the extension’s JavaScript contexts. This enables extensions to employ feature detection techniques for unsupported APIs, allowing them to adapt their behavior based on the APIs actually supported by the app. Setting is only allowed when the context is not loaded. Only certain APIs can be specified here, particularly those within the browser namespace and other dynamic functions and properties, anything else will be silently ignored.

Note: For example, specifying "browser.windows.create" and "browser.storage" in this set will result in the browser.windows.create() function and browser.storage property being undefined.

pub unsafe fn setUnsupportedAPIs( &self, unsupported_ap_is: Option<&NSSet<NSString>>, )

Setter for unsupportedAPIs.

pub unsafe fn webViewConfiguration( &self, ) -> Option<Retained<WKWebViewConfiguration>>

Available on crate feature WKWebViewConfiguration only.

The web view configuration to use for web views that load pages from this extension.

Returns a customized copy of the configuration, originally set in the web extension controller configuration, for this extension. The app must use this configuration when initializing web views intended to navigate to a URL originating from this extension’s base URL. The app must also swap web views in tabs when navigating to and from web extension URLs. This property returns nil if the context isn’t associated with a web extension controller. The returned configuration copy can be customized prior to web view initialization.

Note: Navigations will fail if a web view using this configuration attempts to navigate to a URL that doesn’t originate from this extension’s base URL. Similarly, navigations will be canceled if a web view not configured with this configuration attempts to navigate to a URL that does originate from this extension’s base URL.

pub unsafe fn optionsPageURL(&self) -> Option<Retained<NSURL>>

The URL of the extension’s options page, if the extension has one.

Provides the URL for the dedicated options page, if provided by the extension; otherwise nil if no page is defined. The app should provide access to this page through a user interface element.

Note: Navigation to the options page is only possible after this extension has been loaded.

See also: webViewConfiguration

pub unsafe fn overrideNewTabPageURL(&self) -> Option<Retained<NSURL>>

The URL to use as an alternative to the default new tab page, if the extension has one.

Provides the URL for a new tab page, if provided by the extension; otherwise nil if no page is defined. The app should prompt the user for permission to use the extension’s new tab page as the default.

Note: Navigation to the override new tab page is only possible after this extension has been loaded.

See also: webViewConfiguration

pub unsafe fn grantedPermissions( &self, ) -> Retained<NSDictionary<WKWebExtensionPermission, NSDate>>

Available on crate feature WKWebExtensionPermission only.

The currently granted permissions and their expiration dates.

Permissions that don’t expire will have a distant future date. This will never include expired entries at time of access. Setting this property will replace all existing entries. Use this property for saving and restoring permission status in bulk. Permissions in this dictionary should be explicitly granted by the user before being added. Any permissions in this collection will not be presented for approval again until they expire. This value should be saved and restored as needed by the app.

See also: setPermissionStatus:forPermission:

See also: setPermissionStatus:forPermission:expirationDate:

pub unsafe fn setGrantedPermissions( &self, granted_permissions: &NSDictionary<WKWebExtensionPermission, NSDate>, )

Available on crate feature WKWebExtensionPermission only.

Setter for grantedPermissions.

pub unsafe fn grantedPermissionMatchPatterns( &self, ) -> Retained<NSDictionary<WKWebExtensionMatchPattern, NSDate>>

Available on crate feature WKWebExtensionMatchPattern only.

The currently granted permission match patterns and their expiration dates.

Match patterns that don’t expire will have a distant future date. This will never include expired entries at time of access. Setting this property will replace all existing entries. Use this property for saving and restoring permission status in bulk. Match patterns in this dictionary should be explicitly granted by the user before being added. Any match pattern in this collection will not be presented for approval again until they expire. This value should be saved and restored as needed by the app.

See also: setPermissionStatus:forMatchPattern:

See also: setPermissionStatus:forMatchPattern:expirationDate:

pub unsafe fn setGrantedPermissionMatchPatterns( &self, granted_permission_match_patterns: &NSDictionary<WKWebExtensionMatchPattern, NSDate>, )

Available on crate feature WKWebExtensionMatchPattern only.

Setter for grantedPermissionMatchPatterns.

pub unsafe fn deniedPermissions( &self, ) -> Retained<NSDictionary<WKWebExtensionPermission, NSDate>>

Available on crate feature WKWebExtensionPermission only.

The currently denied permissions and their expiration dates.

Permissions that don’t expire will have a distant future date. This will never include expired entries at time of access. Setting this property will replace all existing entries. Use this property for saving and restoring permission status in bulk. Permissions in this dictionary should be explicitly denied by the user before being added. Any match pattern in this collection will not be presented for approval again until they expire. This value should be saved and restored as needed by the app.

See also: setPermissionStatus:forPermission:

See also: setPermissionStatus:forPermission:expirationDate:

pub unsafe fn setDeniedPermissions( &self, denied_permissions: &NSDictionary<WKWebExtensionPermission, NSDate>, )

Available on crate feature WKWebExtensionPermission only.

Setter for deniedPermissions.

pub unsafe fn deniedPermissionMatchPatterns( &self, ) -> Retained<NSDictionary<WKWebExtensionMatchPattern, NSDate>>

Available on crate feature WKWebExtensionMatchPattern only.

The currently denied permission match patterns and their expiration dates.

Match patterns that don’t expire will have a distant future date. This will never include expired entries at time of access. Setting this property will replace all existing entries. Use this property for saving and restoring permission status in bulk. Match patterns in this dictionary should be explicitly denied by the user before being added. Any match pattern in this collection will not be presented for approval again until they expire. This value should be saved and restored as needed by the app.

See also: setPermissionStatus:forMatchPattern:

See also: setPermissionStatus:forMatchPattern:expirationDate:

pub unsafe fn setDeniedPermissionMatchPatterns( &self, denied_permission_match_patterns: &NSDictionary<WKWebExtensionMatchPattern, NSDate>, )

Available on crate feature WKWebExtensionMatchPattern only.

Setter for deniedPermissionMatchPatterns.

pub unsafe fn hasRequestedOptionalAccessToAllHosts(&self) -> bool

A Boolean value indicating if the extension has requested optional access to all hosts.

If this property is YES, the extension has asked for access to all hosts in a call to browser.runtime.permissions.request(), and future permission checks will present discrete hosts for approval as being implicitly requested. This value should be saved and restored as needed by the app.

pub unsafe fn setHasRequestedOptionalAccessToAllHosts( &self, has_requested_optional_access_to_all_hosts: bool, )

Setter for hasRequestedOptionalAccessToAllHosts.

pub unsafe fn hasAccessToPrivateData(&self) -> bool

A Boolean value indicating if the extension has access to private data.

If this property is YES, the extension is granted permission to interact with private windows, tabs, and cookies. Access to private data should be explicitly allowed by the user before setting this property. This value should be saved and restored as needed by the app.

Note: To ensure proper isolation between private and non-private data, web views associated with private data must use a different WKUserContentController. Likewise, to be identified as a private web view and to ensure that cookies and other website data is not shared, private web views must be configured to use a non-persistent WKWebsiteDataStore.

pub unsafe fn setHasAccessToPrivateData(&self, has_access_to_private_data: bool)

Setter for hasAccessToPrivateData.

pub unsafe fn currentPermissions( &self, ) -> Retained<NSSet<WKWebExtensionPermission>>

Available on crate feature WKWebExtensionPermission only.

The currently granted permissions that have not expired.

See also: grantedPermissions

pub unsafe fn currentPermissionMatchPatterns( &self, ) -> Retained<NSSet<WKWebExtensionMatchPattern>>

Available on crate feature WKWebExtensionMatchPattern only.

The currently granted permission match patterns that have not expired.

See also: grantedPermissionMatchPatterns

pub unsafe fn hasPermission( &self, permission: &WKWebExtensionPermission, ) -> bool

Available on crate feature WKWebExtensionPermission only.

Checks the specified permission against the currently granted permissions.

Parameter permission: The permission for which to return the status.

See also: currentPermissions

See also: hasPermission:inTab:

See also: permissionStatusForPermission:

See also: permissionStatusForPermission:inTab:

pub unsafe fn hasPermission_inTab( &self, permission: &WKWebExtensionPermission, tab: Option<&ProtocolObject<dyn WKWebExtensionTab>>, ) -> bool

Available on crate features WKWebExtensionPermission and WKWebExtensionTab only.

Checks the specified permission against the currently granted permissions in a specific tab.

Parameter permission: The permission for which to return the status.

Parameter tab: The tab in which to return the permission status, or nilif the tab is not known or the global status is desired.

Permissions can be granted on a per-tab basis. When the tab is known, permission checks should always use this method.

See also: currentPermissions

See also: hasPermission:

See also: permissionStatusForPermission:

See also: permissionStatusForPermission:inTab:

pub unsafe fn hasAccessToURL(&self, url: &NSURL) -> bool

Checks the specified URL against the currently granted permission match patterns.

Parameter url: The URL for which to return the status.

See also: currentPermissionMatchPatterns

See also: hasAccessToURL:inTab:

See also: permissionStatusForURL:

See also: permissionStatusForURL:inTab:

See also: permissionStatusForMatchPattern:

See also: permissionStatusForMatchPattern:inTab:

pub unsafe fn hasAccessToURL_inTab( &self, url: &NSURL, tab: Option<&ProtocolObject<dyn WKWebExtensionTab>>, ) -> bool

Available on crate feature WKWebExtensionTab only.

Checks the specified URL against the currently granted permission match patterns in a specific tab.

Parameter url: The URL for which to return the status.

Parameter tab: The tab in which to return the permission status, or nilif the tab is not known or the global status is desired.

Some match patterns can be granted on a per-tab basis. When the tab is known, access checks should always use this method.

See also: currentPermissionMatchPatterns

See also: hasAccessToURL:

See also: permissionStatusForURL:

See also: permissionStatusForURL:inTab:

See also: permissionStatusForMatchPattern:

See also: permissionStatusForMatchPattern:inTab:

pub unsafe fn hasAccessToAllURLs(&self) -> bool

A Boolean value indicating if the currently granted permission match patterns set contains the <all _urls> pattern.

This does not check for any * host patterns. In most cases you should use the broader hasAccessToAllHosts.

See also: currentPermissionMatchPatterns

See also: hasAccessToAllHosts

pub unsafe fn hasAccessToAllHosts(&self) -> bool

A Boolean value indicating if the currently granted permission match patterns set contains the <all _urls> pattern or any * host patterns.

See also: currentPermissionMatchPatterns

See also: hasAccessToAllURLs

pub unsafe fn hasInjectedContent(&self) -> bool

A Boolean value indicating whether the extension has script or stylesheet content that can be injected into webpages.

If this property is YES, the extension has content that can be injected by matching against the extension’s requested match patterns.

See also: hasInjectedContentForURL:

pub unsafe fn hasInjectedContentForURL(&self, url: &NSURL) -> bool

Checks if the extension has script or stylesheet content that can be injected into the specified URL.

Parameter url: The webpage URL to check.

Returns: Returns YES if the extension has content that can be injected by matching the URL against the extension’s requested match patterns.

The extension context will still need to be loaded and have granted website permissions for its content to actually be injected.

pub unsafe fn hasContentModificationRules(&self) -> bool

A boolean value indicating whether the extension includes rules used for content modification or blocking.

This includes both static rules available in the extension’s manifest and dynamic rules applied during a browsing session.

pub unsafe fn permissionStatusForPermission( &self, permission: &WKWebExtensionPermission, ) -> WKWebExtensionContextPermissionStatus

Available on crate feature WKWebExtensionPermission only.

Checks the specified permission against the currently denied, granted, and requested permissions.

Parameter permission: The permission for which to return the status.

Permissions can be granted on a per-tab basis. When the tab is known, access checks should always use the method that checks in a tab.

See also: permissionStatusForPermission:inTab:

See also: hasPermission:

pub unsafe fn permissionStatusForPermission_inTab( &self, permission: &WKWebExtensionPermission, tab: Option<&ProtocolObject<dyn WKWebExtensionTab>>, ) -> WKWebExtensionContextPermissionStatus

Available on crate features WKWebExtensionPermission and WKWebExtensionTab only.

Checks the specified permission against the currently denied, granted, and requested permissions.

Parameter permission: The permission for which to return the status.

Parameter tab: The tab in which to return the permission status, or nilif the tab is not known or the global status is desired.

Permissions can be granted on a per-tab basis. When the tab is known, access checks should always specify the tab.

See also: permissionStatusForPermission:

See also: hasPermission:inTab:

pub unsafe fn setPermissionStatus_forPermission( &self, status: WKWebExtensionContextPermissionStatus, permission: &WKWebExtensionPermission, )

Available on crate feature WKWebExtensionPermission only.

Sets the status of a permission with a distant future expiration date.

Parameter status: The new permission status to set for the given permission.

Parameter permission: The permission for which to set the status.

This method will update grantedPermissions and deniedPermissions. Use this method for changing a single permission’s status. Only WKWebExtensionContextPermissionStatusDeniedExplicitly, WKWebExtensionContextPermissionStatusUnknown, and WKWebExtensionContextPermissionStatusGrantedExplicitly states are allowed to be set using this method.

See also: setPermissionStatus:forPermission:expirationDate:

See also: setPermissionStatus:forPermission:inTab:

pub unsafe fn setPermissionStatus_forPermission_expirationDate( &self, status: WKWebExtensionContextPermissionStatus, permission: &WKWebExtensionPermission, expiration_date: Option<&NSDate>, )

Available on crate feature WKWebExtensionPermission only.

Sets the status of a permission with a specific expiration date.

Parameter status: The new permission status to set for the given permission.

Parameter permission: The permission for which to set the status.

Parameter expirationDate: The expiration date for the new permission status, or nilfor distant future.

This method will update grantedPermissions and deniedPermissions. Use this method for changing a single permission’s status. Passing a nil expiration date will be treated as a distant future date. Only WKWebExtensionContextPermissionStatusDeniedExplicitly, WKWebExtensionContextPermissionStatusUnknown, and WKWebExtensionContextPermissionStatusGrantedExplicitly states are allowed to be set using this method.

See also: setPermissionStatus:forPermission:

See also: setPermissionStatus:forPermission:inTab:

pub unsafe fn permissionStatusForURL( &self, url: &NSURL, ) -> WKWebExtensionContextPermissionStatus

Checks the specified URL against the currently denied, granted, and requested permission match patterns.

Parameter url: The URL for which to return the status.

URLs and match patterns can be granted on a per-tab basis. When the tab is known, access checks should always use the method that checks in a tab.

See also: permissionStatusForURL:inTab:

See also: hasAccessToURL:

pub unsafe fn permissionStatusForURL_inTab( &self, url: &NSURL, tab: Option<&ProtocolObject<dyn WKWebExtensionTab>>, ) -> WKWebExtensionContextPermissionStatus

Available on crate feature WKWebExtensionTab only.

Checks the specified URL against the currently denied, granted, and requested permission match patterns.

Parameter url: The URL for which to return the status.

Parameter tab: The tab in which to return the permission status, or nilif the tab is not known or the global status is desired.

URLs and match patterns can be granted on a per-tab basis. When the tab is known, access checks should always use this method.

See also: permissionStatusForURL:

See also: hasAccessToURL:inTab:

pub unsafe fn setPermissionStatus_forURL( &self, status: WKWebExtensionContextPermissionStatus, url: &NSURL, )

Sets the permission status of a URL with a distant future expiration date.

Parameter status: The new permission status to set for the given URL.

Parameter url: The URL for which to set the status.

The URL is converted into a match pattern and will update grantedPermissionMatchPatterns and deniedPermissionMatchPatterns. Use this method for changing a single URL’s status. Only WKWebExtensionContextPermissionStatusDeniedExplicitly, WKWebExtensionContextPermissionStatusUnknown, and WKWebExtensionContextPermissionStatusGrantedExplicitly states are allowed to be set using this method.

See also: setPermissionStatus:forURL:expirationDate:

See also: setPermissionStatus:forURL:inTab:

pub unsafe fn setPermissionStatus_forURL_expirationDate( &self, status: WKWebExtensionContextPermissionStatus, url: &NSURL, expiration_date: Option<&NSDate>, )

Sets the permission status of a URL with a distant future expiration date.

Parameter status: The new permission status to set for the given URL.

Parameter url: The URL for which to set the status.

Parameter expirationDate: The expiration date for the new permission status, or nilfor distant future.

The URL is converted into a match pattern and will update grantedPermissionMatchPatterns and deniedPermissionMatchPatterns. Use this method for changing a single URL’s status. Passing a nil expiration date will be treated as a distant future date. Only WKWebExtensionContextPermissionStatusDeniedExplicitly, WKWebExtensionContextPermissionStatusUnknown, and WKWebExtensionContextPermissionStatusGrantedExplicitly states are allowed to be set using this method.

See also: setPermissionStatus:forURL:

See also: setPermissionStatus:forURL:inTab:

pub unsafe fn permissionStatusForMatchPattern( &self, pattern: &WKWebExtensionMatchPattern, ) -> WKWebExtensionContextPermissionStatus

Available on crate feature WKWebExtensionMatchPattern only.

Checks the specified match pattern against the currently denied, granted, and requested permission match patterns.

Parameter pattern: The pattern for which to return the status.

Match patterns can be granted on a per-tab basis. When the tab is known, access checks should always use the method that checks in a tab.

See also: permissionStatusForMatchPattern:inTab:

See also: hasAccessToURL:inTab:

pub unsafe fn permissionStatusForMatchPattern_inTab( &self, pattern: &WKWebExtensionMatchPattern, tab: Option<&ProtocolObject<dyn WKWebExtensionTab>>, ) -> WKWebExtensionContextPermissionStatus

Available on crate features WKWebExtensionMatchPattern and WKWebExtensionTab only.

Checks the specified match pattern against the currently denied, granted, and requested permission match patterns.

Parameter pattern: The pattern for which to return the status.

Parameter tab: The tab in which to return the permission status, or nilif the tab is not known or the global status is desired.

Match patterns can be granted on a per-tab basis. When the tab is known, access checks should always use this method.

See also: permissionStatusForMatchPattern:

See also: hasAccessToURL:inTab:

pub unsafe fn setPermissionStatus_forMatchPattern( &self, status: WKWebExtensionContextPermissionStatus, pattern: &WKWebExtensionMatchPattern, )

Available on crate feature WKWebExtensionMatchPattern only.

Sets the status of a match pattern with a distant future expiration date.

Parameter status: The new permission status to set for the given match pattern.

Parameter pattern: The match pattern for which to set the status.

This method will update grantedPermissionMatchPatterns and deniedPermissionMatchPatterns. Use this method for changing a single match pattern’s status. Only WKWebExtensionContextPermissionStatusDeniedExplicitly, WKWebExtensionContextPermissionStatusUnknown, and WKWebExtensionContextPermissionStatusGrantedExplicitly states are allowed to be set using this method.

See also: setPermissionStatus:forMatchPattern:expirationDate:

See also: setPermissionStatus:forMatchPattern:inTab:

pub unsafe fn setPermissionStatus_forMatchPattern_expirationDate( &self, status: WKWebExtensionContextPermissionStatus, pattern: &WKWebExtensionMatchPattern, expiration_date: Option<&NSDate>, )

Available on crate feature WKWebExtensionMatchPattern only.

Sets the status of a match pattern with a specific expiration date.

Parameter status: The new permission status to set for the given match pattern.

Parameter pattern: The match pattern for which to set the status.

Parameter expirationDate: The expiration date for the new permission status, or nilfor distant future.

This method will update grantedPermissionMatchPatterns and deniedPermissionMatchPatterns. Use this method for changing a single match pattern’s status. Passing a nil expiration date will be treated as a distant future date. Only WKWebExtensionContextPermissionStatusDeniedExplicitly, WKWebExtensionContextPermissionStatusUnknown, and WKWebExtensionContextPermissionStatusGrantedExplicitly states are allowed to be set using this method.

See also: setPermissionStatus:forMatchPattern:

See also: setPermissionStatus:forMatchPattern:inTab:

pub unsafe fn loadBackgroundContentWithCompletionHandler( &self, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

Loads the background content if needed for the extension.

Parameter completionHandler: A block to be called upon completion of the loading process, with an optional error.

This method forces the loading of the background content for the extension that will otherwise be loaded on-demand during specific events. It is useful when the app requires the background content to be loaded for other reasons. If the background content is already loaded, the completion handler will be called immediately. An error will occur if the extension does not have any background content to load or loading fails.

pub unsafe fn actionForTab( &self, tab: Option<&ProtocolObject<dyn WKWebExtensionTab>>, ) -> Option<Retained<WKWebExtensionAction>>

Available on crate features WKWebExtensionAction and WKWebExtensionTab only.

Retrieves the extension action for a given tab, or the default action if nil is passed.

Parameter tab: The tab for which to retrieve the extension action, or nil to get the default action.

The returned object represents the action specific to the tab when provided; otherwise, it returns the default action. The default action is useful when the context is unrelated to a specific tab. When possible, specify the tab to get the most context-relevant action.

See also: performActionForTab:

pub unsafe fn performActionForTab( &self, tab: Option<&ProtocolObject<dyn WKWebExtensionTab>>, )

Available on crate feature WKWebExtensionTab only.

Performs the extension action associated with the specified tab or performs the default action if nil is passed.

Parameter tab: The tab for which to perform the extension action, or nil to perform the default action.

Performing the action will mark the tab, if specified, as having an active user gesture. When the tab parameter is nil, the default action is performed. The action can either trigger an event or display a popup, depending on how the extension is configured. If the action is configured to display a popup, implementing the appropriate web extension controller delegate method is required; otherwise, no action is performed for popup actions.

pub unsafe fn commands(&self) -> Retained<NSArray<WKWebExtensionCommand>>

Available on crate feature WKWebExtensionCommand only.

The commands associated with the extension.

Provides all commands registered within the extension. Each command represents an action or behavior available for the web extension.

See also: performCommand:

pub unsafe fn performCommand(&self, command: &WKWebExtensionCommand)

Available on crate feature WKWebExtensionCommand only.

Performs the specified command, triggering events specific to this extension.

Parameter command: The command to be performed.

This method performs the given command as if it was triggered by a user gesture within the context of the focused window and active tab.

pub unsafe fn performCommandForEvent(&self, event: &NSEvent) -> bool

Available on crate feature objc2-app-kit and macOS only.

Performs the command associated with the given event.

This method checks for a command corresponding to the provided event and performs it, if available. The app should use this method to perform any extension commands at an appropriate time in the app’s event handling, like in sendEvent: of NSApplication or NSWindow subclasses.

Parameter event: The event representing the user input.

Returns: Returns YES if a command corresponding to the event was found and performed, NO otherwise.

pub unsafe fn commandForEvent( &self, event: &NSEvent, ) -> Option<Retained<WKWebExtensionCommand>>

Available on crate feature WKWebExtensionCommand and crate feature objc2-app-kit and macOS only.

Retrieves the command associated with the given event without performing it.

Returns the command that corresponds to the provided event, if such a command exists. This provides a way to programmatically determine what action would occur for a given event, without triggering the command.

Parameter event: The event for which to retrieve the corresponding command.

Returns: The command associated with the event, or nil if there is no such command.

pub unsafe fn menuItemsForTab( &self, tab: &ProtocolObject<dyn WKWebExtensionTab>, ) -> Retained<NSArray<NSMenuItem>>

Available on crate feature WKWebExtensionTab and crate feature objc2-app-kit and macOS only.

pub unsafe fn userGesturePerformedInTab( &self, tab: &ProtocolObject<dyn WKWebExtensionTab>, )

Available on crate feature WKWebExtensionTab only.

Should be called by the app when a user gesture is performed in a specific tab.

Parameter tab: The tab in which the user gesture was performed.

When a user gesture is performed in a tab, this method should be called to update the extension context. This enables the extension to be aware of the user gesture, potentially granting it access to features that require user interaction, such as activeTab. Not required if using performActionForTab:.

See also: hasActiveUserGestureInTab:

pub unsafe fn hasActiveUserGestureInTab( &self, tab: &ProtocolObject<dyn WKWebExtensionTab>, ) -> bool

Available on crate feature WKWebExtensionTab only.

Indicates if a user gesture is currently active in the specified tab.

Parameter tab: The tab for which to check for an active user gesture.

An active user gesture may influence the availability of certain permissions, such as activeTab. User gestures can be triggered by various user interactions with the web extension, including clicking on extension menu items, executing extension commands, or interacting with extension actions. A tab as having an active user gesture enables the extension to access features that require user interaction.

See also: userGesturePerformedInTab:

pub unsafe fn clearUserGestureInTab( &self, tab: &ProtocolObject<dyn WKWebExtensionTab>, )

Available on crate feature WKWebExtensionTab only.

Should be called by the app to clear a user gesture in a specific tab.

Parameter tab: The tab from which the user gesture should be cleared.

When a user gesture is no longer relevant in a tab, this method should be called to update the extension context. This will revoke the extension’s access to features that require active user interaction, such as activeTab. User gestures are automatically cleared during navigation in certain scenarios; this method is needed if the app intends to clear the gesture more aggressively.

See also: userGesturePerformedInTab:

pub unsafe fn openWindows( &self, ) -> Retained<NSArray<ProtocolObject<dyn WKWebExtensionWindow>>>

Available on crate feature WKWebExtensionWindow only.

The open windows that are exposed to this extension.

Provides the windows that are open and visible to the extension, as updated by the didOpenWindow: and didCloseWindow: methods. Initially populated by the windows returned by the extension controller delegate method webExtensionController:openWindowsForExtensionContext:.

See also: didOpenWindow:

See also: didCloseWindow:

pub unsafe fn focusedWindow( &self, ) -> Option<Retained<ProtocolObject<dyn WKWebExtensionWindow>>>

Available on crate feature WKWebExtensionWindow only.

The window that currently has focus for this extension.

Provides the window that currently has focus, as set by the didFocusWindow: method. It will be nil if no window has focus or if a window has focus that is not visible to the extension. Initially populated by the window returned by the extension controller delegate method webExtensionController:focusedWindowForExtensionContext:.

See also: didFocusWindow:

pub unsafe fn openTabs( &self, ) -> Retained<NSSet<ProtocolObject<dyn WKWebExtensionTab>>>

Available on crate feature WKWebExtensionTab only.

A set of open tabs in all open windows that are exposed to this extension.

Provides a set of tabs in all open windows that are visible to the extension, as updated by the didOpenTab: and didCloseTab: methods. Initially populated by the tabs in the windows returned by the extension controller delegate method webExtensionController:openWindowsForExtensionContext:.

See also: didOpenTab:

See also: didCloseTab:

pub unsafe fn didOpenWindow( &self, new_window: &ProtocolObject<dyn WKWebExtensionWindow>, )

Available on crate feature WKWebExtensionWindow only.

Should be called by the app when a new window is opened to fire appropriate events with only this extension.

Parameter newWindow: The newly opened window.

This method informs only the specific extension of the opening of a new window. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

See also: didCloseWindow:

See also: openWindows

pub unsafe fn didCloseWindow( &self, closed_window: &ProtocolObject<dyn WKWebExtensionWindow>, )

Available on crate feature WKWebExtensionWindow only.

Should be called by the app when a window is closed to fire appropriate events with only this extension.

Parameter newWindow: The window that was closed.

This method informs only the specific extension of the closure of a window. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

See also: didOpenWindow:

See also: openWindows

pub unsafe fn didFocusWindow( &self, focused_window: Option<&ProtocolObject<dyn WKWebExtensionWindow>>, )

Available on crate feature WKWebExtensionWindow only.

Should be called by the app when a window gains focus to fire appropriate events with only this extension.

Parameter focusedWindow: The window that gained focus, or nilif no window has focus or a window has focus that is not visible to this extension.

This method informs only the specific extension that a window has gained focus. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

pub unsafe fn didOpenTab(&self, new_tab: &ProtocolObject<dyn WKWebExtensionTab>)

Available on crate feature WKWebExtensionTab only.

Should be called by the app when a new tab is opened to fire appropriate events with only this extension.

Parameter newTab: The newly opened tab.

This method informs only the specific extension of the opening of a new tab. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

See also: didCloseTab:

See also: openTabs

pub unsafe fn didCloseTab_windowIsClosing( &self, closed_tab: &ProtocolObject<dyn WKWebExtensionTab>, window_is_closing: bool, )

Available on crate feature WKWebExtensionTab only.

Should be called by the app when a tab is closed to fire appropriate events with only this extension.

Parameter closedTab: The tab that was closed.

Parameter windowIsClosing: A boolean value indicating whether the window containing the tab is also closing.

This method informs only the specific extension of the closure of a tab. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

See also: didOpenTab:

See also: openTabs

pub unsafe fn didActivateTab_previousActiveTab( &self, activated_tab: &ProtocolObject<dyn WKWebExtensionTab>, previous_tab: Option<&ProtocolObject<dyn WKWebExtensionTab>>, )

Available on crate feature WKWebExtensionTab only.

Should be called by the app when a tab is activated to notify only this specific extension.

Parameter activatedTab: The tab that has become active.

Parameter previousTab: The tab that was active before. This parameter can be nilif there was no previously active tab.

This method informs only the specific extension of the tab activation. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

pub unsafe fn didSelectTabs( &self, selected_tabs: &NSArray<ProtocolObject<dyn WKWebExtensionTab>>, )

Available on crate feature WKWebExtensionTab only.

Should be called by the app when tabs are selected to fire appropriate events with only this extension.

Parameter selectedTabs: The set of tabs that were selected.

This method informs only the specific extension that tabs have been selected. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

pub unsafe fn didDeselectTabs( &self, deselected_tabs: &NSArray<ProtocolObject<dyn WKWebExtensionTab>>, )

Available on crate feature WKWebExtensionTab only.

Should be called by the app when tabs are deselected to fire appropriate events with only this extension.

Parameter deselectedTabs: The set of tabs that were deselected.

This method informs only the specific extension that tabs have been deselected. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

pub unsafe fn didMoveTab_fromIndex_inWindow( &self, moved_tab: &ProtocolObject<dyn WKWebExtensionTab>, index: NSUInteger, old_window: Option<&ProtocolObject<dyn WKWebExtensionWindow>>, )

Available on crate features WKWebExtensionTab and WKWebExtensionWindow only.

Should be called by the app when a tab is moved to fire appropriate events with only this extension.

Parameter movedTab: The tab that was moved.

Parameter index: The old index of the tab within the window.

Parameter oldWindow: The window that the tab was moved from, or nilif the tab is moving from no open window.

If the window is staying the same, the current window should be specified. This method informs only the specific extension that a tab has been moved. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

pub unsafe fn didReplaceTab_withTab( &self, old_tab: &ProtocolObject<dyn WKWebExtensionTab>, new_tab: &ProtocolObject<dyn WKWebExtensionTab>, )

Available on crate feature WKWebExtensionTab only.

Should be called by the app when a tab is replaced by another tab to fire appropriate events with only this extension.

Parameter oldTab: The tab that was replaced.

Parameter newTab: The tab that replaced the old tab.

This method informs only the specific extension that a tab has been replaced. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

pub unsafe fn didChangeTabProperties_forTab( &self, properties: WKWebExtensionTabChangedProperties, changed_tab: &ProtocolObject<dyn WKWebExtensionTab>, )

Available on crate feature WKWebExtensionTab only.

Should be called by the app when the properties of a tab are changed to fire appropriate events with only this extension.

Parameter properties: The properties of the tab that were changed.

Parameter changedTab: The tab whose properties were changed.

This method informs only the specific extension of the changes to a tab’s properties. If the intention is to inform all loaded extensions consistently, you should use the respective method on the extension controller instead.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for WKWebExtensionContext

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for WKWebExtensionContext

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<WKWebExtensionContext> for WKWebExtensionContext

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for WKWebExtensionContext

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for WKWebExtensionContext

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for WKWebExtensionContext

const NAME: &'static str = "WKWebExtensionContext"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = dyn MainThreadOnly

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for WKWebExtensionContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for WKWebExtensionContext

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for WKWebExtensionContext

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for WKWebExtensionContext

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for WKWebExtensionContext

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for WKWebExtensionContext

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for WKWebExtensionContext

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for WKWebExtensionContext

impl Eq for WKWebExtensionContext