C/C++编程：libssh2 API学习

一时失言乱红尘 2023-01-09 01:19 878阅读 0赞

### 文章目录 ###

*  libssh2\_sftp\_init
 *  libssh2\_sftp\_fstat\_ex
 *  libssh2\_sftp\_open
 *  libssh2\_sftp\_open\_ex
 *  libssh2\_sftp\_read
 *  libssh2\_sftp\_close
 *  libssh2\_sftp\_close\_handle
 *  libssh2\_sftp\_shutdown
 *  libssh2\_sftp\_last\_error
 *  libssh2\_session\_block\_directions
 *  libssh2\_session\_handshake
 *  libssh2\_session\_init
 *  libssh2\_session\_init\_ex
 *  libssh2\_session\_disconnect
 *  libssh2\_session\_disconnect\_ex
 *  libssh2\_session\_free
 *  libssh2\_hostkey\_hash
 *  libssh2\_session\_set\_blocking
 *  libssh2\_userauth\_list
 *  libssh2\_userauth\_password
 *  libssh2\_userauth\_password\_ex
 *  libssh2\_init
 *  libssh2\_exit
 *  libssh2\_version

# libssh2\_sftp\_init #

#include <libssh2.h> #include <libssh2_sftp.h>
    
    LIBSSH2_SFTP * libssh2_sftp_init(LIBSSH2_SESSION *session);

名称

*  libssh2\_sftp\_init-为给定的SSH会话打开SFTP通道。

描述：

*  打开一个通道并初始化SFTP子系统。
 *  尽管SFTP子系统在与Channel API导出的通道类型相同的通道上运行，但该协议本身实现了自己独特的二进制数据包协议，必须使用libssh2\_sftp \_ \*（）系列功能进行管理
 *  SFTP会话完成后，必须使用libssh2\_sftp\_shutdown函数销毁它。

返回值

*  指向新分配的SFTP实例的指针，失败时为NULL。

错误

*  LIBSSH2\_ERROR\_ALLOC-内部内存分配调用失败。
 *  LIBSSH2\_ERROR\_SOCKET\_SEND-无法在套接字上发送数据。
 *  LIBSSH2\_ERROR\_SOCKET\_TIMEOUT -
 *  LIBSSH2\_ERROR\_SFTP\_PROTOCOL-套接字上收到无效的SFTP协议响应，或者SFTP操作导致服务器返回错误代码。
 *  LIBSSH2\_ERROR\_EAGAIN-标记为非阻塞I / O，但调用将阻塞。

# libssh2\_sftp\_fstat\_ex #

名称：

*  获取或设置SFTP文件句柄上的属性

参数：

*  `handle` ：libssh2\_sftp\_open\_ex的返回值
 *  `attrs` ：

# libssh2\_sftp\_open #

名称：

*  libssh2\_sftp\_open\_ex调用的便利宏

#include <libssh2.h>
    
    LIBSSH2_SFTP_HANDLE * libssh2_sftp_open（LIBSSH2_SFTP * sftp，const char * path，unsigned long flags，long mode）;

# libssh2\_sftp\_open\_ex #

#include <libssh2.h>
    #include <libssh2_sftp.h>
     
    LIBSSH2_SFTP_HANDLE *
    libssh2_sftp_open_ex(LIBSSH2_SFTP *sftp, const char *filename,
                         unsigned int filename_len, unsigned long flags,
                         long mode, int open_type);

名称

*  libssh2\_sftp\_open-在SFTP上打开文件的文件句柄。

参数：

