FTP文件上传控件开发文档-Xproer.FtpUploader

版权所有 2009-2014 荆门泽优软件有限公司

保留所有权利

官方网站：http://www.ncmem.com

产品首页：http://www.ncmem.com/webplug/ftp-uploader2/index.asp

在线演示：http://www.ncmem.com/products/ftp-uploader2/demo/index.html

产品介绍：http://www.cnblogs.com/xproer/archive/2011/04/04/2005241.html

开发文档：http://www.cnblogs.com/xproer/archive/2011/03/15/1984413.html

升级日志：http://www.cnblogs.com/xproer/archive/2011/04/04/2005251.html

资源下载：示例下载,开发文档,加密解密工具,cab安装包(x86),cab安装包(x64),VC库,根证书,ServU-7.x,ServU-9.x,FileZilla Server,

联系邮箱：[email protected]

联系QQ：1085617561

1. 概述

Xproer.FtpUploader文件上传控件可以帮助用户向服务器上传超过100G大小的文件。同时提供了断点续传的功能。如果用户在上传文件的过程中出现网络错误在下次上传时仍然可以继续上次上传的位置上传，而不需要重新上传，这个功能可以帮助用户节省许多时间，从而提高用户体能。有了这个功能新颖网络FTP文件上传控件就能够在更加复杂的网络环境中使用。

在实际的应用环境中，不同的用户可能会上传相同的文件，这些文件有的甚至达到2G左右，如果许多这样的文件重复存在那么将会占用许多的服务器空间。现在新颖网络FTP文件上传控件提供了MD5文件验证功能，通过这个功能系统可以在用户上传文件前在服务器验证相同的文件是否存在，如果存在那么就不必上传相同的文件，这样就可以帮助企业节省更多的服务器空间，从而为企业节省成本。

2. 正式包布署说明

1.将FtpUploader.cab,FtpUploader64.cab上传到服务器中。

2.修改FtpUploader.js中的Clsid,ActiveX名称,CabPath地址和版本号。

3. 快速开始

在本地快速搭建测试环境步骤：

1.架设FTP服务器。

2.修改演示文件中的配置。

3.运行示例。index.html

3.1. 架设FTP服务器

新颖网络FTP文件上传插件支持Microsoft FTP，Serv-U和FileZilla。

以下分别为FTP服务器的架设教程：

安装ServU—7.1：http://www.cnblogs.com/xproer/archive/2010/11/20/1882370.html

安装ServU-6.4.0.6：http://www.cnblogs.com/xproer/archive/2011/03/28/1998042.html

安装FileZilla Server：http://www.cnblogs.com/xproer/archive/2010/12/23/1914588.html

安装Microsoft FTP Server：http://www.cnblogs.com/xproer/archive/2011/03/06/1972192.html

3.2. 添加测试帐号

由于测试版FtpUploader只能连接127.0.0.1服务器，且只能以test帐号登陆，所以在演示时需要添加test帐号。

帐号：test

密码：test

3.3. 配置FTP信息

修改演示文件FtpUploader.html中的配置信息。

var ftpMgr = new FtpUploaderMg();

ftpMgr.Config["Server"] = "127.0.0.1";//测试版插件只能连接这个IP

ftpMgr.Config["UserName"] = "test";//设置FTP用户名。注意此处仅为了方便测试，正式应用时会将用户名和密码封装在控件内部。

ftpMgr.Config["UserPass"] = "test";//设置FTP密码。注意此处仅为了方便测试，正式应用时会将用户名和密码封装在控件内部。

3.4. 运行示例

在IE中打开文件FtpUploader.html

4. 用户接口

4.1. 设置FTP登陆信息

<script type="text/javascript" language="javascript">

var ftpMgr = new FtpUploaderMgr();

ftpMgr.Config["Server"] = "127.0.0.1";//测试版插件只能连接这个IP

ftpMgr.Config["UserName"] = "test";//设置FTP用户名。注意此处仅为了方便测试，正式使用时会将用户名和密码封装在控件内部。

