快速集成并使用

下载开发包

点击下载

解压开发包,根目录下面包含libs目录。libs目录包含集成所需的动态库libgotyeapi.so以及配套的gotyeapi.jar,libs-ifly目录是讯飞语音库(可选)。

集成开发包

新建一个安卓工程,将开发包libs目录里的动态库文件(libgotyeapi.so)拷贝至工程的libs目录下(如下图步骤①),将gotyeapi.jar拷贝到libs根目录(如下图步骤②),右键gotyeapi.jar包,将其添加到build path里(如下图步骤③)(点此查看大图) :

复制以下必需权限并添加到工程AndroidManifest.xml文件里(如上图步骤④):

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />

亲加API在新版本中内置了讯飞语音转文字功能,如果需要使用该功能,则需要按照上图步骤⑤和步骤⑥所示,将libs-ifly下面的libmsc.so,Msc.jar及Sunflower.jar拷贝至对应目录,同时将两个jar包按步骤③同样的操作添加到工程的build Path下。同时还需要额外添加以下权限:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.READ_CONTACTS" />

恭喜!集成完毕,您可以开始使用亲加API接口了!

入门使用演示

在正式介绍API接口前,我们将用20余行有效代码(除去系统自动生成、变量声明以及打印语句)展示亲加API的初始化、登录、文本发送、语音短信录制发送、语音识别、消息接收、语音短信下载、语音短信自动播放八大常用功能:

package com.example.hellogotye;
import com.gotye.api.GotyeAPI;
import com.gotye.api.GotyeDelegate;
import com.gotye.api.GotyeMessage;
import com.gotye.api.GotyeUser;
import com.gotye.api.WhineMode;
import android.os.Bundle;
import android.util.Log;
import android.app.Activity;

public class MainActivity extends Activity {

private static final String mTag = "HelloGotye";
private GotyeAPI apiist = GotyeAPI.getInstance();///< 获取GotyeAPI单实例对象
private static final String appkey = "9c236035-2bf4-40b0-bfbf-e8b6dec54928"; ///< 这里填写您在亲加官网注册的appkey

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    apiist.init(this, appkey); ///< 使用活动上下文以及appkey初始化亲加API
    apiist.initIflySpeechRecognition();///< 如需开启语音识别功能,请添加此行

    apiist.addListener(delegate); ///< 注册监听,用于接收异步回调

    apiist.login("James", null); ///< 使用指定用户名James开始登录!
}

// 申明一个监听器,在这个里面,重写那些您感兴趣的回调函数
private GotyeDelegate delegate = new GotyeDelegate() {

    // 监听登录回调,登录成功后,自动发送一条文本消息和一条语音消息
    public void onLogin(int code, GotyeUser user) {
        Log.i(mTag, "login callback, code: " + code);

        // 测试文本发送功能:
        GotyeUser receiver = new GotyeUser("Finn"); ///< 创建一个名叫Finn的消息接收者(要确保接收者账号已经注册过)
        GotyeMessage message = GotyeMessage.createTextMessage(receiver, "hello"); ///< 创建一条发送给Finn简单文本消息
        apiist.sendMessage(message); ///< 发送文本消息

        // 测试语音发送功能:
        apiist.startTalk(receiver, WhineMode.DEFAULT, false, 10000); ///< 开始录制一段长度为10秒钟的语音消息发送给Finn
    };

    // 监听消息发送回调
    public void onSendMessage(int code, GotyeMessage message) {
        Log.i(mTag, "sendMessage callback, code: " + code);
    };

    // 监听录音停止回调
    public void onStopTalk(int code, GotyeMessage message,
            boolean isVoiceReal) {
        Log.i(mTag, "recording finished. calling sendMessage to send it...");

        if(message.getText()!=null && message.getText().length() > 0){
            message.putExtraData(message.getText().getBytes());///< 如果启动了语音识别,将识别出来的文字作为消息附加字段发送出去
        }

        apiist.sendMessage(message); ///< 发送录制好的语音消息
    };

    // 监听接收消息回调
    public void onReceiveMessage(GotyeMessage message) {
        Log.i(mTag, "received a message from "
                + message.getSender().getName() + ", message type is "
                + message.getType());
        switch (message.getType()) {
        case GotyeMessageTypeText:///< 文本消息
            Log.i(mTag, "text: " + message.getText()); ///< 显示接收到的文本消息内容
            break;

        case GotyeMessageTypeAudio: ///< 语音消息
            Log.i(mTag, "audio duration: "
                    + message.getMedia().getDuration() / 1000
                    + "s, downloading audio automatically...");
            apiist.downloadMediaInMessage(message); ///< 开始下载语音消息内容
            break;
        }
    };

    // 监听消息下载回调
    public void onDownloadMediaInMessage(int code, GotyeMessage message) {
        apiist.playMessage(message); ///< 下载完成,自动播放语音消息
    };
 };
}

接口索引文档

查看安卓API的索引文档可以点击此处

基本调用流程

下图为增强版API基础接口调用流程图,该流程简单描述了调用各个功能的必要准备和流程。用户可以根据自身需求,集成相应的功能(点此查看大图):

初始化

在调用API的任何接口之前,请先确保使用准确的appkey初始化API:

//使用您在亲加管理平台申请到的appkey初始化API,appkey如果为空会返回参数错误。
//context为android上下文环境
//下文提到的gotyeApi即为GotyeAPI,后续不再赘述。
GotyeAPI gotyeApi=GotyeAPI.getInstance();
gotyeApi.init(context,appKey);

监听异步回调

亲加API的回调都是异步的,如果要监听回调,只需要从监听类GotyeDelegate继承下来,或者定义一个GotyeDelegate的对象,重写回调函数,调用以下接口注册或移除:

GotyeDelegate listener = new GotyeDelegate(){
public void onLogin(int code, GotyeUser user) {
        Log.i(mTag, "login callback, code: " + code);
    };
};
//注册监听
gotyeApi.addListener(listener);
//移除监听
gotyeApi.removeListener(listener);

提醒:当监听以后不再使用可以主动删除以免造成多个地方响应

线程安全

为了简化使用,API的所有异步回调都是在UI主线程被执行,值得注意的是,API的接口本身并非线程安全的,在不同的线程去调用API接口,极有可能导致无法预料的运行结果,因此我们强烈推荐:仅在UI主线程去调用API接口。

常用数据结构定义

多媒体(GotyeMedia)

媒体对象,包含语音、图片或者纯数据的相关信息

GotyeMediaType type;    ///< 媒体类型:语音/图片/用户数据/额外数据
GotyeMediaStatus status;    ///< 媒体文件状态:下载中,下载完成等
String url; ///< 媒体在服务器的相对url
String path;    ///< 保存语音/图片缩略图/用户数据的本地文件路径
String pathEx; ///< 保存语音PCM元数据(需解码)/图片大图(需下载)的本地文件路径
int duration;  ///< 语音时长(毫秒),只在语音时生效

注意:API会自动为每个多媒体对象创建好文件存储路径,但并不意味着指定路径下的文件就一定存在,有些是需要通过下载接口调用才能获取到指定文件的,比如音频,原始大图。

聊天对象基类(GotyeChatTarget)

GotyeChatTargetType type;   ///< 聊天对象类型 ,用户/群组/聊天室
long Id;  ///< 聊天室/群组的唯一标志符,从服务器获取,该字段对用户无效
String name;  ///< 用户唯一标志符,如果对象类型为聊天室/群组时,这个字段表示其名称.
GotyeMedia icon; ///< 用户/聊天室/群组 图标

GotyeChatTarget是用户(GotyeUser)/聊天室(GotyeRoom)/群组(GotyeGroup)的公共基类,使用时请不要直接构造一个GotyeChatTarget基类对象,参考下面其子类构造函数。

用户(GotyeUser)

String nickname; ///< 用户的昵称
GotyeGender gender; ///< 用户的性别
boolean isBlocked; ///< 是否已被黑名单
boolean isFriend; ///< 是否是好友
String info; ///< 用户信息
boolean hasGotDetail; ///< 是否已经获取了详情信息

申明一个用户非常简单:

GotyeUser user=new GotyeUser(“someone”);  //构造一个账号为someone的单聊用户

聊天室(GotyeRoom)

boolean isTop; ///< 是否为热门聊天室
int capacity; ///< 该聊天室可容纳的最多人数
int onlineNumber;  ///< 当前在线人数

一般来说聊天室/群组不需要由使用者自己创建,而是通过API接口获取并构造好,除非已经明确知道聊天室/群组的唯一标志ID。

群组(GotyeGroup)

GotyeGroupType ownerType; ///< 群类型(公共群/私有群)
String ownerAccount; ///< 群的所有者账号
boolean needAuthentication;///< 是否需要认证加入
int  capacity; ///< 群成员最大数量
String info; ///< 群信息

通知(GotyeNotify)

通知对象,目前只有群组申请相关的通知需要用到

// 对象原型参考 GotyeNotify
long dbID;  ///< 本地数据库唯一ID
long date; ///< 通知发送的时间
boolean isRead;  ///< 是否已读
GotyeChatTarget sender;  ///< 通知发送者
GotyeChatTarget receiver;  ///< 通知接受者
GotyeChatTarget from;  ///< 通知来源的群组
boolean agree;  ///< 是否同意(用于入群申请答复)
boolean isSystemNotify; ///< 是否是系统通知(目前未使用)
GotyeNotifyType type; ///< 通知类型:入群邀请/申请/答复
String text;   ///< 通知的文字内容

消息(GotyeMessage)

消息对象,保存发送和接受的消息的全部信息

///<对象原型参考 GotyeMessage
long id;   ///< 消息在服务器的ID
long date;  ///< 消息发送的时间,如果本地与服务器时间不一致,容易导致消息列表乱序
long dbId;  ////< 消息在本地数据库唯一ID
String text;    ///< 文本消息的文本,只在文本消息时有效
GotyeMedia media;   ///< audio/image/userdata消息的数据对象
GotyeMedia extra;   ///< 额外数据 extra Data的数据对象
GotyeMessageType type;  ///< 消息类型: 文本,语音,图片,用户数据
GotyeMessageStatus status;  ///< 指示消息状态,未读,发送成功/失败等等
GotyeChatTarget sender;  ///< 消息发送者-用户
GotyeChatTarget receiver;   ///<消息接受者-用户/群组/聊天室