*  sftp ： libssh2\_sftp\_init返回的SFTP实例
 *  filename ：要打开的远程文件/目录资源
 *  filename\_len ：文件名长度
 *  flag ：LIBSSH2\_FXF\_ \*常量的任何合理组合：
    
     *  LIBSSH2\_FXF\_READ
        
         *  打开文件进行读取
     *  LIBSSH2\_FXF\_WRITE
        
         *  打开文件进行写入
         *  如果同时指定了this和LIBSSH2\_FXF\_READ，则将同时打开该文件以进行读取和写入。
     *  LIBSSH2\_FXF\_APPEND
        
         *  强制所有写入将数据追加到文件末尾
     *  LIBSSH2\_FXF\_CREAT
        
         *  如果指定了此标志，则如果一个不存在，则将创建一个新文件
         *  如果指定了LIBSSH2\_FXF\_TRUNC，则新文件如果以前存在，则将被截断为零长度
     *  LIBSSH2\_FXF\_TRUNC
        
         *  通过指定LIBSSH2\_FXF\_CREAT，在创建文件时强制将具有相同名称的现有文件截断为零长度。如果使用此标志，还必须指定LIBSSH2\_FXF\_CREAT
     *  LIBSSH2\_FXF\_EXCL
        
         *  如果命名文件已经存在，则导致请求失败。
         *  如果使用此标志，还必须指定LIBSSH2\_FXF\_CREAT
 *  mode
    
     *  POSIX文件权限，用于分配是否是新创建的文件。请参见<libssh2\_sftp.h>中的LIBSSH2\_SFTP\_S\_ \*便利性定义。
 *  open\_type
    
     *  LIBSSH2\_SFTP\_OPENFILE（打开文件）
     *  LIBSSH2\_SFTP\_OPENDIR（打开目录）

返回值：

*  指向新创建的LIBSSH2\_SFTP\_HANDLE实例的指针，失败时为NULL

错误

# libssh2\_sftp\_read #

#include <libssh2.h> #include <libssh2_sftp.h>
    
    ssize_t libssh2_sftp_read（LIBSSH2_SFTP_HANDLE * handle，char * buffer，size_t buffer_maxlen）;

名称：

*  从SFTP句柄读取数据

参数：

*  handle：libssh2\_sftp\_open\_ex返回的SFTP文件句柄
 *  buffer：buffer是一个指针，它指向一个预先分配的缓冲区
 *  buffer\_maxlen：最多可以读取的字节数

返回值：

*  实际填充到缓冲区中的字节数，否则为负数。否则它将返回LIBSSH2\_ERROR\_EAGAIN。虽然LIBSSH2\_ERROR\_EAGAIN是负数，但它本身并不是真正的失败。

说明：

*  从LIBSSH2\_SFTP\_HANDLE中读取数据块。
 *  该方法是在POSIX read（2）函数之后建模的， 并使用相同的调用语义。
 *  libssh2\_sftp\_read将尝试读取尽可能多的内容，但是如果文件指针到达末尾或进一步读取会导致套接字阻塞，则它可能不会填充所有缓冲区。

# libssh2\_sftp\_close #

名称：

*  libssh2\_sftp\_close\_handle调用的便利宏

#include <libssh2.h>
    
    int libssh2_sftp_close（LIBSSH2_SFTP_HANDLE * handle）;

# libssh2\_sftp\_close\_handle #

#include <libssh2.h> 
    #include <libssh2_sftp.h>
    
    int libssh2_sftp_close_handle（LIBSSH2_SFTP_HANDLE * handle）;
    
    int libssh2_sftp_close（LIBSSH2_SFTP_HANDLE * handle）;
    
    int libssh2_sftp_closedir（LIBSSH2_SFTP_HANDLE * handle）;

名称：

*  关闭文件句柄

参数：

*  handle：libssh2\_sftp\_open\_ex或libssh2\_sftp\_opendir（这是一个宏）的返回值

说明：

*  关闭活动的LIBSSH2\_SFTP\_HANDLE。
 *  因为文件和目录共享相同的基础存储机制，所以这些方法可以互换使用。libssh2\_sftp\_close和libssh2\_sftp\_closedir是libssh2\_sftp\_close\_handle的宏

返回值：

