libssh2_session_set_last_error: Add function

Net::SSH2, the Perl wrapping module for libssh2 implements several features*
on top of libssh2 that can fail and so need some mechanism to report the error
condition to the user.

Until now, besides the error state maintained internally by libssh2, another
error state was maintained at the Perl level for every session object and then
additional logic was used to merge both error states. That is a maintenance
nighmare, and actually there is no way to do it correctly and consistently.

In order to allow the high level language to add new features to the library
but still rely in its error reporting features the new function
libssh2_session_set_last_error (that just exposses _libssh2_error_flags) is
introduced.

*) For instance, connecting to a remote SSH service giving the hostname and
port.

Signed-off-by: Salvador Fandino <sfandino@yahoo.com>
Signed-off-by: Salvador Fandiño <sfandino@yahoo.com>
This commit is contained in:
Salvador Fandino 2015-10-15 17:36:03 +02:00 committed by Daniel Stenberg
parent ad23faaae6
commit b83c3e056e
7 changed files with 58 additions and 1 deletions

View File

@ -139,6 +139,7 @@ set(MAN_PAGES
libssh2_session_init_ex.3
libssh2_session_last_errno.3
libssh2_session_last_error.3
libssh2_session_set_last_error.3
libssh2_session_method_pref.3
libssh2_session_methods.3
libssh2_session_set_blocking.3

View File

@ -110,6 +110,7 @@ dist_man_MANS = \
libssh2_session_init_ex.3 \
libssh2_session_last_errno.3 \
libssh2_session_last_error.3 \
libssh2_session_set_last_error.3 \
libssh2_session_method_pref.3 \
libssh2_session_methods.3 \
libssh2_session_set_blocking.3 \

View File

@ -18,3 +18,4 @@ Numeric error code corresponding to the the Error Code constants.
.SH SEE ALSO
.BR libssh2_session_last_error(3)
.BR libssh2_session_set_last_error(3)

View File

@ -29,3 +29,4 @@ Numeric error code corresponding to the the Error Code constants.
.SH SEE ALSO
.BR libssh2_session_last_errno(3)
.BR libssh2_session_set_last_error(3)

View File

@ -0,0 +1,33 @@
.TH libssh2_session_set_last_error 3 "26 Oct 2015" "libssh2 1.6.1" "libssh2 manual"
.SH NAME
libssh2_session_set_last_error - sets the internal error state
.SH SYNOPSIS
#include <libssh2.h>
int
libssh2_session_set_last_error(LIBSSH2_SESSION *session, int errcode, const char *errmsg)
.SH DESCRIPTION
\fIsession\fP - Session instance as returned by
.BR libssh2_session_init_ex(3)
\fIerrcode\fP - One of the error codes as defined in the public
libssh2 header file.
\fIerrmsg\fP - If not NULL, a copy of the given string is stored
inside the session object as the error message.
This function is provided for high level language wrappers
(i.e. Python or Perl) and other libraries that may extend libssh2 with
additional features while still relying on its error reporting
mechanism.
.SH RETURN VALUE
Numeric error code corresponding to the the Error Code constants.
.SH AVAILABILITY
Added in 1.6.1
.SH SEE ALSO
.BR libssh2_session_last_error(3)
.BR libssh2_session_last_errno(3)

View File

@ -567,6 +567,9 @@ LIBSSH2_API int libssh2_session_last_error(LIBSSH2_SESSION *session,
char **errmsg,
int *errmsg_len, int want_buf);
LIBSSH2_API int libssh2_session_last_errno(LIBSSH2_SESSION *session);
LIBSSH2_API int libssh2_session_set_last_error(LIBSSH2_SESSION* session,
int errcode,
const char* errmsg);
LIBSSH2_API int libssh2_session_block_directions(LIBSSH2_SESSION *session);
LIBSSH2_API int libssh2_session_flag(LIBSSH2_SESSION *session, int flag,

View File

@ -1290,7 +1290,24 @@ libssh2_session_last_errno(LIBSSH2_SESSION * session)
return session->err_code;
}
/* libssh2_session_flag
/* libssh2_session_set_last_error
*
* Sets the internal error code for the session.
*
* This function is available specifically to be used by high level
* language wrappers (i.e. Python or Perl) that may extend the library
* features while still relying on its error reporting mechanism.
*/
LIBSSH2_API int
libssh2_session_set_last_error(LIBSSH2_SESSION* session,
int errcode,
const char* errmsg)
{
return _libssh2_error_flags(session, errcode, errmsg,
LIBSSH2_ERR_FLAG_DUP);
}
/* Libssh2_session_flag
*
* Set/Get session flags
*