接口返回值(状态码)一览表

CodeWaitingCallback          = -1,   ///< 异步调用成功,请等待回调
CodeOK                       = 0,    ///<操作成功
CodeSystemBusy               = 1,    ///< 系统忙,正在处理中
CodeNotLoginYet              = 2,    ///< 还未登陆
CodeCreateFileFailed         = 3,    ///< 创建文件失败
CodeTargetIsSelf             = 4,    ///< 目标是自己(已废除)
CodeReloginOK                = 5,    ///< 重登陆成功
CodeOfflineLoginOK           = 6,    ///< 离线登陆模式成功
CodeTimeout                  = 300,  ///< 超时
CodeVerifyFailed             = 400,  ///< 验证失败
CodeNoPermission             = 401,  ///< 没有权限
CodeRepeatOper               = 402,  ///< 重复操作
CodeGroupNotFound            = 403,  ///< 群组未找到
CodeUserNotFound             = 404,  ///< 用户未找到
CodeLoginFailed              = 500,  ///< 登录失败(此命名有误,应为操作失败)
CodeForceLogout              = 600,  ///< 强制登出(被其他设备同一账号踢下线).
CodeNetworkDisConnected      = 700,  ///< 网络连接断开
CodeRoomNotExist             = 33,   ///< 聊天室不存在
CodeRoomIsFull               = 34,   ///< 聊天室人数已满
CodeNotInRoom                = 35,   ///< 不在聊天室内
CodeForbidden                = 36,   ///< 操作禁止
CodeAlreadyInRoom            = 39,   ///< 已经在聊天室中
CodeUserNotExist             = 804,  ///< 用户不存在
CodeRequestMicFailed         = 806,  ///< 请求Mic失败
CodeVoiceTimeOver            = 807,  ///< 录音时间超出
CodeRecorderBusy             = 808,  ///< 录音设备正在使用
CodeVoiceTooShort            = 809,  ///< 录音时间过短 < 1000ms
CodeInvalidArgument          = 1000, ///< 有不合法参数
CodeServerProcessError       = 1001, ///< 服务器处理失败(可能含有非法参数)
CodeDBError                  = 1002, ///< 操作数据库失败.
CodeUnkonwnError             = 1100  ///< 未知错误
                                                 805  ///自己已被对方拉黑

登录退出

登录/退出

//使用指定的用户名登录,应该确保该用户名在整个app数据库系统中是唯一的,否则会出现在同一个appkey之下,使用相同的用户名登录会互相挤掉线的情况,如果你的app设置的是公开注册,password请填null,如果是授权注册,则password不能为null和空字串
gotyeApi.login("username",null);///<对应回调GotyeDelegate中的onLogin
gotyeApi.logout();///< 退出登录,对应回调GotyeDelegate中的onLogout

注意:API大部分接口返回值都是int类型,具体值请参考GotyeStatusCode, 凡是所有具备对应异步回调的接口,正常返回值应该是CodeWaitingCallback(即-1) 当接收到onLogout回调,有可能是相同账号在其他设备上登录引发的强制下线,可以通过回调里面的参数来区分

回调原型:

void onLogin(int code, GotyeUser user);  /// <当前登陆的用户
void onLogout(int code);

登录回调

登录回调(onLogin)中的状态码可能有以下五种情况:

CodeOK:正常登录成功
CodeOfflineLoginOK:离线登录成功
CodeReloginOK:重新登录成功(离线转在线)
CodeVerifyFailed:认证失败
CodeNetworkDisConnected:网络请求失败

登出回调

登出回调(onLogout)中的状态码可能有以下三种情况:
CodeOK:正常登出成功
CodeNetworkDisConnected: 网络异常,转换成离线状态, 这种情况下API会自动重连
CodeForceLogout:账号在其他设备登录,被强制下线

断线重连

如果某个账号已经调用接口登录成功,那么在整个app运行期间,只要用户不调用退出登录接口,期间不管网络状况如何变化,API均会在底层尝试重连,每次重连耗时15秒以上仍未成功则会被认为超时,并在5秒后尝试下一次重连。但期间不管网络是否正常,如果用户不小心调用了logout,API会认为用户有意退出登录,就会回到初始状态,不再有任何重连操作,除非用户重新调用登录接口。

如果app重新激活或者网络恢复,则会自动重连并产生回调:

void onReconnecting(int code, GotyeUser user);

重新连接的onLogin回调状态值会有所不同:

CodeReloginOK表示重新连接成功

在线状态

//调用下面的接口可以获知当前是否处于在线状态
//GotyeUser.LOGIN_STATE_OFFLINE: 已登出(调用了logout)
//GotyeUser.LOGIN_STATE_BELOWLINE: 离线状态(网络恢复正常后会自动重连)或者未登录
//GotyeUser.LOGIN_STATE_ONLINE: 在线
int online =gotyeApi.isOnLine();

获取账户信息

API在登录成功后,会自动向服务器获取登录账号的详细信息,如果获取成功,会通过以下回调通知给出:

void onGetProfile(int code,GotyeUser user);

