/* ipssh_sftp_clt.h - Public SFTP API of Wind River SSH */

/*
 ******************************************************************************
 *                     INTERPEAK API HEADER FILE
 *
 *   Document no: @(#) $Name: VXWORKS_ITER40_2019102207 $ $RCSfile: ipssh_sftp_clt.h,v $ $Revision: 1.15.16.4 $
 *   $Source: /home/interpeak/CVSRoot/ipssh/include/ipssh_sftp_clt.h,v $
 *   $Author: jren $ $Date: 2017-12-13 02:42:24 $
 *   $State: Exp $ $Locker:  $
 *
 *   INTERPEAK_COPYRIGHT_STRING
 *   Design and implementation by Roger Boden <roger@interpeak.se>
 ******************************************************************************
 */
#ifndef IPSSH_SFTP_CLT_H
#define IPSSH_SFTP_CLT_H

/*
 ****************************************************************************
 * 1                    DESCRIPTION
 ****************************************************************************
 */

/*
DESCRIPTION
This library contains the SFTP API for Wind River SSH.
*/

/*
 ****************************************************************************
 * 2                    CONFIGURATION
 ****************************************************************************
 */

#include "ipssh_config.h"


/*
 ****************************************************************************
 * 3                    INCLUDE FILES
 ****************************************************************************
 */

#include <ipcom_type.h>
#include <ipcom_cstyle.h>
#include <ipcom_err.h>
#include <ipcom_list.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 ****************************************************************************
 * 4                    DEFINES
 ****************************************************************************
 */

/* File open and creation flags */
#define IPSSH_FXF_READ            0x00000001
#define IPSSH_FXF_WRITE           0x00000002
#define IPSSH_FXF_APPEND          0x00000004
#define IPSSH_FXF_CREAT           0x00000008
#define IPSSH_FXF_TRUNC           0x00000010
#define IPSSH_FXF_EXCL            0x00000020


/*
 ****************************************************************************
 * 5                    TYPES
 ****************************************************************************
 */

    /* Forward declarations */
    struct Ipssh_conn_st;

    struct Ipssh_dirent_st
    {
        char name[256];
        char longname[256];
        struct Ip_stat attr;
    };
    typedef struct Ipssh_dirent_st Ipssh_dirent;

/*
 ****************************************************************************
 * 6                    FUNCTIONS
 ****************************************************************************
 */

