Inheritance diagram for FtpSession:

[legend]

Collaboration diagram for FtpSession:

[legend]

Public Member Functions
_.Library.Status	OnClose ()

_.Library.Boolean	Append (_.Library.String Filename, _.Library.AbstractStream Stream)
	Append the data contained in Stream to the file named in Filename.

_.Library.Boolean	Ascii ()
	Switch the ftp server transfer type to Ascii. More...

_.Library.Boolean	Binary ()
	Switch the ftp server transfer type to Binary. More...

_.Library.Boolean	ChangeUser (_.Library.String Username, _.Library.String Password)
	Change the user that we are logged in as. More...

_.Library.Boolean	Connect (_.Library.String Server, _.Library.String Username, _.Library.String Password, _.Library.Integer Port)
	Connect to an Ftp server. More...

_.Library.Boolean	Delete (_.Library.String Filename)
	Delete the file Filename on the Ftp server.

_.Library.Boolean	Features ()
	See which features the ftp server supports.

_.Library.Boolean	GetDirectory (_.Library.String Path)
	Return the current directory the Ftp server is in the parameter Path that. More...

_.Library.Boolean	List (_.Library.String Pattern, _.Library.AbstractStream Stream)
	Read in the files that match the Pattern in a human readable format. More...

_.Library.Boolean	Logout ()
	Logoff and disconnect from the Ftp server.

_.Library.Boolean	MDTM (_.Library.String Filename, _.Library.Float Time)
	If the FTP server supports it then this will return a files modification time based on GMT. More...

_.Library.Boolean	MakeDirectory (_.Library.String Path)
	Create a new directory on the Ftp server. More...

_.Library.Boolean	NameList (_.Library.String Path, _.Library.ArrayOfDataTypes FileArray)
	Given a Path this will return an array of filenames including their path in the parameter. More...

_.Library.Boolean	RemoveDirectory (_.Library.String Path)
	Delete the directory passed in Path from the Ftp server.

_.Library.Boolean	Rename (_.Library.String OldFilename, _.Library.String NewFilename)
	Rename a file from OldFilename to NewFilename.

_.Library.Integer	Retrieve (_.Library.String Filename, _.Library.AbstractStream Stream)
	Retrieve the file specified by Filename into Stream. More...

_.Library.Integer	RetryRetrieve (_.Library.String Filename, _.Library.AbstractStream Stream)
	If a <METHOD>Retrieve</METHOD> failed because the connection was lost this allows. More...

_.Library.Boolean	SetDirectory (_.Library.String Path)
	Set the directory on the Ftp server to Path.

_.Library.Boolean	SetToParentDirectory ()
	Move to parent directory on the Ftp server.

_.Library.Boolean	Size (_.Library.String Filename, _.Library.Integer Size)
	If the FTP server supports it then this will return a files size based on the current. More...

_.Library.Boolean	Status (_.Library.String Status)
	Return the status of the Ftp server in the Status parameter which should. More...

_.Library.Boolean	Store (_.Library.String Filename, _.Library.AbstractStream Stream)
	Store the data in Stream in the Filename on the Ftp server.

_.Library.Boolean	StoreFiles (_.Library.String Directory, _.Library.String Wildcards, _.Library.String Delimiter)
	Upload the files in Directory matching the set of Wildcards to the Server. More...

_.Library.Boolean	System (_.Library.String System)
	Return information about the type of computer you are connected to in the. More...

_.Library.Boolean	sendCommand (_.Library.String Command, _.Library.Boolean noread)
	Generic method to send a command to the ftp server and read the response. More...

Public Member Functions inherited from RegisteredObject
_.Library.Status	OnAddToSaveSet (_.Library.Integer depth, _.Library.Integer insert, _.Library.Integer callcount)
	This callback method is invoked when the current object is added to the SaveSet,. More...

_.Library.Status	OnConstructClone (_.Library.RegisteredObject object, _.Library.Boolean deep, _.Library.String cloned)
	This callback method is invoked by the <METHOD>ConstructClone</METHOD> method to. More...

_.Library.Status	OnNew ()
	This callback method is invoked by the <METHOD>New</METHOD> method to. More...

