ipworksssl.Ftps
|
IP*Works! SSL V9 | |||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||
java.lang.Object
public class Ftps
The FTPS Bean can be used to transfer files to and from FTP servers using the FTP Protocol.
The FTPS Bean is the SSL-enabled equivalent of the IP*Works! FTP bean. The main difference is the introduction of a set of new configuration settings, properties and events that deal with SSL security. The ipworksssl.Ftps#config and {@link ipworksssl.Ftps#config configuration settings determine which protocols are enabled and at what security level. The {@link ipworksssl.Ftps#getSSLCert SSLCert} property is used to select a client certificate if the server is requesting client authentication. The {@link ipworksssl.Ftps#config configuration setting, together with the {@link ipworksssl.FtpsSSLServerAuthenticationEvent SSLServerAuthentication} event allow you to check the server identity and other security attributes. Finally, the {@link ipworksssl.FtpsSSLStatusEvent SSLStatus} event provides information about the SSL handshake.
The FTPS Bean implements a standard FTP client as specified in RFC 959 and RFC 1579 with the added option of SSL security (RFC 2228) in both the protocol and data channels.
The first step in using the bean is specifying the {@link ipworksssl.Ftps#getRemoteHost RemoteHost} , {@link ipworksssl.Ftps#getUser User} and {@link ipworksssl.Ftps#getPassword Password} . The file to upload to or download from is given by the {@link ipworksssl.Ftps#getRemoteFile RemoteFile} property. The file to download to or upload from is specified by {@link ipworksssl.Ftps#getLocalFile LocalFile} . The current path in the server is specified by the {@link ipworksssl.Ftps#getRemotePath RemotePath} property. The {@link ipworksssl.Ftps#isPassive Passive} property is especially useful if the client is behind a firewall which inhibits incoming connections to higher ports.
If {@link ipworksssl.Ftps#getLocalFile LocalFile} is set to something other than an empty string, then files are received in {@link ipworksssl.Ftps#getLocalFile LocalFile} , otherwise the data is received through the {@link ipworksssl.FtpsTransferEvent Transfer} event. {@link ipworksssl.FtpsStartTransferEvent StartTransfer} and {@link ipworksssl.FtpsEndTransferEvent EndTransfer} are fired at the beginning and end of transmission.
The {@link ipworksssl.FtpsPITrailEvent PITrail} event traces the interaction between the client and the server (the FTP Protocol Interface connection).
Directory listings are received through the {@link ipworksssl.FtpsDirListEvent DirList} event.
| Field Summary | |
|---|---|
static int |
sslAutomatic
|
static int |
sslExplicit
|
static int |
sslImplicit
|
static int |
sslNone
|
static int |
tmASCII
|
static int |
tmBinary
|
static int |
tmDefault
|
| Constructor Summary | |
|---|---|
Ftps()
Creates an instance of Ftps Bean. |
|
Ftps(java.lang.String runtimeLicense)
Creates an instance of Ftps Bean with specified run-time license. |
|
| Method Summary | |
|---|---|
void |
abort()
Abort Current Upload/Download. |
void |
addFtpsEventListener(FtpsEventListener l)
|
void |
append()
Append data from LocalFile to a RemoteFile on an FTP server. |
java.lang.String |
config(java.lang.String configurationString)
Sets or retrieves a {@link ipworksssl.Ftps#config configuration setting. |
void |
deleteFile(java.lang.String fileName)
Remove a file specified by FileName from an FTP server. |
void |
doEvents()
Processes events from the internal message queue. |
void |
download()
Download a RemoteFile from an FTP server. |
java.lang.String |
getAccount()
The user account to login with. |
DirEntryList |
getDirList()
Collection of entries resulting in the last directory listing. |
long |
getFileSize()
The size of the file pointed to by RemoteFile . |
java.lang.String |
getFileTime()
The last modification time of the file pointed to by RemoteFile . |
Firewall |
getFirewall()
A set of properties related to firewall access. |
java.lang.String |
getLastReply()
The last reply from the server. |
java.lang.String |
getLocalFile()
The path to a local file for download/upload. |
java.lang.String |
getLocalHost()
The name of the local host or user-assigned IP interface through which connections are initiated or accepted. |
java.lang.String |
getPassword()
The password to log in. |
java.lang.String |
getRemoteFile()
The name of the remote file for uploading, downloading, etc. |
java.lang.String |
getRemoteHost()
The domain name or IP address of the FTP server. |
java.lang.String |
getRemotePath()
The current path in the FTP server. |
int |
getRemotePort()
The port for the FTP service (default is 21). |
Certificate |
getSSLAcceptServerCert()
Instructs the bean to unconditionally accept the server certificate that matches the supplied certificate. |
Certificate |
getSSLCert()
The certificate to be used during SSL negotiation. |
Certificate |
getSSLServerCert()
The server certificate for the last established connection. |
int |
getSSLStartMode()
Determines how the bean starts the SSL negotiation. |
java.lang.String |
getStartByte()
The byte index in RemoteFile and LocalFile from which to start the transmission. |
int |
getTimeout()
A timeout for the bean. |
int |
getTransferMode()
The transfer mode (ASCII or Binary). |
java.lang.String |
getUser()
The user identifier to use for login. |
void |
interrupt()
Interrupt the current method. |
boolean |
isConnected()
Shows whether the bean is connected. |
boolean |
isFileExists()
Returns True if the file specified by RemoteFile exists on the remote server. |
boolean |
isIdle()
The current status of the component. |
boolean |
isOverwrite()
Indicates whether or not the bean should overwrite files during transfer. |
boolean |
isPassive()
Controls whether to direct the server into passive mode. |
void |
listDirectory()
List the current directory specified by RemotePath on an FTP server. |
void |
listDirectoryLong()
List extended directory information for RemotePath . |
void |
logoff()
Logoff from the FTP server by posting a QUIT command. |
void |
logon()
Logon to the FTP RemoteHost using the current User and Password . |
void |
makeDirectory(java.lang.String newDir)
Create a directory on an FTP server. |
void |
removeDirectory(java.lang.String dirName)
Remove a directory specified by DirName from an FTP server. |
void |
removeFtpsEventListener(FtpsEventListener l)
|
void |
renameFile(java.lang.String newName)
Change the name of RemoteFile to NewName . |
void |
setAccount(java.lang.String account)
The user account to login with. |
void |
setCommand(java.lang.String command)
Used to send additional commands directly to the server. |
void |
setConnected(boolean connected)
Shows whether the bean is connected. |
void |
setDownloadStream(java.io.OutputStream downloadStream)
Sets the stream to which the downloaded data from the server will be written. |
void |
setFirewall(Firewall firewall)
A set of properties related to firewall access. |
void |
setLocalFile(java.lang.String localFile)
The path to a local file for download/upload. |
void |
setLocalHost(java.lang.String localHost)
The name of the local host or user-assigned IP interface through which connections are initiated or accepted. |
void |
setOverwrite(boolean overwrite)
Indicates whether or not the bean should overwrite files during transfer. |
void |
setPassive(boolean passive)
Controls whether to direct the server into passive mode. |
void |
setPassword(java.lang.String password)
The password to log in. |
void |
setRemoteFile(java.lang.String remoteFile)
The name of the remote file for uploading, downloading, etc. |
void |
setRemoteHost(java.lang.String remoteHost)
The domain name or IP address of the FTP server. |
void |
setRemotePath(java.lang.String remotePath)
The current path in the FTP server. |
void |
setRemotePort(int remotePort)
The port for the FTP service (default is 21). |
void |
setSSLAcceptServerCert(Certificate SSLAcceptServerCert)
Instructs the bean to unconditionally accept the server certificate that matches the supplied certificate. |
void |
setSSLCert(Certificate SSLCert)
The certificate to be used during SSL negotiation. |
void |
setSSLStartMode(int SSLStartMode)
Determines how the bean starts the SSL negotiation. |
void |
setStartByte(java.lang.String startByte)
The byte index in RemoteFile and LocalFile from which to start the transmission. |
void |
setTimeout(int timeout)
A timeout for the bean. |
void |
setTransferMode(int transferMode)
The transfer mode (ASCII or Binary). |
void |
setUploadStream(java.io.InputStream uploadStream)
Sets the stream from which the bean will read data to upload to the server. |
void |
setUser(java.lang.String user)
The user identifier to use for login. |
void |
storeUnique()
Upload a file with a Unique Name to an FTP server. |
void |
upload()
Upload a file specified by LocalFile to an FTP server. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final int sslAutomatic
public static final int sslImplicit
public static final int sslExplicit
public static final int sslNone
public static final int tmDefault
public static final int tmASCII
public static final int tmBinary
| Constructor Detail |
|---|
public Ftps()
public Ftps(java.lang.String runtimeLicense)
| Method Detail |
|---|
public java.lang.String getAccount()
This property contains the user account to use when logging in. Some servers may require an Account in order to Logon or in order to access specific privileges, like uploading or deleting files.
public void setAccount(java.lang.String account)
throws IPWorksSSLException
This property contains the user account to use when logging in. Some servers may require an Account in order to Logon or in order to access specific privileges, like uploading or deleting files.
IPWorksSSLException
public void setCommand(java.lang.String command)
throws IPWorksSSLException
This property can be used to send additional commands directly to the server. Check the LastReply property and/or trap the PITrail events
coming from the server to get the response.
IPWorksSSLExceptionpublic boolean isConnected()
This property is used to determine whether or not the bean is connected to the remote host.
public void setConnected(boolean connected)
throws IPWorksSSLException
This property is used to determine whether or not the bean is connected to the remote host.
IPWorksSSLExceptionpublic DirEntryList getDirList()
This property contains the collection of entries resulting in the last directory listing. A collection is returned after a response is received from the server after a call to either ListDirectory or ListDirectoryLong . The collection is made up of entries for each listing in the current directory, specified by the RemotePath property.
{@link ipworksssl.Ftps#config can be used to control the number of directory listings saved.
This collection is indexed from 0 to size - 1.
public boolean isFileExists()
RemoteFile exists on the remote server.
This property returns True if the file exists on the remote server. It returns false if the file does not exist. You must specify the file you wish to check by setting the RemoteFile prior to calling this method.
If the bean is busy or is not connected, 0 is returned.
If there is no FTP session in place, one is automatically created by first calling the Logon method.
public long getFileSize()
RemoteFile .
When this property is read, the FTP server is queried for the file size, and the response is provided as the property value.
If the bean is busy or is not connected, 0 is returned.
public java.lang.String getFileTime()
RemoteFile .
When this property is read, the FTP server is queried for the file modification time, and the response is provided as the property value. The time will be converted to the local time zone.
If the bean is busy or is not connected, an empty string is returned.
public Firewall getFirewall()
This is a Firewall type property which
contains fields describing the firewall
through which the bean will attempt to connect.
public void setFirewall(Firewall firewall)
throws IPWorksSSLException
This is a Firewall type property which
contains fields describing the firewall
through which the bean will attempt to connect.
IPWorksSSLExceptionpublic boolean isIdle()
Idle will be False if the component is currently busy (communicating
and/or waiting for an answer), and True at all other times.
public java.lang.String getLastReply()
This property indicates the last reply received from the server. It
can be used for informational purposes. The same information
and more can also be retrieved through the PITrail event.
public java.lang.String getLocalFile()
This property is used by the Upload and Download methods to specify the path to a local file to be downloaded/uploaded. See the method descriptions for more information.
Example (Setting LocalFile)
FTPControl.LocalFile = "C:\localfile.txt"
FTPControl.RemoteFile = "remotefile.txt"
FTPControl.Download()
FTPControl.LocalFile = "C:\localfile2.txt"
FTPControl.RemoteFile = "folder/remotefile2.txt"
FTPControl.Download()
public void setLocalFile(java.lang.String localFile)
throws IPWorksSSLException
This property is used by the Upload and Download methods to specify the path to a local file to be downloaded/uploaded. See the method descriptions for more information.
Example (Setting LocalFile)
FTPControl.LocalFile = "C:\localfile.txt"
FTPControl.RemoteFile = "remotefile.txt"
FTPControl.Download()
FTPControl.LocalFile = "C:\localfile2.txt"
FTPControl.RemoteFile = "folder/remotefile2.txt"
FTPControl.Download()
IPWorksSSLExceptionpublic java.lang.String getLocalHost()
The LocalHost property contains the name of the local host
as obtained by the gethostname() system call, or if the
user has assigned an IP address, the value of that address.
In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.
If the bean is connected, the LocalHost property shows
the IP address of the interface through which the connection
is made in internet dotted format (aaa.bbb.ccc.ddd). In most
cases, this is the address of the local host, except for multi-homed
hosts (machines with more than one IP interface).
NOTE: LocalHost is not persistent. You must always set it in
code, and never in the property window.
public void setLocalHost(java.lang.String localHost)
throws IPWorksSSLException
The LocalHost property contains the name of the local host
as obtained by the gethostname() system call, or if the
user has assigned an IP address, the value of that address.
In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.
If the bean is connected, the LocalHost property shows
the IP address of the interface through which the connection
is made in internet dotted format (aaa.bbb.ccc.ddd). In most
cases, this is the address of the local host, except for multi-homed
hosts (machines with more than one IP interface).
NOTE: LocalHost is not persistent. You must always set it in
code, and never in the property window.
IPWorksSSLExceptionpublic boolean isOverwrite()
This property is a value indicating whether or not the bean should overwrite downloaded files. If Overwrite is false, an error will be thrown whenever LocalFile exists before a download operation.
public void setOverwrite(boolean overwrite)
throws IPWorksSSLException
This property is a value indicating whether or not the bean should overwrite downloaded files. If Overwrite is false, an error will be thrown whenever LocalFile exists before a download operation.
IPWorksSSLExceptionpublic boolean isPassive()
This property controls whether to direct the server into passive mode. Many firewalls will not allow the FTP server to open a connection from outside to the higher ports where the FTP client bean expects them. If Passive is set to TRUE , the bean will use the PASV instead of the PORT command and will thus direct the server into passive mode: connections are initiated only by the client.
public void setPassive(boolean passive)
throws IPWorksSSLException
This property controls whether to direct the server into passive mode. Many firewalls will not allow the FTP server to open a connection from outside to the higher ports where the FTP client bean expects them. If Passive is set to TRUE , the bean will use the PASV instead of the PORT command and will thus direct the server into passive mode: connections are initiated only by the client.
IPWorksSSLExceptionpublic java.lang.String getPassword()
This property contains the password used to log in and must be set before the bean connects to the FTP server.
public void setPassword(java.lang.String password)
throws IPWorksSSLException
This property contains the password used to log in and must be set before the bean connects to the FTP server.
IPWorksSSLExceptionpublic java.lang.String getRemoteFile()
This property contains the name of the remote file to upload, download, etc. and is either an absolute file path, or a relative path based on RemotePath .
A number of methods use RemoteFile as an argument.
Example (Setting RemoteFile)
FTPControl.LocalFile = "C:\localfile.txt"
FTPControl.RemoteFile = "remotefile.txt"
FTPControl.Download()
FTPControl.LocalFile = "C:\localfile2.txt"
FTPControl.RemoteFile = "folder/remotefile2.txt"
FTPControl.Download()
Note: This property will also act as a file mask when performing ListDirectory or ListDirectoryLong .
Example (Using RemoteFile as a file mask):
FTPControl.RemoteFile = "*.txt"
FTPControl.ListDirectory()
The RemoteFile property supports several pattern matching characters. The
following special characters are supported for pattern matching:
If the above characters need to be used as a literal in a FileMask then they must be escaped by surrounding them with a []. (Note, "]" and "-" do not need to be escaped) See below for the escape sequences:
For example, if you wanted to download a file whose name was [Something].txt
you could set the RemoteFile property to: [[]Something].txt
public void setRemoteFile(java.lang.String remoteFile)
throws IPWorksSSLException
This property contains the name of the remote file to upload, download, etc. and is either an absolute file path, or a relative path based on RemotePath .
A number of methods use RemoteFile as an argument.
Example (Setting RemoteFile)
FTPControl.LocalFile = "C:\localfile.txt"
FTPControl.RemoteFile = "remotefile.txt"
FTPControl.Download()
FTPControl.LocalFile = "C:\localfile2.txt"
FTPControl.RemoteFile = "folder/remotefile2.txt"
FTPControl.Download()
Note: This property will also act as a file mask when performing ListDirectory or ListDirectoryLong .
Example (Using RemoteFile as a file mask):
FTPControl.RemoteFile = "*.txt"
FTPControl.ListDirectory()
The RemoteFile property supports several pattern matching characters. The
following special characters are supported for pattern matching:
If the above characters need to be used as a literal in a FileMask then they must be escaped by surrounding them with a []. (Note, "]" and "-" do not need to be escaped) See below for the escape sequences:
For example, if you wanted to download a file whose name was [Something].txt
you could set the RemoteFile property to: [[]Something].txt
IPWorksSSLExceptionpublic java.lang.String getRemoteHost()
This property specifies the IP address (IP number in dotted internet format) or Domain Name of the FTP server. It is set before a connection is attempted and cannot be changed once a connection is in progress.
If this property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, an error is returned.
If the bean is configured to use a SOCKS firewall, the value assigned to this property may be preceded with an "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.
public void setRemoteHost(java.lang.String remoteHost)
throws IPWorksSSLException
This property specifies the IP address (IP number in dotted internet format) or Domain Name of the FTP server. It is set before a connection is attempted and cannot be changed once a connection is in progress.
If this property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, an error is returned.
If the bean is configured to use a SOCKS firewall, the value assigned to this property may be preceded with an "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.
IPWorksSSLExceptionpublic java.lang.String getRemotePath()
This property shows the current working directory on the FTP server. It can also be used to change the working directory by setting it to an absolute directory path, or a relative path with respect to the existing value of this property.
If the first two bytes of the new path are "..", then a change to one level above in the directory tree is performed.
Setting this property causes the bean to send the appropriate command to the remote server only if connected.
Example (Changing Directory)
FTPControl.Logon()
FTPControl.RemotePath = "/home/user"
public void setRemotePath(java.lang.String remotePath)
throws IPWorksSSLException
This property shows the current working directory on the FTP server. It can also be used to change the working directory by setting it to an absolute directory path, or a relative path with respect to the existing value of this property.
If the first two bytes of the new path are "..", then a change to one level above in the directory tree is performed.
Setting this property causes the bean to send the appropriate command to the remote server only if connected.
Example (Changing Directory)
FTPControl.Logon()
FTPControl.RemotePath = "/home/user"
IPWorksSSLExceptionpublic int getRemotePort()
This property contains the port for the FTP service, which defaults to 21 if not set. A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.
For implicit SSL, use port 990 (please refer to the SSLStartMode property for more information).
public void setRemotePort(int remotePort)
throws IPWorksSSLException
This property contains the port for the FTP service, which defaults to 21 if not set. A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.
For implicit SSL, use port 990 (please refer to the SSLStartMode property for more information).
IPWorksSSLExceptionpublic Certificate getSSLAcceptServerCert()
If it finds any issues with the certificate presented by the server, the bean will normally terminate the connection with an error.
You may override this behavior by supplying a value for SSLAcceptServerCert .
If the certificate supplied in SSLAcceptServerCert is the same as the
certificate presented by the server, then the server
certificate is accepted unconditionally, and the connection will continue
normally.
Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.
public void setSSLAcceptServerCert(Certificate SSLAcceptServerCert)
throws IPWorksSSLException
If it finds any issues with the certificate presented by the server, the bean will normally terminate the connection with an error.
You may override this behavior by supplying a value for SSLAcceptServerCert .
If the certificate supplied in SSLAcceptServerCert is the same as the
certificate presented by the server, then the server
certificate is accepted unconditionally, and the connection will continue
normally.
Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.
IPWorksSSLExceptionpublic Certificate getSSLCert()
The digital certificate that the bean will use
during SSL negotiation. Set this property to a valid
certificate before starting SSL negotiation. To set
a certificate, you may set the Encoded field to
the encoded certificate. To select a certificate, use
the store and subject fields.
public void setSSLCert(Certificate SSLCert)
throws IPWorksSSLException
The digital certificate that the bean will use
during SSL negotiation. Set this property to a valid
certificate before starting SSL negotiation. To set
a certificate, you may set the Encoded field to
the encoded certificate. To select a certificate, use
the store and subject fields.
IPWorksSSLExceptionpublic Certificate getSSLServerCert()
SSLServerCert contains the server certificate for the
last established connection.
SSLServerCert is reset every time a new connection is attempted.
public int getSSLStartMode()
The SSLStartMode property may have one of the following values:
SSLStartMode is set to sslExplicit . In all other cases, SSL negotiation will be implicit
( sslImplicit ).
public void setSSLStartMode(int SSLStartMode)
throws IPWorksSSLException
The SSLStartMode property may have one of the following values:
SSLStartMode is set to sslExplicit . In all other cases, SSL negotiation will be implicit
( sslImplicit ).
IPWorksSSLExceptionpublic java.lang.String getStartByte()
RemoteFile and LocalFile from which to start the transmission.
This property contains a zero-based index in both RemoteFile and LocalFile that determines the point where the transmission of data starts from. This is useful for resuming interrupted downloads and uploads of files from FTP servers.
Once set, the StartByte index is used for all future downloads/uploads. The property must be reset to "0" for normal downloads/uploads.
The type of the property is a string instead of numeric to allow for certain implementations that expect an alphanumeric marker of the start index.
In the Transfer event, the TransferredBytes parameter will include the bytes skipped (i.e. it will show StartByte more bytes than actually transferred).
NOTE: some FTP servers may not support the FTP 'REST' command. If that is the case with the server you are accessing, you will not be able to use the StartByte property.
public void setStartByte(java.lang.String startByte)
throws IPWorksSSLException
RemoteFile and LocalFile from which to start the transmission.
This property contains a zero-based index in both RemoteFile and LocalFile that determines the point where the transmission of data starts from. This is useful for resuming interrupted downloads and uploads of files from FTP servers.
Once set, the StartByte index is used for all future downloads/uploads. The property must be reset to "0" for normal downloads/uploads.
The type of the property is a string instead of numeric to allow for certain implementations that expect an alphanumeric marker of the start index.
In the Transfer event, the TransferredBytes parameter will include the bytes skipped (i.e. it will show StartByte more bytes than actually transferred).
NOTE: some FTP servers may not support the FTP 'REST' command. If that is the case with the server you are accessing, you will not be able to use the StartByte property.
IPWorksSSLExceptionpublic int getTimeout()
If the Timeout property is set to 0, all operations
will run uninterrupted until successful completion or an error condition
is encountered.
If Timeout is set to a positive value, the bean will
wait for the operation to complete before returning control.
The bean will use DoEvents to enter an efficient wait loop
during any potential waiting period, making sure that all system events
are processed immediately as they arrive. This ensures that the host
application does not "freeze" and remains responsive.
If Timeout expires, and the operation is not yet complete,
the bean throws an exception.
Please note that by default, all timeouts are inactivity timeouts ,
i.e. the timeout period is extended by Timeout seconds when
any amount of data is successfully sent or received.
Optionally, the behavior of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum
of Timeout seconds since the beginning of the operation, without
extending the timeout period during communications.
This behavior is controlled by the ipworksssl.Ftps#config configuration setting.
The default value for the {@link ipworksssl.Ftps#getTimeout Timeout} property is 60 (seconds).
public void setTimeout(int timeout)
throws IPWorksSSLException
If the Timeout property is set to 0, all operations
will run uninterrupted until successful completion or an error condition
is encountered.
If Timeout is set to a positive value, the bean will
wait for the operation to complete before returning control.
The bean will use DoEvents to enter an efficient wait loop
during any potential waiting period, making sure that all system events
are processed immediately as they arrive. This ensures that the host
application does not "freeze" and remains responsive.
If Timeout expires, and the operation is not yet complete,
the bean throws an exception.
Please note that by default, all timeouts are inactivity timeouts ,
i.e. the timeout period is extended by Timeout seconds when
any amount of data is successfully sent or received.
Optionally, the behavior of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum
of Timeout seconds since the beginning of the operation, without
extending the timeout period during communications.
This behavior is controlled by the ipworksssl.Ftps#config configuration setting.
The default value for the {@link ipworksssl.Ftps#getTimeout Timeout} property is 60 (seconds).
IPWorksSSLExceptionpublic int getTransferMode()
This property specifies the transfer mode, either ASCII or binary. The valid options for the TransferMode property are as follows:
public void setTransferMode(int transferMode)
throws IPWorksSSLException
This property specifies the transfer mode, either ASCII or binary. The valid options for the TransferMode property are as follows:
IPWorksSSLExceptionpublic java.lang.String getUser()
This property contains the user identifier to be used when logging in and must be set before the bean connects to the FTP server.
public void setUser(java.lang.String user)
throws IPWorksSSLException
This property contains the user identifier to be used when logging in and must be set before the bean connects to the FTP server.
IPWorksSSLException
public void abort()
throws IPWorksSSLException
This method sends an ABOR command to the FTP server. It is used to interrupt file uploads/downloads.
IPWorksSSLException
public void append()
throws IPWorksSSLException
LocalFile to a RemoteFile on an FTP server.
This method causes the server-DTP to accept the data transferred via the data connection and to store the data in a file on the server site. If the file specified in the pathname exists on the server site, then the data shall be appended to that file; otherwise the file specified in the
pathname shall be created on the server site.
Similar to the Upload method but the local file specified by LocalFile is appended to RemoteFile on the server as opposed to replacing it as done by the Upload method. RemoteFile is either an absolute path on the server, or a path relative to RemotePath .
The server will create a file with that name if it doesn't already exist (similar to Upload).
If there is no FTP session in place, one is automatically created by first calling the Logon method.
IPWorksSSLException
public java.lang.String config(java.lang.String configurationString)
throws IPWorksSSLException
{@link ipworksssl.Ftps#config Config} is a generic method available in every bean. It is used to set and retrieve {@link ipworksssl.Ftps#config configuration settingsfor the bean.
These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the bean, access to these internal properties is provided through the {@link ipworksssl.Ftps#config Config} method.
To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).
To read (query) the value of a {@link ipworksssl.Ftps#config configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.
The bean accepts one or more of the following configuration settings . Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the bean, access to these internal properties is provided through the {@link ipworksssl.Ftps#config Config} method.
A,B,C,X=Y|RegEx Since group X represents the IsDir value, the user must specify Y to indicate what value that group must have in order for IsDir to be true.
Take for instance a simple entry in this format:
22 Test.txt 2,1,-1,-1|([0-9]+)\s(.*) As seen in the above example -1 can also be specified as the integer value. When this is specified that field is ignored.
In the second scenario, {@link ipworksssl.Ftps#config is a positive value, the system will attempt to send pending data until the specified {@link ipworksssl.Ftps#config is reached. If this attempt fails, then the system will reset the connection.
The default behavior (which is also the default mode for stream sockets) might result in a long delay in closing the connection. Although the bean returns control immediately, the system could hold system resources until all pending data is sent (even after your application closes).
Setting this property to False forces an immediate disconnection. If you know that the other side has received all the data you sent (by a client acknowledgment, for example), setting this property to False might be the appropriate course of action.
NOTE: This functionality is only available in Java and .NET.
NOTE: This is the same as Host . This setting is provided for use by beans that do not directly expose Firewall properties.
{@link ipworksssl.Ftps#getRemotePort RemotePort} is the port in which the firewall will listen to. If set to 0, the firewall will select a random port. The binding (address and port) is provided through the {@link ipworksssl.FtpsConnectionStatusEvent ConnectionStatus} event.
The connection to the firewall is made by calling the {@link ipworksssl.Ftps#connect Connect} method.
In the second scenario, {@link ipworksssl.Ftps#config is a positive value, the system will attempt to send pending data until the specified {@link ipworksssl.Ftps#config is reached. If this attempt fails, then the system will reset the connection.
The default behavior (which is also the default mode for stream sockets) might result in a long delay in closing the connection. Although the bean returns control immediately, the system could hold system resources until all pending data is sent (even after your application closes).
Setting this property to False forces an immediate disconnection. If you know that the other side has received all the data you sent (by a client acknowledgment, for example), setting this property to False might be the appropriate course of action.
If the bean is connected, the {@link ipworksssl.Ftps#getLocalHost LocalHost} setting shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).
{@link ipworksssl.Ftps#getLocalPort LocalPort} cannot be changed once a connection is made. Any attempt to set this when a connection is active will generate an error.
This; setting is useful when trying to connect to services that require a trusted port in the client side. An example is the remote shell (rsh) service in UNIX systems.
If no {@link ipworksssl.Ftps#getEOL EOL} is found, and {@link ipworksssl.Ftps#config bytes are accumulated in the buffer, the {@link ipworksssl.FtpsDataInEvent DataIn} event is fired with the EOL parameter set to False, and the buffer is reset.
The minimum value for {@link ipworksssl.Ftps#config is 256 bytes. The default value is 2048 bytes. The maximum value is 65536 bytes.
Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities in your application.
When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the {@link ipworksssl.Ftps#config config setting.
When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the {@link ipworksssl.Ftps#config config setting.
TLS 1.1 and TLS1.2 support are only available starting with Windows 7.
The special value "*" (default) picks the default SSL provider defined in the system.
Note: On Windows systems, the default SSL Provider is "Microsoft Unified Security Protocol Provider" and cannot be changed.
The special value "*" means that the component will pick all of the supported cipher suites. If SSLEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.
Multiple cipher suites are separated by semicolons.
Example values:
obj.config("SSLEnabledCipherSuites=*");
obj.config("SSLEnabledCipherSuites=SSL_RSA_WITH_RC4_128_SHA");
obj.config("SSLEnabledCipherSuites=SSL_RSA_WITH_RC4_128_SHA; SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA"); SSLEnabledCipherSuites is used together with SSLCipherStrength .
Note: This configuration setting is available only in .NET and Java.
obj.Config("SSLEnabledProtocols=3072"); // TLS1.2 (supports SHA_256)
obj.Config("SSLAlgorithmList=CALG_SHA_256;CALG_MD5"); This option is only valid in Windows.
IPWorksSSLException
public void deleteFile(java.lang.String fileName)
throws IPWorksSSLException
This method is used to remove a file specified by FileName from an FTP server. The remote file or directory specified by FileName is deleted. FileName is either an absolute path on the server, or a path relative to RemotePath .
If there is no FTP session in place, one is automatically created by first calling the Logon method.
IPWorksSSLException
public void doEvents()
throws IPWorksSSLException
When DoEvents is called, the bean processes any
available events. If no events are available, it waits for a
preset period of time, and then returns.
IPWorksSSLException
public void download()
throws IPWorksSSLException
RemoteFile from an FTP server.
This method is used to download the remote file specified by RemoteFile to the local file specified by LocalFile , or it is retrieved through the Transfer event if the LocalFile property is "" (empty string). RemoteFile is either an absolute path on the server, or a path relative to RemotePath .
If there is no FTP session in place, one is automatically created by first calling the Logon method.
Example (Download a File)
FTPControl.LocalFile = "C:\localfile.txt"
FTPControl.RemoteFile = "remotefile.txt"
FTPControl.Download()
FTPControl.LocalFile = "C:\localfile2.txt"
FTPControl.RemoteFile = "folder/remotefile2.txt"
FTPControl.Download()
IPWorksSSLException
public void interrupt()
throws IPWorksSSLException
If there is no method in progress, Interrupt simply returns, doing nothing.
IPWorksSSLException
public void listDirectory()
throws IPWorksSSLException
RemotePath on an FTP server.
This method is used to list the directory (or file mask) specified in RemoteFile . RemoteFile is either an absolute path on the server, or a path relative to RemotePath .
The file listing is received through the DirList event.
Similar to ListDirectoryLong , except only file names are returned.
Note that since RemoteFile acts as a file mask, to retrieve a complete directory listing RemoteFile should be set to empty string or a mask like "*".
If there is no FTP session in place, one is automatically created by first calling the Logon method.
IPWorksSSLException
public void listDirectoryLong()
throws IPWorksSSLException
RemotePath .
This method is used to request a directory (or file mask) listing specified in RemoteFile . RemoteFile is either an absolute path on the server, or a path relative to RemotePath .
The file listing is received through the DirList event. Extended file information is returned.
Note that since RemoteFile acts as a file mask, to retrieve a complete directory listing RemoteFile should be set to empty string or a mask like "*".
If there is no FTP session in place, one is automatically created by first calling the Logon method.
IPWorksSSLException
public void logoff()
throws IPWorksSSLException
This method is used to logoff from the FTP server by posting a QUIT command. If that fails, the connection is terminated by the local host.
IPWorksSSLException
public void logon()
throws IPWorksSSLException
RemoteHost using the current User and Password .
This method is used to logon to the FTP server using the current User and Password . If TransferMode is not 0 (Default), then the FTP transfer mode is set to the appropriate value.
Example (Logging On)
FTPControl.RemoteHost = "ftpserver"
FTPControl.User = "username"
FTPControl.Password = "password"
FTPControl.Logon()
IPWorksSSLException
public void makeDirectory(java.lang.String newDir)
throws IPWorksSSLException
This method is used to create a directory with path specified by NewDir on the FTP server. NewDir is either an absolute path on the server, or a path relative to RemotePath .
If there is no FTP session in place, one is automatically created by first calling the Logon method.Note that when MakeDirectory is called, RemoteFile is changed to NewDir .
IPWorksSSLException
public void removeDirectory(java.lang.String dirName)
throws IPWorksSSLException
This property is used to remove a directory with path specified by DirName from the FTP server. DirName is either an absolute path on the server, or a path relative to RemotePath .
If there is no FTP session in place, one is automatically created by first calling the Logon method.
IPWorksSSLException
public void renameFile(java.lang.String newName)
throws IPWorksSSLException
RemoteFile to NewName .
This property is used to change the name of a remote file, specified by RemoteFile to NewName . RemoteFile and NewName are either absolute paths on the server, or a path relative to RemotePath .
If there is no FTP session in place, one is automatically created by first calling the Logon method.
IPWorksSSLException
public void setDownloadStream(java.io.OutputStream downloadStream)
throws IPWorksSSLException
This method is used to set the stream to which the downloaded data from the server will be written. If a download stream is set before the Download method is called, the downloaded data will be written to the stream. The stream should be open and normally set to position 0.
The bean will automatically close this stream if ipworksssl.Ftps#config is true (default).
If the stream is closed, you will need to call {@link ipworksssl.Ftps#setDownloadStream SetDownloadStream} again before calling {@link ipworksssl.Ftps#download Download} again.
The downloaded content will be written starting at the current position in the stream.
If {@link ipworksssl.Ftps#getStartByte StartByte} is non zero the server will be instructed to skip those bytes before starting to send the content of the file so it is up to you to build the stream appropriately in that case.
Note: {@link ipworksssl.Ftps#setDownloadStream SetDownloadStream} and {@link ipworksssl.Ftps#getLocalFile LocalFile} will reset the other.
IPWorksSSLException
public void setUploadStream(java.io.InputStream uploadStream)
throws IPWorksSSLException
This method is used to set the stream from which the bean will read data to upload to the server. If an upload stream is set before the Upload method is called, the content of the stream will be read by the bean and uploaded to the server. The stream should be open and normally set to position 0.
The bean will automatically close this stream if ipworksssl.Ftps#config is true (default). If the stream is closed, you will need to call {@link ipworksssl.Ftps#setUploadStream SetUploadStream} again before calling {@link ipworksssl.Ftps#upload Upload} again.
The content of the stream will be read from the current position all the way to the end and no bytes will be skipped even if {@link ipworksssl.Ftps#getStartByte StartByte} is set to a non zero value (though the server will be instructed to skip those bytes in its file).
Note: {@link ipworksssl.Ftps#setUploadStream SetUploadStream} and {@link ipworksssl.Ftps#getLocalFile LocalFile} will reset the other.
IPWorksSSLException
public void storeUnique()
throws IPWorksSSLException
This method is used to upload a file with a Unique Name to an FTP server. Similar to the Upload method but the server determines a unique name for the LocalFile to be saved on the current directory given by RemotePath . The server includes the new name of the file in its response. The user should check the PITrail event, or LastReply property to retrieve this generated filename.
IPWorksSSLException
public void upload()
throws IPWorksSSLException
LocalFile to an FTP server.
This method uploads a local file specified by LocalFile to the remote file specified by RemoteFile . RemoteFile is either an absolute path on the server, or a path relative to RemotePath .
If there is no FTP session in place, one is automatically created by first calling the Logon method.
If you want to append to a server file, please refer to the Append method.
Example (Upload a File)
FTPControl.LocalFile = "C:\localfile.txt"
FTPControl.RemoteFile = "remotefile.txt"
FTPControl.Upload()
FTPControl.LocalFile = "C:\localfile2.txt"
FTPControl.RemoteFile = "folder/remotefile2.txt"
FTPControl.Upload()
IPWorksSSLException
public void addFtpsEventListener(FtpsEventListener l)
throws java.util.TooManyListenersException
java.util.TooManyListenersExceptionpublic void removeFtpsEventListener(FtpsEventListener l)
|
IP*Works! SSL V9 | |||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||