ftpMgr.Config["UserPass"] = "test";//设置FTP密码。注意：此处仅为了方便测试，正式使用时会将用户名和密码封装在控件内部。

</script>

4.2. 打开帐号加密功能

<script type="text/javascript" language="javascript">

var ftpMgr = new FtpUploaderMgr();

ftpMgr.Config["Encryption"] = true;//打开帐号加密功能，帐号和密码都会被自动解密

</script>

4.3. 设置允许上传的文件类型

允许指定的文件类型：jpg,png,gif,bmp,doc,xls,ppt,rar,txt

允许所有的文件类型：*

<script type="text/javascript" language="javascript">

var ftpMgr = new FtpUploaderMgr();

ftpMgr.Config["FileFilter"] = "doc,xls,ppt,txt,png,jpg,bmp,gif,rar";//不同的文件类型以逗号分隔。如果允许所有的文件类型，则输入*

</script>

4.4. 上传指定路径的文件

主要步骤如下：

1.通过AddFile()函数添加指定文件。

2.通过PostFirst()函数上传文件。

<script type="text/javascript" language="javascript">

var ftpMgr = new FtpUploaderMgr();

ftpMgr.AddFile("D:\\Soft\\QQ2011.exe");

ftpMgr.PostFirst();

</script>

4.5. 自动创建多级目录

说明：

1.目录必须以反斜杠(/)分隔，不能是其它分隔符，比如正斜杠(\)

<script type="text/javascript" language="javascript">

var ftpMgr = new FtpUploaderMgr();

ftpMgr.Config["Server"] = "127.0.0.1";

ftpMgr.Config["RemoteFolder"] = "test1/test2/test3";//自动创建多级目录

window.onload = function()

{

ftpMgr.Init();

};

</script>

5. 功能

5.1. 文件MD5验证

主要步骤如下：

1. 将文件验证方式设为md5

2. 处理FtpUploader_MD5_Complete事件

1.设置文件验证方式

打开FtpUploader.js

修改FtpUploaderMgr的Config属性

将CrypType值改为md5

2.处理FtpUploader_MD5_Complete事件

打开文件FtpUploader.js，找到下面的代码。在修改此函数的逻辑，添加服务器验证的代码。

function FtpUploader_MD5_Complete(obj)

{

var cry = obj.Config["CrypType"].toLowerCase();

if (cry == "md5")

{

this.MD5 = obj.ATL.MD5;

alert(this.MD5);

}

else if (cry == "crc")

{

this.CRC = obj.ATL.CRC;

alert(this.CRC);

}

//在下面增加向服务器验证MD5的代码。

//obj.Upload();

}

6. JavaScript对象

6.1. FtpUploader对象

类型：JavaScript

文件上传对象的包装类，用户在实际的项目中只需要创建FtpUploader对象，然后通过FtpUploader对象就可以进行文件上传操作。

语法：

JavaScript（声明）

function FtpUploader() { }

属性

	名称	说明
	pMsg	消息对象。是一个DIV
	pProcess	上传进度条对象。是一个DIV
	pPercent	上传进度百分比对象。是一个DIV
	pButton	控制按钮对象。是一个A
	LocalFile	包含完整路径的本地文件名称。例：C:\qq.exe

方法

	名称	说明
	Ready	指示文件上传对象准备完毕
	Post	开始上传文件
	Stop	停止文件上传
	PostNext	继续传输上传队列中的下一个文件

Ready方法

将上传任务状态设置为准备状态。

Post方法

开始上传文件。

说明：此函数将会自动实现断点续传功能。如果当前任务文件只上传了一半，则在下次开始时XSUploader组件将会自动定位到上次上传的位置继续上传数据。

Stop方法

停止上传任务。

PostNext方法

继续上传队列中下一个任务。

事件

FtpUploader_StateChanged事件

语法

function FtpUploader_StateChanged(obj,state)

参数：

obj

