# SDK介绍

AIUI移动端/PC端SDK为开发者提供了简单易用的交互接口。AIUIAgent是和AIUI交互的桥梁,开发者可以发送不同的AIUIMessage来控制AIUI的运行,如发送CMD_WAKEUP使AIUI进入唤醒就绪状态,发送CMD_RESET_WAKEUP使AIUI进入休眠状态。同时通过AIUIListener监听接收AIUI抛出的AIUIEvent进行解析,如通过EVENT_RESULT解析AIUI返回的听写和语义结果,通过EVENT_SLEEP得知AIUI进入休眠状态。

AIUI移动端/PC端解决方案支持Android、iOS、Linux、Windows,各个平台都有类似的接口。

# Android SDK接口

AIUIAgent

用于与AIUI SDK交互的接口类为AIUIAgentAIUIAgent提供如下接口:

//创建AIUIAgent实例
static AIUIAgent createAgent(Context context, String cfg, AIUIListener listener)

//发送AIUI消息
void sendMessage(AIUIMessage message)

//销毁AIUIAgent实例
void destroy()

创建AIUIAgent实例时有两个重要的参数,cfg与listener。cfg里的内容可以指定AIUI的一些工作特性,如交互模式、场景设置、语音合成设置等,具体内容参见AIUI配置文件。listener则是指定AIUI的事件回调监听器,在这里可以监听到一系列的事件,如唤醒事件、语义结果事件、VAD事件等,具体可参见AIUIEvent

AIUIListener

创建AIUIAgent时传递的参数AIUIListener是用于接受AIUI SDK抛出事件的监听器。AIUIListener定义如下:

interface AIUIListener
{
	void onEvent(AIUIEvent event);
}

AIUIEvent

AIUIListener中监听的抛出事件的类型是AIUIEventAIUIEvent定义如下:

class AIUIEvent
{
	int eventType; //事件类型
	int arg1;      //参数1
	int arg2;      //参数2
	String info;
	Bundle data;
}

AIUI定义了多种AIUIEvent,有不同eventType。当AIUIEvent取不同的eventType时,其余字段有不同的定义,详细定义请见AIUIEvent的定义说明。

AIUIMessage

AIUIAgent中sendMessage方法用于向AIUI发送消息,消息类型是AIUIMessageAIUIMessage定义如下:

class AIUIMessage
{
	int msgType;   //消息类型
	int arg1;      //参数1 默认空值 0
	int arg2;      //参数2 默认空值0
	String params; //默认空值 null
	byte[] data;   //默认空值 null
}

AIUI定义了多种AIUIMessage,有不同的msgType。当AIUIMessage取不同的msgType时,其他成员有不同的定义,详细定义解释请见AIUIMessage的定义说明。

AIUISetting

AIUISetting是AIUI设置类,用于日志开关、日志存放目录等设置, 该类的所有公有方法均为静态方法。

  • setAIUIDir(String dir),设置AIUI文件夹路径,SDK会在该路径下保存日志等文件;
  • getAIUIDir(),获取AIUI文件夹路径
  • setMscCfg(String cfg),设置msc.cfg中的配置到SDK
  • getMscCfg(),获取msc配置
  • setShowLog(boolean show),是否打印AIUI日志
  • setNetLogLevel(LogLevel level),设置网络交互日志(打印到aiui.log文件)等级,只会打印高于该等级的日志
  • setLogLevel(LogLevel level),设置logcat调试日志等级,只会打印高于该等级的日志
  • setSaveDataLog(boolean save),设置是否保存数据日志,设置为true时,输入(音频、文本等)和云端返回的结果都将保存
  • setDataLogDir(String dir),设置数据日志存储路径

# iOS SDK接口

用于与AIUI SDK交互的接口类为IFlyAIUIAgentIFlyAIUIAgent提供如下接口:

@interface IFlyAIUIAgent : NSObject

-(instancetype) initWithParams:(NSString*) cfgParams withListener:(id) listener;

/*!
	* 创建AIUIAgent
	*
	*  @param cfgParams cfg文件内容
	*  @return YES:设置成功;NO:设置失败
	*/
