第十章 使用FTP

IRIS提供了一个类%Net.FtpSession，可以使用它从InterSystems IRIS内建立与FTP服务器的会话。

# 建立FTP会话

要建立FTP会话，请执行以下操作：

1. 创建%Net.FtpSession的实例。
2. 可以选择设置此实例的属性，以控制会话的常规行为：

- Timeout 超时指定等待FTP服务器回复的时间(以秒为单位)。
- SSLConfiguration指定用于连接的激活的SSL/TLS配置(如果有)。如果FTP服务器使用HTTPS，请使用此选项。
- TranslateTable指定在读取文件内容或写入文件内容时要使用的转换表。
- UsePASV启用PASV模式。
- 当FTP服务器使用https时，SSLCheckServerIdentity适用。默认情况下，当%Net.FtpSession的实例连接到SSL/TLS服务器时，它会检查证书服务器名称是否与用于连接到服务器的DNS名称匹配。如果这些名称不匹配，则不允许连接。

若要禁用此检查，请将SSLCheckServerIdentity属性设置为0。

3. 调用Connect()方法以连接到特定的FTP服务器。
4. 调用ascii()或binary()方法将传输模式分别设置为ASCII模式或二进制模式。要查看当前传输模式，请检查实例的Type属性的值。

注意：%Net.FtpSession的每个方法都返回一个状态，应该检查该状态。这些方法还设置提供有关会话状态的有用信息的属性的值：
- 如果当前已连接，则CONNECTED为TRUE，否则为FALSE。
- ReturnCode包含上次与FTP服务器通信时的返回代码。
- ReturnMessage包含上次与FTP服务器通信时的返回消息。

Status()方法返回(通过引用)FTP服务器的状态。

命令的转换表

%Net.FtpSession在FTP服务器上查看文件名和路径名时，使用RFC 2640中介绍的技术自动处理字符集转换。当%Net.FtpSession的实例连接到FTP服务器时，它会使用Feat消息来确定服务器是否使用UTF-8字符。如果是，它将命令通道通信切换到UTF-8，以便所有文件名和路径名都可以正确地与UTF-8相互转换。

如果服务器不支持FEAT命令或未报告支持UTF-8，%Net.FtpSession实例将使用RAW模式并读取或写入RAW字节。

在极少数情况下，如果需要指定要使用的转换表，请设置%Net.FtpSession实例的CommandTranslateTable属性。一般情况下，应该没有必要使用此属性。

FTP文件和系统方法

一旦建立了FTP会话，就可以调用会话实例的方法来执行FTP任务。%Net.FtpSession提供以下读写文件的方法：

Delete()

删除文件。

Retrieve()

将文件从FTP服务器复制到InterSystems IRIS流中，并通过引用返回该流。要使用此流，请使用标准流方法：Write()、WriteLine()、Read()、ReadLine()、Rewind()、MoveToEnd()和Clear()。还可以使用流的Size属性。

RetryRetrieve()

允许继续检索文件，因为给定的流是由上一次使用Retrieve()创建的。

Store()

将 IRIS流的内容写入FTP服务器上的文件。

Append()

将流的内容追加到指定文件的末尾。

Rename()

重命名文件。

此外，%Net.FtpSession提供了导航和修改FTP服务器上的文件系统的方法：GetDirectory()、SetDirectory()、SetToParentDirectory()和MakeDirectory()。

要检查文件系统的内容，请使用list()或NameList()方法。
- List()创建一个流，其中包含其名称与给定模式匹配的所有文件的列表，并通过引用返回该流。
- NameList()创建文件名数组并通过引用返回该数组。

还可以使用ChangeUser()方法更改为其他用户；这比注销并再次登录要快。使用Logout()方法注销。

System()方法返回(通过引用)有关托管FTP服务器的计算机类型的信息。

Size()和MDTM()方法分别返回文件的大小和修改时间。

使用通用sendCommand()方法向FTP服务器发送命令并读取响应。此方法可用于发送%Net.FtpSession中未明确支持的命令。

使用链接的流上载大文件

如果要上传大文件，请考虑使用流接口的LinkToFile()方法。也就是说，不是创建流并将文件读入其中，而是创建流并将其链接到文件。在调用%Net.FtpSession的Store()方法时使用此链接流。

Method SendLargeFile(ftp As %Net.FtpSession, dir As %String, filename As %String)
{
    Set filestream=##class(%FileBinaryStream).%New()
    Set sc=filestream.LinkToFile(dir_filename)
    If $$$ISERR(sc) {do $System.Status.DisplayError(sc) quit }

    //上传的文件将与原始文件同名
    Set newname=filename

    Set sc=ftp.Store(newname,filestream)
    If $$$ISERR(sc) {do $System.Status.DisplayError(sc) quit }
}

自定义FTP服务器发出的回调

可以自定义FTP服务器生成的回调。例如，通过这样做，可以向用户提供服务器仍在处理大型传输的指示，或允许用户中止传输。

要自定义FTP回调，请执行以下操作：

1. 创建%Net.FtpCallback的子类。
2. 在这个子类中，实现RetrieveCallback()方法，该方法在从FTP服务器接收数据时定期调用。
3. 还要实现StoreCallback()方法，在将数据写入FTP服务器时会定期调用该方法。
4. 创建FTP会话时(如“建立FTP会话”中所述)，将回调属性设置为等于的子类%Net.FtpCallback。