//
//  MtopService.h
//  mtopext
//
//  mtop api 调用统一入口
//
//  Created by sihai on 4/11/14.
//  Copyright (c) 2014 Taobao. All rights reserved.
//

#import <Foundation/Foundation.h>
#import <mtopext/MtopExtRequestDelegate.h>
#import <mtopext/MtopExtRequest.h>
#import <mtopext/MtopExtResponse.h>
#import <mtopext/LoginProtocol.h>
#import <mtopext/TBSDKConfiguration.h>
#import <mtopext/TBSDKAccountInfo.h>

/**
 * 内置二方MTOP实例ID
 */
#define MTOP_ID_INNER     @"INNER"


/**
 * 内置三方MTOP实例ID
 */
#define MTOP_ID_OPEN      @"OPEN"


/**
 * MTOP 实例接口。MTOP 支持多实例，目前支持2种类型(MtopType)，每一种类型均可创建多个实例，不同的实例以不同ID识别。
 *
 * 注意：该类型禁止被继承。
 */
@interface MtopService : NSObject


/**
 * 获取默认实例，默认返回ID为 MTOP_ID_INNER（二方类型）的实例。但是可以通过配置文件 mtopsdk_configuration.plist
 * 来设置默认返回类型。配置文件配置规则(示例)如下：
 *
 * Root (Dictionary)
 *  |
 *  |---DefaultID : @"INNER" (@"INNER" 内置二方实例; @“OPEN” 内置三方实例；或其他自定义实例 )
 *
 * @return MTOP实例
 */
+ (nullable instancetype) getInstance;



/**
 * 通过实例ID来获取对应实例。其中已经内置ID为 MTOP_ID_INNER 与 MTOP_ID_OPEN 实例, 如果需要新增实例，请通过
 * mtopsdk_configuration.plist 配置文件来新增实例，只有在 plist 中注册过的ID，才可以使用。配置文件配置规则(示例)如下：
 *
 * ROOT (dictionary)
 *  |---ExternalInstances (dictionary)
 *            |---- @"id1":@"0" (0 表示该实例类型为二方实例)
 *            |-----@"id2":@"1" (1 表示该实例类型为三方实例)
 *
 * 注意：ID为 MTOP_ID_INNER 与 MTOP_ID_OPEN 实例不可在配置文件中修改类型，已经分别设置为二方、三方实力。若不是
 *      MTOP_ID_INNER 与 MTOP_ID_OPEN，且名称未在plist中注册，返回nil.
 *
 * @param Id 索引MTOP实例的KEY值。可以为 MTOP_ID_INNER/MTOP_ID_OPEN 或者定义在 mtopsdk_configuration.plist 中
 * @return MTOP实例。若非内置实例且名称未注册，则返回nil.
 */
+ (nullable instancetype) getInstanceWithID:(nonnull NSString *)Id;


/**
 * 获取指定类型的实例。该接口废弃，使用 getInstanceWithName: 接口代替，kTypeInner对应 MTOP_ID_INNER，
 * kTypeOpen 对应 MTOP_ID_OPEN。
 *
 * @param type, 指定二方(kTypeInner) 或三方(kTypeOpen)
 * @return MTOP实例。若该类型未创建，则会同步创建一新实例。
 */
+ (nullable instancetype) getInstanceWithType:(MtopType)type DEPRECATED_MSG_ATTRIBUTE("请使用[getInstanceWithID:]替换");


/**
 * 获取默认实例，实例ID为 MTOP_ID_OPEN. 该方法线程安全。
 *
 * @return MTOP实例
 */
+ (nullable instancetype) shareInstance DEPRECATED_MSG_ATTRIBUTE("兼容原三方API");


/**
 * 当前实例的配置
 */
- (nonnull TBSDKConfiguration *)configuration;


/**
 * 当前实例ID。
 */
- (nonnull NSString *)ID;


/**
 * 当前实例类型。
 */
- (MtopType)type;