FtpUploader对象

state

控件状态。

STA_Leisure	= 0	//空闲
,STA_Uploading	= 1	//上传中(暂时保留)
,STA_Complete	= 2	//传输完毕
,STA_Error	= 3	//错误
,STA_Connected	= 4	//服务器已连接
,STA_MD5_Working	= 5	//正在计算MD5
,STA_MD5_Complete	= 6	//MD5计算完毕

6.2. FtpUploaderMgr对象

类型：JavaScript

文件上传管理类。所有上传的文件都是通过此类来进行管理的。

构造函数

FtpUploaderMgr()

方法

AddFile方法

添加一个文件到上传对列中

语法：

void AddFile(fid);

参数：

fid

新上传任务的文件ID，此ID用来区域不同的上传任务。必须保证唯一。

PostFirst方法

开始上传队列中的第一个文件。

语法：

void PostFirst()

Exist方法

检查上传队列中是否存在指定文件。

语法：

bool Exist();

返回值：

true

表示存在。

false

不存在。

说明：此函数是根据本地文件的完整路径来检测的。

SetFileFilter方法

设置文件过滤器。

语法

void SetFileFilter(filter)

参数：

filter 文件类型字符串。由逗号分隔。示例：exe,gif,png

SetExtFilter方法

设置允许的文件类型。如果不设置文件类型，则表示不允许上传任何类型。

语法

bool IsExtFilter(fname);

参数：

filter 文件类型字符串，使用逗号分隔。示例：gif,jpg,bmp,png

属性

Config属性

提供插件的全局配置信息。在项目如果需要修改插件的配置信息，只需要通Config属性来控件即可。

语法：

this.Config = {

"Server" : "127.0.0.1"

, "UserName" : "test"

, "UserPass" : "test"

, "RemoteFolder": ""

, "Port" : 21

, "FileFilter": "*"//允许上传的文件类型。示例：jpg,bmp,gif,png,doc,xls,ppt,txt

};

示例-设置插件信息

var uploaderMgr = new FtpUploaderManager("FilePostLister");

uploaderMgr.Config["Server"] = "tel.ftp.u.115.com:21";

uploaderMgr.Config["UserName"] = "1199925";

uploaderMgr.Config["UserPass"] = "4b29da413f";

uploaderMgr.Config["RemoteFolder"] = "upload";

7. ActiveX对象

7.1. Xproer.FtpPartition对象

CLSID：9463F939-F485-404f-9FB0-8729E82DE11F

类型：ActiveX

多文件选择对象。弹出一个文件选择对话框，为用户提供选择多个文件的功能。

方法

	名称	说明
	ShowDialog	弹出文件选择对话框
	GetSelectedFiles	获取用户选择的文件列表

GetSelectedFiles方法

获取用户选择的文件列表数组。

示例

下面的代码示例将会创建一个文件选择框，并弹出用户所选择的文件名称。

JavaScript：

<script type="text/javascript" language="javascript">

function ShowSelectFileDlg()

{

var uploaderMgr = new FtpUploaderMgr();

var obj = new ActiveXObject("Xproer.FtpPartition");//创建文件选择对话框

if (!obj.ShowDialog()) return;

var list = obj.GetSelectedFiles();//获取用户选择的文件

if (list.lbound(1) == null) return;

for (var index = list.lbound(1); index <= list.ubound(1); index++)

{

if (!uploaderMgr.Exist(list.getItem(index)))

{

uploaderMgr.AddFile(list.getItem(index));

}

}

uploaderMgr.PostFirst();

}

</script>

7.2. Xproer.FtpUploader对象

CLSID：572A8DD8-0CAC-46c0-A363-B3496887E3D9

类型：ActiveX

文件上传对象，负责文件具体的上传和续传工作。

