Struct LAContext

Source
#[repr(C)]
pub struct LAContext { /* private fields */ }
Available on crate feature LAContext only.
Expand description

Class that represents an authentication context.

This context can be used for evaluating policies.

See: LAPolicy

See also Apple’s documentation

Implementations§

Source§

impl LAContext

Source

pub unsafe fn canEvaluatePolicy_error( &self, policy: LAPolicy, ) -> Result<(), Retained<NSError>>

Determines if a particular policy can be evaluated.

Policies can have certain requirements which, when not satisfied, would always cause the policy evaluation to fail - e.g. a passcode set, a fingerprint enrolled with Touch ID or a face set up with Face ID. This method allows easy checking for such conditions.

Applications should consume the returned value immediately and avoid relying on it for an extensive period of time. At least, it is guaranteed to stay valid until the application enters background.

Warning: Do not call this method in the reply block of evaluatePolicy:reply: because it could lead to a deadlock.

Parameter policy: Policy for which the preflight check should be run.

Parameter error: Optional output parameter which is set to nil if the policy can be evaluated, or it contains error information if policy evaluation is not possible.

Returns: YES if the policy can be evaluated, NO otherwise.

Source

pub unsafe fn evaluatePolicy_localizedReason_reply( &self, policy: LAPolicy, localized_reason: &NSString, reply: &Block<dyn Fn(Bool, *mut NSError)>, )

Available on crate feature block2 only.

Evaluates the specified policy.

Policy evaluation may involve prompting user for various kinds of interaction or authentication. Actual behavior is dependent on evaluated policy, device type, and can be affected by installed configuration profiles.

Be sure to keep a strong reference to the context while the evaluation is in progress. Otherwise, an evaluation would be canceled when the context is being deallocated.

The method does not block. Instead, the caller must provide a reply block to be called asynchronously when evaluation finishes. The block is executed on a private queue internal to the framework in an unspecified threading context. Other than that, no guarantee is made about which queue, thread, or run-loop the block is executed on.

Implications of successful policy evaluation are policy specific. In general, this operation is not idempotent. Policy evaluation may fail for various reasons, including user cancel, system cancel and others, see LAError codes.

Parameter policy: Policy to be evaluated.

Parameter reply: Reply block that is executed when policy evaluation finishes. success Reply parameter that is YES if the policy has been evaluated successfully or NO if the evaluation failed. error Reply parameter that is nil if the policy has been evaluated successfully, or it contains error information about the evaluation failure.

Parameter localizedReason: Application reason for authentication. This string must be provided in correct localization and should be short and clear. It will be eventually displayed in the authentication dialog as a part of the following string: “” is trying to .

For example, if the app name is “TestApp” and localizedReason is passed “access the hidden records”, then the authentication prompt will read: “TestApp” is trying to access the hidden records.

Warning: localizedReason parameter is mandatory and the call will throw NSInvalidArgumentException if nil or empty string is specified.

See: LAError

Typical error codes returned by this call are:

LAErrorUserFallback if user tapped the fallback button

LAErrorUserCancel if user has tapped the Cancel button

LAErrorSystemCancel if some system event interrupted the evaluation (e.g. Home button pressed).

Source

pub unsafe fn invalidate(&self)

Invalidates the context.

The context is invalidated automatically when it is (auto)released. This method allows invalidating it manually while it is still in scope.

Invalidation terminates any existing policy evaluation and the respective call will fail with LAErrorAppCancel. After the context has been invalidated, it can not be used for policy evaluation and an attempt to do so will fail with LAErrorInvalidContext.

Invalidating a context that has been already invalidated has no effect.

Source

pub unsafe fn setCredential_type( &self, credential: Option<&NSData>, type: LACredentialType, ) -> bool

Sets a credential to this context.

Some policies allow to bind application-provided credential with them. This method allows credential to be passed to the right context.

Parameter credential: Credential to be used with subsequent calls. Setting this parameter to nil will remove any existing credential of the specified type.

Parameter type: Type of the provided credential.

Returns: YES if the credential was set successfully, NO otherwise.

Source

pub unsafe fn isCredentialSet(&self, type: LACredentialType) -> bool

Reveals if credential was set with this context.

Parameter type: Type of credential we are asking for.

Returns: YES on success, NO otherwise.

Source

