Struct NSFileProviderDomain

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

Available on crate feature NSFileProviderDomain only.

File provider domain.

A file provider domain can be used to represent accounts or different locations exposed within a given file provider.

Domains can be registered to the system using -[NSFileProviderManangeraddDomain:completionHandler:]

By default, a file provider extension does not have any domain.

On the extension side, a separate instance of NSFileProviderExtension will be created for each NSFileProviderDomainregistered. In that case, the NSFileProviderExtension.domainproperties will indicate which domain the NSFileProviderExtension belongs to (or nil if none).

All the files on disk belonging to the same domain must be grouped inside a common directory. That directory path is indicated by the pathRelativeToDocumentStorageproperty.

See also Apple’s documentation

Implementations

impl NSFileProviderDomain

pub unsafe fn initWithIdentifier_displayName_pathRelativeToDocumentStorage( this: Allocated<Self>, identifier: &NSFileProviderDomainIdentifier, display_name: &NSString, path_relative_to_document_storage: &NSString, ) -> Retained<Self>

Initialize a new non-replicated NSFileProviderDomain

The extension will be implementing NSFileProviderExtension.

The file provider extension implementation can pick any identifieras it sees fit to identify the group of items. The identifier must not contain any characters from this set: [/:]

Parameter displayName: a user visible string representing the group of items the file provider extension is using.

Parameter pathRelativeToDocumentStorage: a path relative to NSFileProviderExtension.documentStorageURL.

pub unsafe fn initWithIdentifier_displayName( this: Allocated<Self>, identifier: &NSFileProviderDomainIdentifier, display_name: &NSString, ) -> Retained<Self>

Initialize a new replicated NSFileProviderDomain

The extension will be implementing NSFileProviderReplicatedExtension.

The file provider extension implementation can pick any identifieras it sees fit to identify the group of items. The identifier must not contain any characters from this set: [/:]

In order to migrate a non-replicated domain to a replicated one, implementers have to make sure that they do not use the default domain, and then call +[NSFileProviderManager addDomain:completionHandler:] using the NSFileProviderDomain object returned by that init method.

A domain with a specific identifier can be added multiple times; subsequent adds will update the properties of the existing domain. If a replicated domain is added “on top” of a non-replicated domain, the domain will be migrated to be replicated; existing bookmarks will remain valid, but the (externally visible) location of items will change to reflect the replicated location.

It is not possible to migrate the default domain in this manner (since the default domain can not be added). It is recommended to migrate usage of the default domain to a domain with an explicit identifier instead.

Parameter displayName: a user visible string representing the group of items the file provider extension is using.

pub unsafe fn initWithDisplayName_userInfo_volumeURL( this: Allocated<Self>, display_name: &NSString, user_info: &NSDictionary, volume_url: Option<&NSURL>, ) -> Retained<Self>

Initialize a new replicated NSFileProviderDomain on a specific volume.

If a volumeURL is specified, and that volume is eligible, the domain will be located on this volume. The URL is used to designate a volume but doesn’t influence where on this volume is the domain going to be stored.

In order to avoid domainID collisions between volumes, the NSFileProviderDomainIdentifier of external domains are generated randomly by FileProvider. The provider should therefore use the userInfo to associate all necessary information to map the created object to the corresponding account. The userInfo will be persisted on the volume where the domain was created. If that is an external volume, the userInfo can be used on other devices to assist in setting up the domain on those devices. See theNSFileProviderExternalVolumeHandling protocol for more details.

pub unsafe fn identifier(&self) -> Retained<NSFileProviderDomainIdentifier>

The identifier - as provided by the file provider extension.

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

The display name shown by the system to represent this domain.

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

The path relative to the document storage of the file provider extension. Files belonging to this domains should be stored under this path.

pub unsafe fn isDisconnected(&self) -> bool

If set, the domain is present, but disconnected from its extension. In this state, the user continues to be able to browse the domain’s contents, but the extension doesn’t receive updates on modifications to the files, nor is it consulted to update folder’s contents.

The disconnected state can be modified on an existing domain via the disconnectWithReason method on NSFileProviderManager.

pub unsafe fn userEnabled(&self) -> bool

If user has disabled this domain from Files.app on iOS or System Settings on macOS, this will be set to NO.

pub unsafe fn isHidden(&self) -> bool

If this domain is not user visible.

Typically, this can be used for dry-run migration. The files are still on disk though.

pub unsafe fn setHidden(&self, hidden: bool)

Setter for isHidden.

pub unsafe fn isReplicated(&self) -> bool

If the domain is a replicated domain.

If set to YES, it means the domain is replicated. By default, on macOS, the value will always be YES.

