全局接口
| 接口名稱 | 功能說明 |
|---|---|
| XL_Init | 初始化SDK，并使其為處理後續操作做好準備。 |
| XL_UnInit | 反初始化SDK，釋放子產品運作期間申請的資源。 |
| XL_DelTempFile | 删除臨時檔案 |
| XL_SetSpeedLimit | 設定最大下載下傳速度 |
| XL_SetProxy | 設定全局代理 |
| XL_SetUserAgent | 設定HTTP請求時用戶端資訊 |
| XL_ParseThunderPrivateUrl | 将迅雷專用鍊轉成實際URL |
| XL_SetUploadSpeedLimit | 限制上傳速度 |
| XL_CreateTaskByURL | 簡單封裝了XL_CreateTask接口 |
| XL_CreateTaskByThunder | 拉起迅雷7建立下載下傳任務 |
| XL_ForceStopTask | 強制暫停任務 |
任務接口
| XL_CreateTask | 建立任務 |
| XL_DeleteTask | 銷毀任務 |
| XL_StartTask | 開始任務 |
| XL_StopTask | 停止任務 |
| XL_QueryTaskInfoEx | 查詢任務資訊 |
接口詳細說明
BOOLXL_Init(void)
初始化下載下傳引擎，并使其為處理後續操作做好準備。
- 傳回值：TRUE表示成功，FALSE表示失敗。一些特殊情況會導緻初始化失敗，如：二進制檔案缺失。
- 說明：該接口必須與XL_Unint(void)成對出現。調用該接口的時，xldl.dll會拉起MiniThunderPlatform.exe子程序。
BOOL XL_UnInit(void)
反初始化下載下傳引擎，釋放子產品運作期間申請的資源。
- 傳回值：TRUE表示成功，FALSE表示失敗。
- 說明：調用該接口後，會通知MiniThunderPlatform.exe子程序退出。
HANDLE XL_CreateTask(DownTaskParam &stParam)
建立任務。可以建立任務也可以續傳任務，參數中IsResume用于表示任務是否是續傳任務。其他資訊請參考DownTaskParam的定義。
- 參數： [in] stParam，建立任務需要的參數。
- DownTaskParam參考：
struct DownTaskParam { int nReserved1; TCHAR szTaskUrl[2084]; // 任務URL，支援http,https,ftp,ftps格式 TCHAR szRefUrl[2084]; // 可空，HTTP下載下傳所在的網頁URL TCHAR szCookies[4096]; // 可空，浏覽器cookie TCHAR szFilename[MAX_PATH]; // 下載下傳儲存檔案名. TCHAR szReserved[MAX_PATH]; TCHAR szSavePath[MAX_PATH]; // 檔案儲存目錄 HWND hReserved; BOOL bReserved1; TCHAR szReserved1[64]; TCHAR szReserved2[64]; BOOL IsOnlyOriginal; //是否隻從原始位址下載下傳 UINT nReserved2; BOOL bReserved2; BOOL IsResume; // 是否用續傳 DWORD reserved[2048]; } - 傳回值：傳回任務的句柄。
- 說明：任務建立後，是不會馬上就下載下傳的，需要調用XL_StartTask。異步執行。
BOOL XL_DeleteTask(HANDLE hTask)
銷毀任務，釋放任務在運作期間申請的資源。
- 參數： [in]hTask，任務句柄
- 傳回值：TRUE表示成功，FALSE表示失敗。當任務不存在時，調用會失敗。
- 說明：在任務暫停、成功以及删除任務的時候都需要調用該接口，保證資源盡快的釋放。 異步執行,如果任務出于pending狀态則不能調用該接口。
BOOL XL_StartTask(HANDLE hTask);
開始下載下傳。任務建立成功後，不會馬上開始下載下傳，需調用此接口才會開始下載下傳。
- 說明：異步執行,如果任務出于pending狀态則不能調用該接口。
BOOL XL_StopTask(HANDLE hTask)
停止下載下傳
- 說明：擷取任務資訊是使用輪詢方式的，最終任務下載下傳了多少資料在任務停止下載下傳後查詢才是正确的。調用後任務不會立即停止，需輪詢到任務狀态為PAUSE之後，才能擷取到。
BOOL XL_QueryTaskInfoEx(HANDLE hTask, DownTaskInfo & stTaskInfo);
查詢任務目前資訊。
- 參數： [in]hTask，任務句柄 [out] stTaskInfo, 任務資訊。
- DownTaskInfo參考：
struct DownTaskInfo { DOWN_TASK_STATUS stat; //任務狀态 TASK_ERROR_TYPE fail_code; //錯誤碼 TCHAR szFilename[MAX_PATH]; //檔案名 TCHAR szReserved[MAX_PATH]; __int64 nTotalSize; // 該任務總大小(位元組) __int64 nTotalDownload; // 下載下傳有效位元組數(可能存在回退的情況) float fPercent; // 下載下傳進度 int nTotalTime; // 不提供該值 int nSrcTotal; // 總資源數 int nSrcUsing; // 可用資源數 int nReserved1; int nReserved2; int nReserved3; int nReserved; __int64 nTotalUpload; // 現不提供該值 __int64 nDonationP2P; // p2p資源貢獻的資料長度 __int64 nReserved4; __int64 nDonationOrgin; // 原始資源貢獻的資料長度 __int64 nDonationP2S; // 鏡像資源貢獻的資料長度 __int64 nReserved5; __int64 nReserved6; int nSpeed; // 速度(位元組/秒) int nSpeedP2S; // 加速伺服器資源的下載下傳速度 int nSpeedP2P; // peer下載下傳速度 bool IsOriginUsable; // 原始資源是否可用 float fReserved; int bReserved; DWORD reserved[64]; }; enum DOWN_TASK_STATUS { NOITEM = 0, TSC_ERROR, TSC_PAUSE, TSC_DOWNLOAD, TSC_COMPLETE, TSC_STARTPENDING, TSC_STOPPENDING }; enum TASK_ERROR_TYPE { TASK_ERROR_UNKNOWN = 0x00, // 未知錯誤 TASK_ERROR_DISK_CREATE = 0x01, // 建立檔案失敗 TASK_ERROR_DISK_WRITE = 0x02, // 寫檔案失敗 TASK_ERROR_DISK_READ = 0x03, // 讀檔案失敗 TASK_ERROR_DISK_RENAME = 0x04, // 重命名失敗 TASK_ERROR_DISK_PIECEHASH = 0x05, // 檔案片校驗失敗 TASK_ERROR_DISK_FILEHASH = 0x06, // 檔案全文校驗失敗 TASK_ERROR_DISK_DELETE = 0x07, // 删除檔案失敗失敗 TASK_ERROR_DOWN_INVALID = 0x10, // 無效的DOWN位址 TASK_ERROR_PROXY_AUTH_TYPE_UNKOWN = 0x20, // 代理類型未知 TASK_ERROR_PROXY_AUTH_TYPE_FAILED = 0x21, // 代理認證失敗 TASK_ERROR_HTTPMGR_NOT_IP = 0x30, // http下載下傳中無ip可用 TASK_ERROR_TIMEOUT = 0x40, // 任務逾時 TASK_ERROR_CANCEL = 0x41, // 任務取消 TASK_ERROR_TP_CRASHED= 0x42, // MINITP崩潰 TASK_ERROR_ID_INVALID = 0x43, // TaskId 非法 }; - 說明：IsOriginUsable，原始資源是否可用，是一個布爾型的參數，但是原始連接配接原始資源是一個耗時的操作，意味着中間有段時間原始資源是否有效是未知的。這個參數的初始态是false，是以就存在原始資源是有效，但在任務剛開始時這個參數是false的問題。上層在使用該值的時候需要根據業務邏輯再做處理。
BOOL XL_DelTempFile(DownTaskParam &stParam)
删除任務的臨時檔案。下載下傳引擎會建立 .td 、 .td.cfg字尾的檔案用來儲存已下載下傳的資料。
- 參數： [in]stParam，任務參數，參考建立任務中的參數。但是這裡隻有檔案儲存的目錄和檔案名是必須。
- 說明：檔案名是最後真正儲存到磁盤的檔案名，不帶臨時檔案字尾名。最終儲存的檔案名會和建立任務不一樣，是以這個檔案名要以查詢任務資訊傳回的檔案名為準。在儲存路徑下已經存在相同檔案名的檔案時，最終儲存的檔案名就會自動改變檔案名：filename.zip → filename（1）.zip。 異步執行。
void XL_SetSpeedLimit(INT32 nKBps)
設定最大下載下傳速度。
- 參數： [in]nKBps, 速度上限值
- 說明：異步執行
BOOL XL_SetProxy(DOWN_PROXY_INFO &stProxyInfo)
設定下載下傳代理，全局任務代理資訊。
- 參數： [in]stProxyIfno 代理資訊
- DOWN_PROXY_INFO參考：
enum DOWN_PROXY_TYPE { PROXY_TYPE_IE = 0, PROXY_TYPE_HTTP = 1, PROXY_TYPE_RESERVED= 2, //不支援該代理 PROXY_TYPE_SOCK5 = 3, PROXY_TYPE_UNKOWN = 255, }; enum DOWN_PROXY_AUTH_TYPE { PROXY_AUTH_NONE =0, PROXY_AUTH_AUTO, PROXY_AUTH_BASE64, PROXY_AUTH_NTLM, PROXY_AUTH_DEGEST, PROXY_AUTH_UNKOWN, }; struct DOWN_PROXY_INFO { BOOL bIEProxy; BOOL bProxy; DOWN_PROXY_TYPE stPType; DOWN_PROXY_AUTH_TYPE stResverd; TCHAR szHost[2048]; INT32 nPort; TCHAR szUser[50]; TCHAR szPwd[50]; TCHAR szDomain[2048]; }; - 傳回值：TRUE表示成功，FALSE表示失敗。參數非法傳回FALSE
void XL_SetUserAgent(const TCHAR *pszUserAgent)
設定向原始資源的Http任務請求的UserAgent。
- 參數： [in]pszUserAgent，用戶端UserAgent字元串
- 說明：在調用該方法後建立的任務的才會使用新的UserAgent。
BOOL XL_ParseThunderPrivateUrl(const wchar_t *pszThunderUrl, wchar_t *normalUrlBuffer, INT32 bufferLen)
迅雷專用鍊是根據一定邏輯從普通URL轉成的。
- 參數： [in] pszThunderUrl，迅雷專用鍊URL [out] normalUrlBuffer，存儲轉化後的普通URL的緩沖區 [out] bufferLen，normalUrlBuffer的緩沖區大小，機關字元數
- 傳回值：TRUE表示成功，FALSE表示失敗
- 說明：此函數功能獨立，和其他函數沒有依賴關系，可随時單獨使用
void XL_SetUploadSpeedLimit(INT32 nTcpKBps, INT32 nOtherKBps)
可根據實際情況設定外網和内網的上傳速度。
- 參數： [in] nTcpKBps, 内網上傳速度，機關為KB/s [in] nOtherKBps, 外網上傳速度，機關為KB/s
- 傳回值：無
HANDLE XL_CreateTaskByURL(const wchar_t *url, const wchar_t *path, const wchar_t *fileName, BOOL IsResume)
通過任務URL、路徑、檔案名建立任務。
- 參數： [in] url, 任務URL，不能為空，包括空字元字元長度不能超過2084 [in] path, 任務路徑，不能為空，包括空字元字元長度不能超過260 [in] fileName, 任務檔案名，不能為空，包括空字元字元長度不能超過260 [in] IsResume, 是否是續傳任務
- 傳回值：傳回任務的句柄
LONG XL_CreateTaskByThunder(wchar_t *pszUrl, wchar_t *pszFileName, wchar_t *pszReferUrl, wchar_t *pszCharSet, wchar_t *pszCookie)
通過傳遞URL和檔案名等資訊拉起迅雷7的建立面闆建立下載下傳任務。
- 參數： [in] pszUrl，任務URL [in] pszFileName，下載下傳儲存的檔案名 [in] pszReferUrl，引用頁URL [in] pszCharSet，目前網頁的字元集 [in] pszCookie，下載下傳資料所需的cookie
- 傳回值：0成功，其他為失敗
BOOL XL_ForceStopTask(HANDLE hTask)
- 參數： [in] hTask，任務句柄
- 傳回值：TRUE表示成功，FALSE表示失敗。當任務不存在時，調用會失敗
- 說明：在開啟UAC下載下傳大檔案時，調用XL_StopTask可能需要消耗比較長的時間。這種情況下如果需要快速暫停任務，可以調用XL_ForceStopTask，不過有可能導緻已經下載下傳的還沒寫到磁盤的資料丢失。
注意事項
1.全局接口是線程不安全的，且XL_Init外的其他接口必須在該函數成功傳回後才能調用； 2.如果任務處于TSC_STARTPENDING或TSC_STOPPENDING，關于任務的操作隻能調用查詢任務資訊的接口。
接口邏輯說明
任務異步操作
任務的操作是異步執行的。調用接口有兩個操作： 1.操作上層xldl.dll中的虛任務 2.在指令隊列對push一條相關操作的指令
接口層可以操作的任務都是虛任務，真實任務是在MiniThunderPlatfom程序建立的。任務建立的流程： 1.Xldl建立虛任務； 2.将操作與參數push到指令隊列； 3.指令處理線程負責執行隊列中的指令，與MiniThunderPlatfom同步通信； 4.MiniThunderPlatfom建立任務成功後，虛任務就可以和實任務映射。 之後所有對virtual task 的操作都将映射到真正的task，并在MiniTP執行真正的操作。 任務資訊查詢，任務資訊的更新需要調用者驅動，需要調用者每隔1s調用一次該接口。任務資訊查詢和更新的流程： 1.調用接口查詢資訊時，先從虛任務查詢任務資訊，第一次調用的時候肯定沒有資訊 2.将查詢操作與參數push到指令隊列； 3.指令處理線程負責執行隊列中的指令，與MiniThunderPlatfom同步通信； 4.查詢到真實任務資訊後，将資訊存儲到虛任務中； 5.第二次查詢就可以直接查詢到任務資訊，這些資訊是上一次查詢到的。 這裡就會出現這樣的情況，第一次查詢操作不能擷取到任務資訊，即任務處于pause/start_pending狀态中。更極端的情況，任務下載下傳完成前一次查詢沒有調用過，在任務完成後再調用該接口會發現任務進度為0。
子程序異常退出
這種情況是不被歡迎的，但又不可避免。子程序異常退出後MiniThunderPlatfom建立的任務會銷毀。這樣，虛任務除了與真實任務的映射關系，其實并無意義。這時候，查詢任務資訊就會傳回任務出錯，錯誤碼為TASK_ERROR_ID_INVALID（任務id非法）。這時需要重新建立續傳任務，接口為XL_CreateTask，結構體中其他參數與建立普通任務相同，參數IsResume設為TRUE。
其它
SDK檔案說明
Sdk總共有10個二進制檔案。二進制檔案之間的依賴關系如下圖所示：
各個檔案功能介紹：
| 檔案名 | 功能 |
|---|---|
| xldl.dll | 導出MiniTP接口 |
| MiniThunderPlatform.exe | 獨立程序 |
| download_engine.dll | MiniTP核心庫 |
| zlib1.dll | 壓縮通信資料 |
| dl_peer_id.dll | 擷取迅雷用戶端辨別 |
| XLBugReport.exe | 負責上報捕獲到的崩潰 |
| XLBugHandler.dll | 負責拉起XLBugReport .exe |
| minizip.dll、mini_unzip.dll | 用于壓縮檔案崩潰堆棧 |
| atl71.dll | 微軟提供的程式庫 |
![測試基礎第一課[圖]](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=)