Struct CNContactStore

Source

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

Available on crate feature CNContactStore only.

Expand description

Provides methods to fetch and save contacts.

The CNContactStore is a thread safe class that can fetch and save contacts, fetch and save groups, and fetch containers.

Note: Some good practices are:

Only fetch contact properties that will be used.
When fetching all contacts and caching the results, first fetch all contact identifiers only. Then fetch batches of detailed contacts by identifiers as you need them.
To aggregate several contact fetches collect a set of unique contact identifiers from the fetches. Then fetch batches of detailed contacts by identifiers.
When CNContactStoreDidChangeNotification is posted, if you cache any fetched contacts/groups/containers then they must be refetched and the old cached objects released.

Implementations§

Source §

impl CNContactStore

Source

pub unsafe fn authorizationStatusForEntityType( entity_type: CNEntityType, ) -> CNAuthorizationStatus

Indicates the current authorization status to access contact data.

Based upon the access, the application could display or hide its UI elements that would access any Contacts API. This method is thread safe.

Returns: Returns the authorization status for the given entityType.

Source

pub unsafe fn requestAccessForEntityType_completionHandler( &self, entity_type: CNEntityType, completion_handler: &DynBlock<dyn Fn(Bool, *mut NSError)>, )

Available on crate feature block2 only.

Request access to the user’s contacts.

Users are able to grant or deny access to contact data on a per-application basis. To request access to contact data, call requestAccessForEntityType:completionHandler:. This will not block the application while the user is being asked to grant or deny access. The user will only be prompted the first time access is requested; any subsequent CNContactStore calls will use the existing permissions. The completion handler is called on an arbitrary queue.

Note: Recommended to use CNContactStore instance methods in this completion handler instead of the UI main thread. This method is optional when CNContactStore is used on a background thread. If it is not used in that case, CNContactStore will block if the user is asked to grant or deny access.

Parameter entityType: Set to CNEntityTypeContacts.

Parameter completionHandler: This block is called upon completion. If the user grants access then granted is YES and error is nil. Otherwise granted is NO with an error.

Source

pub unsafe fn unifiedContactsMatchingPredicate_keysToFetch_error( &self, predicate: &NSPredicate, keys: &NSArray<ProtocolObject<dyn CNKeyDescriptor>>, ) -> Result<Retained<NSArray<CNContact>>, Retained<NSError>>

Available on crate feature CNContact only.

Fetch all unified contacts matching a given predicate.

Use only predicates from CNContact+Predicates.h. Compound predicates are not supported. Due to unification the returned contacts may have a different identifier.

Note: To fetch all contacts use enumerateContactsWithFetchRequest:error:usingBlock:.

Parameter predicate: The predicate to match against.

Parameter keys: The properties to fetch into the returned CNContact objects. Should only fetch the properties that will be used. Can combine contact keys and contact key descriptors.

Parameter error: If an error occurs, contains error information.

Returns: An array of CNContact objects matching the predicate. If no matches are found, an empty array is returned. If an error occurs, nil is returned.

Source

pub unsafe fn unifiedContactWithIdentifier_keysToFetch_error( &self, identifier: &NSString, keys: &NSArray<ProtocolObject<dyn CNKeyDescriptor>>, ) -> Result<Retained<CNContact>, Retained<NSError>>

Available on crate feature CNContact only.

Fetch a unified contact with a given identifier.

Due to unification the returned contact may have a different identifier. To fetch a batch of contacts by identifiers use [CNContact predicateForContactsWithIdentifiers:].

Parameter identifier: The identifier of the contact to fetch.

Parameter keys: The properties to fetch into the returned CNContact object. Should only fetch the properties that will be used. Can combine contact keys and contact key descriptors.

Parameter error: If an error occurs, contains error information.

Returns: The unified contact matching or linked to the identifier. If no contact with the given identifier is found, nil is returned and error is set to CNErrorCodeRecordDoesNotExist.

Source

pub unsafe fn unifiedMeContactWithKeysToFetch_error( &self, keys: &NSArray<ProtocolObject<dyn CNKeyDescriptor>>, ) -> Result<Retained<CNContact>, Retained<NSError>>

Available on crate feature CNContact only.

Fetch the unified contact that is the “me” card.

Fetches the contact that is represented in the user interface as “My Card”.

Parameter keys: The properties to fetch into the returned CNContact object. Should only fetch the properties that will be used. Can combine contact keys and contact key descriptors.

Parameter error: If an error occurs, contains error information.

Returns: The unified contact that is the “me” card. If no “me” card is set, nil is returned.

Source