/*******************************************************************************
*
* ipssh_sftp_clt_open - open a connection to an SFTP server
*
* This routine establishes a connection to an SFTP server.
*
* Parameters:
* \is
* \i <ssh_conn>
* Connection handle.
* \i <hostname>
* Host name or IP address of the SFTP server.
* \i <port>
* Port on which the SFTP server listens.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or one of the following errors:
* \is
* \i 'IPCOM_ERR_INVALID_ARG'
* Arguments are bad; for example, no authentication data set.
* \i 'IPCOM_ERR_AUTH_FAILED'
* Server rejected the login request.
* \i 'IPCOM_ERR_FAILED'
* Connection could not be established.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_open
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* hostname,
     Ip_u16 port
    );

/*******************************************************************************
*
* ipssh_sftp_clt_get - get a file from the server
*
* This routine transfers a file from the SFTP server to the local file system.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <src_path>
* The path to the source file on the SFTP server.
* \i <dst_path>
* The Path to the destination file on the local file system.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or one of the following errors:
* \is
* \i 'IPCOM_ERR_INVALID_ARGS'
* invalid input parameters.
* \i 'IPCOM_ERR_NOT_FOUND'
* The file does not exist on the SFTP server.
* \i 'IPCOM_ERR_PERMISSION_DENIED'
* Insufficient permission to access file on SFTP server.
* \i 'IPCOM_ERR_FAILED'
* Operation failed.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_get
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* src_path,
     const char* dst_path
    );

/*******************************************************************************
*
* ipssh_sftp_clt_put - transfer a file to the server
*
* This routine transfers a file from the local file system to the SFTP server.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <src_path>
* The path to the source file on the local file system.
* \i <dst_path>
* The path to the destination file on the SFTP server.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or one of the following errors:
* \is
* \i 'IPCOM_ERR_INVALID_ARGS'
* invalid input parameters.
* \i 'IPCOM_ERR_NOT_FOUND'
* File does not exist on the SFTP server.
* \i 'IPCOM_ERR_PERMISSION_DENIED'
* Insufficient permission to access file on SFTP server.
* \i 'IPCOM_ERR_FAILED'
* Operation failed.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_put
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* src_path,
     const char* dst_path
    );


/*******************************************************************************
*
* ipssh_sftp_clt_put_flags - transfer a file to the server
*
* This routine transfers a file from the local file system to the SFTP server.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <src_path>
* The path to the source file on the local file system.
* \i <dst_path>
* The path to the destination file on the SFTP server.
* \i <dst_path_flags>
* File open flags for the destination file on the SFTP server.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or one of the following errors:
* \is
* \i 'IPCOM_ERR_INVALID_ARGS'
* invalid input parameters.
* \i 'IPCOM_ERR_NOT_FOUND'
* File does not exist on the SFTP server.
* \i 'IPCOM_ERR_PERMISSION_DENIED'
* Insufficient permission to access file on SFTP server.
* \i 'IPCOM_ERR_FAILED'
* Operation failed.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_put_flags
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* src_path,
     const char* dst_path,
     Ip_u32 dst_path_flags
    );


/*******************************************************************************
*
* ipssh_sftp_clt_close - close a connection
*
* Disconnects an SFTP connection and frees all resources tied to the connection.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or an error code (see 'ipcom_err.h').
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_close
    (
     struct Ipssh_conn_st* ssh_conn
    );

/*******************************************************************************
*
* ipssh_sftp_clt_set_userid - set user ID for authentication
*
* This routine sets the user ID to be used for authenticating to the SFTP
* server.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <user>
* User ID to be used for authentication.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or the following error:
* \is
* \i 'IPCOM_ERR_INVALID_ARG'
* User ID is too long.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_set_userid
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* user
    );

/*******************************************************************************
*
* ipssh_sftp_clt_set_pw - set password for authentication
*
* This routine sets the password to be used for authenticating to the SFTP
* server.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <pw>
* The password to be used for authentication.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or the following error:
* \is
* \i 'IPCOM_ERR_INVALID_ARG'
* Password is too long.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_set_pw
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* pw
    );

/*******************************************************************************
*
* ipssh_sftp_clt_set_key - set key pair for publickey authentication
*
* This routine sets the key pair that will be used for publickey authenticating to the
* SFTP server. The reference counter of the key is incremented. RSA and DSA key
* pairs are currently supported.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <key>
* Key pair.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or an error code (see 'ipcom_err.h').
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_set_key
    (
     struct Ipssh_conn_st* ssh_conn,
     EVP_PKEY* key
    );


/*******************************************************************************
*
* ipssh_sftp_clt_set_hostb_key - set key pair for hostbased authentication
*
* This routine sets the key pair that will be used for hostbased authenticating to the
* SFTP server. The reference counter of the key is incremented. RSA and DSA key
* pairs are currently supported.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <key>
* Key pair.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or an error code (see 'ipcom_err.h').
*
* ERRNO:
*/

    IP_PUBLIC Ip_err ipssh_sftp_clt_set_hostb_key
    (
     struct Ipssh_conn_st* ssh_conn,
     EVP_PKEY* key
     );


