1. SDK集成方法

1.1 SDK的组成

迅雷开放SDK目前封装为一个动态链接库，提供了接口头文件(Windows平台还包含导入库)和示例程序。

1.2 SDK集成步骤

1.2.1 申请client_id和相应的密钥

目前只有开放平台管理员有资格，由迅雷对接人在开放平台注册应用。合作方需要提供信息：应用名称，信任授权域名列表，组织名

迅雷下载库注册 Key 和 Name

迅雷开放平台注册商家信息，并返回相关配置给商家(其中 client_id == Key)输入:

name: 应用名称

scopes: 选择client可使用的scopes细则范围，签发token带上

login.login

xtask.p2sp

xtask.emule

xtask.magnet

xindex.query

domain: 允许的域名(或包名)(例如 com.test)，Login时带上

type: 应用类型(客户端||服务端)

description: 应用描述，额外信息

输出:

client_id

用于签发token (合作方应用标识)

client_secret

用于签发token

scopes

用于签发token

project_id

用于签发token (project_id 当前统一为：2rvk4e3gkdnl7u1kl0k)

1.2.2 登录和下载流程

1.3 代码示例

1.3.1 放置dll库

头文件：xl_sdk_interface.h

库文件：xl_sdk.dll

1.3.2 示例程序#include "xl_sdk_interface.h"

#include

#define TEST_CLIENTID "Need a valid ClientID"

#define TEST_APPNAME "Need a valid AppName"

#define TEST_APPVERSION "1.0"

#define TEST_DOMAIN "i.xunlei.com"

const char* GetLoginToken(){

static char loginToken[4096] = { 0 };

printf("Input a login token:\n");

scanf("%s", loginToken);//用户根据ClientID生成登录Token

printf("\n");

return loginToken;

}

const char* GetTaskToken(const char* sessionID){

static char taskToken[4096] = { 0 };

printf("Input a task token:\n");

scanf("%s", taskToken); //用户根据SessionID生成任务Token

printf("\n");

return taskToken;

}

int main(int argn, char** argv){

XLSDK_INIT_PARAM initParam =

{

TEST_CLIENTID,

TEST_APPNAME,

TEST_APPVERSION,

"d:\\Temp\\"

};

XLSDK_ERRNO initResult = XLSDK_Init(&initParam);

printf("XLSDK_Init clientID:%s\n appName:%s\n appVersion:%s\n cfgPath:%s\n initResult:%d\n\n",

initParam.clientID, initParam.appName, initParam.appVersion, initParam.cfgPath, initResult);

if (initResult != XLSDK_ERRNO_SUCCESS)

{

return initResult;

}

XLSDK_SetUploadSwitch(true);

XLSDK_SetSpeedLimit(-1, -1);

const char* loginToken = GetLoginToken();

const char* domain = TEST_DOMAIN;

char sessionID[MAX_SESSION_ID_LEN] = { 0 };

XLSDK_ERRNO loginResult = XLSDK_Login(loginToken, domain, sessionID);

printf("XLSDK_Login loginToken:%s\n domain:%s\n loginResult:%d\n sessionID:%s\n\n",

loginToken, domain, loginResult, sessionID);

if (loginResult != XLSDK_ERRNO_SUCCESS)

{

XLSDK_Uninit();

return loginResult;

}

const char* taskToken = GetTaskToken(sessionID);

XLSDK_START_TASK_PARAM startTaskParam =

{

XLSDK_CTM_NEW,

XLSDK_TM_NORMAL,

0,

"http://down.sandai.net/mac/thunder_3.4.1.4368.dmg",

"",

"",

"",

"",

"d:\\Temp\\",

"thunder_3.4.1.4368.dmg"

};

uint64_t taskID = 0;

XLSDK_ERRNO startTaskResult = XLSDK_StartTask(taskToken, &startTaskParam, &taskID);

printf("XLSDK_StartTask taskToken:%s\n startTaskResult:%d\n taskID:%llu\n\n",

taskToken, startTaskResult, taskID);

if (startTaskResult != XLSDK_ERRNO_SUCCESS)

{

XLSDK_Uninit();

return startTaskResult;

}

while (true)

{

XLSDK_TASK_INFO taskInfo;

XLSDK_ERRNO getTaskInfoResult = XLSDK_GetTaskInfo(taskID, &taskInfo);

if (getTaskInfoResult != XLSDK_ERRNO_SUCCESS)

{

break;

}

printf("XLSDK_GetTaskInfo taskID:%llu, status:%d, taskErrno:%d, fileSize:%llu, downloadSize:%llu, "

"downloadSpeed:%llu, checkedSize:%llu, tokenErrno:%d\n",

taskID, taskInfo.status, taskInfo.taskErrno, taskInfo.fileSize, taskInfo.downloadSize,

taskInfo.downloadSpeed, taskInfo.checkedSize, taskInfo.tokenErrno);

if (taskInfo.status == XLSDK_TASK_STATUS_SUCCESS

|| taskInfo.status == XLSDK_TASK_STATUS_FAILED)

{

break;

}

if (taskInfo.tokenErrno != XLSDK_TOKEN_ERRNO_NORMAL)

{

if (taskInfo.tokenErrno == XLSDK_TOKEN_ERRNO_SESSION_EXPIRED)

{

XLSDK_ERRNO loginResult = XLSDK_Login(loginToken, domain, sessionID);

printf("XLSDK_Login loginToken:%s\n domain:%s\n loginResult:%d\n sessionID:%s\n\n",

loginToken, domain, loginResult, sessionID);

if (loginResult != XLSDK_ERRNO_SUCCESS)

{

break;

}

}

if (taskInfo.tokenErrno == XLSDK_TOKEN_ERRNO_TOKEN_EXPIRED

|| taskInfo.tokenErrno == XLSDK_TOKEN_ERRNO_SESSION_EXPIRED)

{

const char* taskToken = GetTaskToken(sessionID);

int setTaskTokenResult = XLSDK_SetTaskToken(taskID, taskToken);

if (setTaskTokenResult != XLSDK_ERRNO_SUCCESS)

{

break;

}

}

}

// Do something or Sleep(1000);

}

XLSDK_ReleaseTask(taskID);

XLSDK_Uninit();

return 0;

}