pub unsafe fn evaluateAccessControl_operation_localizedReason_reply( &self, access_control: &SecAccessControl, operation: LAAccessControlOperation, localized_reason: &NSString, reply: &Block<dyn Fn(Bool, *mut NSError)>, )

Available on crate features block2 and objc2-security only.

Evaluates access control object for the specified operation.

Access control evaluation may involve prompting user for various kinds of interaction or authentication. Actual behavior is dependent on evaluated access control, device type, and can be affected by installed configuration profiles.

Be sure to keep a strong reference to the context while the evaluation is in progress. Otherwise, an evaluation would be canceled when the context is being deallocated.

The method does not block. Instead, the caller must provide a reply block to be called asynchronously when evaluation finishes. The block is executed on a private queue internal to the framework in an unspecified threading context. Other than that, no guarantee is made about which queue, thread, or run-loop the block is executed on.

After successful access control evaluation, the LAContext can be used with keychain operations, so that they do not require user to authenticate.

Access control evaluation may fail for various reasons, including user cancel, system cancel and others, see LAError codes.

Parameter accessControl: Access control object that is typically created by SecAccessControlCreateWithFlags.

Parameter operation: Type of operation the access control will be used with.

Parameter localizedReason: Application reason for authentication. This string must be provided in correct localization and should be short and clear. It will be eventually displayed in the authentication dialog as a part of the following string: “” is trying to .

For example, if the app name is “TestApp” and localizedReason is passed “access the hidden records”, then the authentication prompt will read: “TestApp” is trying to access the hidden records.

Parameter reply: Reply block that is executed when access control evaluation finishes. success Reply parameter that is YES if the access control has been evaluated successfully or NO if the evaluation failed. error Reply parameter that is nil if the access control has been evaluated successfully, or it contains error information about the evaluation failure.

Warning: localizedReason parameter is mandatory and the call will throw NSInvalidArgumentException if nil or empty string is specified.

Source

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

Fallback button title.

Allows fallback button title customization. If set to empty string, the button will be hidden. A default title “Use Password…” is used when this property is left nil.

Source

pub unsafe fn setLocalizedFallbackTitle( &self, localized_fallback_title: Option<&NSString>, )

Source

pub unsafe fn maxBiometryFailures(&self) -> Option<Retained<NSNumber>>

👎Deprecated: No longer supported

This property is deprecated and setting it has no effect.

Source

pub unsafe fn setMaxBiometryFailures( &self, max_biometry_failures: Option<&NSNumber>, )

👎Deprecated: No longer supported

Setter for maxBiometryFailures.

Source

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

Cancel button title.

Allows cancel button title customization. A default title “Cancel” is used when this property is left nil or is set to empty string.

Source

pub unsafe fn setLocalizedCancelTitle( &self, localized_cancel_title: Option<&NSString>, )

Source

pub unsafe fn touchIDAuthenticationAllowableReuseDuration( &self, ) -> NSTimeInterval

Time interval for accepting a successful Touch ID or Face ID device unlock (on the lock screen) from the past.

This property can be set with a time interval in seconds. If the device was successfully unlocked by biometry within this time interval, then biometric authentication on this context will succeed automatically and the reply block will be called without prompting user for Touch ID or Face ID.

The default value is 0, meaning that no previous biometric unlock can be reused.

This property is meant only for reusing biometric matches from the device lock screen. It does not allow reusing previous biometric matches in application or between applications.

The maximum supported interval is 5 minutes and setting the value beyond 5 minutes does not increase the accepted interval.

See: LATouchIDAuthenticationMaximumAllowableReuseDuration

Source

pub unsafe fn setTouchIDAuthenticationAllowableReuseDuration( &self, touch_id_authentication_allowable_reuse_duration: NSTimeInterval, )

Source

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

Allows setting the default localized authentication reason on context.

A localized string from this property is displayed in the authentication UI if the caller didn’t specify its own authentication reason (e.g. a keychain operation with kSecUseAuthenticationContext). This property is ignored if the authentication reason was provided by caller.

Source

pub unsafe fn setLocalizedReason(&self, localized_reason: &NSString)

Setter for localizedReason.

Source

pub unsafe fn interactionNotAllowed(&self) -> bool

Allows running authentication in non-interactive mode.

