SophaxChat/Tor/TorFramework/TORController.h

1//
2//  TORController.h
3//  Tor
4//
5//  Created by Conrad Kramer on 5/10/14.
6//
7
8#import <Foundation/Foundation.h>
9#import "TORCircuit.h"
10
11#ifdef __cplusplus
12#define TOR_EXTERN extern "C" __attribute__((visibility ("default")))
13#else
14#define TOR_EXTERN extern __attribute__((visibility ("default")))
15#endif
16
17NS_ASSUME_NONNULL_BEGIN
18
19typedef BOOL (^TORObserverBlock)(NSArray<NSNumber *> *codes, NSArray<NSData *> *lines, BOOL *stop);
20
21#if __IPHONE_OS_VERSION_MAX_ALLOWED >= 100000 || __MAC_OS_X_VERSION_MAX_ALLOWED >= 101200
22TOR_EXTERN NSErrorDomain const TORControllerErrorDomain;
23#else
24TOR_EXTERN NSString * const TORControllerErrorDomain;
25#endif
26
27NS_SWIFT_NAME(TorController)
28@interface TORController : NSObject
29
30@property (nonatomic, readonly, copy) NSOrderedSet<NSString *> *events;
31@property (nonatomic, readonly, getter=isConnected) BOOL connected;
32
33- (instancetype)init NS_UNAVAILABLE;
34- (instancetype)initWithSocketURL:(NSURL *)url NS_DESIGNATED_INITIALIZER;
35- (instancetype)initWithSocketHost:(NSString *)host port:(in_port_t)port NS_DESIGNATED_INITIALIZER;
36- (instancetype)initWithControlPortFile:(NSURL *)file;
37
38- (BOOL)connect:(out NSError **)error;
39- (void)disconnect;
40
41// Commands
42- (void)authenticateWithData:(NSData *)data completion:(void (^__nullable)(BOOL success, NSError * __nullable error))completion;
43- (void)resetConfForKey:(NSString *)key completion:(void (^__nullable)(BOOL success, NSError * __nullable error))completion;
44- (void)setConfForKey:(NSString *)key withValue:(NSString *)value completion:(void (^__nullable)(BOOL success, NSError * __nullable error))completion;
45- (void)setConfs:(NSArray<NSDictionary *> *)configs completion:(void (^__nullable)(BOOL success, NSError * __nullable error))completion;
46- (void)listenForEvents:(NSArray<NSString *> *)events completion:(void (^__nullable)(BOOL success, NSError * __nullable error))completion;
47- (void)getInfoForKeys:(NSArray<NSString *> *)keys completion:(void (^)(NSArray<NSString *> *values))completion; // TODO: Provide errors
48- (void)getSessionConfiguration:(void (^)(NSURLSessionConfiguration * __nullable configuration))completion;
49- (void)sendCommand:(NSString *)command arguments:(nullable NSArray<NSString *> *)arguments data:(nullable NSData *)data observer:(TORObserverBlock)observer;
50
51/**
52 Get a list of all currently available circuits with detailed information about their nodes.
53
54 @note There's no clear way to determine, which circuit actually was used by a specific request.
55
56 @param completion The callback upon completion of the task. Will return A list of `TORCircuit`s . Empty if no circuit could be found.
57 */
58- (void)getCircuits:(void (^)(NSArray<TORCircuit *> * _Nonnull circuits))completion;
59
60/**
61 Resets the Tor connection: Sends "SIGNAL RELOAD" and "SIGNAL NEWNYM" to the Tor thread.
62
63 See https://torproject.gitlab.io/torspec/control-spec.html#signal
64
65 @param completion Completion callback. Will return true, if signal calls where successful, false if not.
66 */
67- (void)resetConnection:(void (^__nullable)(BOOL success))completion;
68
69/**
70 Try to close a list of circuits identified by their IDs.
71
72 If some closings weren't successful, the most obvious reason would be, that the circuit with the given
73 ID doesn't exist (anymore). So in many circumstances, you can still consider that an ok outcome.
74
75 @param circuitIds List of circuit IDs.
76 @param completion Completion callback. Will return true, if *all* closings were successful, false, if *at least one* closing failed.
77 */
78- (void)closeCircuitsByIds:(NSArray<NSString *> *)circuitIds completion:(void (^__nullable)(BOOL success))completion;
79
80/**
81 Try to close a list of given circuits.
82
83 The given circuits are invalid afterwards, as you just closed them. You should throw them away on completion.
84
85@param circuits List of circuits to close.
86@param completion  Completion callback. Will return true, if *all* closings were successful, false, if *at least one* closing failed.
87*/
88- (void)closeCircuits:(NSArray<TORCircuit *> *)circuits completion:(void (^__nullable)(BOOL success))completion;
89
90/**
91 Resolve countries of given `TORNode`s and updates their `countryCode` property on success.
92
93 Nodes which already contain a `countryCode` will be ignored.
94 IPv4 addresses will be preferred, if Tor is able to resolve IPv4 addresses (if it has loaded the IPv4 geoip database),
95 and if the node has a `ipv4Address` property of non-zero length.
96
97 @param nodes List of `TORNode`s to resolve countries for.
98 @param testCapabilities Ask Tor first, if it is actually able to resolve. (If GeoDB databases are loaded.) Pass NO, if you're sure that Tor is able to to save on queries.
99 @param completion Completion callback.
100 */
101- (void)resolveCountriesOfNodes:(NSArray<TORNode *> * _Nullable)nodes testCapabilities:(BOOL)testCapabilities completion:(void (^__nullable)(void))completion;
102
103// Observers
104- (id)addObserverForCircuitEstablished:(void (^)(BOOL established))block;
105- (id)addObserverForStatusEvents:(BOOL (^)(NSString *type, NSString *severity, NSString *action, NSDictionary<NSString *, NSString *> * __nullable arguments))block;
106- (void)removeObserver:(nullable id)observer;
107
108@end
109
110NS_ASSUME_NONNULL_END