_.Library.Status	OnValidateObject ()
	This callback method is invoked by the <METHOD>ValidateObject</METHOD> method to. More...

Static Public Member Functions
_.Library.Boolean	isPrivate (_.Library.String address)
	Return true if this IPv4 address is a private address.

Public Attributes
	AutoDetectPrivate
	When using PASV mode (see <property>UsePASV</property>) the remote server supplies the. More...

	Callback
	The Callback property is designed to allow user code in the class. More...

	CommandTranslateTable
	The translate table to use for the command channel, specifically for the filename/pathnames. More...

	Connected
	True if we are currently connected to an ftp server and false if not. More...

	IsIPV6
	True if the connection is IPV6 protocol. More...

	LegacySSL
	If true and you specify a <property>SSLConfiguration</property> then this class. More...

	ReturnCode
	ReturnCode is a the three digit number that the ftp server reponds to commands. More...

	ReturnMessage
	ReturnMessage is set to the text message. More...

	SSLCheckServerIdentity
	When making an SSL connection check the server identity in the server certificate matches the name of the system we are connecting to. More...

	SSLConfiguration
	The name of the activated TLS configuration to use for ftp requests. More...

	SSLUseSessionResumption
	When making the SSL connection for the data channel, reuse session parameters from the command channel. More...

	ServerAddr
	Server's IP address to be used in EPSV mode with IPV6 protocol. More...

	Timeout
	Timeout is the amount of time to wait for a response from the ftp server before. More...

	TranslateTable
	The translate table to be used when reading or writing files. More...

	Type
	Type returns the transfer mode the ftp server is currently set to. More...

	UseExtensions
	Indicates whether to use FTP Extensions for IPv6 and NATs. More...

	UsePASV
	Ftp connections are formed from two TCP/IP connections to the remote server,. More...

Private Attributes
	__device
	More...

	__serverIP
	More...

	__transferType
	More...

Additional Inherited Members
Static Public Attributes inherited from RegisteredObject
	CAPTION = None
	Optional name used by the Form Wizard for a class when generating forms. More...

	JAVATYPE = None
	The Java type to be used when exported.

	PROPERTYVALIDATION = None
	This parameter controls the default validation behavior for the object. More...

Detailed Description

For information on using this class, see Using FTP.

The Net.FtpSession class provides a way of interacting with a FTP server so you can send/receive files, get a list of the files on the server, rename files, delete files, etc.

All the methods will return a boolean that is true if the method succeeded and false if it failed. They will also set the two properties <PROPERTY>ReturnCode</PROPERTY> and <PROPERTY>ReturnMessage</PROPERTY> with information from the ftp server you are connected to. This often contains useful information if a method fails. You should at the very least check the return value from each of the methods after every call.

Once you have created an object of this class you need to login to the server you wish to communicate with before you can do anything else, this is done with the <METHOD>Connect</METHOD> method. You can tell if you are connected to a server by looking at the property <PROPERTY>Connected</PROPERTY>.

If an ftp server at 'TestMachine' had a binary file called 'test.exe' in the root ftp directory then the following example will pull this file into InterSystems IRIS.

Set ftp=##class(Net.FtpSession).New() If 'ftp.Connect("TestMachine","ftp","username@domain.com") Write "Not connected",! Quit Write "Ftp server messsage:",!,ftp.ReturnMessage,! Set stream=##class(GlobalCharacterStream).New() If 'ftp.Binary() Write "Can not swap to binary mode",! Quit Write "Mode now: ",ftp.Type,! If 'ftp.Retrieve("test.exe",stream) Write "Failed to get file",! Quit Write "Length of file received: ",stream.Size,! If 'ftp.Logout() Write "Failed to logout",! Quit

Member Function Documentation

◆ OnClose()

_.Library.Status OnClose ( )

For information on using this class, see Using FTP.

The Net.FtpSession class provides a way of interacting with a FTP server so you can send/receive files, get a list of the files on the server, rename files, delete files, etc.

