Syntax
| SFTP.OpenFile(remotePath As String, access As String, createDisposition As String) As String
|
|---|---|
Description
| Opens or creates a file on the remote system. Returns a handle which may be passed to methods for reading and/or writing the file. The remotePath is the remote file path (the path to the file on the server). When the application is finished with the handle, it should call CloseHandle(remotePath).
Important: If the remotePath is an absolute path, then it is a path from the root of the server's filesystem. For example, "/home/joe/someFile.txt". Use a relative path to specify a directory relative to the $HOME directory of the SSH user account. For example, "./someFile.txt".
access should be one of the following strings: "readOnly", "writeOnly", or "readWrite".
createDisposition is a comma-separated list of keywords to provide more control over how the file is opened or created. One of the following keywords must be present: "createNew", "createTruncate", "openExisting", "openOrCreate", or "truncateExisting". All other keywords are optional. The list of keywords and their meanings are shown here:
createNew
A new file is created; if the file already exists the method fails.
createTruncate
A new file is created; if the file already exists, it is opened and truncated.
openExisting
An existing file is opened. If the file does not exist the method fails.
openOrCreate
If the file exists, it is opened. If the file does not exist, it is created.
truncateExisting
An existing file is opened and truncated. If the file does not exist the method fails.
appendData
Data is always written at the end of the file. Data is not required to be appended atomically. This means that if multiple writers attempt to append data simultaneously, data from the first may be lost.
appendDataAtomic
Data is always written at the end of the file. Data MUST be written atomically so that there is no chance that multiple appenders can collide and result in data being lost.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
textMode
Indicates that the server should treat the file as text and convert it to the canonical newline convention in use. When a file is opened with this flag, data is always appended to the end of the file. Servers MUST process multiple, parallel reads and writes correctly in this mode.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
blockRead
The server MUST guarantee that no other handle has been opened with read access, and that no other handle will be opened with read access until the client closes the handle. (This MUST apply both to other clients and to other processes on the server.) In a nutshell, this opens the file in non-sharing mode.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
blockWrite
The server MUST guarantee that no other handle has been opened with write access, and that no other handle will be opened with write access until the client closes the handle. (This MUST apply both to other clients and to other processes on the server.) In a nutshell, this opens the file in non-sharing mode.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
blockDelete
The server MUST guarantee that the file itself is not deleted in any other way until the client closes the handle. No other client or process is allowed to open the file with delete access.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
blockAdvisory
If set, the above "block" modes are advisory. In advisory mode, only other accesses that specify a "block" mode need be considered when determining whether the "block" can be granted, and the server need not prevent I/O operations that violate the block mode. The server MAY perform mandatory locking even if the blockAdvisory flag is set.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
noFollow
If the final component of the path is a symlink, then the open MUST fail.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
deleteOnClose
The file should be deleted when the last handle to it is closed. (The last handle may not be an sftp-handle.) This MAY be emulated by a server if the OS doesn't support it by deleting the file when this handle is closed.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
accessAuditAlarmInfo
The client wishes the server to enable any privileges or extra capabilities that the user may have in to allow the reading and writing of AUDIT or ALARM access control entries.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
accessBackup
The client wishes the server to enable any privileges or extra capabilities that the user may have in order to bypass normal access checks for the purpose of backing up or restoring files.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
backupStream
This flag indicates that the client wishes to read or write a backup stream. A backup stream is a system dependent structured data stream that encodes all the information that must be preserved in order to restore the file from backup medium. The only well defined use for backup stream data read in this fashion is to write it to the same server to a file also opened using the backupStream flag. However, if the server has a well defined backup stream format, there may be other uses for this data outside the scope of this protocol.
(Only supported in SFTP protocol versions 5 and later. See the note below.)
IMPORANT: If remotePath is a filename with no path, such as "test.txt", and the server responds with a "Folder not found" error, then try prepending "./" to the remotePath. For example, instead of passing "test.txt", try "./test.txt".
IMPORTANT note about createDisposition: Many of the options, such as textMode, are not implemented in the SFTP protocol versions 3 and 4. Only SFTP servers at protocol version 5 or later support these options. You can find out the protocol version of your server by examining the value of the ProtocolVersion property after calling InitializeSftp. Also, make sure the ForceV3 property is set to 0 (the default value is 1)
Returns Nothing on failure
|
See Also
| |
Example
Upload from Local Filesystem | Sub Main
' Set some timeouts, in milliseconds:
sftp.ConnectTimeoutMs = 5000
sftp.IdleTimeoutMs = 10000
' Connect to the SSH server.
' The standard SSH port = 22
' The hostname may be a hostname or IP address.
Dim hostname As String
hostname = "sftp.example.com"
Dim port As Long
port = 22
Dim success As Long
success = sftp.Connect(hostname,port)
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' Authenticate with the SSH server. Chilkat SFTP supports
' both password-based authenication as well as public-key
' authentication. This example uses password authenication.
success = sftp.AuthenticatePw("myLogin","myPassword")
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' After authenticating, the SFTP subsystem must be initialized:
success = sftp.InitializeSftp()
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' Open a file for writing on the SSH server.
' If the file already exists, it is overwritten.
' (Specify "createNew" instead of "createTruncate" to
' prevent overwriting existing files.)
Dim handle As String
handle = sftp.OpenFile("hamlet.xml","writeOnly","createTruncate")
If (sftp.LastMethodSuccess <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' Upload from the local file to the SSH server.
success = sftp.UploadFile(handle,"c:/temp/hamlet.xml")
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' -----------------------------------------------------------------------------
' This is important. You must close the handle on the server.
' Otherwise open handles will accumulate on the server until eventually a limit
' is reached and the server will fail on a call to OpenFile.
' -----------------------------------------------------------------------------
' Close the file.
success = sftp.CloseHandle(handle)
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
Debug.Print "Success."
End Sub
|
Example
Where Did My Upload Go? | Sub Main
' Set some timeouts, in milliseconds:
sftp.ConnectTimeoutMs = 5000
sftp.IdleTimeoutMs = 10000
' Connect to the SSH server.
' The standard SSH port = 22
' The hostname may be a hostname or IP address.
Dim hostname As String
hostname = "sftp.example.com"
Dim port As Long
port = 22
Dim success As Long
success = sftp.Connect(hostname,port)
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' Authenticate with the SSH server. Chilkat SFTP supports
' both password-based authenication as well as public-key
' authentication. This example uses password authenication.
success = sftp.AuthenticatePw("myLogin","myPassword")
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' After authenticating, the SFTP subsystem must be initialized:
success = sftp.InitializeSftp()
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' To find the full path of our user account's home directory,
' call RealPath like this:
Dim absPath As String
absPath = sftp.RealPath(".","")
If (sftp.LastMethodSuccess <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
Else
Debug.Print absPath
End If
End Sub
|
Example
Upload Large File in Parts | Sub Main
' Set some timeouts, in milliseconds:
sftp.ConnectTimeoutMs = 5000
sftp.IdleTimeoutMs = 10000
' Connect to the SSH server.
' The standard SSH port = 22
' The hostname may be a hostname or IP address.
Dim hostname As String
hostname = "sftp.example.com"
Dim port As Long
port = 22
Dim success As Long
success = sftp.Connect(hostname,port)
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' Authenticate with the SSH server. Chilkat SFTP supports
' both password-based authenication as well as public-key
' authentication. This example uses password authenication.
success = sftp.AuthenticatePw("myLogin","myPassword")
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' After authenticating, the SFTP subsystem must be initialized:
success = sftp.InitializeSftp()
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' Open a remote file for writing on the SSH server.
' If the file already exists, it is overwritten.
' (Specify "createNew" instead of "createTruncate" to
' prevent overwriting existing files.)
Dim handle As String
handle = sftp.OpenFile("big.zip","writeOnly","createTruncate")
If (sftp.LastMethodSuccess <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' We're going to upload the local file "qa_data/zips/big.zip" (a relative local path from our current working directory)
' to the SFTP server.
Dim localFilePath As String
localFilePath = "qa_data/zips/big.zip"
' Rather than uploading in one shot, we'll read the local file in chunks
' and upload a chunk at a time.
Dim fac As New CkFileAccess
success = fac.OpenForRead(localFilePath)
If (success = 0) Then
success = sftp.CloseHandle(handle)
Debug.Print fac.LastErrorText
Exit Sub
End If
' If we were to split the local file into 128K chunks, how many chunks (blocks) would
' we have, including the last partial block?
Dim blockSize As Long
blockSize = 131072
Dim numBlocks As Long
numBlocks = fac.GetNumBlocks(blockSize)
Debug.Print "Number of blocks = " & numBlocks
Dim bd As New ChilkatBinData
Dim i As Long
i = 0
Do While i < numBlocks
' Read the Nth block, which gets appended to the bd. (which means
' we must clear the contents of bd before the next iteration)
success = fac.ReadBlockBd(i,blockSize,bd)
If (success = 0) Then
success = sftp.CloseHandle(handle)
Debug.Print fac.LastErrorText
Exit Sub
End If
' Upload this block to the open remote file.
success = sftp.WriteFileBd(handle,bd)
If (success = 0) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
' Clear the contents for the next iteration.
success = bd.Clear()
i = i + 1
Loop
' Close the local file.
fac.FileClose
' -----------------------------------------------------------------------------
' This is important. You must close the handle on the server.
' Otherwise open handles will accumulate on the server until eventually a limit
' is reached and the server will fail on a call to OpenFile.
' -----------------------------------------------------------------------------
' Close the remote file handle on the server.
success = sftp.CloseHandle(handle)
If (success <> 1) Then
Debug.Print sftp.LastErrorText
Exit Sub
End If
Debug.Print "Success."
End Sub
|