修改账户信息

/// 参数user是已经修改好的当前用户对象,如果不需要对头像进行修改,第二个参数传null
GotyeUser loginUser = gotyeApi.getLoginUser();
loginUser.setNickname(”新昵称”); ///< 修改昵称
loginUser.setInfo (“too young, too simple, too naive)”;///< 修改扩展信息
String imagePath = “/mnt/sdcard /icon.jpg”;///<新头像本地文件路径,目前仅支持jpg
gotyeApi.reqModifyUserInfo(loginUser,imagePath);

回调原型:

void onModifyUserInfo(int code, GotyeUser user);  ///< 修改的用户

好友系统

用户搜索

gotyeApi.resetUserSearch(); ///< 重置用户搜索,会将本地搜索结果列表和当前页搜索结果列表清空

调用以下接口可以获取到搜索结果列表引用:

List<GotyeUser> results = gotyeApi.getLocalUserSearchList();

这个列表会将每次搜索请求返回的结果累计保存起来,以便用于添加好友或者界面展示等应用场景。

下面的接口调用返回单次搜索结果列表:

List<GotyeUser> searchList = gotyeApi.getLocalUserSearchCurPageList();

搜索用户的接口原型如下:

int reqSearchUserList(int pageIndex, ///< 搜索结果页索引
String username, ///< 设定用户名关键字
String nickname, ///< 设定昵称关键字
GotyeUserGender gender); ///< 设定性别关键字,如果忽略性别SEX_IGNORE

以下接口的调用将会向服务器请求appkey中所有用户的第一页:

gotyeApi.reqSearchUserList(0,””,””,-1);///< 对应回调GotyeDelegate中的onSearchUserList

注意:

  1. 如果pageIndex 为0,API会先清除上述两个搜索列表,相当于默认调用了resetUserSearch;
  2. 搜索结果会保存在上述两个列表中,区别在于getLalUserSearchCurpageList仅保存本次页面的搜索结果,而getLocalUserSearchList则会累计保存多次搜索请求的所有结果;
  3. 搜索结果中的GotyeUser已经包含了最新用户详情;
  4. 异步回调中的两个列表引用参数curPageList和allList与上述两个接口是一个意思:curPageList和getLocalUserSearchCurPageList是同一个列表;allList对应getLocalUserSearchList;
  5. 搜索关键字的设定是并且的关系,而不是或者。如果指定username=”abc”同时指定nickname=”abc”的话,则表示搜索结果必须同时满足这两个条件;
  6. 每页的数量是16,目前不能修改

回调原型:

onSearchUserList(int code, 
List<GotyeUser> allList, ///< 所有搜索列表,一般使用这个值来更新UI
List<GotyeUser> curPageList, ///< 当前页列表,如果为空则表示已没有新的页面
int pageIndex  ///< 搜索结果页索引
);

好友和黑名单简介

亲加API支持好友和黑名单,这两个概念是互不干涉的,例如用户A可以是用户B的好友,同时A也可以在B的黑名单列表中。另外这两个概念,都是单向的,即A在B的好友列表, B却不一定在A的好友列表。A在B的黑名单列表,B可以不在A的黑名单列表。发送消息时,即便AB之间不存在任何好友关系,A和B都可以相互通讯。 但是,如果A在B的黑名单时,A给B发送消息会失败。

获取好友列表/黑名单

调用以下接口可以返回本地数据库存储的好友列表,该列表也属于全局变量:

List<GotyeUser> friendList =gotyeApi.getLocalFriendList();

如需向服务器请求更新该列表,可以调用以下接口:

gotyeApi.reqFriendList(); ///< 对应回调GotyeDelegate  onGetFriendList

成功获取后,通过getLocalFriendList接口获取到的本地好友列表也会被更新,因此收到回调即可刷新UI(如果需要的话)。

回调原型:

void onGetFriendList(int code, List<GotyeUser> friendlist);

获取本地黑名单列表:

List<GotyeUser> blockedList =gotyeApi.getLocalBlockedList();

请求更新:

gotyeApi.reqBlockedList(); ///< 对应回调GotyeDelegate onGetBlockedList

回调原型:

void onGetBlockedList(int code, List<GotyeUser> blockedlist);

添加/删除好友/黑名单

添加好友(参数user为GotyeUser类型):

gotyeApi.reqAddFriend(user); ///< 对应回调GotyeDelegate中的onAddFriend,同时会更新本地好友列表

回调原型:

void onAddFriend(int code, GotyeUser user);

删除好友:

gotyeApi.reqRemoveFriend(user);///< 对应回调GotyeDelegate onRemoveFriend,同时会更新本地好友列表

回调原型:

void onRemoveFriend(int code, GotyeUser user);

添加黑名单:

gotyeApi.reqAddBlocked(user);///< 对应回调GotyeDelegate onAddBlocked,同时会更新本地黑名单列表

回调原型:

void onAddBlocked(int code, GotyeUser user);

从黑名单移除:

apiist-> reqRemoveBlocked(user);///< 对应回调GotyeDelegate onRemoveBlocked,同时会更新本地黑名单列表

回调原型:

onRemoveBlocked(int code, GotyeUser user);

获取用户详情

