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

connectionInstance	Connection instance returned from SSHC_connect().
p_sftpFileHandleDescr	File 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

connectionInstance	Connection instance returned from SSHC_connect().
pFName	Pointer to buffer containing directory name.
fileNameLen	Number of bytes (characters) in the directory name (pFName).
readOrWrite	ORed bitmask of the following flags: SFTP_OPEN_FILE_READ_BINARY SFTP_OPEN_FILE_WRITE_BINARY
pp_retSftpFileHandleDescr	Pointer 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

connectionInstance	Connection instance returned from SSHC_connect().
p_sftpFileHandleDescr	Pointer 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_sftpFileHandleDescr

Pointer 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

connectionInstance	Connection instance returned from SSHC_connect().
p_sftpFileHandleDescr	File 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