长连接通道

更新时间：2025-11-21 16:14:01

长连接通道（MQTT），提供IoT业务协议封装的云端数据下行能力，同时为App提供订阅、取消订阅、发布（暂未启用）、云端下行数据监听等能力。

// 导入长连接通道SDK头文件
#import <RTCXAppExpress/RTCXAppExpress.h>

API接口

长连接通道相关API接口如下：

typedef NS_ENUM(NSInteger, RTCXLinkAppStatus) {
    RTCXLinkAppStatusConnected,
    RTCXLinkAppStatusRefused,
    RTCXLinkAppStatusClosed,
    RTCXLinkAppStatusError,
    RTCXLinkAppStatusProtocolError,
    RTCXLinkAppStatusClosedByBroker
};

/**
 连接通道连接状态侦听者
 */
@protocol LRTCXLinkAppConnectListener<NSObject>
/** 通道连接状况改变
 @param connectState 参见枚举 `RTCXLinkAppStatus`
 */
-(void)onLinkAppConnectState:(RTCXLinkAppStatus)connectState;
@end

@protocol RTCXLinkAppDownListener <NSObject>
/**
 下推数据监听
 
 @param data 消息内容。
 @param iotId 设备唯一标识
 @param topic 下推 Topic 的业务部分，由具体业务确定
 */
-(void)onLinkDownData:(NSData *_Nullable)data topic:(NSString * _Nullable)topic iotId:(NSString *)iotId;

@optional
/**
 数据使用 `onLinkDownData:topic:iotId:` 上抛时，可以先过滤一遍，返回 NO，则不上抛；返回 YES，则会使用 `onLinkDownData:topic:iotId:` 上抛
 
 @param iotId 设备唯一标识
 @param topic 下推 Topic 的业务部分，由具体业务确定
 @return 返回 NO，则不上抛；返回 YES，则会使用 `onLinkDownData:topic:iotId:` 上抛
 */
-(BOOL)arrowHandle:(NSString *)iotId topic:(NSString * _Nullable)topic;
@end

//回调函数定义如下
typedef void(^RTCXLinkAppResponseHandler)(RTCXLinkAppResponse *response);

@protocol RTCXLinkAppProtocol <NSObject>

@property (nonatomic, assign) RTCXLinkAppStatus status;
/**
 设置通道的下推侦听者，如果不需要用的时候，记得调用 `removeDownStreamListener:` 。
 
 @param downListener 侦听下推消息，参见 `RTCXLinkAppDownListener`
 */
- (void)addLinkDownDataListener:(id<RTCXLinkAppDownListener>)downListener;

/**
 取消通道的某个下推侦听者
 
 @param downListener 侦听下推消息，参见 `LKExpDownListener`
 */
-(void)removeLinkDownDataListener:(id<RTCXLinkAppDownListener>)downListener;

/**
 app 向云端订阅 topic 的接口。
 
 @param topic 订阅的消息的 topic，由具体业务确定。暂未启用，建议传Nil，可选
 @param productKey 设备型号  必选
 @param deviceName 设备序列号SN  必选
 @param iotId 平台为设备颁发的ID，设备的唯一标识符 必选
 @param deviceType  设备类型 0：普通设备；1：私有化设备；2：AP设备；默认0，必选
 @param completionHandler 订阅流程完成的 callback，如果 error 为空表示订阅成功，否则订阅失败
 */
- (void)subscribeToTopic:(NSString * _Nullable)topic productKey:(NSString * _Nonnull)productKey deviceName:(NSString * _Nonnull)deviceName iotId:(NSString * _Nonnull)iotId deviceType:(NSInteger)deviceType complete:(void (^)(NSError  * _Nullable error))completionHandler;

/**
 app向云端取消订阅 topic 的接口。
 
 @param topic 取消订阅的消息的 topic，由具体业务确定。暂未启用，建议传Nil，可选
 @param productKey 设备型号  必选
 @param deviceName 设备序列号SN  必选
 @param iotId 平台为设备颁发的ID，设备的唯一标识符 必选
 @param deviceType  设备类型 0：普通设备；1：私有化设备；2：AP设备；默认0，必选
 @param completionHandler 取消订阅流程完成的 callback，如果 error 为空表示订阅成功，否则订阅失败
 */
- (void)unsubscribeToTopic:(NSString * _Nullable)topic productKey:(NSString * _Nonnull)productKey deviceName:(NSString * _Nonnull)deviceName iotId:(NSString * _Nonnull)iotId deviceType:(NSInteger)deviceType complete:(void (^)(NSError  * _Nullable error))completionHandler;