*  成功返回0，失败返回负数。否则它将返回LIBSSH2\_ERROR\_EAGAIN。虽然LIBSSH2\_ERROR\_EAGAIN是负数，但它本身并不是真正的失败。

错误：

*  LIBSSH2\_ERROR\_ALLOC：内部内存分配调用失败。
 *  LIBSSH2\_ERROR\_SOCKET\_SEND：无法在套接字上发送数据。
 *  LIBSSH2\_ERROR\_SOCKET\_TIMEOUT：
 *  LIBSSH2\_ERROR\_SFTP\_PROTOCOL：套接字上收到无效的SFTP协议响应，或者SFTP操作导致服务器返回错误代码。

# libssh2\_sftp\_shutdown #

#include <libssh2.h> 
    #include <libssh2_sftp.h>
    
    int libssh2_sftp_shutdown（LIBSSH2_SFTP * sftp）;

名称：

*  关闭SFTP会话

参数：

*  sftp - libssh2\_sftp\_init返回的SFTP实例

说明：

*  销毁先前初始化的SFTP会话，并释放与其关联的所有资源。

返回值：

*  成功返回0，失败返回负数。否则它将返回LIBSSH2\_ERROR\_EAGAIN。虽然LIBSSH2\_ERROR\_EAGAIN是负数，但它本身并不是真正的失败

# libssh2\_sftp\_last\_error #

名称：

*  返回最后一个特定于SFTP的错误代码

说明：

*  返回SFTP层产生的最后一个错误码。注意，只有在libssh2在前一次调用中返回LIBSSH2\_ERROR\_SFTP\_PROTOCOL时，才会返回一个合理的错误代码。如果使用libssh2\_sftp\_last\_error而没有前面的SFTP协议错误，它将返回一个未指定的值

返回值：

*  SFTP实例的当前错误代码状态。

# libssh2\_session\_block\_directions #

#include <libssh2.h>
    
    int libssh2_session_block_directions（LIBSSH2_SESSION * session）;

名称：

*  获取等待的路线

说明：

*  当任何libssh2函数返回LIBSSH2\_ERROR\_EAGAIN时，应用程序应等待套接字具有可用于读取或写入的数据
 *  根据libssh2\_session\_block\_directions的返回值，应用程序应等待读取，写入或同时等待。

参数：

*  session ：libssh2\_session\_init\_ex返回的会话实例

返回值：

*  返回方向集作为二进制掩码。可以是以下各项的组合：
    
     *  LIBSSH2\_SESSION\_BLOCK\_INBOUND：入站方向被阻止。
     *  LIBSSH2\_SESSION\_BLOCK\_OUTBOUND：出站方向被阻止。
 *  在再次调用libssh2函数之前，应用程序应等待数据可用于套接字。
 *  如果设置了LIBSSH2\_SESSION\_BLOCK\_INBOUND，则select应该在readfds集中包含会话套接字。
 *  相应地，在LIBSSH2\_SESSION\_BLOCK\_OUTBOUND的情况下，writefds设置应包含套接字。

# libssh2\_session\_handshake #

#include <libssh2.h>
    
    int libssh2_session_handshake(LIBSSH2_SESSION *session, libssh2_socket_t socket);

名称

*  执行SSH握手

参数：

*  session - libssh2\_session\_init\_ex返回的会话实例
 *  socket-连接的套接字描述符。通常，尽管该协议允许任何可靠的传输，但TCP连接允许该库尝试使用任何berkeley套接字

返回值

*  成功返回0，失败返回负。

错误

*  LIBSSH2\_ERROR\_SOCKET\_NONE-套接字无效。
 *  LIBSSH2\_ERROR\_BANNER\_SEND-无法将横幅发送到远程主机。
 *  LIBSSH2\_ERROR\_KEX\_FAILURE- >与远程主机的加密密钥交换失败。
 *  LIBSSH2\_ERROR\_SOCKET\_SEND-无法在套接字上发送数据。
 *  LIBSSH2\_ERROR\_SOCKET\_DISCONNECT-套接字已断开连接。
 *  LIBSSH2\_ERROR\_PROTO-套接字上收到无效的SSH协议响应。
 *  LIBSSH2\_ERROR\_EAGAIN-标记为非阻塞I / O，但调用将阻塞。