/*******************************************************************************
*
* ipssh_sftp_clt_get_realpath - convert a relative path to an absolute path
*
* This routine converts a relative path on the server into an absolute path.
* This is useful for converting a path containing .. or a relative pathname
* without a leading slash into an absolute path.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <path>
* The relative path to be converted.
* \i <buf>
* The buffer for holding the returned path.
* \i <buf_len>
* The length of the buffer, in bytes.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or one of the following errors:
* \is
* \i 'IPCOM_ERR_INVALID_ARGS'
* Buffer is too small to contain the returned path.
* \i 'IPCOM_ERR_FAILED'
* Communication with server failed.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_get_realpath
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* path,
     char* buf,
     int buf_len
    );

/*******************************************************************************
*
* ipssh_sftp_clt_get_cwd - get current working directory on the server
*
* This routine returns the current working directory on the SFTP server.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <buf>
* The buffer for holding the returned directory name.
* \i <buf_len>
* The length of the buffer, in bytes.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or one of the following errors:
* \is
* \i 'IPCOM_ERR_INVALID_ARGS'
* Buffer is too small to contain the returned directory name.
* \i 'IPCOM_ERR_FAILED'
* Communication with server failed.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_get_cwd
    (
     struct Ipssh_conn_st* ssh_conn,
     char* buf,
     int buf_len
    );

/*******************************************************************************
*
* ipssh_sftp_clt_chdir - change current working directory on the server
*
* This routine changes the current working directory on the SFTP server.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <path>
* The path to the new working directory, either relative or absolute.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or the following error:
* \is
* \i 'IPCOM_ERR_FAILED'
* Working directory not updated.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_chdir
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* path
    );

/*******************************************************************************
*
* ipssh_sftp_clt_mkdir - create a directory on the server
*
* This routine creates a directory on the remote server.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <path>
* The path to the directory to be created.
* \i <mode>
* An integer specifying the file privileges that apply to the directory.
* The integer is usually expressed as an octal value, read (4), write (2) and
* execute (1). These values can be combined, e.g. 6 means read and write
* permission. Three octal value are used to express the priviliges for the
* user, group and others, respectively. For example 0644 means the user has
* read and write privileges, the group has read  privileges and
* others have read privileges.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' if the directory was created.
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_mkdir
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* path,
     Ip_mode_t mode
    );

/*******************************************************************************
*
* ipssh_sftp_clt_rmdir - delete a directory on the server
*
* The routine deletes a directory on the remote server.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <path>
* The path to the directory to be deleted.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS', if the directory was deleted. [* What if not
* deleted--e.g., insufficient privilege]
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_rmdir
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* path
    );

/*******************************************************************************
*
* ipssh_sftp_clt_opendir - open a directory stream on a server
*
* This routine opens a directory stream for a specified directory. The stream is
* positioned at the first entry in the directory.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <path>
* The path to the directory.
* \ie
*
* RETURNS: A pointer to the directory stream, or 'IP_NULL' if the operation
* failed.
*
* ERRNO:
*/
    IP_PUBLIC void* ipssh_sftp_clt_opendir
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* path
    );

/*******************************************************************************
*
* ipssh_sftp_clt_readdir - read the next directory entry on the server
*
* This routine returns a pointer to an 'ipssh_dirent' structure containing the
* next directory entry in the specified directory stream.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <handle>
* A handle to the directory stream.
* \ie
*
* RETURNS: A pointer to an 'ipssh_dirent' structure, or 'IP_NULL' if the last
* entry has been read.
*
* ERRNO:
*/
    IP_PUBLIC Ipssh_dirent* ipssh_sftp_clt_readdir
    (
     struct Ipssh_conn_st* ssh_conn,
     void* handle
    );

/*******************************************************************************
*
* ipssh_sftp_clt_closedir - close a directory stream on the server
*
* This routine closes a directory stream that was opened with
* ipssh_sftp_clt_opendir().
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i <handle>
* A handle to the directory stream to be closed.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or the following error:
* \is
* \i 'IPCOM_ERR_FAILED'
* Communication with the SFTP server failed.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_closedir
    (
     struct Ipssh_conn_st* ssh_conn,
     void* handle
    );

/*******************************************************************************
*
* ipssh_sftp_clt_rename - rename a file on the server
*
* This routine renames a file on the server.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \i oldpath
* path to the file to be renamed
* \i newpath
* new path for the renamed file
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or one of the following errors:
* \is
* \i 'IPCOM_ERR_NOT_FOUND'
* File not found on SFTP server.
* \i 'IPCOM_ERR_PERMISSION_DENIED'
* Insufficient privileges to rename file.
* \i 'IPCOM_ERR_FAILED'
* Communication with SFTP server failed.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_rename
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* oldpath,
     const char* newpath
    );

/*******************************************************************************
*
* ipssh_sftp_clt_unlink - delete a file on the server
*
* This routine deletes a file from the server.
*
* Parameters:
* \is
* \i <ssh_conn>
* A handle to the connection.
* \ie
*
* RETURNS: 'IPCOM_SUCCESS' or one of the following errors:
* \is
* \i 'IPCOM_ERR_NOT_FOUND'
* File not found on SFTP server.
* \i 'IPCOM_ERR_PERMISSION_DENIED'
* Insufficient privileges to remove file.
* \i 'IPCOM_ERR_FAILED'
* Communication with SFTP server failed.
* \ie
*
* ERRNO:
*/
    IP_PUBLIC Ip_err ipssh_sftp_clt_unlink
    (
     struct Ipssh_conn_st* ssh_conn,
     const char* path
    );

#ifdef __cplusplus
}
#endif

#endif

/*
 ****************************************************************************
 *                      END OF FILE
 ****************************************************************************
 */