属性

	名称	说明
	FileID	文件ID。必须唯一。
	LocalFile	包含完整路径的本地文件名称。例：D:\QQ.exe
	RemoteFolder	远程文件夹，文件上传后在服务器端存储的位置
	RemoteFile	远程文件名称。
	UserName	FTP服务器用户名
	UserPass	FTP服务器密码
	IP	FTP服务器IP地址
	Port	FTP服务器端口。默认为21
	Passive	是否被动模式。默认false

事件

	名称	说明
	OnPost	每当向服务器传输成功一部分数据时发生
	OnStateChanged	状态改变事件。MD5计算，上传错误，等。详细参考FtpUploader_StateChanged事件

OnConnected事件

服务器连接成功事件。

语法：

function FtpUploader_Connected(obj)

参数：

obj JS上传对象。

OnComplete事件

传输完成事件，当文件成功上传完毕后，系统将会调用此方法

语法

function FtpUploader_Complete(obj)

参数：

obj JS上传对象。

OnPost事件

传输数据事件。每当XSUploader插件成功向服务器传输二进制数据后将触发此事件。

语法：

function FtpUploader_Process(obj, speed, postedLength, percent, time)

参数：

obj	JS上传对象。
speed	上传速度。5KB/S
postedLength	已上传大小。12.05MB
percent	已完成百分比。50%
time	剩余时间。00:02:10

OnError事件

传输错误事件，当传输出现错误时系统将会自动调用此事件。

语法：

function FtpUploader_Error(obj, errCode)

参数：

obj JS上传对象。

errCode 错误码。

错误码

"0":	"启动网络环境错误"
"1":	"SOCKET错误"
"2":	"打开SOCKET错误"
"3":	"创建SOCKET错误"
"4":	"连接服务器错误"
"5":	"发送用户名错误"
"6":	"发送密码错误"
"7":	"发送数据错误"
"8":	"本地文件为空"
"9":	"远程文件为空"
"10":	"服务器IP为空"
"11":	"用户名为空"
"12":	"密码为空"
"13":	"本地文件不存在"
"14":	"不能读取本地文件"
"15":	"向本地文件写入数据失败"
"16":	"向服务器写入数据失败"
"17":	"网络命令错误"
"18":	"远程文件不存在"
"19":	"创建目录失败"
"20":	"本地文件大小超过1G"
"21":	"用户名或密码错误"
"22":	"IP未授权"

示例

下面的代码将会创建一个上传项，并将本地C盘下的myfile.txt文件上传到服务端，并以myfile.txt保存。

JavaScript

var upFile = new FileUploader(1);//这里创建了一个文件上传任务,并将文件ID设置为1

upFile.ATL.UserName = "test"; //设置FTP服务器用户名

upFile.ATL.UserPass = "test"; //设置FTP服务器密码

upFile.ATL.IP = "192.168.1.1"; //设置FTP服务器IP地址

upFile.ATL.Passive = false; //传输模式为被动模式

upFile.ATL.LocalFileName = "C:\\myfile.txt";//设置要上传的本地文件

upFile.ATL.RemoteFileName = "myfile.txt"; //设置目标文件名称

upFile.ATL.RemoteFolder = ""; //设置远程文件夹，用来存放用户上传的文件。这里默认为根目录。

//设置事件，这些事件必须设置，否则上传任务将无法执行

upFile.ATL.OnComplete = FtpUploader_Complete;

upFile.ATL.OnPost = FtpUploader_Process;

upFile.ATL.OnError = FtpUploader_Error;

upFile.ATL.OnConnected = FtpUploader_Connected;

upFile.Post(); //开始上传

7.3. Xproer.FtpDroper对象

CLSID：9FC9422C-5C02-4879-889C-9C0014EB384B

类型：ActiveX

文件拖放面板，为用户提供文件的拖放功能。

事件

OnFileDrop事件

文件拖放事件。当用户从资源管理器向拖放面板中拖放文件时此事件将会自动被调用。

参数：

arguments[0]

文件列表数组

示例-获取用户拖放的文件列表名称

<HTML>

<HEAD>

<TITLE>New Page</TITLE>

</HEAD>

<BODY>