返回值

*  成功返回0，失败返回负。

# libssh2\_session\_init #

名称

*  `libssh2_session_init`： `libssh2_session_init_ex`调用的便利宏

#include <libssh2.h>
    
    LIBSSH2_SESSION * libssh2_session_init（void）;

描述

*  这是使用基础函数`libssh2_session_init_ex`的公共libssh2头文件中定义的宏。

# libssh2\_session\_init\_ex #

#include <libssh2.h>
    
    LIBSSH2_SESSION * libssh2_session_init_ex(LIBSSH2_ALLOC_FUNC((*myalloc)), LIBSSH2_FREE_FUNC((*myfree)), LIBSSH2_REALLOC_FUNC((*myrealloc)), void *abstract);
    
    LIBSSH2_SESSION * libssh2_session_init(void);

名称：

*  libssh2\_session\_init\_ex-初始化SSH会话对象

描述：

*  初始化SSH会话对象。默认情况下，系统内存分配器（malloc（），free（），realloc（））将用于任何动态分配的内存块。可以使用此API调用的扩展版本指定备用内存分配功能，和/或可以将可选的特定于应用程序的数据附加到会话对象。
 *  **在配置会话选项或启动与远程服务器的SSH会话之前，必须首先调用此方法。**

参数：

*  myalloc-自定义分配器函数。有关实现分配器回调的信息，请参阅“回调”部分。传递NULL值以使用默认系统分配器。
 *  myfree-定制的解除分配器功能。有关实现deallocator回调的信息，请参阅“回调”部分。传递NULL值以使用默认的系统解除分配器。
 *  myrealloc-自定义重新分配器功能。有关实现重新分配器回调的信息，请参阅“回调”部分。传递NULL值以使用默认的系统重新分配器。
 *  abstract-指向应用程序特定回调数据的任意指针。该值将传递给与命名会话实例关联的任何回调函数。

返回值：

*  指向新分配的LIBSSH2\_SESSION实例的指针，或在错误时为NULL

其他：

*  libssh2\_session\_free
 *  libssh2\_session\_handshake

# libssh2\_session\_disconnect #

名称：

*  libssh2\_session\_disconnect\_ex调用的便利宏

#include <libssh2.h>
    
    int libssh2_session_disconnect（LIBSSH2_SESSION * session，const char * description）;

# libssh2\_session\_disconnect\_ex #

#include <libssh2.h>
    
    int libssh2_session_disconnect_ex(LIBSSH2_SESSION *session, int reason, const char *description, const char *lang);
    
    int libssh2_session_disconnect(LIBSSH2_SESSION *session, const char *description);

名称

*  libssh2\_session\_disconnect\_ex-终止传输层

描述：

*  向与会话关联的远程主机发送断开连接消息，以及原因符号和详细说明。

参数：

*  `session` ：`libssh2_session_init_ex`返回的会话实例
 *  `reason`：断开原因常量之一
 *  `description`：易于理解的断开原因
 *  `lang`：描述所提供描述语言/编码的本地化字符串

其他：

*  libssh2\_session\_init\_ex

# libssh2\_session\_free #

名称：

*  libssh2\_session\_free-释放与会话实例关联的资源

描述：

*  释放与会话实例关联的所有资源。通常在`libssh2_session_disconnect_ex`之后调用

其他：

*  libssh2\_session\_init\_ex
 *  libssh2\_session\_disconnect\_ex

# libssh2\_hostkey\_hash #

#include <libssh2.h>
    
    const char * libssh2_hostkey_hash(LIBSSH2_SESSION *session, int hash_type);