/**
 RPC请求接口，封装了业务的上行 request 以及下行 response。
 
 @param topic 请求的 topic，由具体业务确定。暂未启用，建议传Nil，可选
 @param productKey 设备型号  必选
 @param deviceName 设备序列号SN  必选
 @param iotId 平台为设备颁发的ID，设备的唯一标识符 必选
 @param deviceType  设备类型 0：普通设备；1：私有化设备；2：AP设备；默认0，必选
 @param opts 可选配置项，可空，预留
 @param data 业务参数。
 @param responseHandler 业务服务器响应回调接口，参见 `RTCXLinkAppResponse`
 
-(void)invokeToTopic:(NSString * _Nullable)topic productKey:(NSString * _Nonnull)productKey deviceName:(NSString * _Nonnull)deviceName iotId:(NSString * _Nonnull)iotId deviceType:(NSInteger)deviceType opts:(NSDictionary* _Nullable)opts data:(NSData *)data respHandler:(RTCXLinkAppResponseHandler)responseHandler;
 */

/**
  发布消息接口，不同于 `invokeToTopic:productKey:deviceName:iotId:deviceType:opts:params:respHandler:` 。这个接口不会有业务回执。
 
 @param topic 请求的 topic，由具体业务确定。暂未启用，建议传Nil，可选
 @param productKey 设备型号  必选
 @param deviceName 设备序列号SN  必选
 @param iotId 平台为设备颁发的ID，设备的唯一标识符 必选
 @param deviceType  设备类型 0：普通设备；1：私有化设备；2：AP设备；默认0，必选
 @param data 业务参数。
 @param completeCallback 业务服务器响应回调接口
 
-(void)publishToTopic:(NSString * _Nullable)topic productKey:(NSString * _Nonnull)productKey deviceName:(NSString * _Nonnull)deviceName iotId:(NSString * _Nonnull)iotId deviceType:(NSInteger)deviceType data:(NSData *)data complete:(void(^)(NSError* _Nullable))completeCallback;
 */
 
/**
 增加通道连接状态变化 listener
 @param listener 通道连接状态侦听者
 */
-(void)addLinkConnectListener:(id<LRTCXLinkAppConnectListener>)listener;

/**
 移除通道连接状态变化 listener
 @param listener 通道连接状态侦听者
 */
-(void)removeLinkConnectListener:(id<LRTCXLinkAppConnectListener>)listener;

@end

订阅

长连接通道，采用MQTT协议，基于订阅/发布模型设计。订阅某个Topic后，当其他服务或者终端往这个Topic发布消息时，便能通过下行监听收到消息。下面以订阅某台设备Topic为例。

__weak typeof(self) weakSelf = self;
[LKSignallingService(RTCXLinkAppProtocol) subscribeToTopic:nil productKey:self.curDevice.productKey deviceName:self.curDevice.deviceName iotId:self.curDevice.iotId deviceType:0 complete:^(NSError * _Nullable error) {
    if (error) {
        [weakSelf showToast:[NSString stringWithFormat:@"%ld : %@",error.code,error.userInfo[NSLocalizedFailureReasonErrorKey]]];
    }
    weakSelf.isSubscribed = error == nil;
}];

取消订阅

取消订阅是订阅的逆过程，二者遵循同样的Topic规则。取消订阅之后，将不会再收到该Topic的下行消息，仍然以取消订阅某台设备Topic为例。

__weak typeof(self) weakSelf = self;
[LKSignallingService(RTCXLinkAppProtocol) unsubscribeToTopic:nil productKey:self.curDevice.productKey deviceName:self.curDevice.deviceName iotId:self.curDevice.iotId deviceType:0 complete:^(NSError * _Nullable error) {
    if (error) {
        [weakSelf showToast:[NSString stringWithFormat:@"%ld : %@",error.code,error.userInfo[NSLocalizedFailureReasonErrorKey]]];
    }
    weakSelf.isSubscribed = NO;
}];

注册下行监听

注册下行Listener，才能接收到订阅过的Topic数据

// 1. 注册下行数据监听

[LKSignallingService(RTCXLinkAppProtocol) addLinkDownDataListener:self];

// 2. 实现下行数据监听协议方法

#pragma mark -- RTCXLinkAppDownListene --
-(void)onLinkDownData:(NSData *_Nullable)data topic:(NSString * _Nullable)topic iotId:(NSString *)iotId {
    NSString *text = self.messageL.text?:@"";
    self.messageL.text = [NSString stringWithFormat:@"%@\n%@",text,[[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]];
}

-(BOOL)arrowHandle:(NSString *)iotId topic:(NSString * _Nullable)topic {
    if ([iotId isEqualToString:self.curDevice.iotId]) {
        return YES;// 返回YES，说明对此topic感兴趣,SDK会调用[listener onLinkDownData:iotId:]
    }
    return NO;
}

注册连接状态监听

注册通道连接状态Listener，当连接状态发生变化时，可接收到状态通知

// 1. 注册状态监听

[LKSignallingService(RTCXLinkAppProtocol) addLinkConnectListener:self];

// 2. 实现状态监听协议方法

#pragma mark -- LRTCXLinkAppConnectListener --
-(void)onLinkAppConnectState:(RTCXLinkAppStatus)connectState {
    [self getConnectStatusString:connectState];
}