#[repr(C)]pub struct LAContext { /* private fields */ }
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
impl LAContext
Sourcepub unsafe fn canEvaluatePolicy_error(
&self,
policy: LAPolicy,
) -> Result<(), Retained<NSError>>
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.
Sourcepub unsafe fn evaluatePolicy_localizedReason_reply(
&self,
policy: LAPolicy,
localized_reason: &NSString,
reply: &Block<dyn Fn(Bool, *mut NSError)>,
)
Available on crate feature block2
only.
pub unsafe fn evaluatePolicy_localizedReason_reply( &self, policy: LAPolicy, localized_reason: &NSString, reply: &Block<dyn Fn(Bool, *mut NSError)>, )
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:
“
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).
Sourcepub unsafe fn invalidate(&self)
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.
Sourcepub unsafe fn setCredential_type(
&self,
credential: Option<&NSData>,
type: LACredentialType,
) -> bool
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.
Sourcepub unsafe fn isCredentialSet(&self, type: LACredentialType) -> bool
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.
Sourcepub 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.
pub unsafe fn evaluateAccessControl_operation_localizedReason_reply( &self, access_control: &SecAccessControl, operation: LAAccessControlOperation, localized_reason: &NSString, reply: &Block<dyn Fn(Bool, *mut NSError)>, )
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:
“
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.
Sourcepub unsafe fn localizedFallbackTitle(&self) -> Option<Retained<NSString>>
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.
Sourcepub unsafe fn setLocalizedFallbackTitle(
&self,
localized_fallback_title: Option<&NSString>,
)
pub unsafe fn setLocalizedFallbackTitle( &self, localized_fallback_title: Option<&NSString>, )
Setter for localizedFallbackTitle
.
Sourcepub unsafe fn maxBiometryFailures(&self) -> Option<Retained<NSNumber>>
👎Deprecated: No longer supported
pub unsafe fn maxBiometryFailures(&self) -> Option<Retained<NSNumber>>
This property is deprecated and setting it has no effect.
Sourcepub unsafe fn setMaxBiometryFailures(
&self,
max_biometry_failures: Option<&NSNumber>,
)
👎Deprecated: No longer supported
pub unsafe fn setMaxBiometryFailures( &self, max_biometry_failures: Option<&NSNumber>, )
Setter for maxBiometryFailures
.
Sourcepub unsafe fn localizedCancelTitle(&self) -> Option<Retained<NSString>>
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.
Sourcepub unsafe fn setLocalizedCancelTitle(
&self,
localized_cancel_title: Option<&NSString>,
)
pub unsafe fn setLocalizedCancelTitle( &self, localized_cancel_title: Option<&NSString>, )
Setter for localizedCancelTitle
.
Sourcepub unsafe fn touchIDAuthenticationAllowableReuseDuration(
&self,
) -> NSTimeInterval
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
Sourcepub unsafe fn setTouchIDAuthenticationAllowableReuseDuration(
&self,
touch_id_authentication_allowable_reuse_duration: NSTimeInterval,
)
pub unsafe fn setTouchIDAuthenticationAllowableReuseDuration( &self, touch_id_authentication_allowable_reuse_duration: NSTimeInterval, )
Setter for touchIDAuthenticationAllowableReuseDuration
.
Sourcepub unsafe fn localizedReason(&self) -> Retained<NSString>
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.
Sourcepub unsafe fn setLocalizedReason(&self, localized_reason: &NSString)
pub unsafe fn setLocalizedReason(&self, localized_reason: &NSString)
Setter for localizedReason
.
Sourcepub unsafe fn interactionNotAllowed(&self) -> bool
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.
Sourcepub unsafe fn setInteractionNotAllowed(&self, interaction_not_allowed: bool)
pub unsafe fn setInteractionNotAllowed(&self, interaction_not_allowed: bool)
Setter for interactionNotAllowed
.
Sourcepub unsafe fn biometryType(&self) -> LABiometryType
Available on crate feature LABiometryType
only.
pub unsafe fn biometryType(&self) -> LABiometryType
LABiometryType
only.Indicates the type of the biometry supported by the device.
Sourcepub unsafe fn evaluatedPolicyDomainState(&self) -> Option<Retained<NSData>>
👎Deprecated
pub unsafe fn evaluatedPolicyDomainState(&self) -> Option<Retained<NSData>>
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.
Sourcepub unsafe fn domainState(&self) -> Retained<LADomainState>
Available on crate feature LADomainState
only.
pub unsafe fn domainState(&self) -> Retained<LADomainState>
LADomainState
only.Contains authentication domain state.
Methods from Deref<Target = NSObject>§
Sourcepub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
Handle messages the object doesn’t recognize.
See Apple’s documentation for details.
Methods from Deref<Target = AnyObject>§
Sourcepub fn class(&self) -> &'static AnyClass
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());
Sourcepub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
👎Deprecated: this is difficult to use correctly, use Ivar::load
instead.
pub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
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.
Sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: DowncastTarget,
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 ClassType for LAContext
impl ClassType for LAContext
Source§const NAME: &'static str = "LAContext"
const NAME: &'static str = "LAContext"
Source§type ThreadKind = <<LAContext as ClassType>::Super as ClassType>::ThreadKind
type ThreadKind = <<LAContext as ClassType>::Super as ClassType>::ThreadKind
Source§impl NSObjectProtocol for LAContext
impl NSObjectProtocol for LAContext
Source§fn isEqual(&self, other: Option<&AnyObject>) -> bool
fn isEqual(&self, other: Option<&AnyObject>) -> bool
Source§fn hash(&self) -> usize
fn hash(&self) -> usize
Source§fn isKindOfClass(&self, cls: &AnyClass) -> bool
fn isKindOfClass(&self, cls: &AnyClass) -> bool
Source§fn is_kind_of<T>(&self) -> bool
fn is_kind_of<T>(&self) -> bool
isKindOfClass
directly, or cast your objects with AnyObject::downcast_ref