TrustCore SDK NanoSSH API reference  version 7.0
SFTP Client I/O Functions

Functions

MOC_EXTERN sbyte4 SSHC_closeFile (sbyte4 connectionInstance, sftpcFileHandleDescr *p_sftpFileHandleDescr)
 Close a file on an SFTP server. More...
 
MOC_EXTERN sbyte4 SSHC_openFile (sbyte4 connectionInstance, ubyte *pFName, ubyte4 pFNameLen, sbyte4 readOrWrite, sftpcFileHandleDescr **pp_retSftpFileHandleDescr)
 Open a file on an SFTP server. More...
 
MOC_EXTERN sbyte4 SSHC_readFile (sbyte4 connectionInstance, sftpcFileHandleDescr *p_sftpFileHandleDescr)
 Read a file on an SFTP server. More...
 
MOC_EXTERN sbyte4 SSHC_sftpNumBytesRead (sftpcFileHandleDescr *p_sftpFileHandleDescr)
 Get the number of bytes read from an open file. More...
 
MOC_EXTERN sbyte4 SSHC_writeFile (sbyte4 connectionInstance, sftpcFileHandleDescr *p_sftpFileHandleDescr)
 Write a file to an SFTP server. More...
 

Detailed Description

Function Documentation

◆ SSHC_closeFile()

MOC_EXTERN sbyte4 SSHC_closeFile ( sbyte4  connectionInstance,
sftpcFileHandleDescr p_sftpFileHandleDescr 
)

This function sends a close file request to the connected SSH/SFTP server, disabling the file from further access until it is reopened.

Since
1.41
Version
1.41 and later

To enable this function, the following flags must be defined in moptions.h:

  • __ENABLE_MOCANA_SSH_CLIENT__
  • __ENABLE_MOCANA_SSH_FTP_CLIENT__

sshc.h

Parameters
connectionInstanceConnection instance returned from SSHC_connect().
p_sftpFileHandleDescrFile handle descriptor returned from SSHC_openFile().
Returns
OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.
Remarks
This function is applicable to synchronous SFTP clients.

sshc.h

◆ SSHC_openFile()

MOC_EXTERN sbyte4 SSHC_openFile ( sbyte4  connectionInstance,
ubyte *  pFName,
ubyte4  pFNameLen,
sbyte4  readOrWrite,
sftpcFileHandleDescr **  pp_retSftpFileHandleDescr 
)

This function sends a request to the connected SSH/SFTP server to open an existing file for read and/or write operations.

Since
1.41
Version
1.41 and later

To enable this function, the following flags must be defined in moptions.h:

  • __ENABLE_MOCANA_SSH_CLIENT__
  • __ENABLE_MOCANA_SSH_FTP_CLIENT__

sshc.h

Parameters
connectionInstanceConnection instance returned from SSHC_connect().
pFNamePointer to buffer containing directory name.
fileNameLenNumber of bytes (characters) in the directory name (pFName).
readOrWriteORed bitmask of the following flags:
  • SFTP_OPEN_FILE_READ_BINARY
  • SFTP_OPEN_FILE_WRITE_BINARY
pp_retSftpFileHandleDescrPointer to address of handle descriptor structure, which on return contains opened file's information.
Returns
OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.
Remarks
This function is applicable to synchronous SFTP clients.

sshc.h

◆ SSHC_readFile()

MOC_EXTERN sbyte4 SSHC_readFile ( sbyte4  connectionInstance,
sftpcFileHandleDescr p_sftpFileHandleDescr 
)

This function sends a request to the connected SSH/SFTP server to read the specified file and return its contents and the SFTP operation status through the function parameters. If the entire file was read successfully, SSH_FTP_EOF is returned as the SFTP operation status (obtained by calling SSHC_sftpRequestStatusCode()).

Since
1.41
Version
1.41 and later

To enable this function, the following flags must be defined in moptions.h:

  • __ENABLE_MOCANA_SSH_CLIENT__
  • __ENABLE_MOCANA_SSH_FTP_CLIENT__

sshc.h

Parameters
connectionInstanceConnection instance returned from SSHC_connect().
p_sftpFileHandleDescrPointer to handle descriptor structure containing the desired file's information.
Returns
OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.
Remarks
This function is applicable to synchronous SFTP clients.

sshc.h

◆ SSHC_sftpNumBytesRead()

MOC_EXTERN sbyte4 SSHC_sftpNumBytesRead ( sftpcFileHandleDescr p_sftpFileHandleDescr)

This function returns the number of bytes already read from the specified open file. Typically an application first calls SSHC_openFile() and then calls this function to keep track of download (read) progress.

Since
1.41
Version
1.41 and later

To enable this function, the following flags must be defined in moptions.h:

  • __ENABLE_MOCANA_SSH_CLIENT__
  • __ENABLE_MOCANA_SSH_FTP_CLIENT__

sshc.h

Parameters
p_sftpFileHandleDescrPointer to file handle descriptor.
Returns
Number of bytes already read from the file.
Remarks
This function is applicable to synchronous SFTP clients.
Note
After the file download (read) is complete, the file should be closed by calling SSHC_closeFile().

sshc.h

◆ SSHC_writeFile()

MOC_EXTERN sbyte4 SSHC_writeFile ( sbyte4  connectionInstance,
sftpcFileHandleDescr p_sftpFileHandleDescr 
)

This function sends a write file request to the connected SSH/SFTP server and returns the SFTP operation status through the p_sftpFileHandleDescr parameter. SSH_FTP_EOF indicates success. (To obtain the SFTP operation status, call SSHC_sftpRequestStatusCode().)

Since
1.41
Version
1.41 and later

To enable this function, the following flags must be defined in moptions.h:

  • __ENABLE_MOCANA_SSH_CLIENT__
  • __ENABLE_MOCANA_SSH_FTP_CLIENT__

sshc.h

Parameters
connectionInstanceConnection instance returned from SSHC_connect().
p_sftpFileHandleDescrFile handle descriptor returned from SSHC_openFile().
Returns
OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.
Remarks
This function is applicable to synchronous SFTP clients.

sshc.h