| /** |
| * Copyright (c) 2023 Project CHIP Authors |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| #import <Foundation/Foundation.h> |
| #import <Matter/MTRDefines.h> |
| #import <Matter/MTRDeviceController.h> |
| |
| NS_ASSUME_NONNULL_BEGIN |
| |
| typedef NS_ENUM(NSUInteger, MTRStorageSecurityLevel) { |
| // Data must be stored in secure (encrypted) storage. |
| MTRStorageSecurityLevelSecure, |
| // Data may be stored in the clear. |
| MTRStorageSecurityLevelNotSecure, |
| } MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6)); |
| |
| typedef NS_ENUM(NSUInteger, MTRStorageSharingType) { |
| // Data must not be shared at all (just store locally). |
| MTRStorageSharingTypeNotShared, |
| |
| // Data must be shared, but only between controllers that have the same node |
| // identity (same fabric, same node ID, same CATs). |
| MTRStorageSharingTypeSameIdentity, |
| |
| // Data must be shared, but only between controllers that have the same |
| // access to devices (e.g. controllers that all have the same CATs if ACLs |
| // are being done via CATs). |
| MTRStorageSharingTypeSameACLs, |
| |
| // Data must be shared across all controllers on a given fabric. |
| MTRStorageSharingTypeSameFabric, |
| } MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6)); |
| |
| /** |
| * Protocol for storing and retrieving controller-specific data. |
| * |
| * Implementations of this protocol MUST keep these things in mind: |
| * |
| * 1) The controller provided to the delegate methods may not be fully |
| * initialized when the callbacks are called. The only safe thing to do with |
| * it is to get its controllerID. |
| * |
| * 2) The delegate method calls will happen on the queue that was provided along |
| * with the delegate. All Matter work will be blocked until the method |
| * completes, and these calls may themselves block other Matter API calls |
| * from completing. Attempting to call any Matter API on the queue used for |
| * this delegate, apart from de-serializing and serializing the items being |
| * stored and calling MTRDeviceControllerStorageClasses(), is likely to lead |
| * to deadlocks. |
| * |
| * 3) Security level and sharing type will always be the same for any given key value |
| * and are provided to describe the data should the storage delegate choose to |
| * implement separating storage location by security level and sharing type. |
| */ |
| MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6)) |
| @protocol MTRDeviceControllerStorageDelegate <NSObject> |
| @required |
| /** |
| * Return the stored value for the given key, if any, for the provided |
| * controller. Returns nil if there is no stored value. |
| * |
| * The set of classes that might be decoded by this function is available by |
| * calling MTRDeviceControllerStorageClasses(). |
| */ |
| - (nullable id<NSSecureCoding>)controller:(MTRDeviceController *)controller |
| valueForKey:(NSString *)key |
| securityLevel:(MTRStorageSecurityLevel)securityLevel |
| sharingType:(MTRStorageSharingType)sharingType; |
| |
| /** |
| * Store a value for the given key. Returns whether the store succeeded. |
| */ |
| - (BOOL)controller:(MTRDeviceController *)controller |
| storeValue:(id<NSSecureCoding>)value |
| forKey:(NSString *)key |
| securityLevel:(MTRStorageSecurityLevel)securityLevel |
| sharingType:(MTRStorageSharingType)sharingType; |
| |
| /** |
| * Remove the stored value for the given key. Returns whether the remove succeeded. |
| */ |
| - (BOOL)controller:(MTRDeviceController *)controller |
| removeValueForKey:(NSString *)key |
| securityLevel:(MTRStorageSecurityLevel)securityLevel |
| sharingType:(MTRStorageSharingType)sharingType; |
| |
| @optional |
| /** |
| * Return all keys and values stored, if any, for the provided controller, in a |
| * dictionary. Returns nil if there are no stored values. |
| * |
| * securityLevel and sharingType are provided as a hint for the storage delegate |
| * to load from the right security level and sharing type, if the implementation |
| * stores them separately. If the implementation includes key/value pairs from other |
| * security levels or sharing types, they will be ignored by the caller. |
| * |
| * The set of classes that might be decoded by this function is available by |
| * calling MTRDeviceControllerStorageClasses(). |
| */ |
| - (nullable NSDictionary<NSString *, id<NSSecureCoding>> *)valuesForController:(MTRDeviceController *)controller |
| securityLevel:(MTRStorageSecurityLevel)securityLevel |
| sharingType:(MTRStorageSharingType)sharingType; |
| |
| /** |
| * Store a list of key/value pairs in the form of a dictionary. Returns whether |
| * the store succeeded. Specifically, if any keys in this dictionary fail to store, |
| * the storage delegate should return NO. |
| */ |
| - (BOOL)controller:(MTRDeviceController *)controller |
| storeValues:(NSDictionary<NSString *, id<NSSecureCoding>> *)values |
| securityLevel:(MTRStorageSecurityLevel)securityLevel |
| sharingType:(MTRStorageSharingType)sharingType; |
| @end |
| |
| MTR_EXTERN MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6)) |
| NSSet<Class> * MTRDeviceControllerStorageClasses(void); |
| |
| NS_ASSUME_NONNULL_END |