1  /*
 2   * Copyright (c) 2017 Apple Inc. All Rights Reserved.
 3   *
 4   * @APPLE_LICENSE_HEADER_START@
 5   *
 6   * This file contains Original Code and/or Modifications of Original Code
 7   * as defined in and that are subject to the Apple Public Source License
 8   * Version 2.0 (the 'License'). You may not use this file except in
 9   * compliance with the License. Please obtain a copy of the License at
10   * http://www.opensource.apple.com/apsl/ and read it before using this
11   * file.
12   *
13   * The Original Code and all software distributed under the License are
14   * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15   * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16   * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17   * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18   * Please see the License for the specific language governing rights and
19   * limitations under the License.
20   *
21   * @APPLE_LICENSE_HEADER_END@
22   */
23  
24  #if OCTAGON
25  
26  #import <Foundation/Foundation.h>
27  #import <dispatch/dispatch.h>
28  #import "keychain/ckks/NSOperationCategories.h"
29  
30  NS_ASSUME_NONNULL_BEGIN
31  
32  @class CKKSCondition;
33  
34  #define CKKSResultErrorDomain @"CKKSResultOperationError"
35  enum {
36      CKKSResultSubresultError = 1,
37      CKKSResultSubresultCancelled = 2,
38      CKKSResultTimedOut = 3,
39  };
40  
41  #define CKKSResultDescriptionErrorDomain @"CKKSResultOperationDescriptionError"
42  
43  @interface CKKSResultOperation : NSBlockOperation
44  @property (nullable) NSError* error;
45  @property (nullable) NSDate* finishDate;
46  @property CKKSCondition* completionHandlerDidRunCondition;
47  
48  @property NSInteger descriptionErrorCode; // Set to non-0 for inclusion of this operation in NSError chains. Code is application-dependent, but will be -1 in cases of excessive recursion.
49  
50  // If you subclass CKKSResultOperation, this is the method corresponding to descriptionErrorCode. Fill it in to your heart's content.
51  - (NSError* _Nullable)descriptionError;
52  
53  // Very similar to addDependency, but:
54  //   if the dependent operation has an error or is canceled, cancel this operation
55  - (void)addSuccessDependency:(CKKSResultOperation*)operation;
56  - (void)addNullableSuccessDependency:(CKKSResultOperation*)operation;
57  
58  // Call to check if you should run.
59  // Note: all subclasses must call this if they'd like to comply with addSuccessDependency
60  // Also sets your .error property to encapsulate the upstream error
61  - (bool)allDependentsSuccessful;
62  
63  // Allows you to time out CKKSResultOperations: if they haven't started by now, they'll cancel themselves
64  // and set their error to indicate the timeout
65  - (instancetype)timeout:(dispatch_time_t)timeout;
66  
67  // Convenience constructor.
68  + (instancetype)operationWithBlock:(void (^)(void))block;
69  + (instancetype)named:(NSString*)name withBlock:(void (^)(void))block NS_SWIFT_NAME(init(name:block:));
70  + (instancetype)named:(NSString*)name withBlockTakingSelf:(void(^)(CKKSResultOperation* op))block NS_SWIFT_NAME(init(name:blockTakingSelf:));
71  
72  // Determine if all these operations were successful, and set this operation's result if not.
73  - (bool)allSuccessful:(NSArray<CKKSResultOperation*>*)operations;
74  
75  // Call this to prevent the timeout on this operation from occuring.
76  // Upon return, either this operation is cancelled, or the timeout will never fire.
77  - (void)invalidateTimeout;
78  
79  // Reports the state of this operation. Used for making up description strings.
80  - (NSString*)operationStateString;
81  @end
82  
83  NS_ASSUME_NONNULL_END
84  #endif // OCTAGON
85