Skip to content

Commit 844a40c

Browse files
tyrionchentyrionchen
committed
feat: TcrProxy SDK 1.1.0
支持连接状态回调
1 parent c231ea7 commit 844a40c

File tree

14 files changed

+269
-20
lines changed

14 files changed

+269
-20
lines changed

‎Doc/代理SDK接入指南.md‎

Lines changed: 90 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
- [集成准备](#集成准备)
1515
- [权限与配置](#权限与配置)
1616
- [代理服务接入流程](#代理服务接入流程)
17+
- [连接状态监听](#连接状态监听)
1718
- [代码示例](#代码示例)
1819
- [Proxy接口说明](#proxy接口说明)
1920

@@ -105,41 +106,121 @@ iOS 无需特殊权限，亦无需在 Info.plist 中声明特殊内容，但请
105106
106107
---
107108

109+
## 连接状态监听
110+
111+
> Proxy 新增连接状态监听能力，可以实时获知代理服务器的连接状态，包括断开、重连中、连接完成等，有助于业务流程和体验优化。
112+
113+
### 设置连接状态监听
114+
115+
引入头文件：
116+
117+
```objc
118+
#import <TCRPROXYSDK/Proxy.h>
119+
#import <TCRPROXYSDK/ProxyConnectionDelegate.h>
120+
```
121+
122+
实现监听协议：
123+
124+
```objc
125+
@interface MyProxyConnectionObserver : NSObject <ProxyConnectionDelegate>
126+
@end
127+
128+
@implementation MyProxyConnectionObserver
129+
130+
- (void)onConnectionStateChanged:(ConnectionState)state message:(NSString *)message {
131+
NSLog(@"Proxy连接状态: %ld, 描述: %@", (long)state, message);
132+
// 可根据状态处理UI/业务
133+
}
134+
135+
@end
136+
```
137+
138+
注册监听：
139+
140+
```objc
141+
MyProxyConnectionObserver *observer = [[MyProxyConnectionObserver alloc] init];
142+
[[Proxy sharedInstance] setConnectionDelegate:observer];
143+
```
144+
145+
> 若不再需要监听，可调用 `setConnectionDelegate:nil`，即可移除。
146+
147+
#### 状态枚举说明
148+
149+
SDK 定义的 `ConnectionState` 枚举：
150+
151+
| 枚举 | 值 | 描述 |
152+
|----------------|------|---------------|
153+
| Disconnected | 0 | 连接断开 |
154+
| Connecting | 1 | 连接中/重连中 |
155+
| Connected | 2 | 连接完成 |
156+
157+
若需获取状态文本描述，可使用：
158+
159+
```objc
160+
NSString *desc = [ConnectionStateHelper descriptionForConnectionState:state];
161+
```
162+
163+
#### 典型场景示例
164+
- **连接完成后通知业务层可以进行云端访问**
165+
- **UI层展示当前连接进度/告警**
166+
167+
---
168+
108169
## 代码示例
109170
110171
```objc
111172
// 1. 监听代理中继信息回调（以 TcrSessionObserver 示例）
112173
- (void)onEvent:(TcrEvent)event eventData:(id)eventData {
113174
if (event == PROXY_RELAY_AVAILABLE) {
114175
NSString *relayInfoString = (NSString *)eventData;
115-
// 初始化代理（带宽参数可选）
176+
// 1.初始化代理
116177
BOOL ok = [[Proxy sharedInstance] initWithRelayInfoString:relayInfoString];
117178
if (ok) {
118-
// 2. 启动代理
179+
// 2. 设置连接状态监听
180+
MyProxyConnectionObserver *observer = [[MyProxyConnectionObserver alloc] init];
181+
[[Proxy sharedInstance] setConnectionDelegate:observer];
182+
// 3. 启动代理
119183
[[Proxy sharedInstance] startProxy];
120184
}
121185
}
122186
}
123187
124-
// 3. 不再需要代理时
188+
// 4. 不再需要代理及监听时
125189
[[Proxy sharedInstance] stopProxy];
190+
[[Proxy sharedInstance] setConnectionDelegate:nil];
126191
```
127192

128193
---
129194

130195
## Proxy接口说明
131196

132-
| 方法名 | 说明 | 参数说明 | 返回值 | 备注 |
133-
| ------------------------------------------------------------------------------------------------------ | ------------ | --------------------------------------------------------- | ------ | ------------------ |
197+
| 方法名 | 说明 | 参数说明 | 返回值 | 备注 |
198+
| ------------------------------------------------------------------------------------------------------ | ----------------- | --------------------------------------------------------- | ------ | ------------------ |
134199
| `+ (instancetype)sharedInstance` | 获取单例，日志默认级别4 | 无 | Proxy* | 单例模式 |
135200
| `+ (instancetype)sharedInstanceWithLogLevel:(NSInteger)logLevel` | 获取单例，指定日志级别 | logLevel: 2-VERBOSE, 3-DEBUG, 4-INFO, 5-WARNING, 6-ERROR | Proxy* | 仅本地调试时用到 |
136-
| `- (BOOL)initWithRelayInfoString:(NSString *)relayInfoString` | 初始化代理服务 | relayInfoString: 云端下发的代理中继信息 | BOOL | 必须在 startProxy 前调用 |
201+
| `- (BOOL)initWithRelayInfoString:(NSString *)relayInfoString` | 初始化代理服务 | relayInfoString: 云端下发的代理中继信息 | BOOL | 必须在 startProxy 前调用 |
137202
| `- (BOOL)initWithBandwidth:(nullable NSString *)bandwidth relayInfoString:(NSString *)relayInfoString` | 初始化代理服务并限制带宽 | bandwidth: @"1MB"/@"500KB"（最大 4MB）<br>relayInfoString: 同上 | BOOL | 必须在 startProxy 前调用 |
138-
| `- (void)startProxy` | 启动代理服务 | 无 | 无 | 必须已成功调用初始化方法 |
139-
| `- (void)stopProxy` | 停止代理服务 | 无 | 无 | |
203+
| `- (void)startProxy` | 启动代理服务 | 无 | 无 | 必须已成功调用初始化方法 |
204+
| `- (void)stopProxy` | 停止代理服务 | 无 | 无 | |
205+
| `- (void)setConnectionDelegate:(nullable id<ProxyConnectionDelegate>)delegate` | 设置连接状态监听器 | delegate: 连接状态变化监听器，传nil可清除监听 | 无 | 需监听代理连接状态场景适用 |
206+
207+
---
208+
209+
### ProxyConnectionDelegate 协议
210+
211+
```objc
212+
@protocol ProxyConnectionDelegate <NSObject>
213+
/// 连接状态变化回调
214+
/// @param state 当前连接状态（枚举）
215+
/// @param message 状态描述字符串
216+
- (void)onConnectionStateChanged:(ConnectionState)state message:(NSString *)message;
217+
@end
218+
```
140219
141220
---
142221
143222
### 其他说明
144223
145-
- iOS SDK 采用全局单例模式设计，建议在应用合适生命周期同步初始化、关闭代理，避免后台无故长时间占用资源。
224+
- iOS SDK 采用全局单例模式设计，建议在应用合适生命周期同步初始化、关闭代理，避免后台无故长时间占用资源。
225+
226+
---

‎SDK/TCRPROXYSDK.xcframework/Info.plist‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,32 +8,32 @@
88
<key>BinaryPath</key>
99
<string>TCRPROXYSDK.framework/TCRPROXYSDK</string>
1010
<key>LibraryIdentifier</key>
11-
<string>ios-arm64_x86_64-simulator</string>
11+
<string>ios-arm64</string>
1212
<key>LibraryPath</key>
1313
<string>TCRPROXYSDK.framework</string>
1414
<key>SupportedArchitectures</key>
1515
<array>
1616
<string>arm64</string>
17-
<string>x86_64</string>
1817
</array>
1918
<key>SupportedPlatform</key>
2019
<string>ios</string>
21-
<key>SupportedPlatformVariant</key>
22-
<string>simulator</string>
2320
</dict>
2421
<dict>
2522
<key>BinaryPath</key>
2623
<string>TCRPROXYSDK.framework/TCRPROXYSDK</string>
2724
<key>LibraryIdentifier</key>
28-
<string>ios-arm64</string>
25+
<string>ios-arm64_x86_64-simulator</string>
2926
<key>LibraryPath</key>
3027
<string>TCRPROXYSDK.framework</string>
3128
<key>SupportedArchitectures</key>
3229
<array>
3330
<string>arm64</string>
31+
<string>x86_64</string>
3432
</array>
3533
<key>SupportedPlatform</key>
3634
<string>ios</string>
35+
<key>SupportedPlatformVariant</key>
36+
<string>simulator</string>
3737
</dict>
3838
</array>
3939
<key>CFBundlePackageType</key>

‎SDK/TCRPROXYSDK.xcframework/ios-arm64/TCRPROXYSDK.framework/Headers/ConnectionState.h‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
2+
//
3+
// ConnectionState.h
4+
// TCRPROXYSDK
5+
//
6+
// Created by cyy on 2025/09/30.
7+
//
8+
9+
#import <Foundation/Foundation.h>
10+
11+
NS_ASSUME_NONNULL_BEGIN
12+
13+
/// 连接状态枚举定义
14+
typedef NS_ENUM(NSInteger, ConnectionState) {
15+
/// 连接断开
16+
Disconnected = 0,
17+
/// 连接中/重连中
18+
Connecting = 1,
19+
/// 连接完成
20+
Connected = 2
21+
};
22+
23+
/// 连接状态工具类
24+
@interface ConnectionStateHelper : NSObject
25+
26+
/// 从状态值获取连接状态枚举
27+
/// @param state 状态值
28+
/// @return 连接状态枚举
29+
+ (ConnectionState)connectionStateFromValue:(NSInteger)state;
30+
31+
/// 获取连接状态描述
32+
/// @param state 连接状态
33+
/// @return 状态描述字符串
34+
+ (NSString *)descriptionForConnectionState:(ConnectionState)state;
35+
36+
@end
37+
38+
NS_ASSUME_NONNULL_END

‎SDK/TCRPROXYSDK.xcframework/ios-arm64/TCRPROXYSDK.framework/Headers/Proxy.h‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
//
77

88
#import <Foundation/Foundation.h>
9+
#import <TCRPROXYSDK/ProxyConnectionDelegate.h>
910

1011
NS_ASSUME_NONNULL_BEGIN
1112

@@ -35,6 +36,14 @@ NS_ASSUME_NONNULL_BEGIN
3536
/// 停止代理服务
3637
- (void)stopProxy;
3738

39+
/// 设置连接状态变化监听器
40+
/// 通过此接口可以监听代理服务的连接状态变化，包括：
41+
/// - 连接断开
42+
/// - 连接中/重连中
43+
/// - 连接完成
44+
/// @param delegate 连接状态变化监听器，传nil可清除监听
45+
- (void)setConnectionDelegate:(nullable id<ProxyConnectionDelegate>)delegate;
46+
3847
@end
3948

4049
NS_ASSUME_NONNULL_END

‎SDK/TCRPROXYSDK.xcframework/ios-arm64/TCRPROXYSDK.framework/Headers/ProxyConnectionDelegate.h‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
2+
//
3+
// ProxyConnectionDelegate.h
4+
// TCRPROXYSDK
5+
//
6+
// Created by cyy on 2025/09/30.
7+
//
8+
9+
#import <Foundation/Foundation.h>
10+
#import <TCRPROXYSDK/ConnectionState.h>
11+
12+
NS_ASSUME_NONNULL_BEGIN
13+
14+
/// 连接状态回调协议
15+
@protocol ProxyConnectionDelegate <NSObject>
16+
17+
/// 连接状态变化回调
18+
/// @param state 当前连接状态
19+
/// @param message 状态描述信息
20+
- (void)onConnectionStateChanged:(ConnectionState)state message:(NSString *)message;
21+
22+
@end
23+
24+
NS_ASSUME_NONNULL_END

‎SDK/TCRPROXYSDK.xcframework/ios-arm64/TCRPROXYSDK.framework/Headers/TCRPROXYSDK.h‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,5 @@ FOUNDATION_EXPORT double TCRPROXYSDKVersionNumber;
1414
FOUNDATION_EXPORT const unsigned char TCRPROXYSDKVersionString[];
1515

1616
#import <TCRPROXYSDK/Proxy.h>
17+
#import <TCRPROXYSDK/ConnectionState.h>
18+
#import <TCRPROXYSDK/ProxyConnectionDelegate.h>

‎SDK/TCRPROXYSDK.xcframework/ios-arm64/TCRPROXYSDK.framework/TCRPROXYSDK‎

25.3 KB
Binary file not shown.

‎SDK/TCRPROXYSDK.xcframework/ios-arm64_x86_64-simulator/TCRPROXYSDK.framework/Headers/ConnectionState.h‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
2+
//
3+
// ConnectionState.h
4+
// TCRPROXYSDK
5+
//
6+
// Created by cyy on 2025/09/30.
7+
//
8+
9+
#import <Foundation/Foundation.h>
10+
11+
NS_ASSUME_NONNULL_BEGIN
12+
13+
/// 连接状态枚举定义
14+
typedef NS_ENUM(NSInteger, ConnectionState) {
15+
/// 连接断开
16+
Disconnected = 0,
17+
/// 连接中/重连中
18+
Connecting = 1,
19+
/// 连接完成
20+
Connected = 2
21+
};
22+
23+
/// 连接状态工具类
24+
@interface ConnectionStateHelper : NSObject
25+
26+
/// 从状态值获取连接状态枚举
27+
/// @param state 状态值
28+
/// @return 连接状态枚举
29+
+ (ConnectionState)connectionStateFromValue:(NSInteger)state;
30+
31+
/// 获取连接状态描述
32+
/// @param state 连接状态
33+
/// @return 状态描述字符串
34+
+ (NSString *)descriptionForConnectionState:(ConnectionState)state;
35+
36+
@end
37+
38+
NS_ASSUME_NONNULL_END

‎SDK/TCRPROXYSDK.xcframework/ios-arm64_x86_64-simulator/TCRPROXYSDK.framework/Headers/Proxy.h‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
//
77

88
#import <Foundation/Foundation.h>
9+
#import <TCRPROXYSDK/ProxyConnectionDelegate.h>
910

1011
NS_ASSUME_NONNULL_BEGIN
1112

@@ -35,6 +36,14 @@ NS_ASSUME_NONNULL_BEGIN
3536
/// 停止代理服务
3637
- (void)stopProxy;
3738

39+
/// 设置连接状态变化监听器
40+
/// 通过此接口可以监听代理服务的连接状态变化，包括：
41+
/// - 连接断开
42+
/// - 连接中/重连中
43+
/// - 连接完成
44+
/// @param delegate 连接状态变化监听器，传nil可清除监听
45+
- (void)setConnectionDelegate:(nullable id<ProxyConnectionDelegate>)delegate;
46+
3847
@end
3948

4049
NS_ASSUME_NONNULL_END

‎SDK/TCRPROXYSDK.xcframework/ios-arm64_x86_64-simulator/TCRPROXYSDK.framework/Headers/ProxyConnectionDelegate.h‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
2+
//
3+
// ProxyConnectionDelegate.h
4+
// TCRPROXYSDK
5+
//
6+
// Created by cyy on 2025/09/30.
7+
//
8+
9+
#import <Foundation/Foundation.h>
10+
#import <TCRPROXYSDK/ConnectionState.h>
11+
12+
NS_ASSUME_NONNULL_BEGIN
13+
14+
/// 连接状态回调协议
15+
@protocol ProxyConnectionDelegate <NSObject>
16+
17+
/// 连接状态变化回调
18+
/// @param state 当前连接状态
19+
/// @param message 状态描述信息
20+
- (void)onConnectionStateChanged:(ConnectionState)state message:(NSString *)message;
21+
22+
@end
23+
24+
NS_ASSUME_NONNULL_END

0 commit comments

Comments
 (0)