+ (instancetype) createAgent:(NSString *) cfgParams withListener:(id) listener;

/*!
	* 发送AIUI消息
	*
	*  @param msg 消息实例
	*/
- (void) sendMessage:(IFlyAIUIMessage *)msg;

/*!
	* 销毁AIUIAgent
	*/
- (void) destroy;

/*!
	* 设置GPS定位信息。
	*
	*  @param lng 经度值
	*  @param lat 纬度值
	*/
- (void) setGPSwithLng:(NSNumber *)lng andLat:(NSNumber *)lat;

@end

cfg内容参见AIUI配置文件

IFlyAIUIListener

实现IFlyAIUIListener协议类的接口,用于获取结果回调。接口如下所示:

@protocol IFlyAIUIListener <NSObject>

@required
/*!
	* 事件回调<br>
	* SDK所有输出都通过event抛出。
	*
	@param event AIUI事件,具体参见IFlyAIUIEvent。
	*/
- (void) onEvent:(IFlyAIUIEvent *) event ;

@end

IFlyAIUIEvent

IFlyAIUIListener中监听的抛出事件的类型是IFlyAIUIEventIFlyAIUIEvent定义如下:

/*!
	* AIUI事件类,业务结果、SDK内部状态变化等输出信息都通过事件抛出。
	*/
@interface IFlyAIUIEvent : NSObject

/**
	* 事件类型。
	*/
@property (nonatomic, assign) int eventType;

/**
	* 扩展参数1。
	*/
@property (nonatomic, assign) int arg1;

/**
	* 扩展参数2。
	*/
@property (nonatomic, assign) int arg2;

/**
	* 描述信息。
	*/
@property (nonatomic, copy) NSString *info;

/**
	* 附带数据。
	*/
@property (nonatomic, strong) NSDictionary *data;

@end

IFlyAIUIMessage

IFlyAIUIAgent中sendMessage方法用于向AIUI发送消息。消息类型是IFlyAIUIMessageIFlyAIUIMessage定义如下:

/*!
	* AIUI消息类,AIUI所有的输入都是通过消息发送到SDK内部。
	*/
@interface IFlyAIUIMessage : NSObject

/**
	* 消息类型。
	*/
@property (nonatomic, assign) int msgType;

/**
	* 扩展参数1。
	*/
@property (nonatomic, assign) int arg1;

/**
	* 扩展参数2。
	*/
@property (nonatomic, assign) int arg2;

/**
	* 业务参数。
	*/
@property (nonatomic, copy) NSString *params;

/**
	* 附带数据。
	*/
@property (nonatomic, strong) NSData *data;

/**
	* 附加参数,一般用于控件层。
	*/
@property (nonatomic, strong) NSDictionary *dic;

@end

# Windows/Linux SDK接口

IAIUIAgent

用于与AIUI SDK交互的接口类为IAIUIAgentIAIUIAgent提供如下接口:

/**
	* AIUI代理类,单例对象,应用通过代理与AIUI交互。
	*/
class IAIUIAgent
{
public:
	AIUIEXPORT virtual ~IAIUIAgent();

	/**
		* 创建Agent单例对象,AIUI开始工作。
		* 注:该方法总是返回非空对象,非空并不代表创建过程中无错误发生。
		*
		* @param params 参数设置
		* @param listener 事件监听器
		* @return AIUIAgent单例对象指针
		*/
	AIUIEXPORT static IAIUIAgent* createAgent(const char* params, IAIUIListener* listener);

	/**
		* 发送消息给AIUI,消息中可以包含命令、参数和数据,具体格式参见IAIUIMessage。
		*
		* @param msg AIUI消息
		* message 如果指定了非空的Buffer *data, 在Message在内部处理后会自动release()这部分data;
		* 而不能外部去释放掉。
		*/
	virtual void sendMessage(IAIUIMessage* message) = 0;

	/**
		* 销毁AIUIAgent对象,AIUI停止工作。
		*/
	virtual void destroy() = 0;
};

cfg内容参见AIUI配置文件