If the context is used in a keychain query by the means of kSecUseAuthenticationContext, then setting this property to YES has the same effect as passing kSecUseNoAuthenticationUI in the query, i.e. the keychain call will eventually fail with errSecInteractionNotAllowed instead of displaying the authentication UI.

If this property is used with a LocalAuthentication evaluation, it will eventually fail with LAErrorNotInteractive instead of displaying the authentication UI.

Source

pub unsafe fn setInteractionNotAllowed(&self, interaction_not_allowed: bool)

Source

pub unsafe fn biometryType(&self) -> LABiometryType

Available on crate feature LABiometryType only.

Indicates the type of the biometry supported by the device.

Source

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

👎Deprecated

Contains policy domain state.

This property is set only when evaluatePolicy is called and succesful Touch ID or Face ID authentication was performed, or when canEvaluatePolicy succeeds for a biometric policy. It stays nil for all other cases. If biometric database was modified (fingers or faces were removed or added), evaluatedPolicyDomainState data will change. Nature of such database changes cannot be determined but comparing data of evaluatedPolicyDomainState after different evaluatePolicy will reveal the fact database was changed between calls.

Warning: Please note that the value returned by this property can change exceptionally between major OS versions even if the state of biometry has not changed.

Source

pub unsafe fn domainState(&self) -> Retained<LADomainState>

Available on crate feature LADomainState only.

Contains authentication domain state.

Source§

impl LAContext

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.

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

Trait Implementations§

Source§

impl AsRef<AnyObject> for LAContext

Source§

fn as_ref(&self) -> &AnyObject

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

impl AsRef<LAContext> for LAContext

Source§

fn as_ref(&self) -> &Self

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

impl AsRef<NSObject> for LAContext

Source§

fn as_ref(&self) -> &NSObject

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

impl Borrow<AnyObject> for LAContext

Source§

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value. Read more
Source§

impl Borrow<NSObject> for LAContext

Source§

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value. Read more
Source§

impl ClassType for LAContext

Source§

const NAME: &'static str = "LAContext"

The name of the Objective-C class that this type represents. Read more
Source§

type Super = NSObject

The superclass of this class. Read more
Source§

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

Whether the type can be used from any thread, or from only the main thread. Read more
Source§

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents. Read more
Source§

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

Get an immutable reference to the superclass.
Source§

impl Debug for LAContext

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Deref for LAContext

Source§

type Target = NSObject

The resulting type after dereferencing.
Source§

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

Dereferences the value.
Source§

impl Hash for LAContext

Source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

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

Feeds a slice of this type into the given Hasher. Read more
Source§

impl Message for LAContext

Source§

fn retain(&self) -> Retained<Self>
where Self: Sized,

Increment the reference count of the receiver. Read more
Source§

impl NSObjectProtocol for LAContext

Source§

fn isEqual(&self, other: Option<&AnyObject>) -> bool
where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object. Read more
Source§

fn hash(&self) -> usize
where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure. Read more
Source§

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. Read more
Source§

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. Read more
Source§

fn isMemberOfClass(&self, cls: &AnyClass) -> bool
where Self: Sized + Message,

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

fn respondsToSelector(&self, aSelector: Sel) -> bool
where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector. Read more
Source§

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool
where Self: Sized + Message,

Check whether the object conforms to a given protocol. Read more
Source§

fn description(&self) -> Retained<NSObject>
where Self: Sized + Message,

A textual representation of the object. Read more
Source§

fn debugDescription(&self) -> Retained<NSObject>
where Self: Sized + Message,

A textual representation of the object to use when debugging. Read more
Source§

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. Read more
Source§

fn retainCount(&self) -> usize
where Self: Sized + Message,

The reference count of the object. Read more
Source§

impl PartialEq for LAContext

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

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

impl RefEncode for LAContext

Source§

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

The Objective-C type-encoding for a reference of this type. Read more
Source§

impl DowncastTarget for LAContext

Source§

impl Eq for LAContext

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<'a, T> AllocAnyThread for T
where T: ClassType<ThreadKind = dyn AllocAnyThread + 'a> + ?Sized,

Source§

fn alloc() -> Allocated<Self>
where Self: Sized + ClassType,

Allocate a new instance of the class. Read more
Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

Source§

type Target = T

🔬This is a nightly-only experimental API. (arbitrary_self_types)
The target type on which the method may be called.
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> AutoreleaseSafe for T
where T: ?Sized,