Struct WKWebExtension

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

Available on crate feature WKWebExtension only.

A WKWebExtension object encapsulates a web extension’s resources that are defined by a `manifest.json`` file.

This class handles the reading and parsing of the manifest file along with the supporting resources like icons and localizations.

See also Apple’s documentation

Implementations

impl WKWebExtension

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

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

pub unsafe fn extensionWithAppExtensionBundle_completionHandler( app_extension_bundle: &NSBundle, completion_handler: &DynBlock<dyn Fn(*mut WKWebExtension, *mut NSError)>, mtm: MainThreadMarker, )

Available on crate feature block2 only.

Returns a web extension initialized with a specified app extension bundle.

Parameter appExtensionBundle: The bundle to use for the new web extension.

Parameter completionHandler: A block to be called with an initialized web extension, or nilif the object could not be initialized due to an error.

The app extension bundle must contain a manifest.json file in its resources directory. If the manifest is invalid or missing, or the bundle is otherwise improperly configured, an error will be returned.

pub unsafe fn extensionWithResourceBaseURL_completionHandler( resource_base_url: &NSURL, completion_handler: &DynBlock<dyn Fn(*mut WKWebExtension, *mut NSError)>, mtm: MainThreadMarker, )

Available on crate feature block2 only.

Returns a web extension initialized with a specified resource base URL, which can point to either a directory or a ZIP archive.

Parameter resourceBaseURL: The file URL to use for the new web extension.

Parameter completionHandler: A block to be called with an initialized web extension, or nilif the object could not be initialized due to an error.

The URL must be a file URL that points to either a directory with a manifest.json file or a ZIP archive containing a manifest.json file. If the manifest is invalid or missing, or the URL points to an unsupported format or invalid archive, an error will be returned.

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

An array of all errors that occurred during the processing of the extension.

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

Note: Once the extension is loaded, use the errors property on an extension context to monitor any runtime errors, as they can occur after the extension is loaded.

pub unsafe fn manifest(&self) -> Retained<NSDictionary<NSString, AnyObject>>

The parsed manifest as a dictionary.

pub unsafe fn manifestVersion(&self) -> c_double

The parsed manifest version, or 0 if there is no version specified in the manifest.

Note: An WKWebExtensionErrorUnsupportedManifestVersion error will be reported if the manifest version isn’t specified.

pub unsafe fn supportsManifestVersion(&self, manifest_version: c_double) -> bool

Checks if a manifest version is supported by the extension.

Parameter manifestVersion: The version number to check.

Returns: Returns YES if the extension specified a manifest version that is greater than or equal to manifestVersion.

pub unsafe fn defaultLocale(&self) -> Option<Retained<NSLocale>>

The default locale for the extension. Returns nil if there was no default locale specified.

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

The localized extension name. Returns nil if there was no name specified.

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

The localized extension short name. Returns nil if there was no short name specified.

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

The localized extension display version. Returns nil if there was no display version specified.

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

The localized extension description. Returns nil if there was no description specified.

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

The default localized extension action label. Returns nil if there was no default action label specified.

This label serves as a default and should be used to represent the extension in contexts like action sheets or toolbars prior to the extension being loaded into an extension context. Once the extension is loaded, use the actionForTab: API to get the tab-specific label.

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

The extension version. Returns nil if there was no version specified.

pub unsafe fn iconForSize(&self, size: CGSize) -> Option<Retained<NSImage>>

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

pub unsafe fn actionIconForSize( &self, size: CGSize, ) -> Option<Retained<NSImage>>

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

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

Available on crate feature WKWebExtensionPermission only.

The set of permissions that the extension requires for its base functionality.

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

Available on crate feature WKWebExtensionPermission only.

The set of permissions that the extension may need for optional functionality. These permissions can be requested by the extension at a later time.

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

Available on crate feature WKWebExtensionMatchPattern only.

The set of websites that the extension requires access to for its base functionality.

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

Available on crate feature WKWebExtensionMatchPattern only.

The set of websites that the extension may need access to for optional functionality. These match patterns can be requested by the extension at a later time.

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

Available on crate feature WKWebExtensionMatchPattern only.

The set of websites that the extension requires access to for injected content and for receiving messages from websites.

pub unsafe fn hasBackgroundContent(&self) -> bool

A Boolean value indicating whether the extension has background content that can run when needed.

If this property is YES, the extension can run in the background even when no webpages are open.

pub unsafe fn hasPersistentBackgroundContent(&self) -> bool

A Boolean value indicating whether the extension has background content that stays in memory as long as the extension is loaded.

Note: Note that extensions are only allowed to have persistent background content on macOS. An WKWebExtensionErrorInvalidBackgroundPersistence error will be reported on iOS, iPadOS, and visionOS if an attempt is made to load a persistent extension.

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.

Note: Once the extension is loaded, use the hasInjectedContent property on an extension context, as the injectable content can change after the extension is loaded.

pub unsafe fn hasOptionsPage(&self) -> bool

A Boolean value indicating whether the extension has an options page.

If this property is YES, the extension includes a dedicated options page where users can customize settings. The app should provide access to this page through a user interface element, which can be accessed via optionsPageURL on an extension context.

pub unsafe fn hasOverrideNewTabPage(&self) -> bool

A Boolean value indicating whether the extension provides an alternative to the default new tab page.

If this property is YES, the extension can specify a custom page that can be displayed when a new tab is opened in the app, instead of the default new tab page. The app should prompt the user for permission to use the extension’s new tab page as the default, which can be accessed via overrideNewTabPageURL on an extension context.

pub unsafe fn hasCommands(&self) -> bool

A Boolean value indicating whether the extension includes commands that users can invoke.

If this property is YES, the extension contains one or more commands that can be performed by the user. These commands should be accessible via keyboard shortcuts, menu items, or other user interface elements provided by the app. The list of commands can be accessed via commands on an extension context, and invoked via performCommand:.

pub unsafe fn hasContentModificationRules(&self) -> bool

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

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 WKWebExtension

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for WKWebExtension

fn as_ref(&self) -> &NSObject

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

impl AsRef<WKWebExtension> for WKWebExtension

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for WKWebExtension

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for WKWebExtension

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for WKWebExtension

const NAME: &'static str = "WKWebExtension"

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 WKWebExtension

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

Formats the value using the given formatter.

impl Deref for WKWebExtension

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for WKWebExtension

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 WKWebExtension

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for WKWebExtension

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 WKWebExtension

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 WKWebExtension

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

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

impl DowncastTarget for WKWebExtension

impl Eq for WKWebExtension