IAIUIListener

创建IAIUIAgent时传递的参数IAIUIListener是用于接受AIUI SDK抛出事件的监听器。IAIUIListener定义如下:

/**
	* AIUI事件监听接口。SDK所有输出都通过回调onEvent方法抛出。
	*/
class AIUIListener
{
public:
	AIUIEXPORT virtual ~AIUIListener();

	/**
		* 事件回调,SDK所有输出都通过event抛出。
		*
		* @param event AIUI事件
		*/
	virtual void onEvent(const IAIUIEvent& event) const = 0;
};

typedef AIUIListener IAIUIListener;

IAIUIEvent

IAIUIListener中监听的抛出事件的类型是IAIUIEventIAIUIEvent定义如下:

/**
	* AIUI事件类。业务结果、SDK内部状态变化等输出信息都通过事件抛出。SDK通过回调抛出事件后会
	* 立即释放事件中的内存对象,若要在别处使用到这些内存对象,开发者需要在回调中做拷贝。
	*/
class IAIUIEvent
{
public:
	AIUIEXPORT virtual ~IAIUIEvent();

	/**
		* 获取事件类型。取值参见AIUIConstant中EVENT_开头的常量定义。
		*/
	virtual int getEventType() = 0;

	/**
		* 获取扩展参数1。
		*/
	virtual int getArg1() = 0;

	/**
		* 获取扩展参数2。
		*/
	virtual int getArg2() = 0;

	/**
		* 获取描述信息。返回的指针不可外部delete或者free。
		*/
	virtual const char* getInfo() = 0;

	/**
		* 获取附带数据。返回的内存不可外部delete或者free。
		*/
	virtual IDataBundle* getData() = 0;
};

AIUI定义了多种IAIUIEvent,有不同eventType。当IAIUIEvent取不同的eventType时,其余字段有不同的定义,详细定义请见AIUIEvent的定义说明。

IAIUIMessage

IAIUIAgent中sendMessage方法用于向AIUIService发送AIUI消息。消息类型是IAIUIMessageIAIUIMessage定义如下:

/**
	* AIUI消息类。AIUI所有的输入都是通过消息发送到SDK内部。
	*/
class IAIUIMessage
{
public:
	AIUIEXPORT virtual ~IAIUIMessage();

	/**
		* 创建消息对象。
		*
	* @param msgType 消息类型,参见AIUIConstant中CMD_开头的常量定义
		* @param arg1 扩展参数1
		* @param arg2 扩展参数2
		* @param params 业务参数,传入后内部会做拷贝
	* @param data 附带数据,Message在SDK内部处理后会自动释放, 不需要外部释放。
	*
		* @return IAIUIMessage 对象指针
		*/
	AIUIEXPORT static IAIUIMessage*  create(
		int msgType ,
		int arg1 = 0,
		int arg2 = 0,
		const char* params = "",
		Buffer* data = 0);

	/**
		* 获取消息类型。类型取值参见AIUIConstant中CMD_开头的常量定义。
		*/
	virtual int getMsgType() = 0;

	/**
		* 获取扩展参数1。
		*/
	virtual int getArg1() = 0;

	/**
		* 获取扩展参数2。
		*/
	virtual int getArg2() = 0;

	/**
		* 获取业务参数。
		*/
	virtual const char* getParams() = 0;

	/**
		* 获取附带数据。
		*/
	virtual Buffer* getData() = 0;

	/**
		* 释放附带数据
		*/
	virtual void releaseData() = 0;

	/**
		* 销毁消息对象本身。注意:不会释放Buffer* data。
		*/
	virtual void destroy() = 0;
};

AIUI定义了多种IAIUIMessage,有不同的msgType。当IAIUIMessage取不同的msgType时,其他成员有不同的定义,详细定义解释请见AIUIMessage的定义说明。

注:iOS/Windows/Linux中命名与android中的命名类似,稍有不同,一般加前缀“I”表示接口,如,“AIUIMessage”在android中为AIUIMessage,在iOS中为IAIUIMessage,使用时请注意比较区分。