pub unsafe fn enumeratorForContactFetchRequest_error( &self, request: &CNContactFetchRequest, ) -> Result<Retained<CNFetchResult<NSEnumerator<CNContact>>>, Retained<NSError>>

Available on crate features CNContact and CNContactFetchRequest and CNFetchRequest and CNFetchResult only.

Enumerate a contact fetch request.

Executes the given fetch request and returns an enumerator for the results. This may prevent all records from being loaded into memory at once.

An exception may be thrown if an error occurs during enumeration.

Parameter request: A description of the records to fetch.

Parameter error: If the fetch fails, contains an NSErrorobject with more information.

Returns: An enumerator of the records matching the result, or nilif there was an error.

Source

pub unsafe fn enumeratorForChangeHistoryFetchRequest_error( &self, request: &CNChangeHistoryFetchRequest, ) -> Result<Retained<CNFetchResult<NSEnumerator<CNChangeHistoryEvent>>>, Retained<NSError>>

Available on crate features CNChangeHistoryEvent and CNChangeHistoryFetchRequest and CNFetchRequest and CNFetchResult only.

Enumerate a change history fetch request.

Executes the given fetch request and returns an enumerator for the results. This may prevent all events from being loaded into memory at once.

An exception may be thrown if an error occurs during enumeration.

Parameter request: A description of the events to fetch.

Parameter error: If the fetch fails, contains an NSErrorobject with more information.

Returns: An enumerator of the events matching the result, or nilif there was an error.

Source

pub unsafe fn enumerateContactsWithFetchRequest_error_usingBlock( &self, fetch_request: &CNContactFetchRequest, error: Option<&mut Option<Retained<NSError>>>, block: &DynBlock<dyn Fn(NonNull<CNContact>, NonNull<Bool>) + '_>, ) -> bool

Available on crate features CNContact and CNContactFetchRequest and CNFetchRequest and block2 only.

Enumerates all contacts matching a contact fetch request.

This method will wait until the enumeration is finished. If there are no results, the block is not called and YES is returned.

Parameter fetchRequest: The contact fetch request that specifies the search criteria.

Parameter error: If an error occurs, contains error information.

Parameter block: Called for each matching contact. Set *stop to YES to stop the enumeration.

Returns: YES if successful, otherwise NO.

Source

pub unsafe fn groupsMatchingPredicate_error( &self, predicate: Option<&NSPredicate>, ) -> Result<Retained<NSArray<CNGroup>>, Retained<NSError>>

Available on crate feature CNGroup only.

Fetch all groups matching a given predicate.

Use only predicates from CNGroup+Predicates.h. Compound predicates are not supported.

Parameter predicate: The predicate to match against. Set to nil to match all groups.

Parameter error: If an error occurs, contains error information.

Returns: An array of CNGroup objects matching the predicate. If no matches are found, an empty array is returned. If an error occurs, nil is returned.

Source

pub unsafe fn containersMatchingPredicate_error( &self, predicate: Option<&NSPredicate>, ) -> Result<Retained<NSArray<CNContainer>>, Retained<NSError>>

Available on crate feature CNContainer only.

Fetch all containers matching a given predicate.

Use only predicates from CNContainer+Predicates.h. Compound predicates are not supported.

Parameter predicate: The predicate to match against. Set to nil to match all containers.

Parameter error: If an error occurs, contains error information.

Returns: An array of CNContainer objects matching the predicate. If no matches are found, an empty array is returned. If an error occurs, nil is returned.

Source

pub unsafe fn executeSaveRequest_error( &self, save_request: &CNSaveRequest, ) -> Result<(), Retained<NSError>>

Available on crate feature CNSaveRequest only.

Executes a save request.

Do not access objects when save request is executing. A save request with contacts may modify the contacts while executing. A save request only applies the changes to the objects. If there are overlapping changes with multiple, concurrent CNSaveRequests then the last saved change wins.

Parameter saveRequest: Save request to execute.

Parameter error: If an error occurs, contains error information.

Returns: YES if successful, otherwise NO.

Source

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

The current history token.

Retrieve the current history token. If you are fetching contacts or change history events, you should use the token on the CNFetchResultinstead.

Source

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

The identifier of the default container.

This identifier can be used to fetch the default container.

Returns: The identifier of the default container. If the caller lacks Contacts authorization or an error occurs, nil is returned.

Source §

impl CNContactStore

Methods declared on superclass NSObject.

Source

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

Source

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

Methods from Deref<Target = NSObject>§

Source

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

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>§

Source

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());

Source

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.

Source

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`
    }
}