All the methods will return a boolean that is true if the method succeeded and false if it failed. They will also set the two properties <PROPERTY>ReturnCode</PROPERTY> and <PROPERTY>ReturnMessage</PROPERTY> with information from the ftp server you are connected to. This often contains useful information if a method fails. You should at the very least check the return value from each of the methods after every call.

Once you have created an object of this class you need to login to the server you wish to communicate with before you can do anything else, this is done with the <METHOD>Connect</METHOD> method. You can tell if you are connected to a server by looking at the property <PROPERTY>Connected</PROPERTY>.

If an ftp server at 'TestMachine' had a binary file called 'test.exe' in the root ftp directory then the following example will pull this file into InterSystems IRIS.

Set ftp=##class(Net.FtpSession).New() If 'ftp.Connect("TestMachine","ftp","username@domain.com") Write "Not connected",! Quit Write "Ftp server messsage:",!,ftp.ReturnMessage,! Set stream=##class(GlobalCharacterStream).New() If 'ftp.Binary() Write "Can not swap to binary mode",! Quit Write "Mode now: ",ftp.Type,! If 'ftp.Retrieve("test.exe",stream) Write "Failed to get file",! Quit Write "Length of file received: ",stream.Size,! If 'ftp.Logout() Write "Failed to logout",! Quit

Reimplemented from RegisteredObject.

◆ Ascii()

_.Library.Boolean Ascii ( )

Switch the ftp server transfer type to Ascii.

This will for example convert Cr/Lf

to Lf for Unix systems. When transfering text files you should use this mode. The current mode can be found by looking at the property <PROPERTY>Type</PROPERTY>.

◆ Binary()

_.Library.Boolean Binary ( )

Switch the ftp server transfer type to Binary.

This will store the data in exactly

the same format it is sent in. When transfering any binary files you should use this mode. The current mode can be found by looking at the property <PROPERTY>Type</PROPERTY>.

◆ ChangeUser()

_.Library.Boolean ChangeUser	(	_.Library.String	Username,
		_.Library.String	Password
	)

Change the user that we are logged in as.

This assumes you are already connected

to the ftp server at this point.

◆ Connect()

_.Library.Boolean Connect	(	_.Library.String	Server,
		_.Library.String	Username,
		_.Library.String	Password,
		_.Library.Integer	Port
	)

Connect to an Ftp server.

You should supply the server IP address or domain name

to connect to as the Server parameter. Also most Ftp server will require a Username and a Password in order to allow you to login. To login to an anonymous Ftp server use the Username="anonymous" and the Password is your email address.
Port is an optional parameter that specifies the IP port number to connect on if it is not the standard port of 21.

◆ GetDirectory()

_.Library.Boolean GetDirectory ( _.Library.String Path )

Return the current directory the Ftp server is in the parameter Path that.

is passed by reference.

◆ List()

_.Library.Boolean List	(	_.Library.String	Pattern,
		_.Library.AbstractStream	Stream
	)

Read in the files that match the Pattern in a human readable format.

into Stream. The Pattern can include a path as well pattern to search for, and if no pattern is specified then it will list all the files in this directory. The information returned contains server information like the file size, permissions modification time as well as the filename. The format of this is server specific.

◆ MDTM()

_.Library.Boolean MDTM	(	_.Library.String	Filename,
		_.Library.Float	Time
	)

If the FTP server supports it then this will return a files modification time based on GMT.

as a float value in the Time output argument. Returns true if it completed correctly.

◆ MakeDirectory()

_.Library.Boolean MakeDirectory ( _.Library.String Path )

Create a new directory on the Ftp server.

Path should be passed by

reference and it will return the name of the directory created. The Ftp server will translate the path you give it into its own format (which may be different) and is the value returned by in Path.

◆ NameList()

_.Library.Boolean NameList	(	_.Library.String	Path,
		_.Library.ArrayOfDataTypes	FileArray
	)

Given a Path this will return an array of filenames including their path in the parameter.

FileArray, this parameter should be passed by reference and if not already created it will create a new <CLASS>ArrayOfDataTypes</CLASS>. An example of its use assuming is:

New fileArray,key If 'ftp.NameList("",.fileArray) Write "Failed to get name list",! Set key="" Write "List of Files:",! For Write fileArray.GetNext(.key),! Quit:(key="")

◆ Retrieve()

_.Library.Integer Retrieve	(	_.Library.String	Filename,
		_.Library.AbstractStream	Stream
	)

Retrieve the file specified by Filename into Stream.

If Stream is not specified it will be created, in which case you should pass it by reference so it can be returned to the caller.

◆ RetryRetrieve()

_.Library.Integer RetryRetrieve	(	_.Library.String	Filename,
		_.Library.AbstractStream	Stream
	)

If a <METHOD>Retrieve</METHOD> failed because the connection was lost this allows.

you to retry getting the file. So if you have got 1/2 of the original file in the first attempt for Filename you pass the Stream with this half into this method and it will start where the other transfer left off.

◆ Size()

_.Library.Boolean Size	(	_.Library.String	Filename,
		_.Library.Integer	Size
	)

If the FTP server supports it then this will return a files size based on the current.

transfer type in the Size output argument. Returns true if it completed correctly.

◆ Status()

_.Library.Boolean Status ( _.Library.String Status )

Return the status of the Ftp server in the Status parameter which should.

be passed by reference.

◆ StoreFiles()

_.Library.Boolean StoreFiles	(	_.Library.String	Directory,
		_.Library.String	Wildcards,
		_.Library.String	Delimiter
	)

Upload the files in Directory matching the set of Wildcards to the Server.

Multiple Wildcards can be passed. In this case, each wildcard must be separated by the Delimiter. The default Delimiter is ";". <method>StoreFiles</method> ignores subdirectories. All files will be uploaded using the current transfer mode (<property>Type</property>). This means that binary and ASCII files cannot be uploaded together in a single call. If mixed file types are needed, separate the upload into batches, for example:

If 'ftp.Ascii() Write "Can not swap to Ascii mode",! Quit If 'ftp.StoreFiles("/myfiles","*.txt;*.csv") Write "Failed to store text files",! Quit If 'ftp.Binary() Write "Failed to swap to Binary mode",! Quit If 'ftp.StoreFiles("/myfiles","*.bin") Write "Failed to store binary files",! Quit

◆ System()

_.Library.Boolean System ( _.Library.String System )

Return information about the type of computer you are connected to in the.

by reference parameter System.

◆ sendCommand()

_.Library.Boolean sendCommand	(	_.Library.String	Command,
		_.Library.Boolean	noread
	)

Generic method to send a command to the ftp server and read the response.

It returns true if the command

worked and false if there was an error status returned. See <property>ReturnStatus</property> for the returned status and <property>ReturnMessage</property> for the returned message.

Member Data Documentation

◆ AutoDetectPrivate

AutoDetectPrivate

When using PASV mode (see <property>UsePASV</property>) the remote server supplies the.

IP address and port to connect to. On misconfigured servers it is possible this may report a private IP address when we are connecting to it from a public IP address so the PASV connection fails. We automatically detect this and use the initial IP address we had connected to in this case, but if you set this property =0 it turns this detection off. If this property is 2 then we never use the PASV supplied server IP and always use the original server address.

◆ Callback

Callback

The Callback property is designed to allow user code in the class.

<CLASS>Net.FtpCallback</CLASS> to be called at regular intervals during an ftp <METHOD>Store</METHOD> or <METHOD>Retrieve</METHOD>. This can display the progress of the ftp operation to the user and could allow the user to abort the transfer.

◆ CommandTranslateTable

CommandTranslateTable

The translate table to use for the command channel, specifically for the filename/pathnames.

See Translation Tables.
Normally this should not be specified in which case if the ftp server supports UTF-8 then we will use that for the filename/pathnames, if the server does not support UTF-8 then we will use RAW mode and just read the bytes as sent.

◆ Connected

Connected

True if we are currently connected to an ftp server and false if not.

◆ IsIPV6

IsIPV6

True if the connection is IPV6 protocol.

◆ LegacySSL

LegacySSL

If true and you specify a <property>SSLConfiguration</property> then this class.

