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

最新推荐文章于 2025-03-27 10:20:52 发布

OceanStar的学习笔记

最新推荐文章于 2025-03-27 10:20:52 发布

阅读量7k

点赞数 5

分类专栏： C++

原文链接：https://www.libssh2.org/libssh2_version.html

版权

C++ 专栏收录该内容

1060 篇文章

订阅专栏

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_ERROR_ALLOC-内部内存分配调用失败。
LIBSSH2_ERROR_SOCKET_SEND-无法在套接字上发送数据。
LIBSSH2_ERROR_SOCKET_TIMEOUT -
LIBSSH2_ERROR_SFTP_PROTOCOL-套接字上收到无效的SFTP协议响应，或者SFTP操作导致服务器返回错误代码。
LIBSSH2_ERROR_EAGAIN-标记为非阻塞I / O，但调用将阻塞。

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);

在这里插入图片描述
参数：

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可以将这种情况与失败的情况区分开。

在这里插入图片描述

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) );

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

文章目录

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