在API消息数据类型中(后续会有详细介绍),发送者和接收者通常都是GotyeChatTarget类型,它是用户(GotyeUser),群(GotyeGroup)以及聊天室(GotyeRoom)的共同父类,包含了这3类数据结构的基本属性,但有时候仅有这些基本信息还不够,为了能通过GotyeChatTarget变量获取到更多的详情,可以使用如下接口(以用户为例,其中target是GotyeChatTarget类型):

GotyeUser user = gotyeApi.getUserDetail(target,false);

注意:

1.这个接口会直接从本地数据库查询用户详情,如果发现本地数据库查询不到,则会忽略掉第二个参数,自动向服务器请求详情,请求成功会通过回调GotyeDelegate中的 onRequestUserInfo给出通知; 2.第二个参数forceRequest的含义是:当该值为false时,只要本地数据库有详情,则不会再向服务器请求,否则一定会发起查询请求;如果为true,则不管本地数据库是否存在数据,都会强制向服务器发起查询请求。

回调原型:

void onGetUserDetail(int code, GotyeUser user); ///< 获取到的用户详情

获取聊天室和群详情同理:

GotyeRoom  room = gotyeApi.getRoomDetail(target); ///< target是GotyeChatTarget, 且其类型为聊天室
GotyeGroup  group = gotyeApi.getGroupDetail(target,forceRequest); ///< target是GotyeChatTarget, 且其类型为群组

回调原型:

void onGetGroupDetail(int code, GotyeGroup group); ///< 获取到的群组详情

获取用户头像

有时候我们会希望在界面上展示好友(群/聊天室)头像,这个时候可以调用如下接口去下载其头像到本地 :

gotyeApi.downloadMedia(url);///< 对应回调GotyeDelegate中的:onDownloadMedia,url为被下载对象中的Icon中的url

回调原型:

void onDownloadMedia(int code,GotyeMedia media); ///< 通过media的getPath()即可获取到下载到的图片路径

聊天室

获取聊天室列表

调用以下接口可以获取到本地数据库缓存聊天室列表:

List<GotyeRoom> roomList =gotyeApi.getLocalRoomList();

清除本地聊天室列表缓存:

gotyeApi.clearLocalRoomList();

向服务器请求更新聊天室信息:

gotyeApi .reqRoomList (int pageIndex);  //对应回调GotyeDelegate onGetRoomList

请求成功的话,API会自动更新本地聊天室列表,同时写入数据库。

回调原型:

void onGetRoomList(int code, List<GotyeRoom> roomList);

进入聊天室

调用下述代码可以进入指定聊天室(其中的room为GotyeRoom类型):

gotyeApi.enterRoom (room);///< 对应回调GotyeDelegate  onEnterRoom

回调原型:

void onEnterRoom(int code, GotyeRoom room); ///< 进入的聊天室

退出聊天室

退出指定聊天室:

gotyeApi.leaveRoom (room);///< 对应回调GotyeDelegate   onLeaveRoom

回调原型:

void onLeaveRoom(int code, GotyeRoom room); ///< 离开的聊天室

获取聊天室成员列表

获取聊天室成员列表(请求第0页成员表):

gotyeApi.reqRoomMemberList (room, 0);// 对应回调GotyeDelegate onGetRoomMemberList

回调原型:

void onGetRoomMemberList(int code,
GotyeRoom room,/// <请求的聊天室
int pageIndex,/// <请求时传入的页索引
List<GotyeUser>allMemberList, ///< 获取到的累计所有成员表(全局变量)
List<GotyeUser>curPageMemberList ///< 当前页所对应的成员列表(全局变量)
);

提示: 1.这里回调返回的curPageMemberLis表示当前页结果集合,allMemberList表示已查询的结果集 2.返回的列表中的用户详细信息已经是服务器最新

判断是否在指定聊天室

判断是否已经在聊天室中:

boolean isIn = gotyeApi.isInRoom(room); ///< 返回 true表示已经在聊天室中

判断该房间是否支持实时语音

以下接口的返回值可以直接用来判断一个聊天室是否支持实时语音:

boolean support = gotyeApi.supportRealtime(room);

群组

公共群搜索

群组在即时通讯云中分为公共群和私有群,API提供了对公共群的搜索功能,相关接口的调用方式,和用户搜索几乎一致:

gotyeApi.resetGroupSearch (); ///< 重置群组搜索,会将本地搜索结果列表和当前页搜索结果列表清空

调用以下接口可以获取到群组搜索结果列表引用:

List<GotyeGroup> searchList =gotyeApi.getLocalUserSearchList();

获取单页群组搜索结果列表:

List<GotyeGroup> searchList = gotyeApi.getLocalGroupSearchCurPageList();

发起单页群组搜索,和搜索用户相比,群组搜索只有一个搜索关键字,即群组名字:

gotyeApi.reqSearchGroup(“vacation”, pageIndex); /// <对应回调GotyeDelegate中的onSearchGroupList

回调原型:

void onSearchGroupList(int code,
List<GotyeGroup>allList, ///< 获取到的累计所有列表
List<GotyeGroup> curPageList,///< 当前页所对应的群组列表
int pageIndex///< 请求时传入的页索引
);