名称

*  libssh2\_hostkey\_hash-返回远程主机密钥的哈希

描述：

*  返回远程系统的主机键的计算摘要。
 *  返回的字符串的长度是特定于hash\_type的（例如，MD5为16个字节，SHA1为20个字节，SHA256为32个字节）。

参数：

*  session - libssh2\_session\_init\_ex返回的会话实例
 *  hash\_type - LIBSSH2\_HOSTKEY\_HASH\_MD5， LIBSSH2\_HOSTKEY\_HASH\_SHA1或LIBSSH2\_HOSTKEY\_HASH\_SHA256之一。

返回值：

*  计算的主机密钥哈希值，如果信息不可用（会话尚未启动，或者请求的哈希算法不可用），则为NULL
 *  散列由原始二进制字节组成，而不是十六进制数字，因此不能直接打印

# libssh2\_session\_set\_blocking #

名称

*  libssh2\_session\_set\_blocking-设置或者清除会话的阻塞模式

#include <libssh2.h>
    
    void libssh2_session_set_blocking(LIBSSH2_SESSION *session, int blocking);

描述：

*  设置或者清除会话的阻塞模式
 *  在会话上设置或清除选中的阻塞模式。这将立即影响与此会话相关的任何通道。
 *  如果在一个没有可用数据的会话上执行读操作：
    
     *  阻塞会话将等待数据到达并返回它接收到的数据
     *  非阻塞会话将立即返回一个空缓冲区。
 *  如果在没有空间存放更多数据的会话上执行写操作
    
     *  阻塞的会话将等待空间
     *  非阻塞会话将立即返回而不写入任何东西

参数：

*  `session`： `libssh2_session_init_ex`返回的会话实例
 *  `blocking`：非0阻塞，0不阻塞

# libssh2\_userauth\_list #

名称：

*  libssh2\_userauth\_list-列出支持的身份验证方法

#include <libssh2.h>
     
    char *
    libssh2_userauth_list(LIBSSH2_SESSION *session, const char *username,
                          unsigned int username_len);

![在这里插入图片描述][20210121175614239.png]  
参数：

*  `session` ： libssh2\_session\_init\_ex返回的会话实例
 *  `username`：认证时将使用的用户名。请注意，大多数服务器实现不允许请求之间使用不同的用户名进行身份验证。因此，该用户名必须与以后的userauth调用中使用的用户名相同。
 *  `username_len`：用户名参数的长度

返回值：

*  成功后，以逗号分隔的受支持身份验证方案列表。该列表由libssh2内部管理。失败时返回NULL。

错误：

*  LIBSSH2\_ERROR\_ALLOC-内部内存分配调用失败
 *  LIBSSH2\_ERROR\_SOCKET\_SEND-无法在套接字上发送数据
 *  LIBSSH2\_ERROR\_EAGAIN-标记为非阻塞I / O，但调用

其他API：

*  libssh2\_session\_init\_ex

将**SSH\_USERAUTH\_NONE**请求发送到远程主机。除非远程主机配置为不接受任何可行的身份验证方案（不太可能），否则它将返回**SSH\_USERAUTH\_FAILURE**以及其支持的身份验证方案的列表。万一没有身份验证成功，这种方法将返回NULL。通过检查libssh2\_userauth\_authenticated可以将这种情况与失败的情况区分开。

![在这里插入图片描述][20210121180817876.png]

# libssh2\_userauth\_password #

libssh2\_userauth\_password- `libssh2_userauth_password_ex`调用的便捷宏

#define libssh2_userauth_password(session, username, password)  libssh2_userauth_password_ex((session), (username),                               strlen(username),                               (password), strlen(password), NULL)

# libssh2\_userauth\_password\_ex #