<!—object对象用来帮助ActiveX控件进行自动升级-->

<OBJECT ID="FilePanel1" WIDTH=192 HEIGHT=192 CLASSID="clsid: AF145FF6-EF91-4C91-BD85-D4ECCA224D27" DATA="DATA:application/x-oleobject;BASE64,P0yJ/coEwUiWnGww8Tau4AADAADYEwAA2BMAAA==">

</OBJECT>

<div id="divFileLister"></div>

<script language="javascript" type="text/javascript">

var obj = document.getElementById("FilePanel1");

obj.OnFileDrop = EventFileDrop;

function EventFileDrop()

{

var lister = document.getElementById("divFileLister");

var list = obj.GetSelectedFiles();//获取选择的文件

for (var index = list.lbound(1); index <= list.ubound(1); ++index)

{

lister.innerHTML += "<p>文件名：" + list.getItem(index) + "</p>";

}

}

</script>

</BODY>

</HTML>

8. 数据库设计

序号	列名	数据类型	长度	小数位	标识	主键	允许空	默认值	说明
1	ID	int			是	是	否
2	FileName	varchar	50				是		文件名称。QQ.exe,客户端通过encodeURIComponent编码
3	LocalFile	varchar	255				是		包含完整路径的本地文件名称。D:\Soft\QQ.exe
4	RemoteFileName	varchar	255				是		远程文件名称。一般情况下指用户重新设置的文件名称。QQ.exe
5	RemoteFolder	varchar	255				是		远程文件夹名称。示例：F:\ftp\user1
6	PostedLength	varchar	50				是		已上传长度。以字节为单位。
7	FileLength	varchar	50				是		文件长度。以字节为单位
8	PostedPercent	varchar	4				是		已上传百分比。示例：10%
9	FileMD5	varchar	32				是		文件MD5
10	PostComplete	bit	2				否	0	是否已上传完毕。
11	UserID	int					是	0	用户ID。一般与用户数据表相关联
12	PostedTime	datetime					是	Now()

9. UI模板

您可以根据需要修改此模板。

HTML:

<div class="UploaderItem" id="UploaderTemplate">

<div class="UploaderItemLeft">

<div class="FileName top-space">FtpUploader程序开发.pdf</div>

<div class="ProcessBorder top-space">

<div class="Process"></div>

</div>

<div class="PostInf top-space">已上传:15.3MB 速度:20KB/S 剩余时间:10:02:00</div>

</div>

<div class="UploaderItemRight">

<a class="Btn" href="javascript:void(0);">取消</a>

<div class="ProcessNum">35%</div>

</div>

</div>

10. CSS模板

CSS模型，可以通过IE8来查看HTML构架。

开发者可以根据需要来修改样式。通过修改下面的样式可以自定义上传项模板的大小高度宽度和颜色。

//文件上传项模板