注意: 与用户搜索一样,群组搜索的异步回调GotyeDelegate中的onSearchGroupList中的curPageList和allList分别和getLocalGroupSearchCurPageList与getLocalUserSearchList返回值是相同的列表。

获取群列表

调用以下接口可以获取到本地数据库缓存的群组列表,该列表也是全局变量,这里的群组是指登录账号所在的群组(包括自己创建的以及自己加入的):

List<GotyeGroup> groupList = gotyeApi.getLocalGroupList();

如果想更新该列表,可以发起如下请求:

gotyeApi .reqGroupList(); ///< 对应回调GotyeDelegate onGetGroupList

回调原型:

void onGetGroupList(int code, List<GotyeGroup> grouplist); /// <所有群列表

注意:

  1. 回调中的grouplist引用和上述本地群组都是临时生成

  2. 回调中的群组信息已经是包含群组详细信息,可以直接使用

  3. 登录账号最多只能查看到自己的100个群组。(包括自己创建的以及自己加入的)

获取群成员列表

获取群组成员列表(请求第0页成员表):

gotyeApi.reqGroupMemberList (group, 0);///< 对应回调GotyeDelegate onGetGroupMemberList

回调原型:

void onGetGroupMemberList(int code,
GotyeGroup group,///< 请求的群组
int pageIndex,///< 请求时传入的页索引
List<GotyeUser> allMemberList; ///< 获取到的累计所有成员表
List<GotyeUser> curPageMemberList///< 当前页所对应的成员列表
}

提示:

  1. 这里回调返回的curPageMemberList以及allMemberList与前面提到的列表一样,也是临时生成;
  2. 返回的列表中的用户详细信息已经是服务器最新、

创建/解散 群

创建群组时可以指定一系列参数:

GotyeGroup group=new GotyeGroup();
group.setGroupName( "client team"); ///< 设定群名字
group.setInfo(“api development guys"); ///< 设定群扩展信息
group.setOwnerType (GotyeGroupType.GotyeGroupTypePublic); ///< 设定群类型(公共群/私有群)
group.setNeedAuthentication(false); ///< 是否需要验证才能加入
gotyeApi.createGroup(GotyeGroup, String);///< 对应回调GotyeDelegate中的onCreateGroup

回调原型:

void onCreateGroup(int code,
GotyeGroup group);///< 创建的群组

如果登录账号是群主,则拥有解散群的权限:

gotyeApi.dismissGroup (group);/// < 对应回调GotyeDelegate   onDismissGroup

回调原型:

void onDismissGroup(int code, GotyeGroup group);///< 解散的群组

修改群详情

与创建群组时指定的参数一样,修改群详情时这些参数都可以在后续再次更改,并且,修改群信息时还可以指定群图标(如果需要的话):

group.setGroupName(“server team”); ///< 设定群名字
String imagePath = “/mnt/sdcard/icon.jpg”;///<设定新图标路径,目前仅支持jpg
gotyeApi.reqModifyGroupInfo(group, imagePath);
/// <对应回调GotyeDelegate中的onModifyGroupInfo

注意: 如果不需要对图标进行修改,第二个参数传null.

回调原型:

void onModifyGroupInfo(int code,GotyeGroup group);///< 修改的群组

加入/离开 群

如果想加入某个群组(群组信息可能来自群搜索,或者入群邀请),调用以下接口即可(前提是group已经有详情,否则群id必须 > 0):

gotyeApi.joinGroup(group); ///< 对应回调GotyeDelegate  onJoinGroup

回调原型:

void onJoinGroup(int code,
GotyeGroup group);///< 加入的群组

对应离开群接口:

gotyeApi.leaveGroup(group); ///< 对应回调GotyeDelegate onLeaveGroup

注意:如果是群主调用离开群的接口,那么群组会自动解散。

回调原型:

Void onLeaveGroup(int code, GotyeGroup group);///< group为离开的群组

踢出群成员

如果登录账号拥有群主权限,则可以进行踢人操作(member为GotyeUser类型):

gotyeApi.kickoutGroupMember(group, member); ///< 对应回调GotyeDelegate  onKickoutUser

回调原型:

void onKickoutGroupMember(int code,
GotyeGroup group, ///< 操作的群组
GotyeUser user);  ///< 被踢出的用户

转让群

如果登录账号拥有群主权限,还可以转让群(user为GotyeUser类型):

gotyeApi.changeGroupowner(GotyeGroup group,
               GotyeUser user); ///< 对应回调GotyeDelegate  onChangeGroupOwner

回调原型:

void onChangeGroupOwner(int code,
GotyeGroup group,///< 操作的群组
GotyeUser user);  /// <被转让群的用户

群状态改变

当群状态有改变,所有群成员会收到如下回调:

void onUserJoinGroup(group, user); ///< 当有用户加入群时
void onUserLeaveGroup(group, user); ///< 当有用户离开群时
void onUserDismissGroup(group, user); ///< 当群被群主解散时;
void onUserKickdFromGroup(group,kicked,actor); ///< 当有用户被群主踢出群时

通知

邀请入群

API允许群成员向其他人发起入群邀请:

gotyeApi.inviteUserToGroup (user,group,inviteMessage);

被邀请方将会收到入群通知:

//详见GotyeDelegate
void onReceiveNotify(int code,GotyeNotify notify);///<通知主体
notify.type  ///<GotyeNotifyTypeGroupInvite类型为邀请入群的通知
notify.sender///<邀请的发起人
notify.text///<邀请词

申请入群

向某个群的群主提出入群的申请(群可以来自群搜索):

gotyeApi.reqJoinGroup(group, "我要入群!");

该群群主会收到如下通知:

void onReceiveNotify(code,notify);///<通知主体
notify.type  ///<GotyeNotifyTypeJoinGroupRequest类型为申请入群的通知
notify.sender///<申请的发起人
notify.text///<申请词

回复入群申请

群主对入群申请回复(其中notify为入群申请的通知主体):

gotyeApi.replyJoinGroup (notify, “同意!”, true);

申请人会收到如下通知:

//详见GotyeDelegate
void onReceiveNotify (NotyeNotify notify);///< 通知主体
notify.type  ///< GotyeNotifyTypeJoinGroupReply类型为回复申请入群的通知
notify.sender  ///< 回复的发送方
notify.text  ///< 回复词
notify.agree  ///< 是否同意

消息对象

单聊(私聊)

GotyeUser receiver = new GotyeUser("username");

注意:username长度限制在64字节,设置username的时候,不能包含@、空格、逗号、点。

群聊

GotyeGroup receiver = new GotyeGroup(id);

聊天室聊(帮派、公会、世界频道)

GotyeRoom receiver = new GotyeRoom(id);

提示:下面消息中的receiver参数为构造出来的消息对象。

消息

创建消息

即时通讯云支持发送文本,图片,语音,自定义数据四种类型。除语音消息外,其他三种消息都有对应的工厂方法来创建,语音消息虽然也有工厂方法,但一般只由API内部自动调用。

文本消息

创建文本消息的接口参数比较简单:

GotyeMessage message = GotyeMessage.createTextMessage(receiver, “Hello”);

注意: API允许发送的文本消息字符串的最大长度为6KB。这里的receiver是GotyeChatTarget类型,可以填入GotyeUser/GotyeRoom/GotyeGroup的任意一种聊天对象变量, 其他类型消息也是一样, 后续不再赘述。

图片消息

创建图片消息:

String imagePath = “/mnt/sdcard /icon.jpg”; ///< 设定原始图片路径,目前仅支持jpg
GotyeMessage message = GotyeMessage.createImageMessage(receiver, imagePath);

注意: API允许发送的原始图片的文件最大为6MB。发送图片时,API会生成一张原始图片的缩略图,该缩略图的文件大小被限制在6KB以内,随同消息一同到达接收方。而原始图片则被上传到服务器,接收端在收到消息后需要调用下载接口才能获取到原始图片。

语音消息

开始录音:

gotyeApi.startTalk(user,WhineMode.Default,maxDuration); ///< 单聊api,user为聊天对象,WhineMode为语音变声参数,maxDuration为时长(单位ms) 
gotyeApi.startTalk(group,WhineMode.Default,maxDuration); ///< 群聊语音消息
gotyeApi.startTalk(room,WhineMode.Default,realtime,maxDuration);
///<realtime如果为true,则开始实时语音,聊天室所有用户会收到onRealPlayStart的回调

结束录音:

gotyeApi.stopTalk();

当录音结束,如果不是实时语音,由API内部生成一条语音消息,API会在对应的异步回调中将创建好的语音消息给出:

void onStopTalk (code///< 录音结束状态码
message,///< 语音短信模式下API生成的语音消息,如果是实时模式,该参数无效!!!
realtime) ///< 是否实时模式,false表示语音短信

语音消息产生后发送:

//发送语音消息
gotyeApi.sendMessage(message);///< 不调用发送消息方法消息是不会发送给对方的。但是该条语音消息会保存在本地。

自定义数据消息

自定义数据消息 API支持发送用户自定义数据:

byte[] userdata = “1234567890”.getBytes(); ///< 自定义数据内容不能超过4KB
GotyeMessage message = GotyeMessage.createUserDataMessage(receiver,userdata,len);

或者发送指定路径文件里的数据内容:

String path = “/mnt/sdcard /userdata.txt”; ///<文件内容不能超过4KB
GotyeMessage message = GotyeMessage.createUserDataMessage(receiver,path);

获取自定义数据(如果存在): byte[] data = message.getUserData();

消息附加字段

API支持发送消息时附加发送一些额外的数据,其大小不允许超过2.5KB:

byte[]buf = “This is some extra data info with message”.getBytes();
message.putExtraData(buf); ///< 或者传入一个文件路径,API会自动从文件中读取内容
byte[] data = message.getExtraData(); ///< 获取数据

发送消息

消息创建好之后,调用以下接口便可发送:

gotyeApi.sendMessage (message); ///< 对应回调GotyeDelegate  onSendMessage

发送消息的回调原型:

void onSendMessage(int code, GotyeMessage message);

接收/下载 消息

下载消息:

gotyeApi.downloadMediaInMessage(message)///< 只有图片消息和语音消息需要下载

注意: 新收到的消息如果是图片或语音类型,图片和语音文件并不随消息一起到达接收方,需要手动调用该方法下载。

回调到GotyeDelegate 中的onDownloadMessage

void onDownloadMediaInMessage(int code, GotyeMessage message);

回调原型: void onDownloadMediaInMessage(int code, GotyeMessage message); /// <下载的消息,下载好的媒体文件在message.media.path或pathEx中

接收离线消息

即时通讯云支持离线消息存储,当登录账号下线后,服务器会将该账号相关的离线消息保存在数据库中。以便下次登录获取。API获取离线消息的接口很简单:

void beginReceiveOfflineMessage();///< 对应回调GotyeDelegate中的onGetMessageList

获取消息列表

如果需要获取跟某个指定对象(好友/聊天室/群组)的聊天消息列表,可以使用以下接口:

List<GotyeMessage> messages=gotyeApi.getMessageList(GotyeChatTarget target, boolean more);

这里获取到的消息列表是指与聊天对象的若干条最新消息,而且返回的列表对象是全局变量,可以保存其指针使用。对好友和群组来说,调用这个接口会首先从本地数据库读取指定条目消息(默认10条),如果接收到离线消息,那么离线消息也会被插入到该列表,同时写入数据库;对聊天室来说,进入聊天室调用该接口,会向服务器请求历史消息记录,请求的条目是固定的(默认10条)。下面的两个接口可以设定从本地数据库读取消息时的条目和每次从服务器拉取历史消息时指定的条目数:

gotyeApi.setMessageReadIncrement(20); ///< 设定单次从本地数据库读取消息增量为20,默认10
gotyeApi .setMessageRequestIncrement(15); ///< 设定单次向服务器请求消息增量为15,默认10

不论是从本地数据库读取,离线消息接收,还是历史聊天记录获取,通过getMessageList获取到的本地列表都会被自动更新,因此到收到GotyeDelegate onGetMessageList回调,该接口总是返回最新消息列表。该接口的第二个参数more的函数是,如果设为false,则返回跟上次调用相同的消息列表,否则消息条目可能会递增。

回调原型:

void onGetMessageList(int code, int totalCount);  ///< 获取到的消息列表

删除消息

API提供了删除消息的接口:

gotyeApi.deleteMessage(message); ///< 删除单个消息
gotyeApi.clearMessages(target); ///< 删除对应聊天对象的所有消息

获取/更新消息状态

GotyeMessage的status字段表征了该消息的当前状态,具体定义请参考GotyeMessageStatus枚举体。

获取和某个聊天对象target(GotyeChatTarget,用户/群组/聊天室)的未读消息数:

int unreadCount = gotyeApi.getUnreadMessageCount(target);

获取全部未读消息数:

int count = gotyeApi.getTotalUnreadMessageCount();

将和某个聊天对象的全部消息标记为已读(未读):

gotyeApi.markMessagesAsRead(target, true/*false*/); ///< 全部标记为已读状态

将单条消息标记为已读(未读):

gotyeApi.markOneMessageAsRead(message, true/*false*/); ///< 将message标记为已读状态

播放音频消息

如果消息为音频类型,则可以调用以下接口去播放(如果音频已经被下载):

gotyeApi.playMessage (message); /// <对应回调GotyeDelegate中的onPlayStart,onPlaying和onPlayStop

要停止正在播放的音频,请调用接口:

gotyeApi.stopPlay(); ///< 对应回调onPlayStop

获取录音时的音量波动值

录音时,如果需要动态显示当前说话时的音量波动,可通过以下接口实时获取:

int power = gotyeApi.getTalkingPower(); ///< power取值范围[0, 255]

敏感词过滤

敏感词过滤开关接口,默认为开启状态。

void enableTextFilter(GotyeChatTargetType type,boolean enabled);

会话

获取本地会话列表

API支持获取本地会话列表(最近联系人列表, 该列表只存在本地,不同步到服务器):

List<GotyeChatTarget> sessionList = gotyeApi.getSessionList();

获取会话详情

每个会话其实对应的是GotyeUser,GotyeGroup,GotyeRoom。据此可以获取任何相关的数据

激活/隐藏 会话

如果激活一个会话,则意味着当API接收到与该聊天对象相关的消息时,该条消息总是被设为已读状态,反之如果隐藏该会话,接收到的消息默认为未读状态。

gotyeApi.activeSession(target); ///< 激活与target的会话
gotyeApi.deactiveSession(target); ///< 隐藏与target的会话

删除会话

如需删除一个会话,调用下述接口:

gotyeApi.deleteSession(target, alsoRemoveMessages);

注意:

删除会话的同时是否删除这个聊天对象的所有本地记录,取决于第二个参数。

会话置顶

API允许将某个会话置顶,置顶后该会话将会处于本地会话列表的第一位:

gotyeApi.markSessionIsTop(target,isTop);

推送

Android中的推送其实是基于Service在后台运行的,Service中收到消息后发出通知,我们可以在Service中实现GotyeDelegate并注册监听,当有消息过来时会回调如下:

void onReceiveMessage(int code,GotyeMessage message);

注意: 这里的主要用于在通知栏里提示用户,具体可参考GotyeIM demo中的实现

返回顶部