will use non-standard implied SSL on the data and command channel rather than using RFC4217. Depending on the configuration of the server you are talking to it may be needed to also send 'PBSZ 0' and 'PROT P' before you can communicate, this can be done with 'Set rc=ftp.sendCommand("PBSZ 0"),rc2=ftp.sendCommand("PROT P")'.

◆ ReturnCode

ReturnCode

ReturnCode is a the three digit number that the ftp server reponds to commands.

with. This can be used to determine if the command completed or if there were problems. See the rfc on ftp for more information on these codes.

◆ ReturnMessage

ReturnMessage

ReturnMessage is set to the text message.

that the ftp server responds with, this often contains useful information if a method failed, or useful information such as the text banner you get when you first login to an ftp server.

◆ SSLCheckServerIdentity

SSLCheckServerIdentity

When making an SSL connection check the server identity in the server certificate matches the name of the system we are connecting to.

This defaults to being off and matches based on the rules layed out in section 3.1 of RFC 2818.

◆ SSLConfiguration

SSLConfiguration

The name of the activated TLS configuration to use for ftp requests.

If specified then we use TLS on the FTP connection as specified in RFC4217. Both the data and the command channel will be secured with TLS after the initial connect on the command channel tells the remote server to switch to TLS mode.

◆ SSLUseSessionResumption

SSLUseSessionResumption

When making the SSL connection for the data channel, reuse session parameters from the command channel.

This feature requires OpenSSL v1.1.x+.

◆ ServerAddr

ServerAddr

Server's IP address to be used in EPSV mode with IPV6 protocol.

◆ Timeout

Timeout

Timeout is the amount of time to wait for a response from the ftp server before.

assuming that the server is not responding or the network connection is not working. The default value is 10 seconds.

◆ TranslateTable

TranslateTable

The translate table to be used when reading or writing files.

See Translation Tables.

◆ Type

Type

Type returns the transfer mode the ftp server is currently set to.

This can be

either Ascii or Binary. The methods <METHOD>Ascii</METHOD> and <METHOD>Binary</METHOD> change the mode the server is currently set to.

◆ UseExtensions

UseExtensions

Indicates whether to use FTP Extensions for IPv6 and NATs.

When set, the extension commands EPRT and EPSV

will be used in place of the PORT and PASV commands. The default value is 0, but UseExtentions is automatically set to 1 when an IPV6 address is used. The FTP Extension commmands are useful to avoid problems using FTPS with Network Address Translation (NAT) as when traversing firewalls.

◆ UsePASV

UsePASV

Ftp connections are formed from two TCP/IP connections to the remote server,.

a command channel where the ftp commands are sent down and command responses are retrieved and a data channel for streaming large pieces of data. The way the data channel is connected is determined by this property. In PASV mode, the default, this ftp client asks the server where to connect for the data channel and it then initiates this connection to the remote server. If PASV mode is not used then the client tells the remote server where to connect to and the remote server initiates the data connection to this client machine. PASV mode is turned on by default because when going through a firewall having the remote ftp server initiate the data channel often does not work, but PASV mode will work in this case.

◆ __device

__device

private

◆ __serverIP

__serverIP

private

◆ __transferType

__transferType

private

Public Member Functions

Static Public Member Functions

Public Attributes

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ OnClose()

◆ Ascii()

◆ Binary()

◆ ChangeUser()

◆ Connect()

◆ GetDirectory()

◆ List()

◆ MDTM()

◆ MakeDirectory()

◆ NameList()

◆ Retrieve()

◆ RetryRetrieve()

◆ Size()

◆ Status()

◆ StoreFiles()

◆ System()

◆ sendCommand()

Member Data Documentation

◆ AutoDetectPrivate

◆ Callback

◆ CommandTranslateTable

◆ Connected

◆ IsIPV6

◆ LegacySSL

◆ ReturnCode

◆ ReturnMessage

◆ SSLCheckServerIdentity

◆ SSLConfiguration

◆ SSLUseSessionResumption

◆ ServerAddr

◆ Timeout

◆ TranslateTable

◆ Type

◆ UseExtensions

◆ UsePASV

◆ __device

◆ __serverIP

◆ __transferType