div.UploaderItem{width: 410px;font-family: 新宋体;font-size: 12px; background-color: #FFFFFF; height:55px; margin:5px 10px 0 20px;display:none;}

div.top-space{margin:3px 0 0 0;}

//左侧

div.UploaderItemLeft{width:370px; float:left;}

//文件名称

div.UploaderItem div.FileName{width:230px;font-weight: bold; overflow:hidden; text-overflow:ellipsis;white-space:nowrap;}

//进度条边框

div.UploaderItem div.ProcessBorder{width:364px;padding: 0px;border: 1px solid #AAAAAA; }

//进度条背景色

div.UploaderItem div.Process{width:0; height:12px; background-color: #A5DF16;}

//上传信息。例：已上传大小，速度，剩余时间。

div.UploaderItem div.PostInf{color: #7A8F99;}

//右侧

div.UploaderItemRight{width:30px; float:left;margin:3px 0 0 0;}

//已上传百分比

div.UploaderItem div.ProcessNum{width:30px; height:14px; line-height:14px; margin:3px 0 0 0;}

//控制按钮样式

div.UploaderItem a.Btn,div.UploaderItem a.Btn:hover{text-decoration: underline; color:#244281; height:12px;display:block;}

11. 示例代码

11.1. 添加多个文件

以下示例将会弹出一个对话框并将用户选定的文件上传到服务器中。

JavaScript:

<script type="text/javascript" language="javascript">

function ShowSelectFileDlg()

{

var uploaderMgr = new FtpUploaderMgr();

var obj = new ActiveXObject("Xproer.FtpPartition");

if (!obj.ShowDialog()) return;//打开选择文件对话框

var list = obj.GetSelectedFiles();//获取用户选择的文件

if (list.lbound(1) == null) return;

for (var index = list.lbound(1); index <= list.ubound(1); index++)

{

if (!uploaderMgr.Exist(list.getItem(index)))

{

uploaderMgr.AddFile(list.getItem(index));

}

}

uploaderMgr.PostFirst();//开始上传队列中的第一个文件

}

</script>

11.2. 添加需要过滤的文件类型

设置类型只需要调用FileTransferManager的SetFileFilter成员方法来设置要过滤的扩展名称。

<script type="text/javascript" language="javascript">

function UpFiles()

{

var uploaderMgr = new FtpUploaderMgr();

uploaderMgr.SetFileFilter("txt");

}

</script>

11.3. 添加允许上传的文件类型

设置类型只需要调用FileTransferManager的SetExtFilter成员方法来设置要过滤的扩展名称。

<script type="text/javascript" language="javascript">

function UpFiles()

{

var uploaderMgr = new FtpUploaderMgr();

uploaderMgr.SetExtFilter("gif");//只允许上传gif类型的文件

}

</script>

12. 帮助文档

12.1. 如何上传指定路径的文件

主要步骤如下：

1.通过AddFile()函数添加指定文件。

2.通过PostFirst()函数上传文件。

<script type="text/javascript" language="javascript">

var uploaderMgr = new FtpUploaderMgr();

uploaderMgr.AddFile("D:\\Soft\\QQ2011.exe");

uploaderMgr.PostFirst();

</script>

12.2. 如何在文件上传成功后进行自定义操作

FileUploader插件提供了OnComplete事件，当文件上传成功后COM插件将会调用这个事件。开发人员可以在这个事件中编写自已的业务逻辑代码。

以下示例演示如何自定义ActiveX完成事件

var ATL = new ActiveXObject("Xproer.FtpUploader");

ATL.OnComplete = FtpUploader_Complete;//设置事件

//ActiveX事件-上传完成

function FtpUploader_Complete(obj)

{

//开发者可以在此处自定义代码

CurrentFileUploader = null;

obj.pButton.innerText = "";

obj.pProcess.style.width = "100%";

obj.pPercent.innerText = "100%";

obj.pMsg.innerText = "上传完成";

obj.State = FileUploaderState.Complete;

obj.PostNext();

}

12.3. 调用AJAX示例

包含JQuery文件

JQuery官网：http://jquery.com/

JQuery v1.5.2下载地址：http://code.jquery.com/jquery-1.5.2.min.js

<script src="jquery-1.4.1.min.js" type="text/javascript" language="javascript"></script>

function FtpUploader_MD5_Complete(obj)

{

var cry = obj.Config["CrypType"].toLowerCase();

if (cry == "md5")

{

obj.MD5 = obj.ATL.MD5;

}

else if (cry == "crc")

{

obj.CRC = obj.ATL.CRC;

}

//异步调用AJAX，向WEB服务器发送请求，验证相同MD5是否存在

var param = { md5: obj.MD5, uid: obj.Config["UserID"] };

//以AJAX方向添加到服务器

$.ajax({

type: "GET"

, url:["ajax_check.aspx"]

, data: param

, success: function(msg)

{

//已存在相同MD5值文件

if (msg == "1")

{

//自定义逻辑处理

obj.PostNext();

}//不存在

else

{

//开始上传文件

obj.Post();

}

}

});

}