# iOS SDK 基础功能
### 调用规则
1. 主要业务均通过 QDIM 单利调用
```
@interface QDIM : NSObject
/**
获取 SDK 实例
@return QDIMSDK实例
*/
+ (instancetype)sharedSDK;
@end
```
2. 通知方式
SDK 通过两种方式通知上层 API 调动结果:回调(callback) 和 委托(delegate),两种方式都只在主线程触发。
一般回调接口直接反映在对应接口的 `completion` 参数上,调用时设置即可。而委托则需要开发者在合适时机在对应管理类上进行添加和移除:一般推荐在相应 ViewController 或管理类初始化进行委托注册,在其销毁时进行移除。
例如,开发者需要在会话页监听发送的结果
```
@implementation IMSessionViewController
- (void)viewDidLoad
{
...
[[QDIM sharedSDK] addChatDeleage:self];
...
}
#pragma mark - QDChatManagerDelegate
- (void)willSendMessage:(QDMessage *)message
{
}
- (void)dealloc
{
...
[[QDIM sharedSDK] removeChatDelegate:self];
...
}
@end
```
### 初始化 SDK
1. 引入相关头文件 `#import <IMSDK/IMSDK.h>`
2. 在使用 SDK 任何方法之前,都应该首先调用初始化方法。正常业务情况下,初始化方法有仅只应调用一次。
```
@interface QDIM : NSObject
/**
SDK初始化注册
@param option 注册选项
*/
- (void)registerWithOption:(QDSDKOption *)option;
@end
```
QDSDKOption 选项参数列表
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| domain | NSString | 域名 |
| ip | NSString | iP 地址 |
| port | NSInteger | 端口号 |
| pushMode | NSInteger | 推送模式 0:正式环境 1:测试环境 |
调用实例
```
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
...
//推荐在程序启动的时候初始化 IMSDK
QDSDKOption *option = [QDSDKOption sdkOptionWithDomain:@" domain " ip:@" iP " port: ip pushMode: pushModel] ];
[[QDIM sharedSDK] registerWithOption:option];
...
}
```
### 登录
1. 登录
```
/**
登录服务相关Block
@param error 执行结果,如果成功error为nil
*/
typedef void(^QDLoginHandler)(NSError * __nullable error);
@interface QDIM : NSObject
/**
登录
@param userName 用户名
@param userPwd 密码
*/
- (void)loginWithUserName:(NSString *)userName userPwd:(NSString *)userPwd completion:(QDLoginHandler)completion;
@end
```
实例
```
[[QDIM sharedSDK] loginWithUserName:@"your account" userPwd:@" your pwd" completion:^(NSError * _Nullable error) { }];
```
error 为登录错误信息,成功则为 nil。
2. 登出
```
@interface QDIM : NSObject
/**
客户端退出
@param completion 用户在登出是需要调用这个接口进行 SDK 相关数据的清理,回调 Block 中的 error 只是指明和服务器的交互流程中可能出现的错误,但不影响后续的流程。
如用户登出时发生网络错误导致服务器没有收到登出请求,客户端仍可以登出(切换界面,清理数据等),但会出现推送信息仍旧会发到当前手机的问题。
*/
- (void)logout:(nullable QDLoginHandler)completion;
@end
```
3. 回调
可以在登录的时候添加 委托
```
/**
添加登录委托
@param delegate 登录委托
*/
- (void)addLoginDelegate:(id<QDLoginManagerDelegate>)delegate;
/**
移除登录委托关系
@param delegate 登录委托
*/
- (void)removeLoginDelegate:(id<QDLoginManagerDelegate>)delegate;
/**
登录服务相关Block
@param error 执行结果,如果成功error为nil
*/
typedef void(^QDLoginHandler)(NSError * __nullable error);
/**
* 登录步骤枚举
*/
typedef NS_ENUM(NSInteger, QDLoginStep)
{
/**
* 连接服务器
*/
QDLoginStepLinking = 1,
/**
* 连接服务器成功
*/
QDLoginStepLinkOK,
/**
* 连接服务器失败
*/
QDLoginStepLinkFailed,
/**
* 登录
*/
QDLoginStepLogining,
/**
* 登录成功
*/
QDLoginStepLoginOK,
/**
* 登录失败
*/
QDLoginStepLoginFailed,
/**
* 开始同步
*/
QDLoginStepSyncing,
/**
* 同步完成
*/
QDLoginStepSyncOK,
/**
* 连接断开
*/
QDLoginStepLoseConnection,
/**
* 网络切换
* @discussion 这个并不是登录步骤的一种,但是UI有可能需要通过这个状态进行UI展现
*/
QDLoginStepNetChanged,
};
/**
* 被踢下线的原因
*/
typedef NS_ENUM(NSInteger, QDKickReason)
{
/**
* 被另外一个客户端踢下线 (互斥客户端一端登录挤掉上一个登录中的客户端)
*/
QDKickReasonByClient = 1,
/**
* 被服务器踢下线
*/
QDKickReasonByServer = 2,
/**
* 被另外一个客户端手动选择踢下线
*/
QDKickReasonByClientManually = 3,
};
@protocol QDLoginManagerDelegate <NSObject>
@optional;
/**
* 登录回调
*
* @param step 登录步骤
* @discussion 这个回调主要用于客户端UI的刷新
*/
- (void)onLogin:(QDLoginStep)step;
/**
* 被踢(服务器/其他端)回调
*
* @param code 被踢原因
* @param clientType 发起踢出的客户端类型
*/
- (void)onKick:(QDKickReason)code clientType:(QDPlatfromType)clientType;
@end
```
IMSDK 在登录后会同步组织架构、群信息、离线消息,系统通知等。
### 企业通讯录
SDK 会在登录后去自动获取企业的通讯录信息,一般用户只需要本地获取通讯录信息,同样 SDK 也提供了远程获取群信息的接口。
本地获取
```
@interface QDDataHandler : NSObject
/**
根据人员id获取人员信息
@param ID 用户id
*/
+ (nullable QDUser *)getUserByUserID:(NSString *)ID;
/**
根据用户id获取大量用户信息
@param userIdList 用户id数组
*/
+ (NSArray *)getUsersByUserIDList:(NSArray *)userIdList;
/**
根据子ID获取部门
@param ID 节点ID
*/
+ (QDDept *)getDeptByID:(NSString *)ID;
/**
根据部门ID批量获取部门信息
@param deptIdList 部门ID数组
@return 部门信息列表
*/
+ (NSArray<QDDept *> *)getDetpsByDeptIDList:(NSArray *)deptIdList;
/**
获取用户所在组织
@param userID 用户ID
*/
+ (NSArray *)getUserOrgByUserID:(NSString *)userID;
@end
```
远程获取
```
@interface QDIM : NSObject
/**
获取组织架构
*/
- (void)fetchDeptInfo;
/**
获取组织和好友所有人员基本信息
*/
- (void)getAllOrgInfo;
@end
```
当获取完成组织架构的所有人员信息后 会发送通知 `QDNotificationKeyOnGetAllUsersDone`