new function: libssh2_session_banner_get

Returns the banner from the server handshake

Fixes #226

docs/Makefile.am

@@ -92,6 +92,7 @@ dist_man_MANS = \
 	libssh2_scp_send64.3 \
 	libssh2_scp_send_ex.3 \
 	libssh2_session_abstract.3 \
+	libssh2_session_banner_get.3 \
 	libssh2_session_block_directions.3 \
 	libssh2_session_callback_set.3 \
 	libssh2_session_disconnect.3 \

docs/libssh2_session_banner_get.3

@@ -0,0 +1,19 @@
+.TH libssh2_session_banner_get 3 "9 Sep 2011" "libssh2 1.4.0" "libssh2 manual"
+.SH NAME
+libssh2_session_banner_get - get the remote banner
+.SH SYNOPSIS
+#include <libssh2.h>
+
+const char *libssh2_session_banner_get(oLIBSSH2_SESSION *session);
+.SH DESCRIPTION
+Once the session has been setup and \fIlibssh2_session_handshake(3)\fP has
+completed successfully, this function can be used to get the server id from
+the banner each server presents.
+.SH RETURN VALUE
+A pointer to a string or NULL if something failed. The data pointed to will be
+allocated and associated to the session handle and will be freed by libssh2
+when \fIlibssh2_session_free(3)\fP is used.
+.SH SEE ALSO
+.BR libssh2_session_banner_set(3),
+.BR libssh2_session_handshake(3),
+.BR libssh2_session_free(3)

include/libssh2.h

@@ -487,6 +487,7 @@ LIBSSH2_API int libssh2_session_block_directions(LIBSSH2_SESSION *session);
 
 LIBSSH2_API int libssh2_session_flag(LIBSSH2_SESSION *session, int flag,
                                      int value);
+LIBSSH2_API const char *libssh2_session_banner_get(LIBSSH2_SESSION *session);
 
 /* Userauth API */
 LIBSSH2_API char *libssh2_userauth_list(LIBSSH2_SESSION *session,

src/session.c

@@ -1718,3 +1718,19 @@ libssh2_session_block_directions(LIBSSH2_SESSION *session)
     return session->socket_block_directions;
 }
 
+/* libssh2_session_banner_get
+ * Get the remote banner (server ID string)
+ */
+
+LIBSSH2_API const char *
+libssh2_session_banner_get(LIBSSH2_SESSION *session)
+{
+    /* to avoid a coredump when session is NULL */
+    if (NULL == session)
+        return NULL;
+
+    if (NULL==session->remote.banner)
+        return NULL;
+
+    return (const char *) session->remote.banner;
+}