1.4 token签发

1.4.1 签发规则准备所需信息(client_id, client_secret, iss, scopes, project_id, etc…)

签发token

client_secret 作为密钥

使用hmac方式签发 JWT (标准库即可)

token 内claims 包含1.4.2内的claims

1.4.2 代码示例(Java)

签发//https://github.com/auth0/java-jwt

//https://jwt.io/introduction

try {

Algorithm algorithm = Algorithm.HMAC256("secret");// 选加密格式，填入密钥

String token = JWT.create()

.withIssuer("auth0") //填入签发方，例如ludashi

.withClaim("name", 123) //签入内容

.withArrayClaim("array", new Integer[]{1, 2, 3}

.sign(algorithm);

} catch (JWTCreationException exception){

//Invalid Signing configuration / Couldn't convert Claims.

}

验签(合作伙伴用不到，这里只用于展示)//https://github.com/auth0/java-jwt

try {

Algorithm algorithm = Algorithm.HMAC256("secret");

JWTVerifier verifier = JWT.require(algorithm)

.withIssuer("auth0") //填入签发方，例如ludashi

.build(); //Reusable verifier instance

DecodedJWT jwt = verifier.verify(token);

//DecodedJWT jwt = JWT.decode(token); 纯解码

} catch (JWTVerificationException exception){

//Invalid signature/claims

}

1.4.2 token签发字段

Login"iss”:(对于合作商来说是固定字段)

"aud": (对于合作商来说是固定字段，也就是client_id)

"iat": 1595486368, (签发时间戳)

"exp": 1595486368, (过期时间戳，登录token可以设置一小时，创建任务token可以设置一天)

"project_id": (对于合作商来说是固定字段，类似于项目类型)

"scopes”: "login.login" (能力范围，不同的请求不同的取值)

StartTask"iss”:(对于合作商来说是固定字段)

"aud": (对于合作商来说是固定字段，也就是client_id)

"iat": 1595486368, (签发时间戳)

"exp": 1595486368, (过期时间戳，登录token可以设置一小时，创建任务token可以设置一天)

"project_id": (对于合作商来说是固定字段，类似于项目类型)

"scopes”: "xtask.p2sp, xindex.query" (能力范围，不同的请求不同的取值)

“session_id”:(用户身份)

2. 主要接口说明

2.1 XLSDK_Init(const XLSDK_INIT_PARAM* initParam)

说明

初始化SDK

不可重入

参数名称

类型

种类

描述

initParam

struct

in

结构体，包含初始化SDK所需的参数

{

“clientID”:"",

“appName” : “”,

“appVersion” : “”,

“cfgPath” : “”

}

返回值

成功返回0，失败返回相应错误码

2.2 XLSDK_SetUploadSwitch(int uploadSwitch)

说明

设置是否允许上传。可以在Init之后，Unint之前的任何时刻请求这个方法。这个方法如果不请求，默认上传是关闭的。

参数名称

类型

种类

描述

uploadSwitch

int

in

0表示不允许上传，1表示允许上传，其它值保留

2.3 XLSDK_SetSpeedLimit(int64_t maxDownloadSpeed, int64_t maxUploadSpeed)

说明

设置下载、上传限速。可以在Init之后，Unint之前的任何时刻请求这个方法。这个方法如果不请求，默认不限速。

参数名称

类型

种类

描述

maxDownloadSpeed

int64_t

in

字节/秒，-1表示不限速，最小限速值32KB

maxUploadSpeed

int64_t

in

字节/秒，-1表示不限速，最小限速值16KB

返回值

成功返回0，失败返回相应错误码

2.4 XLSDK_Login(const char* loginToken, const char* domain, char* sessionID)

说明

提交用户信息到服务器登录，得到sessionID。

创建任务时需要此sessionID签发token

参数名称

类型

种类

描述

loginToken

string

in

token字符串

domain

string

in

domain

sessionID

string

out

保存sessionID的缓冲区，至少需要1024字节

返回值

成功返回0，失败返回相应错误码

2.5 XLSDK_StartTask(const char* taskToken, const XLSDK_START_TASK_PARAM* startTaskParam, uint64_t* taskID)

说明

创建下载任务，在此之前需设置带有SessionID的token

参数名称

类型

种类

描述

taskToken

string

in

token字符串，需带有XLSDK_Login成功后返回的SessionID，只要不过期，token会一直有效

startTaskParam

struct

in

结构体，包含创建任务所需的参数

{

“transMode” : “”,

“createMode” : “”,

“seqID” : “”,

“url” : “”,

“refURL” : “”,

“cookie” : “”,

“userName” : “”,

“password” : “”,

“filePath” : “”,

“fileName” : “”}

taskID

uint64_t

out

任务ID，后续针对该任务的操作均使用此任务ID

返回值

成功返回0，失败返回相应错误码

2.6 XLSDK_ReleaseTask(uint64_t taskID)

停止下载任务，调用此接口后taskID将失效，不可再用于任务相关接口。所以在请求此接口之前，可以先请求一下XLSDK_GetTaskInfo获取任务状态。

参数名称

类型

种类

描述

taskid

uint64_t

in

任务ID

返回值

成功返回0，失败返回相应错误码

2.7 XLSDK_GetTaskInfo(uint64_t taskID, XLSDK_TASK_INFO* taskInfo)

说明

获取下载任务当前的状态、进度信息

参数名称

类型

种类

描述

taskid

uint64_t

in

任务ID

taskInfo

struct

out

结构体，任务的状态、进度信息

{

“status” : ,

“taskErrno” : “”,

“fileSize” : “”,

“downloadSize” : “”,

“downloadSpeed” : “”,

“checkedSize” : “”,

“tokenErrno” : “”

}

返回值

成功返回0，失败返回相应错误码

2.8 @XLSDK_ERRNO int setTaskToken(long taskID, @NonNull String taskToken)

说明

在任务下载过程中，有可能token会过期，XLSDK_GetTaskInfo会返回相应错误码，这个时候可以通过此接口重新设置一下token

参数名称

类型

种类

描述

taskID

uint64_t

in

任务ID

token

string

in

token字符串

返回值

成功返回0，失败返回相应错误码

2.9 XLSDK_AddResource

说明

向下载任务添加下载资源，暂不支持

参数

reserve

返回值

成功返回0，失败返回相应错误码

2.10 XLSDK_RemoveResource

说明

从下载任务移除之前添加的某类下载资源，暂不支持

参数

reserve

返回值

成功返回0，失败返回相应错误码

2.11 XLSDK_UnInit()

说明

反初始化，不想用下载，但是又不想退出进程的时候使用

参数

无

返回值

成功返回0，失败返回相应错误码