#include <libssh2.h>
    
    int libssh2_userauth_password_ex(LIBSSH2_SESSION *session,
                        const char *username,
                        unsigned int username_len,
                        const char *password,
                        unsigned int password_len,
                        LIBSSH2_PASSWD_CHANGEREQ_FUNC((*passwd_change_cb)));
     
    #define libssh2_userauth_password(session, username, password)  libssh2_userauth_password_ex((session), (username),                               strlen(username),                               (password), strlen(password), NULL)

名称

*  libssh2\_userauth\_password\_ex-使用用户名和密码验证会话

描述：

*  尝试基本密码验证。注意，许多似乎支持普通密码身份验证的SSH服务器实际上已经禁用了它，而是使用键盘交互身份验证(通过PAM或其他支持的身份验证路由)。

参数：

*  session ： libssh2\_session\_init\_ex返回的会话实例
 *  username ：用户名
 *  username\_len ：用户名参数的长度
 *  password ：用于验证用户名的密码
 *  password\_len ：密码参数的长度
 *  passwd\_change\_cb ：如果主机接受身份验证，但请求更改密码，则将发出此回调。如果没有定义回调，但服务器要求更改密码，身份验证将失败。

返回值：

*  成功时返回0，失败时返回负值。它会在阻塞时返回LIBSSH2\_ERROR\_EAGAIN。虽然LIBSSH2\_ERROR\_EAGAIN是一个负数，但它本身并不是真正的失败。

错误：

*  LIBSSH2\_ERROR\_ALLOC - 内部内存分配调用失败。
 *  LIBSSH2\_ERROR\_SOCKET\_SEND - 无法在套接字上发送数据。
 *  LIBSSH2\_ERROR\_PASSWORD\_EXPIRED -
 *  fLIBSSH2\_ERROR\_AUTHENTICATION\_FAILED - 失败，无效的用户名/密码或公钥/私钥。

# libssh2\_init #

名称：

*  libssh2\_init-全局库初始化

#include <libssh2.h>
    
    #define LIBSSH2_INIT_NO_CRYPTO 0x0001
    
    int libssh2_init(int flags);

描述：

*  初始化libssh2函数。这通常会初始化加密库。它使用全局状态，并且不是线程安全的-您必须确保不同时调用此函数。

返回值：

*  如果成功，则返回0，否则返回负值。

可用性：

*  在libssh2 1.2.5中添加

其他API：

*  `libssh2_exit`

# libssh2\_exit #

名称：

*  libssh2\_exit-全局库取消初始化

#include <libssh2.h>
    
    void libssh2_exit（void）;

描述：

*  退出libssh2函数并释放内部使用的所有内存。

可用性：

*  在libssh2 1.2.5中添加

其他API：

*  `libssh2_init`

# libssh2\_version #

*  libssh2\_version–返回libssh2版本号

#include <libssh2.h>
    
    const char * libssh2_version（int required_version）;

描述：

*  如果required\_version小于或等于使用中的libssh2的版本号，则将libssh2的版本号作为指向零终止字符串的指针返回。
 *  所述REQUIRED\_VERSION应的版本号由LIBSSH2\_VERSION\_NUM构造在libssh2.h公共头文件，它是在0xMMmmpp格式的24比特数定义。MM为大写字母，mm为小写字母，pp为音色编号。

返回值：

*  如果REQUIRED\_VERSION不满足，作为一个指向零终止的字符串或NULL
 *  否则，libssh2的版本号被返回

可用性：

*  此功能是在libssh2 1.1中添加的

实例：

*  为了确保您使用正确的libssh2版本运行：

if (!libssh2_version(LIBSSH2_VERSION_NUM)) {
        
      fprintf (stderr, "Runtime libssh2 version too old!");
      exit(1);
    }

*  无条件获取版本号：

printf("libssh2 version: %s", libssh2_version(0) );

[20210121175614239.png]: /images/20221119/d9f1fb5cc5e94645b0a96d360115ac1e.png
[20210121180817876.png]: /images/20221119/b09c32f17e66429eadfc1edfb7505ba9.png