L-SDK开发向导

主题

这是为开发者使用L-SDK的过程指引,你可根据需要跳转到相应的主题。

 

环境准备

linux系统及编译工具

L-SDK基于下述环境发布:

linux kernel 3.0 及以上
gcc 4.5 及以上

你的环境检测可参考下面命令,如果你的环境与上述不同,请自行评估验证。

uname -a
gcc -v

需注意的是,你需要根据系统环境是否是32bit,或者64bit来使用对应版本的L-SDK。你的系统用uname命令时,显示字符串尾部有amd64或者x86_64类似字符表示系统为64bit, 否则有i686或者x86类似字符为32bit。

如果你不确定你的系统是否满足要求,可进入下载页直接安装虚拟机并导入虚拟机镜像

 

程序编译

准备源码目录,例:mysrc

mkdir mysrc
cd mysrc

准备库及头文件,例:LSDK-x86-v4.0.1.0.zip

unzip LSDK-x86-v4.0.1.0.zip
ln -s libet-client3a.so.4.0.1.0 libet-client3a.so

编写应用源文件,例:ETClientDemo.c(例子代码点击下载

检查mysrc目录中包含所有的文件

libet-client3a.so.4.0.1.0
libet-client3a.so
ETClient.h
ETClientDemo.c

编译源程序

gcc -Wall ETClientDemo.c -o ETClientDemo -I. -L. -let-client3a

 

程序运行

请确认你已获得合适的帐号:AppKey、UID、SecretKey

    示例(示例参数为便于举例说明用法,不能用于实际的验证和测试,请你确认已申请了合适的帐号):

    Appkey:9f3ed380-a610-632558
    UID:Fc5wGsTuvumomVomJDeVeJ3SqqPBtLvxkn
    SecretKey:db06c78d1e24cf708a14ec81c9b617ec

配置运行时库目录

export LD_LIBRARY_PATH=.

运行程序ETClientDemo(见下载页),提供合适的帐号参数,例: 服务器地址 lb.kaifakuai.com

./ETClientDemo lb.kaifakuai.com 9f3ed380-a610-632558 db06c78d1e24cf708a14ec81c9b617ec Fc5wGsTuvumomVomJDeVeJ3SqqPBtLvxkn
						

ETClientDemo运行连接服务成功,显示如下:

Et Linux sdk version is 4.0.1.0
now it is discover
now is server net mode
Connecting
connect success

ETClientDemo程序连接上服务器后,可输入命令来向另外的帐号发送消息,例:接收消息端的帐号 Fc6wGsTuvumonVomD2sNn1moaqB1gCXMmv

send_msg Fc6wGsTuvumonVomD2sNn1moaqB1gCXMmv hello

 

接口基础

L-SDK为实现点对点消息、主题消息、群消息以及文件收发提供了众多的C函数接口,基本的登录及消息收发过程按照函数调用过程分为下列几个步骤:

接口创建: et_create_context
设置回调过程: et_set_callback
发现服务器: et_discover_servers
连接服务器: et_connect
发送点对点消息: et_chat_to
断开连接服务器: et_disconnect
接口销毁: et_destroy_context

需要说明的是,L-SDK的C函数接口大部分都是异步接口,即:函数接口返回值表明成功,并不是其功能已完成,而是转到异步的线程继续执行,执行后的结果通过调用者传入的回调函数反馈。因此,调用者需在回调函数中实现检查逻辑,来判定结果。

另外,其他帐号发送过来的消息及相关信息也是从消息回调函数中反馈,并以类型来区分消息种类。

例程ETClientBase为例,详细步骤如下:

    1. 接口创建

    #define APPKEY "9f3ed380-b513-632669"
    #define SECRETKEY "db05c78d1e25cf608a14ce81c9b617ec"
    #define UID "Fc5wGstuvumonVomLSdpvQq6JUxUMJszYP"
    #define SERVER "lb.kaifakuai.com"
    #define PORT 8085
    #define LOCALIP "192.168.1.71"
    et_context client;
    et_create_context(&client, APPKEY, SECRETKEY, UID, LOCALIP, SERVER, PORT, ET_PERSISTENCE_NONE, NULL);

    2. 设置回调过程

    /*回调函数定义*/
    int te_message_arrived(void* context,int type,char *send_userid,char* topic_name, int topic_len,et_context_message* message);
    void te_connection_lost(void* context,et_server_data *server_data, char* cause);
    int te_discover_server(void* context,et_server_data *data);

    /*设置*/
    et_callback_handles callback = {0};
    callback.pfn_on_msg = te_message_arrived;
    callback.pfn_broken = te_connection_lost;
    callback.pfn_on_discover = te_discover_server;
    et_set_callback(client, client, &callback);

    3. 发现服务器

    /*设置并调用发现(注:虽然没有回调参数,仍然是异步接口*/
    int rc = 0;
    rc = et_discover_servers(client,60);

    4. 连接服务器

    连接服务器需传入的参数是由发现服务器获得的,并通过回调函数提供给调用者,因此,我们在实现的回调函数te_discover_server中直接调用连接服务器的函数。

    /*回调定义*/
    void connect_fail_fun(void* context,  et_context_failure_data* response);
    void connect_success_fun(void* context, et_context_success_data* response);
    
    /*实现回调函数te_discover_server,完成连接调用*/							
    int te_discover_server(void* context, et_server_data *data)							
    {							
    	et_connect_options opts = {0};
    	int rc;
    	printf("now it is discover\n");
    								
    	if (data->type == ET_ILINK_INTERNET_SERVER) {
    		printf("now is server net mode\n");
    		
    		opts.on_success = connect_success_fun;	
    		opts.on_failure = connect_fail_fun;
    		opts.context = context;
    		opts.connect_timeout = 30;  /*连接超时*/
    		opts.keep_alive_interval = 60; /*心跳间隔时间*/
    		opts.cleansession = 1;
    		printf("Connecting\n");
    		rc = et_connect(context, data, &opts);
    		if (rc != ET_SUCCESS) {
    			printf("now connect fail\n");
    		}
    	}
    	return 1;								
    }
    

    连接成功时通过回调函数connect_success_fun返回:

    void connect_success_fun(void* context, et_context_success_data* response)
    {
    	printf("connect success\n");
    	is_connected = 1;
    }
    

    5. 发送点对点消息(或者等待消息并接收)

    当前面过程连接成功,则设定成功标志为1;因为是异步过程,我们在此等待连接完成:

    while(is_connected == 0) sleep(1);

    连接成功后,可以在此建立主循环,以等待接收消息,也可以发送消息给其他帐号

    发送消息

    /*定义*/
    #define UID_RECEIVE "Fc5wGsTuvumomVomJFeVeJ3SqqpatLvxNE"
    #define MESSAGE "hello"
    void message_send_success(void* context, et_context_success_data* response);
    void message_send_fail(void* context, et_context_failure_data* response);
    /*调用发送*/
    et_context_response_options opts = {0};
    opts.on_success = message_send_success;
    opts.on_failure = message_send_fail;
    opts.context = client;
    rc = et_chat_to(client, UID_RECEIVE, strlen(MESSAGE), MESSAGE, &opts);

    通过接收按键,我们在此等待消息

    while ((!fgets(kinput, sizeof (kinput), stdin)) || (kinput[0] == 0)) sleep(1);

    如果此时,有其他帐号发消息过来,我们在回调函数te_message_arrived获得通知

    int te_message_arrived(void* context, int type, char *send_userid, char* topic_name, int topic_len, et_context_message* message)
    {
    	int i;
    	char* payloadptr = 0;
    	if (message) payloadptr = message->payload;
    								
    	switch (type) {
    		case CHAT_TO_CHAT_MESSAGE: /*收到et_chat_to接口发送的消息*/
    		{
    			printf("now message arrived\n");
    		}
    		break;
    		   default:
    		break;
    	}
    	
    	if (message)  et_free_message(&message);
    	et_free_memory(topic_name);
    
    	return ET_FREE_MESSAGE_SUCCESS;
    }
    

    6. 断开连接服务器

    /*定义*/
    void disconnect_success(void* context, et_context_success_data* response);
    void disconnect_fail(void* context, et_context_failure_data* response);

    /*断开连接*/
    et_disconnect_options dis_opt = {0};
    dis_opt.on_success = disconnect_success;
    dis_opt.on_failure = disconnect_fail;
    dis_opt.context = client;
    et_disconnect(client, &dis_opt);

    7. 接口销毁

    et_destroy_context(client);

 

完整示例