On iOS, it will depend on the way the NSFileProviderDomain object is contructed. Calling -[NSFileProviderDomain initWithIdentifier:displayName:] will initialize a replicated domain. -[NSFileProviderDomain initWithIdentifier:displayName:pathRelativeToDocumentStorage:] will initialize a non-replicated domain.

To know whether a domain is replicated or not, users are advised to rely on the output of +[NSFileProviderManager getDomainsForProviderIdentifier:completionHandler:]

pub unsafe fn testingModes(&self) -> NSFileProviderDomainTestingModes

Testing modes.

Testing modes are exposed as a means for the provider to have more control over the system in a testing environment. Enabling a testing mode alters the behavior of the system and enables some APIs for that mode.

A process must have the com.apple.developer.fileprovider.testing-mode entitlement in order to configure a domain with non-empty testing modes.

pub unsafe fn setTestingModes( &self, testing_modes: NSFileProviderDomainTestingModes, )

Setter for testingModes.

pub unsafe fn backingStoreIdentity(&self) -> Option<Retained<NSData>>

Identity of the backing store of the domain on the system.

This property only applies for extensions that implement NSFileProviderReplicatedExtension.

This provides an identifier that uniquely identifies the backing store used by the system for the domain. When this identifier has changed, the system has dropped its backing store and is building a new one.

The system may decide to rebuild its backing store if it got corrupted. The backing store can also be rebuilt as a response to the provider calling -[NSFileProviderManager reimportItemsBelowItemWithIdentifier:completionHandler:]. It is guaranteed that calling reimport on the root item will cause the backing store to be rebuilt, but the system can also decide to do so when reimport is called on other items.

When rebuilding the backing store, the system will invalidate any extension instance associated to that domain. As a consequence, the identity of the backing store associated with that domain is guaranteed to be stable for the lifetime of the NSFileProviderReplicatedExtension instance.

pub unsafe fn supportsSyncingTrash(&self) -> bool

Whether the domain supports syncing the trash.

The system supports syncing a trash folder (NSFileProviderTrashContainerItemIdentifier) to the extension. On iOS, this is surfaced to the user as “Recently Deleted” in the Files app. On macOS, this is surfaced to the user as the Trash in Finder.

If the domain is configured with supportsSyncingTrash=YES, the system will reparent trashed files (which were located in the extension’s domain) to NSFileProviderTrashContainerItemIdentifier. If the domain is configured with supportsSyncingTrash=NO, the system will decide how to handle the trashing operation (not guaranteed by API contract).

This property is only applicable for NSFileProviderReplicatedExtension-based domains.

This property defaults to YES.

pub unsafe fn setSupportsSyncingTrash(&self, supports_syncing_trash: bool)

Setter for supportsSyncingTrash.

pub unsafe fn volumeUUID(&self) -> Option<Retained<NSUUID>>

pub unsafe fn userInfo(&self) -> Option<Retained<NSDictionary>>

A dictionary set by the client app. Keys must be strings, values must be [String, Number, Date, Data]

pub unsafe fn setUserInfo(&self, user_info: Option<&NSDictionary>)

Setter for userInfo.

pub unsafe fn replicatedKnownFolders(&self) -> NSFileProviderKnownFolders

List of known folders that are currently replicated by this domain.

pub unsafe fn supportedKnownFolders(&self) -> NSFileProviderKnownFolders

List known folders that can be replicated by this domain.

pub unsafe fn setSupportedKnownFolders( &self, supported_known_folders: NSFileProviderKnownFolders, )

Setter for supportedKnownFolders.

impl NSFileProviderDomain

Methods declared on superclass NSObject.

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

pub unsafe fn new() -> Retained<Self>

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 NSFileProviderDomain

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSFileProviderDomain> for NSFileProviderDomain

fn as_ref(&self) -> &Self

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

impl AsRef<NSObject> for NSFileProviderDomain

fn as_ref(&self) -> &NSObject

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

impl Borrow<AnyObject> for NSFileProviderDomain

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for NSFileProviderDomain

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for NSFileProviderDomain

const NAME: &'static str = "NSFileProviderDomain"

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

type Super = NSObject

The superclass of this class.

type ThreadKind = <<NSFileProviderDomain as ClassType>::Super as ClassType>::ThreadKind

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 NSFileProviderDomain

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

Formats the value using the given formatter.

impl Deref for NSFileProviderDomain

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for NSFileProviderDomain

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 NSFileProviderDomain

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for NSFileProviderDomain

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 NSFileProviderDomain

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 NSFileProviderDomain

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

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

impl DowncastTarget for NSFileProviderDomain

impl Eq for NSFileProviderDomain