|
//
|
// MtopExtRequest.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/MtopAuthProtocol.h>
|
#import <mtopext/TBSDKUTUtility.h>
|
|
@class TBSDKRequest;
|
|
|
#pragma mark - 枚举定义
|
|
|
/**
|
* cache 策略
|
*/
|
typedef NS_ENUM(NSUInteger,CachePolicy) {
|
/**
|
* 默认cache策略。使用这个策略时，request会先查看cache中是否有可用的缓存数据。如果没有，request会像普通request那样工作。
|
* 如果有缓存数据并且缓存数据没有过期，那么request会使用缓存的数据，而且不会向服务器通信。如果缓存数据过期了，request会先
|
* 进行GET请求来向服务器询问数据是否有新的版本。如果服务器说缓存的数据就是当前版本，那么缓存数据将被使用，不会下载新数据。
|
* 在这种情况下，cache的有效期将被设定为服务器端提供的新的有效期。如果服务器提供更新的内容，那么新内容会被下载，并且新的数据
|
* 以及它的有效期将被写入cache。
|
*/
|
AskServerIfModifiedWhenStaleCachePolicy = 0,
|
|
|
/**
|
* 不使用任何cache策略，普通的请求
|
*/
|
DoNotReadAndWriteCacheCachePolicy,
|
|
|
/**
|
* 用于强制刷新，没有cache回调，一定请求网络数据
|
*/
|
AskServerIfModifiedCachePolicy,
|
|
|
/**
|
* 用于强制刷新，有cache回调，一定请求网络数据
|
*/
|
AskServerIfModifiedCacheAndReturnCachePolicy,
|
|
|
/**
|
* 用于MessageBox使用，有cache回调，一定请求网络数据
|
*/
|
AskServerIfModifiedCacheAndReturnCachePolicyMessageBox
|
|
};
|
|
|
/**
|
* 登录控制参数
|
*/
|
typedef NS_ENUM(NSInteger,MtopSessionExpiredOption) {
|
/**
|
* SDK内部标记用，外部业务禁止使用
|
*/
|
MtopSessionExpiredOptionDummy = -1,
|
|
|
/**
|
* Session失效时，什么都不做
|
*/
|
MtopSessionExpiredOptionNone = 0,
|
|
|
/**
|
* Session失效时，只做Auto Login
|
*/
|
MtopSessionExpiredOptionAutoLogin = 1,
|
|
|
/**
|
* Session失效时，先Auto Login，如果Auto Login失败，唤起登录界面
|
*/
|
MtopSessionExpiredOptionAutoLoginAndManualLogin = 2
|
|
};
|
|
|
|
/**
|
* 授权控制参数
|
*/
|
typedef NS_ENUM(NSInteger,MtopAuthExpiredOption){
|
/**
|
* SDK内部标记用，外部业务禁止使用
|
*/
|
MtopAuthExpiredOptionDummy = -1,
|
|
|
/**
|
* Auth失效时，什么都不做
|
*/
|
MtopAuthExpiredOptionNone = 0,
|
|
|
/**
|
* Auth失效时，只做Auto Auth
|
*/
|
MtopAuthExpiredOptionAutoAuth = 1,
|
|
|
/**
|
* Auth失效时，先Auto Auth，如果Auto Auth失败，唤起登录界面
|
*/
|
MtopAuthExpiredOptionAutAuthAndManualAuth = 2
|
};
|
|
|
|
/**
|
* WUA 控制参数
|
*/
|
typedef NS_ENUM(NSUInteger,WuaType) {
|
kWuaDefault = 3,
|
kWuaGeneral,
|
kWuaMini,
|
kWuaAtlas
|
};
|
|
|
/**
|
* 控制请求是属于导购单元还是交易单元。该参数最终体现在请求域名上。
|
*/
|
typedef NS_ENUM(NSUInteger,MtopUnitStrategy) {
|
/**
|
* 导购单元(默认所有请求走导购单元)
|
*/
|
MtopUnitStrategyGuideUnit = 1,
|
|
|
/**
|
* 交易单元
|
*/
|
MtopUnitStrategyTradeUnit
|
};
|
|
#pragma mark - MTOP请求对象
|
|
/**
|
* MTOP请求对象接口。
|
*/
|
@interface MtopExtRequest : NSObject
|
|
|
/**
|
* 本地请求的自定义域名。
|
*/
|
@property(nonatomic, strong) NSString* customHost;
|
|
|
/**
|
* 同步请求, 还是异步请求。默认值为 NO。
|
* 其值取决于对象 [MtopService sync_call:] 与 [MtopService async_call:]
|
*/
|
@property(nonatomic, assign) BOOL isSync;
|
|
|
/**
|
* 指示是否需要登录态，由业务设置。
|
* P.S. 登录相关为什么如此命名？具体原因己不可考。基于兼容性考虑，已不便变动。
|
*/
|
@property(nonatomic, assign) BOOL isNeedEcode;
|
|
|
/**
|
* Session 失效选项。isNeedEcode = YES 的情况下有效。
|
*/
|
@property(nonatomic, assign) MtopSessionExpiredOption sessionExpiredOption;
|
|
|
/**
|
* 指示是否需要Auth授权
|
*/
|
@property(nonatomic, assign) BOOL isNeedAuth;
|
|
|
/**
|
* 授权过期选项。isNeedAuth = YES 的情况下有效。
|
*/
|
@property(nonatomic, assign) MtopAuthExpiredOption authExpiredOption;
|
|
|
/**
|
* 是否启用虚机签名
|
*/
|
@property(nonatomic, assign) BOOL isEnableWUA;
|
|
|
/**
|
* 虚机签名类型。isEnableWUA = YES 的情况下有效。
|
*/
|
@property(nonatomic, assign) WuaType wuaType;
|
|
|
/**
|
* 本地请求的 ttid (渠道号)。如业务未设置，以 TBSDKConfiguration.wapTTID 值为准。
|
*/
|
@property(nonatomic, strong) NSString* ttid;
|
|
|
/**
|
* cache策略
|
*/
|
@property(nonatomic, assign) CachePolicy cachePolicy;
|
|
|
/**
|
* 计算cache key 时需要排查的参数名列表.
|
* 备注：目前用数组而没有用dict是合理的, 参数数量不会多。
|
*/
|
@property(nonatomic, strong) NSMutableArray* excludedCacheKeyParameters;
|
|
|
/**
|
* 是否已经被取消
|
*/
|
@property(atomic, assign) BOOL isCanceled;
|
|
|
/**
|
* 是否需要校验服务端的响应
|
*/
|
@property(assign, nonatomic) BOOL isNeedValidateResponse;
|
|
|
/**
|
* 重试的次数
|
*/
|
@property(nonatomic, assign, readonly) int8_t retryCount;
|
|
|
/**
|
* 自定义请求user id, 影响请求 x-uid 头域
|
*/
|
@property(nonatomic, strong) NSString *userID;
|
|
|
/**
|
* SDK 内部生成的端側trace id, 请求 x-c-traceid 头域值。
|
*/
|
@property(nonatomic, strong, readonly) NSString *clientTraceId;
|
|
|
/**
|
* 全链路埋点ID。
|
*/
|
@property (nonatomic, copy, readonly) NSString *fullTraceID;
|
|
|
/**
|
* 业务ID，值由构造参数传入
|
*/
|
@property(nonatomic, strong, readonly) NSString *bizID;
|
|
|
/**
|
* 当前请求的page name, 埋点用。
|
*/
|
@property(nonatomic, copy) NSString *pageName;
|
|
|
/**
|
* 当前请求的page url, 埋点用。
|
*/
|
@property(nonatomic, copy) NSString *pageUrl;
|
|
|
/**
|
* 当前请求的单元域名策略。
|
*/
|
@property(nonatomic, assign) MtopUnitStrategy UnitStrategy;
|
|
|
/**
|
* 是否使用主线程回调。YES: 不从主线程回调, NO: 从主线程回调。
|
*/
|
@property(nonatomic, assign) BOOL isNotUseMainThreadCallback;
|
|
|
/**
|
* 淘内开放API授权参数对象
|
*/
|
@property (nonatomic,strong, readonly) AuthParamObj *authObj;
|
|
|
#pragma mark - 小程序开放体系参数
|
|
/**
|
* 开放小程序 Appkey. 影响协议头： x-mini-appkey
|
*/
|
@property (nonatomic, strong) NSString *miniAppkey;
|
|
|
/**
|
* 小程序appkey/插件appkey. 影响协议头： x-req-appkey
|
*/
|
@property (nonatomic, strong) NSString *requestAppkey;
|
|
|
/**
|
* 开放业务平台标识码, 目前只有 mini-app / baichuan 两种类型。影响协议头： x-open-biz
|
*/
|
@property (nonatomic, strong) NSString *openBizCode;
|
|
|
/**
|
* 开放业务拓展字段。影响协议头： x-open-biz-data
|
*/
|
@property (nonatomic, strong) NSString *openBizData;
|
|
|
/**
|
* 原底层的 mtop 请求对象. 外部业务禁止修改。
|
*/
|
@property(nonatomic, strong) TBSDKRequest* mrequest;
|
|
#pragma mark - 回调
|
|
/**
|
* Block回调，请求开始
|
*/
|
@property(atomic, copy) MtopExtRequestStarted startedBlock;
|
|
|
/**
|
* Block回调，请求失败
|
*/
|
@property(atomic, copy) MtopExtRequestFailed failedBlock;
|
|
|
/**
|
* Block回调，请求成功
|
*/
|
@property(atomic, copy) MtopExtRequestSucceed succeedBlock;
|
|
|
/**
|
* Delegate回调, 该回调与block回调语义等价，业务方可选择合适自己的方式来设置回调。
|
*/
|
@property(atomic, weak, atomic) id<MtopExtRequestDelegate> delegate;
|
|
|
#pragma mark - 埋点信息
|
|
/**
|
* 埋点信息
|
*/
|
@property(strong, nonatomic) UTDataSet* mtopUT;
|
|
|
#pragma mark - 废弃参数
|
|
@property(nonatomic, strong) NSString *h5URL DEPRECATED_MSG_ATTRIBUTE("使用 pageUrl 代替");
|
@property(nonatomic, strong) NSString* wuaPageName DEPRECATED_MSG_ATTRIBUTE("无用参数");
|
@property(nonatomic, strong) NSString* wuaCtrlName DEPRECATED_MSG_ATTRIBUTE("无用参数");
|
@property(nonatomic, assign) float xCoordinate DEPRECATED_MSG_ATTRIBUTE("无用参数");
|
@property(nonatomic, assign) float yCoordinate DEPRECATED_MSG_ATTRIBUTE("无用参数");
|
@property(nonatomic, strong) NSArray *customHostList DEPRECATED_MSG_ATTRIBUTE("无用参数");
|
@property(nonatomic, weak) id context DEPRECATED_MSG_ATTRIBUTE("无用参数");
|
@property(nonatomic, assign) BOOL isFromOfflineOperation DEPRECATED_MSG_ATTRIBUTE("无用参数");
|
@property(nonatomic, assign) ServerType serverType DEPRECATED_MSG_ATTRIBUTE("无用参数");
|
@property(nonatomic, assign) BOOL isForceHttps DEPRECATED_MSG_ATTRIBUTE("无用参数");
|
@property(nonatomic, assign) BOOL isForceSpdy DEPRECATED_MSG_ATTRIBUTE("无用参数");
|
|
/**
|
* 初始化一个API请求对象
|
* @param apiName API名称
|
* @param apiVersion API版本
|
* @return
|
* MtopExtRequest
|
*/
|
- (MtopExtRequest*) initWithApiName: (NSString*) apiName apiVersion: (NSString*) apiVersion;
|
|
/*!
|
* 初始化一个API请求对象
|
* @param apiName API名称
|
* @param apiVersion API版本
|
* @param bizID 业务组件ID
|
* @return
|
* MtopExtRequest
|
*/
|
- (MtopExtRequest *)initWithApiName:(NSString *)apiName apiVersion:(NSString *)apiVersion bizID:(NSString *)bizID;
|
|
|
/*
|
* 设置请求不被网络库接管
|
*/
|
- (MtopExtRequest *)unHostedByNetWork;
|
|
/*!
|
* 设置网络超时
|
* @param timeout 超时时间，单位秒
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) setNetworkTimeout: (int) timeout;
|
|
/*!
|
* 走https
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) useHttps;
|
|
/*!
|
* 禁止走https
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) disableHttps;
|
|
/*!
|
* 使用post
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) useHttpPost;
|
|
/*!
|
* 添加一个http请求头
|
* @param value HTTP头value, 请不要做urlencode, 底层会统一做的
|
* @param key HTTP头key
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) addHttpHeader: (NSString*) value forKey: (NSString*) key;
|
|
/*!
|
* 一次添加多个头
|
* @param kvs
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) addHttpHeaders: (NSDictionary*) kvs;
|
|
/*!
|
* 添加一个http请求头 (该接口请求头不做UrlEncode)
|
* @param value HTTP头value, 请不要做urlencode, 底层会统一做的
|
* @param key HTTP头key
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) addCustomHttpHeader: (NSString*) value forKey: (NSString*) key;
|
|
/*!
|
* 一次添加多个头 (该接口请求头不做UrlEncode)
|
* @param kvs
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) addCustomHttpHeaders: (NSDictionary*) kvs;
|
|
|
|
/*!
|
* 添加一个协议级参数
|
* @param value 参数值
|
* @param key 参数名
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) addProtocolParameter: (NSString*) value forKey: (NSString*) key;
|
|
/*!
|
* 添加一个扩展参数和data参数平级
|
* @param value 参数值
|
* @param key 参数名
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) addExtParameter: (id) value forKey: (NSString*) key;
|
|
/*!
|
* 一次添加多个扩展参数和data参数平级
|
* @param kvs
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) addExtParameters: (NSDictionary*) kvs;
|
|
/*!
|
* 移除一个扩展参数
|
* @param key
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*
|
*/
|
- (MtopExtRequest*) removeExtParameter: (NSString*) key;
|
|
/*!
|
* 添加一个业务参数(业务级别参数)
|
* @param value 参数值
|
* @param key 参数名
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) addBizParameter: (id) value forKey: (NSString*) key;
|
|
/*!
|
* 一次添加多个业务参数(业务级别参数)
|
* @param kvs
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) addBizParameters: (NSDictionary*) kvs;
|
|
/*!
|
* 移除一个业务参数
|
* @param key
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) removeBizParameter:(NSString*) key;
|
|
/*!
|
* 为了TBSDKMtopServer兼容提供的, 不建议使用
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) clearBizParameters;
|
|
#pragma mark 排队SDK用来设置请求优先级相关参数
|
/*!
|
* 设置API请求优先级参数
|
* @param data 优先级参数
|
*/
|
- (MtopExtRequest*)addPriorityData:(NSDictionary*)data;
|
|
/*！
|
* 设置API请求优先级参数
|
* @param value
|
* @param key
|
*/
|
- (MtopExtRequest*) addPriorityData:(id)value forKey:(NSString *)key;
|
|
#pragma mark 排队SDK用来设置API请求优先级
|
/*!
|
* 设置API请求优先级Flag
|
* @param priorityFlag 优先级标识
|
*/
|
- (void) setPriorityFlag:(BOOL)priorityFlag;
|
|
/*!
|
* 添加要上传的文件
|
* @param data 文件数据
|
* @param fileName 本地文件名(全路径)
|
* @param forKey form field 的 key
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*
|
*/
|
- (MtopExtRequest*) addUploadFileWithData: (NSData*) data fileName: (NSString*) fileName forKey: (NSString*) key;
|
|
/*!
|
* 添加一个计算cache key 时排查的参数名
|
* @param name 参数名
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*) addExcludedCacheKeyParameter: (NSString*) name;
|
|
#pragma mark - 淘内开发api授权设置参数
|
/*!
|
*
|
* @param appkey 需授权的三方应用appkey
|
* @param authParam 授权参数
|
* @return
|
* MtopExtRequest 以便可以链式操作
|
*/
|
- (MtopExtRequest*)setNeedAuth:(NSString *)appkey andAuthParam:(NSDictionary *)authParam;
|
|
|
/**
|
指示生成WUA, 并设定WUA可选参数
|
|
@param pageName
|
@param ctrlName
|
@param xCoordinate
|
@param yCoordinate
|
@return 带wua的MtopExtRequest
|
*/
|
- (MtopExtRequest*) enableWUAWithPageName: (NSString*) pageName
|
ctrlName: (NSString*) ctrlName
|
xCoordinate: (float) xCoordinate
|
yCoordinate: (float) yCoordinate
|
DEPRECATED_MSG_ATTRIBUTE("enableWUAWithPageName is deprecated");
|
|
|
/*!
|
* 获取请求id (请求id是系统生成的唯一的标识)
|
* @return
|
* NSString
|
*/
|
- (NSString*) getRequestId;
|
|
/*!
|
* 获取API名称
|
* @return
|
* NSString
|
*/
|
- (NSString*) getApiName;
|
|
/*!
|
* 获取API版本
|
* @return
|
* NSString
|
*/
|
- (NSString*) getApiVersion;
|
|
/*!
|
* 为了TBSDKMtopServer兼容提供的, 不建议使用
|
* @param apiVersion
|
*
|
*/
|
- (void) setApiName: (NSString*) apiName;
|
|
/*!
|
* 为了TBSDKMtopServer兼容提供的, 不建议使用
|
* @param apiVersion
|
*
|
*/
|
- (void) setApiVersion: (NSString*) apiVersion;
|
|
/*!
|
* 获取扩展参数
|
* @return
|
* NSDictionary
|
*/
|
- (NSDictionary*) getExtParameters;
|
|
/*!
|
* 获取业务参数
|
* @return
|
* NSDictionary
|
*/
|
- (NSDictionary*) getBizParameters;
|
|
/*!
|
* 获取http请求头(不包含协议参数头)
|
*/
|
- (NSDictionary *)getHttpHeaders;
|
|
/*!
|
* 判断请求是否要求使用了post
|
* @return
|
* YES
|
* NO
|
*/
|
- (BOOL) isUseHttpPost;
|
|
/*!
|
* 判断请求是否要求使用了https
|
* @return
|
* YES
|
* NO
|
*/
|
- (BOOL) isUseHttps;
|
|
/*!
|
* 重试计数 retryCount += 1
|
*/
|
- (void) retryed;
|
|
/*!
|
* 是否需要重试
|
*/
|
- (BOOL) isNeedRetry;
|
|
/*!
|
* mtop ut 开始 (开始请求)
|
* @param isSync
|
*/
|
- (void) utStart: (BOOL) isSync;
|
|
/*!
|
* mtop ut 结束
|
*/
|
- (void) utEnd;
|
|
/*!
|
* mtop ut json解析开始
|
*/
|
- (void) utJsonParseStartTime;
|
|
/*!
|
* mtop ut json解析结束
|
*/
|
- (void) utJsonParseEndTime;
|
|
/*!
|
* 取消
|
*/
|
- (void) cancel;
|
|
/*!
|
*
|
*/
|
- (BOOL) isNeedCallback;
|
|
@end
|
