diff options
Diffstat (limited to 'src/libssh2.h')
| -rw-r--r-- | src/libssh2.h | 187 |
1 files changed, 180 insertions, 7 deletions
diff --git a/src/libssh2.h b/src/libssh2.h index e46a07f..ea6c8c3 100644 --- a/src/libssh2.h +++ b/src/libssh2.h @@ -1,3 +1,6 @@ +/** \file + * \brief The libssh2 convenience functions. + */ /* * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com> * @@ -28,39 +31,140 @@ #include <pthsem.h> +/** + * \brief libssh2_session_handshake() wrapper function. + * \param s The libssh2 session object. + * \param fd The open file descriptor for the session. + * \param ev The pth event object to use on poll(). + * \retval 0 on success. + * \retval Non-zero value returned from the library functions or poll() on + * failure. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ int prne_lssh2_handshake (LIBSSH2_SESSION *s, const int fd, pth_event_t ev); +/** + * \brief libssh2_userauth_password_ex() wrapper function. + * \param s The libssh2 session object. + * \param fd The open file descriptor for the session. + * \param id The user name. + * \param pw The password. + * \param ev The pth event object to use on poll(). + * \retval 0 on success. + * \retval Non-zero value returned from the library functions or poll() on + * failure. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ int prne_lssh2_ua_pwd ( LIBSSH2_SESSION *s, const int fd, const char *id, const char *pw, pth_event_t ev); +/** + * \brief libssh2_channel_open_session() wrapper function. + * \param s The libssh2 session object. + * \param fd The open file descriptor for the session. + * \param ev The pth event object to use on poll(). + * \param[out] err The pointer to int for an error code on failure. + * \return The new libssh2 channel object on success. + * \retval NULL on failure. The return value of libssh2_session_last_errno() is + * returned via \p err if used. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ LIBSSH2_CHANNEL *prne_lssh2_open_ch ( LIBSSH2_SESSION *s, const int fd, pth_event_t ev, int *err); +/** + * \brief libssh2_channel_close() wrapper function. + * \param s The libssh2 session object. + * \param c The libssh2 channel object. + * \param fd The open file descriptor for the session. + * \param ev The pth event object to use on poll(). + * \retval 0 on success. + * \retval Non-zero value returned from the library functions or poll() on + * failure. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ int prne_lssh2_close_ch ( LIBSSH2_SESSION *s, LIBSSH2_CHANNEL *c, const int fd, pth_event_t ev); +/** + * \brief libssh2_channel_wait_closed() wrapper function. + * \param s The libssh2 session object. + * \param c The libssh2 channel object. + * \param fd The open file descriptor for the session. + * \param ev The pth event object to use on poll(). + * \retval 0 on success. + * \retval Non-zero value returned from the library functions or poll() on + * failure. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ int prne_lssh2_ch_wait_closed ( LIBSSH2_SESSION *s, LIBSSH2_CHANNEL *c, const int fd, pth_event_t ev); +/** + * \brief libssh2_channel_request_pty() wrapper function. + * \param s The libssh2 session object. + * \param c The libssh2 channel object. + * \param fd The open file descriptor for the session. + * \param term + * \param ev The pth event object to use on poll(). + * \retval 0 on success. + * \retval Non-zero value returned from the library functions or poll() on + * failure. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ int prne_lssh2_ch_req_pty ( LIBSSH2_SESSION *s, LIBSSH2_CHANNEL *c, const int fd, const char *term, pth_event_t ev); +/** + * \brief libssh2_channel_shell() wrapper function. + * \param s The libssh2 session object. + * \param c The libssh2 channel object. + * \param fd The open file descriptor for the session. + * \param ev The pth event object to use on poll(). + * \retval 0 on success. + * \retval Non-zero value returned from the library functions or poll() on + * failure. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ int prne_lssh2_ch_sh ( LIBSSH2_SESSION *s, LIBSSH2_CHANNEL *c, const int fd, pth_event_t ev); +/** + * \brief libssh2_channel_read() wrapper function. + * \param s The libssh2 session object. + * \param c The libssh2 channel object. + * \param fd The open file descriptor for the session. + * \param s_err The standard error flag. Returns data from the standard error + * stream instead of the standard output stream if pass as \c true . + * \param[out] buf The output buffer. + * \param[in] len The byte length of \p buf . + * \param ev The pth event object to use on poll(). + * \return The actual number of bytes read from the stream and written to \p buf + * or a negative value returned from the library functions or poll() on + * failure. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ int prne_lssh2_ch_read ( LIBSSH2_SESSION *s, LIBSSH2_CHANNEL *c, @@ -69,6 +173,19 @@ int prne_lssh2_ch_read ( void *buf, const size_t len, pth_event_t ev); +/** + * \brief libssh2_channel_write() wrapper function. + * \param s The libssh2 session object. + * \param c The libssh2 channel object. + * \param fd The open file descriptor for the session. + * \param buf The buffer containing data to write to the standard input stream. + * \param len The byte length of data to write from \p buf . + * \param ev The pth event object to use on poll(). + * \return The actual number of bytes written to the stream or a negative value + * returned from the library functions or poll() on failure. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ int prne_lssh2_ch_write ( LIBSSH2_SESSION *s, LIBSSH2_CHANNEL *c, @@ -76,6 +193,18 @@ int prne_lssh2_ch_write ( const void *buf, const size_t len, pth_event_t ev); +/** + * \brief libssh2_session_disconnect_ex() wrapper function. + * \param s The libssh2 session object. + * \param c The libssh2 channel object. + * \param fd The open file descriptor for the session. + * \param ev The pth event object to use on poll(). + * \retval 0 on success. + * \retval Non-zero value returned from the library functions or poll() on + * failure. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ int prne_lssh2_discon ( LIBSSH2_SESSION *s, const int fd, @@ -83,22 +212,66 @@ int prne_lssh2_discon ( const char *desc, const char *lang, pth_event_t ev); +/** + * \brief libssh2_userauth_list() wrapper function. + * \param s The libssh2 session object. + * \param fd The open file descriptor for the session. + * \param username The pointer to the null-terminated user name string. + * \param ev The pth event object to use on poll(). + * \param[out] err The pointer to an \c int for returning an error occurred + * during the function call if any. The \c int will be set to zero if the + * the operation was successful (optional) + * \return The pointer to the internal comma-separated and null-terminated + * string of the authentication methods available for the user. + * \retval NULL if an error has occurred. The \c int at \p err is set to the + * \c errno + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ const char *prne_lssh2_ua_list ( LIBSSH2_SESSION *s, const int fd, const char *username, pth_event_t ev, int *err); +/** + * \brief libssh2_userauth_authenticated() wrapper function. + * \param s The libssh2 session object. + * \param fd The open file descriptor for the session. + * \param ev The pth event object to use on poll(). + * \retval 1 if the session has been authenticated. + * \retval 0 if the session has not been authenticated. + * \retval Negative value returned from the library functions or poll() on + * failure. + * \note This is a convenience function that wraps all the operation that + * involves polling and calling the function again. + */ int prne_lssh2_ua_authd ( LIBSSH2_SESSION *s, const int fd, pth_event_t ev); -/* Workaround for the library's shitty design -* -* Cripples LIBSSH2_SESSION's ability to send() and recv() so that -* the library can't use the fd. This is used to guarantee that *_free() -* functions never return EAGAIN. -*/ -void prne_lssh2_cripple_session (LIBSSH2_SESSION *s); +/** + * \brief Free the libssh2 session object. + * \param s The libssh2 session object. + * \note This is a bullshit-free version of libssh2_session_free(). + * \note The function call has no effect if \p s is passed NULL. + * \see prne_lssh2_cripple_session() + */ void prne_lssh2_free_session (LIBSSH2_SESSION *s); + +/* Workarounds */ +/** + * \brief Cripple the session's IO ability. Used to guarantee that + * \c libssh2_session_free() will never return \c EAGAIN . + * \param s The libssh2 session object. + * \warning This function renders the session unusuable. The function must be + * the last function to call before calling \c libssh2_session_free() to + * free the resources. + * \note This function is used in \c prne_lssh2_free_session() . This function + * is exposed just to cover the cases where it's necessary to cripple the + * session manually. + * \see prne_lssh2_free_session() + * \see libssh2_session_free() + */ +void prne_lssh2_cripple_session (LIBSSH2_SESSION *s); |