blob: f09b25643180419b5796ca3ea890de8a7fbfbcd5 [file] [log] [blame]
/**
*
* Copyright (c) 2020 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/MTRCluster.h>
@class MTRSetupPayload;
@class MTRDeviceController;
NS_ASSUME_NONNULL_BEGIN
/**
* Handler for read attribute response, write attribute response, invoke command response and reports.
*
* Handler will receive either values or error. Either one of the parameters will be nil.
*
* @param values Received values are an NSArray object with response-value element as described below.
*
* A response-value is an NSDictionary object with the following key values:
*
* MTRAttributePathKey : MTRAttributePath object. Included for attribute value.
* MTRCommandPathKey : MTRCommandPath object. Included for command response.
* MTREventPathKey : MTREventPath object. Included for event value.
* MTRErrorKey : NSError object. Included to indicate an error.
* MTRDataKey: Data-value NSDictionary object.
* Included when there is data and when there is no error.
* The data-value is described below.
*
* A data-value is an NSDictionary object with the following key values:
*
* MTRTypeKey : data type. MTRSignedIntegerValueType, MTRUnsignedIntegerValueType, MTRBooleanValueType,
* MTRUTF8StringValueType, MTROctetStringValueType, MTRFloatValueType, MTRDoubleValueType,
* MTRNullValueType, MTRStructureValueType or MTRArrayValueType.
*
* MTRValueKey : data value. Per each data type, data value shall be the following object:
*
* MTRSignedIntegerValueType: NSNumber object.
* MTRUnsignedIntegerValueType: NSNumber object.
* MTRBooleanValueType: NSNumber object.
* MTRUTF8StringValueType: NSString object.
* MTROctetStringValueType: NSData object.
* MTRFloatValueType: NSNumber object.
* MTRDoubleValueType: NSNumber object.
* MTRNullValueType: "value" key will not be included.
* MTRStructureValueType: structure-value NSArray object.
* See below for the definition of structure-value.
* MTRArrayValueType: Array-value NSArray object. See below for the definition of array-value.
*
* A structure-value is an NSArray object with NSDictionary objects as its elements. Each dictionary element will
* contain the following key values.
*
* MTRContextTagKey : NSNumber object as context tag.
* MTRDataKey : Data-value NSDictionary object.
*
* An array-value is an NSArray object with NSDictionary objects as its elements. Each dictionary element will
* contain the following key values.
*
* MTRDataKey : Data-value NSDictionary object.
*/
typedef void (^MTRDeviceResponseHandler)(NSArray<NSDictionary<NSString *, id> *> * _Nullable values, NSError * _Nullable error);
/**
* Handler for -subscribeWithQueue: attribute and event reports
*
* @param values This array contains MTRAttributeReport objects for attribute reports, and MTREventReport objects for event reports
*/
typedef void (^MTRDeviceReportHandler)(NSArray * values);
typedef void (^MTRDeviceErrorHandler)(NSError * error);
/**
* Handler for subscribeWithQueue: resubscription scheduling notifications.
* This will be called when subscription loss is detected.
*
* @param error An error indicating the reason the subscription has been lost.
* @param resubscriptionDelay A delay, in milliseconds, before the next
* automatic resubscription will be attempted.
*/
typedef void (^MTRDeviceResubscriptionScheduledHandler)(NSError * error, NSNumber * resubscriptionDelay);
/**
* Handler for openCommissioningWindowWithSetupPasscode.
*/
API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2))
typedef void (^MTRDeviceOpenCommissioningWindowHandler)(MTRSetupPayload * _Nullable payload, NSError * _Nullable error);
extern NSString * const MTRAttributePathKey;
extern NSString * const MTRCommandPathKey;
extern NSString * const MTREventPathKey;
extern NSString * const MTRDataKey;
extern NSString * const MTRErrorKey;
extern NSString * const MTRTypeKey;
extern NSString * const MTRValueKey;
extern NSString * const MTRContextTagKey;
extern NSString * const MTRSignedIntegerValueType;
extern NSString * const MTRUnsignedIntegerValueType;
extern NSString * const MTRBooleanValueType;
extern NSString * const MTRUTF8StringValueType;
extern NSString * const MTROctetStringValueType;
extern NSString * const MTRFloatValueType;
extern NSString * const MTRDoubleValueType;
extern NSString * const MTRNullValueType;
extern NSString * const MTRStructureValueType;
extern NSString * const MTRArrayValueType;
@class MTRClusterStateCacheContainer;
@class MTRAttributeCacheContainer;
@class MTRReadParams;
@class MTRSubscribeParams;
@interface MTRBaseDevice : NSObject
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
/**
* Create a device object with the given node id and controller. This
* will always succeed, even if there is no such node id on the controller's
* fabric, but attempts to actually use the MTRBaseDevice will fail
* (asynchronously) in that case.
*/
+ (instancetype)deviceWithNodeID:(NSNumber *)nodeID controller:(MTRDeviceController *)controller MTR_NEWLY_AVAILABLE;
/**
* Subscribe to receive attribute reports for everything (all endpoints, all
* clusters, all attributes, all events) on the device.
*
* A non-nil attribute cache container will cache attribute values, retrievable
* through the designated attribute cache container.
*
* attributeReportHandler will be called any time a data update is available (with a
* non-nil "value")
*
* The array passed to attributeReportHandler will contain MTRAttributeReport
* instances. Errors for specific paths, not the whole subscription, will be
* reported via those objects.
*
* eventReportHandler will be called any time an event is reported (with a
* non-nil "value")
*
* The array passed to eventReportHandler will contain CHIPEventReport
* instances. Errors for specific paths, not the whole subscription, will be
* reported via those objects.
*
* errorHandler will be called any time there is an error for the entire
* subscription (with a non-nil "error"), and terminate the subscription. This
* will generally not be invoked if auto-resubscription is enabled, unless there
* is a fatal error during a resubscription attempt.
*
* Both report handlers are not supported over XPC at the moment.
*
* The subscriptionEstablished block, if not nil, will be called once the
* subscription is established. This will be _after_ the first (priming) call
* to both report handlers. Note that if the MTRSubscribeParams are set to
* automatically resubscribe this can end up being called more than once.
*
* The resubscriptionScheduled block, if not nil, will be called if
* auto-resubscription is enabled, subscription loss is detected, and a
* resubscription is scheduled. This can be called multiple times in a row
* without an intervening subscriptionEstablished call if the resubscription
* attempts fail.
*/
- (void)subscribeWithQueue:(dispatch_queue_t)queue
params:(MTRSubscribeParams *)params
clusterStateCacheContainer:(MTRClusterStateCacheContainer * _Nullable)clusterStateCacheContainer
attributeReportHandler:(MTRDeviceReportHandler _Nullable)attributeReportHandler
eventReportHandler:(MTRDeviceReportHandler _Nullable)eventReportHandler
errorHandler:(MTRDeviceErrorHandler)errorHandler
subscriptionEstablished:(MTRSubscriptionEstablishedHandler _Nullable)subscriptionEstablished
resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduled MTR_NEWLY_AVAILABLE;
/**
* Reads attributes from the device.
*
* Nil values for endpointID, clusterID, attributeID indicate wildcards
* (e.g. nil attributeID means "read all the attributes from the endpoint(s) and
* cluster(s) that match endpointID/clusterID").
*
* If all of endpointID, clusterID, attributeID are non-nil, a single
* attribute will be read.
*
* If all of endpointID, clusterID, attributeID are nil, all attributes on the
* device will be read.
*
* A non-nil attributeID along with a nil clusterID will only succeed if the
* attribute ID is for a global attribute that applies to all clusters.
*/
- (void)readAttributesWithEndpointID:(NSNumber * _Nullable)endpointID
clusterID:(NSNumber * _Nullable)clusterID
attributeID:(NSNumber * _Nullable)attributeID
params:(MTRReadParams * _Nullable)params
queue:(dispatch_queue_t)queue
completion:(MTRDeviceResponseHandler)completion MTR_NEWLY_AVAILABLE;
/**
* Write to attribute in a designated attribute path
*
* @param value A data-value NSDictionary object as described in
* MTRDeviceResponseHandler.
*
* @param timeoutMs timeout in milliseconds for timed write, or nil.
*
* @param completion response handler will receive either values or error.
*
* Received values are documented in the definition of
* MTRDeviceResponseHandler.
*/
- (void)writeAttributeWithEndpointID:(NSNumber *)endpointID
clusterID:(NSNumber *)clusterID
attributeID:(NSNumber *)attributeID
value:(id)value
timedWriteTimeout:(NSNumber * _Nullable)timeoutMs
queue:(dispatch_queue_t)queue
completion:(MTRDeviceResponseHandler)completion MTR_NEWLY_AVAILABLE;
/**
* Invoke a command with a designated command path
*
* @param commandFields command fields object. The object must be a data-value NSDictionary object
* as described in the MTRDeviceResponseHandler.
* The attribute must be a Structure, i.e.,
* the NSDictionary MTRTypeKey key must have the value MTRStructureValueType.
*
* @param timeoutMs timeout in milliseconds for timed invoke, or nil.
*
* @param completion response handler will receive either values or error.
*/
- (void)invokeCommandWithEndpointID:(NSNumber *)endpointID
clusterID:(NSNumber *)clusterID
commandID:(NSNumber *)commandID
commandFields:(id)commandFields
timedInvokeTimeout:(NSNumber * _Nullable)timeoutMs
queue:(dispatch_queue_t)queue
completion:(MTRDeviceResponseHandler)completion MTR_NEWLY_AVAILABLE;
/**
* Subscribes to the specified attributes on the device.
*
* Nil values for endpointID, clusterID, attributeID indicate wildcards
* (e.g. nil attributeID means "subscribe to all the attributes from the
* endpoint(s) and cluster(s) that match endpointID/clusterID").
*
* If all of endpointID, clusterID, attributeID are non-nil, a single attribute
* will be subscribed to.
*
* If all of endpointID, clusterID, attributeID are nil, all attributes on the
* device will be subscribed to.
*
* A non-nil attributeID along with a nil clusterID will only succeed if the
* attribute ID is for a global attribute that applies to all clusters.
*/
- (void)subscribeToAttributesWithEndpointID:(NSNumber * _Nullable)endpointID
clusterID:(NSNumber * _Nullable)clusterID
attributeID:(NSNumber * _Nullable)attributeID
params:(MTRSubscribeParams * _Nullable)params
queue:(dispatch_queue_t)queue
reportHandler:(MTRDeviceResponseHandler)reportHandler
subscriptionEstablished:(MTRSubscriptionEstablishedHandler _Nullable)subscriptionEstablished
MTR_NEWLY_AVAILABLE;
/**
* Deregister all local report handlers for a remote device
*
* This method is applicable only for a remote device. For a local device, the stack has to be shutdown to stop report handlers.
* There could be multiple clients accessing a node through a remote controller object and hence it is not appropriate
* for one of those clients to shut down the entire stack to stop receiving reports.
*/
- (void)deregisterReportHandlersWithQueue:(dispatch_queue_t)queue completion:(dispatch_block_t)completion MTR_NEWLY_AVAILABLE;
/**
* Open a commissioning window on the device.
*
* On success, completion will be called on queue with the MTRSetupPayload that
* can be used to commission the device.
*
* @param setupPasscode The setup passcode to use for the commissioning window.
* See MTRSetupPayload's generateRandomSetupPasscode for
* generating a valid random passcode.
* @param discriminator The discriminator to use for the commissionable
* advertisement.
* @param duration Duration, in seconds, during which the commissioning
* window will be open.
*/
- (void)openCommissioningWindowWithSetupPasscode:(NSNumber *)setupPasscode
discriminator:(NSNumber *)discriminator
duration:(NSNumber *)duration
queue:(dispatch_queue_t)queue
completion:(MTRDeviceOpenCommissioningWindowHandler)completion
API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2));
@end
/**
* A path indicating a specific cluster on a device (i.e. without any
* wildcards).
*/
MTR_NEWLY_AVAILABLE
@interface MTRClusterPath : NSObject <NSCopying>
@property (nonatomic, readonly, copy) NSNumber * endpoint;
@property (nonatomic, readonly, copy) NSNumber * cluster;
+ (instancetype)clusterPathWithEndpointID:(NSNumber *)endpointID clusterID:(NSNumber *)clusterID;
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
/**
* A path indicating a specific attribute on a device (i.e. without any
* wildcards).
*/
@interface MTRAttributePath : MTRClusterPath <NSCopying>
@property (nonatomic, readonly, copy) NSNumber * attribute;
+ (instancetype)attributePathWithEndpointID:(NSNumber *)endpointID
clusterID:(NSNumber *)clusterID
attributeID:(NSNumber *)attributeID MTR_NEWLY_AVAILABLE;
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
/**
* A path indicating a specific event that can be emitted on a device
* (i.e. without any wildcards). There can be multiple instances of actual
* events for a given event path.
*/
@interface MTREventPath : MTRClusterPath <NSCopying>
@property (nonatomic, readonly, copy) NSNumber * event;
+ (instancetype)eventPathWithEndpointID:(NSNumber *)endpointID
clusterID:(NSNumber *)clusterID
eventID:(NSNumber *)eventID MTR_NEWLY_AVAILABLE;
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
/**
* A path indicating a specific command on a device (i.e. without any
* wildcards).
*/
@interface MTRCommandPath : MTRClusterPath <NSCopying>
@property (nonatomic, readonly, copy) NSNumber * command;
+ (instancetype)commandPathWithEndpointID:(NSNumber *)endpointID
clusterID:(NSNumber *)clusterID
commandID:(NSNumber *)commandID MTR_NEWLY_AVAILABLE;
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
@interface MTRAttributeReport : NSObject
@property (nonatomic, readonly, copy) MTRAttributePath * path;
// value is nullable because nullable attributes can have nil as value.
@property (nonatomic, readonly, copy, nullable) id value;
// If this specific path resulted in an error, the error (in the
// MTRInteractionErrorDomain or MTRErrorDomain) that corresponds to this
// path.
@property (nonatomic, readonly, copy, nullable) NSError * error;
@end
@interface MTREventReport : NSObject
@property (nonatomic, readonly, copy) MTREventPath * path;
@property (nonatomic, readonly, copy) NSNumber * eventNumber; // EventNumber type (uint64_t)
@property (nonatomic, readonly, copy) NSNumber * priority; // PriorityLevel type (uint8_t)
@property (nonatomic, readonly, copy) NSNumber * timestamp; // Timestamp type (uint64_t)
// An instance of one of the event payload interfaces.
@property (nonatomic, readonly, copy) id value;
// If this specific path resulted in an error, the error (in the
// MTRInteractionErrorDomain or MTRErrorDomain) that corresponds to this
// path.
@property (nonatomic, readonly, copy, nullable) NSError * error;
@end
@interface MTRBaseDevice (Deprecated)
/**
* Deprecated MTRBaseDevice APIs.
*/
- (void)subscribeWithQueue:(dispatch_queue_t)queue
minInterval:(uint16_t)minInterval
maxInterval:(uint16_t)maxInterval
params:(MTRSubscribeParams * _Nullable)params
cacheContainer:(MTRAttributeCacheContainer * _Nullable)attributeCacheContainer
attributeReportHandler:(MTRDeviceReportHandler _Nullable)attributeReportHandler
eventReportHandler:(MTRDeviceReportHandler _Nullable)eventReportHandler
errorHandler:(MTRDeviceErrorHandler)errorHandler
subscriptionEstablished:(dispatch_block_t _Nullable)subscriptionEstablishedHandler
resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduledHandler
MTR_NEWLY_DEPRECATED(
"Please use "
"subscribeWithQueue:params:clusterStateCacheContainer:attributeReportHandler:eventReportHandler:errorHandler:"
"subscriptionEstablished:resubscriptionScheduled:");
- (void)readAttributeWithEndpointId:(NSNumber * _Nullable)endpointId
clusterId:(NSNumber * _Nullable)clusterId
attributeId:(NSNumber * _Nullable)attributeId
params:(MTRReadParams * _Nullable)params
clientQueue:(dispatch_queue_t)clientQueue
completion:(MTRDeviceResponseHandler)completion
MTR_NEWLY_DEPRECATED("Please use readAttributesWithEndpointID:clusterID:attributeID:params:queue:completion:");
- (void)writeAttributeWithEndpointId:(NSNumber *)endpointId
clusterId:(NSNumber *)clusterId
attributeId:(NSNumber *)attributeId
value:(id)value
timedWriteTimeout:(NSNumber * _Nullable)timeoutMs
clientQueue:(dispatch_queue_t)clientQueue
completion:(MTRDeviceResponseHandler)completion
MTR_NEWLY_DEPRECATED("Please use writeAttributeWithEndpointID:clusterID:attributeID:value:timedWriteTimeout:queue:completion:");
- (void)invokeCommandWithEndpointId:(NSNumber *)endpointId
clusterId:(NSNumber *)clusterId
commandId:(NSNumber *)commandId
commandFields:(id)commandFields
timedInvokeTimeout:(NSNumber * _Nullable)timeoutMs
clientQueue:(dispatch_queue_t)clientQueue
completion:(MTRDeviceResponseHandler)completion
MTR_NEWLY_DEPRECATED(
"Please use invokeCommandWithEndpointID:clusterID:commandID:commandFields:timedInvokeTimeout:queue:completion");
- (void)subscribeAttributeWithEndpointId:(NSNumber * _Nullable)endpointId
clusterId:(NSNumber * _Nullable)clusterId
attributeId:(NSNumber * _Nullable)attributeId
minInterval:(NSNumber *)minInterval
maxInterval:(NSNumber *)maxInterval
params:(MTRSubscribeParams * _Nullable)params
clientQueue:(dispatch_queue_t)clientQueue
reportHandler:(MTRDeviceResponseHandler)reportHandler
subscriptionEstablished:(dispatch_block_t _Nullable)subscriptionEstablishedHandler
MTR_NEWLY_DEPRECATED("Please use "
"subscribeToAttributesWithEndpointID:clusterID:attributeID:params:queue:"
"reportHandler:subscriptionEstablished:");
- (void)deregisterReportHandlersWithClientQueue:(dispatch_queue_t)queue
completion:(dispatch_block_t)completion
MTR_NEWLY_DEPRECATED("Pease use deregisterReportHandlersWithQueue:completion:");
@end
@interface MTRAttributePath (Deprecated)
+ (instancetype)attributePathWithEndpointId:(NSNumber *)endpointId
clusterId:(NSNumber *)clusterId
attributeId:(NSNumber *)attributeId
MTR_NEWLY_DEPRECATED("Please use attributePathWithEndpointID:clusterID:attributeID:");
@end
@interface MTREventPath (Deprecated)
+ (instancetype)eventPathWithEndpointId:(NSNumber *)endpointId
clusterId:(NSNumber *)clusterId
eventId:(NSNumber *)eventId
MTR_NEWLY_DEPRECATED("Please use eventPathWithEndpointID:clusterID:eventID:");
@end
@interface MTRCommandPath (Deprecated)
+ (instancetype)commandPathWithEndpointId:(NSNumber *)endpointId
clusterId:(NSNumber *)clusterId
commandId:(NSNumber *)commandId
MTR_NEWLY_DEPRECATED("Please use commandPathWithEndpointID:clusterID:commandID:");
@end
NS_ASSUME_NONNULL_END