/**
 * 安装一个自定义的登录模块
 * 在请求API时, 判断本地无session时, 会调用该模块进行登录, 或者服务端返回session效时会调用该模块进行登录, 登录成功后重放失败请求。
 * 在登录的过程中, 有需要登录请求的API的请求会被 pending 到队列, 然后在登录成功后重放, 会登录失败后直接失败
 *
 * @param module, 登陆模块的实现
 */
- (void) installCustomLoginModule:(nonnull id<LoginProtocol>)module;

/**
 * 安装一个自定义的授权模块
 * 在请求API时, 判断本地无AUTH时, 会调用该模块进行登录, 或者服务端返回AUTH无效时会调用该模块进行登录, 登录成功后重放失败请求。
 * 在登录的过程中, 有需要登录请求的API的请求会被 pending 到队列, 然后在登录成功后重放, 会登录失败后直接失败
 *
* @param module, 授权模块的实现
 */
- (void) installCustomAuthModule:(nonnull id<MtopAuthProtocol>)module;


/**
 * 获取当前实例上的登录接口
 */
- (nonnull id<LoginProtocol>) loginModule;


/**
 * 获取当前实例上的鉴权接口
 */
- (nonnull id<MtopAuthProtocol>) authModule;


/**
 * 获取账户信息
 */
- (nullable TBSDKAccountInfo *)currentAccount;

/*!
 * 安装防刷delegate
 * @param delegate
 */
// TO DO
//- (id<FloodProtectionDelegate>) installFloodProtectionDelegate: (id<FloodProtectionDelegate>) delegate;


/**
 * 同步调用API
 *
 * @param request
 * @return MtopExtResponse API响应
 */
- (nullable MtopExtResponse*) sync_call: (nonnull MtopExtRequest*) request;


/**
 * 异步调用API
 *
 * @param request
 * @param delegate
 *
 */
- (void)async_call:(nonnull MtopExtRequest *)request;

/**
 * 异步调用API
 *
 * @param request
 * @param delegate
 *
 */
- (void) async_call: (nonnull MtopExtRequest*) request delegate: (nullable id<MtopExtRequestDelegate>) delegate;


/**
 * 异步调用API, 跳过startFilter之前的filter
 *
 * @param request
 * @param delegate
 * @param startFilter
 *
 */
- (void) async_call:(nonnull MtopExtRequest*) request delegate: (nullable id<MtopExtRequestDelegate>) delegate startFilter: (nullable NSString*) startFilter;

/**
 * 提供一个便捷的方法, 同步调用没有参数的API
 * 
 * @param apiName       API名称
 * @param apiVersion    API版本
 * @return MtopExtResponse API响应
 */
- (nullable MtopExtResponse*) sync_call: (nonnull NSString*) apiName apiVersion: (nonnull NSString*) apiVersion;


/**
 * 提供一个便捷的方法, 同步调用API
 *
 * @param apiName       API名称
 * @param apiVersion    API版本
 * @param bizParameters API业务参数
 * @return MtopExtResponse API响应
 */
- (nullable MtopExtResponse*) sync_call: (nonnull NSString*) apiName apiVersion: (nonnull NSString*) apiVersion bizParameters: (nullable NSDictionary*) bizParameters;

#pragma mark 新增mtop添加／删除全局header以及query参数接口

/**
 * 添加一个全局http请求头(不做URLENCODE)
 *
 * @param value     HTTP头value, 请不要做urlencode, 底层会统一做的
 * @param key       HTTP头key
 */
- (void) addCustomHttpHeader: (nonnull NSString*) value forKey: (nonnull NSString*) key;


/**
 * 添加一个全局http请求头
 * @param value     HTTP头value, 请不要做urlencode, 底层会统一做的
 * @param key       HTTP头key
 */
- (void) addHttpHeader: (nonnull NSString*) value forKey: (nonnull NSString*) key;


/**
 * 提供一个移除全局自定义请求头的方法
 */
- (void)removHttpHeader:(nonnull NSString *)key;


/**
 * 添加一个全局扩展参数和data参数平级
 * @param value     参数值
 * @param key       参数名
 */
- (void) addExtParameter: (nonnull id) value forKey: (nonnull NSString*) key;


/**
 * 移除一个全局扩展参数
 * @param key
 */
- (void) removeExtParameter: (nonnull NSString*) key;


@end