aboutsummaryrefslogtreecommitdiff
path: root/libssh
diff options
context:
space:
mode:
authorAndreas Schneider <mail@cynapses.org>2010-02-05 18:34:39 +0100
committerAndreas Schneider <mail@cynapses.org>2010-02-05 18:34:39 +0100
commit1297da380e0e35989c55ff96c1ecf2e4d10b1e7f (patch)
tree323e0ada6a6ca3e4d621bad9a3e3a5f641d5bd7f /libssh
parent4ee3b28ecb1edcd7b6b761aecb0e331cf0ad96f1 (diff)
downloadlibssh-1297da380e0e35989c55ff96c1ecf2e4d10b1e7f.tar.gz
libssh-1297da380e0e35989c55ff96c1ecf2e4d10b1e7f.tar.xz
libssh-1297da380e0e35989c55ff96c1ecf2e4d10b1e7f.zip
Improve the session documentation.
Diffstat (limited to 'libssh')
-rw-r--r--libssh/init.c19
-rw-r--r--libssh/session.c122
2 files changed, 93 insertions, 48 deletions
diff --git a/libssh/init.c b/libssh/init.c
index 9a584298..ddd56e02 100644
--- a/libssh/init.c
+++ b/libssh/init.c
@@ -31,17 +31,20 @@
#endif
/**
- * \addtogroup ssh_session
+ * @defgroup libssh The libssh API
+ *
+ * This is a library implementing the SSH protocols.
+ *
* @{
*/
/**
- * @brief initialize global cryptographic data structures.
+ * @brief Initialize global cryptographic data structures.
*
* This function should only be called once, at the beginning of the program, in
* the main thread. It may be omitted if your program is not multithreaded.
*
- * @returns 0
+ * @returns 0 on success, -1 if an error occured.
*/
int ssh_init(void) {
if(ssh_crypto_init())
@@ -59,7 +62,8 @@ int ssh_init(void) {
*
* This function should only be called once, at the end of the program!
*
- * @returns -1 in case of error
+ * @returns 0 on succes, -1 if an error occured.
+ *
@returns 0 otherwise
*/
int ssh_finalize(void) {
@@ -77,7 +81,6 @@ int ssh_finalize(void) {
return 0;
}
-/**
- * @}
- */
-/* vim: set ts=2 sw=2 et cindent: */
+/* @} */
+
+/* vim: set ts=4 sw=4 et cindent: */
diff --git a/libssh/session.c b/libssh/session.c
index 0fdef970..2e1ee2be 100644
--- a/libssh/session.c
+++ b/libssh/session.c
@@ -38,14 +38,19 @@
#define FIRST_CHANNEL 42 // why not ? it helps to find bugs.
-/** \defgroup ssh_session SSH Session
- * \brief functions that manage a session
+/**
+ * @defgroup libssh_session The SSH session functions.
+ * @ingroup libssh
+ *
+ * Functions that manage a session.
+ *
+ * @{
*/
-/** \addtogroup ssh_session
- * @{ */
-/** \brief creates a new ssh session
- * \returns new ssh_session pointer
+/**
+ * @brief Create a new ssh session.
+ *
+ * @returns A new ssh_session pointer, NULL on error.
*/
ssh_session ssh_new(void) {
ssh_session session;
@@ -106,7 +111,10 @@ err:
}
/**
- * @brief deallocate a session handle
+ * @brief Deallocate a SSH session handle.
+ *
+ * @param[in] session The SSH session to free.
+ *
* @see ssh_disconnect()
* @see ssh_new()
*/
@@ -183,9 +191,12 @@ void ssh_free(ssh_session session) {
SAFE_FREE(session);
}
-/** \brief disconnect impolitely from remote host by closing the socket.
+/**
+ * @brief Disconnect impolitely from a remote host by closing the socket.
+ *
* Suitable if you forked and want to destroy this session.
- * \param session current ssh session
+ *
+ * @param[in] session The SSH session to disconnect.
*/
void ssh_silent_disconnect(ssh_session session) {
enter_function();
@@ -200,9 +211,13 @@ void ssh_silent_disconnect(ssh_session session) {
leave_function();
}
-/** \brief set the session in blocking/nonblocking mode
- * \param session ssh session
- * \param blocking zero for nonblocking mode
+/**
+ * @brief Set the session in blocking/nonblocking mode.
+ *
+ * @param[in] session The ssh session to change.
+ *
+ * @param[in] blocking Zero for nonblocking mode.
+ *
* \bug nonblocking code is in development and won't work as expected
*/
void ssh_set_blocking(ssh_session session, int blocking) {
@@ -213,12 +228,15 @@ void ssh_set_blocking(ssh_session session, int blocking) {
session->blocking = blocking ? 1 : 0;
}
-/** In case you'd need the file descriptor of the connection
- * to the server/client
- * \brief recover the fd of connection
- * \param session ssh session
- * \return file descriptor of the connection, or -1 if it is
- * not connected
+/**
+ * @brief Get the fd of a connection.
+ *
+ * In case you'd need the file descriptor of the connection to the server/client.
+ *
+ * @param[in] session The ssh session to use.
+ *
+ * @return The file descriptor of the connection, or -1 if it is
+ * not connected
*/
socket_t ssh_get_fd(ssh_session session) {
if (session == NULL) {
@@ -228,8 +246,11 @@ socket_t ssh_get_fd(ssh_session session) {
return ssh_socket_get_fd(session->socket);
}
-/** \brief say to the session it has data to read on the file descriptor without blocking
- * \param session ssh session
+/**
+ * @brief Tell the session it has data to read on the file descriptor without
+ * blocking.
+ *
+ * @param[in] session The ssh session to use.
*/
void ssh_set_fd_toread(ssh_session session) {
if (session == NULL) {
@@ -239,8 +260,10 @@ void ssh_set_fd_toread(ssh_session session) {
ssh_socket_set_toread(session->socket);
}
-/** \brief say the session it may write to the file descriptor without blocking
- * \param session ssh session
+/**
+ * @brief Tell the session it may write to the file descriptor without blocking.
+ *
+ * @param[in] session The ssh session to use.
*/
void ssh_set_fd_towrite(ssh_session session) {
if (session == NULL) {
@@ -250,8 +273,10 @@ void ssh_set_fd_towrite(ssh_session session) {
ssh_socket_set_towrite(session->socket);
}
-/** \brief say the session it has an exception to catch on the file descriptor
- * \param session ssh session
+/**
+ * @brief Tell the session it has an exception to catch on the file descriptor.
+ *
+ * \param[in] session The ssh session to use.
*/
void ssh_set_fd_except(ssh_session session) {
if (session == NULL) {
@@ -261,15 +286,22 @@ void ssh_set_fd_except(ssh_session session) {
ssh_socket_set_except(session->socket);
}
-/** @internal
- * @brief polls the current session for an event and call the
- * appropriate callbacks. Will block until one event happens.
- * @param session session handle.
- * @param timeout An upper limit on the time for which
- * ssh_handle_packets() will block, in milliseconds.
- * Specifying a negative value means an infinite timeout.
- * This parameter is passed to the poll() function.
- * @return SSH_OK if there are no error, SSH_ERROR otherwise.
+/**
+ * @internal
+ *
+ * @brief Poll the current session for an event and call the appropriate
+ * callbacks.
+ *
+ * This will block until one event happens.
+ *
+ * @param[in] session The session handle to use.
+ *
+ * @param[in] timeout Set an upper limit on the time for which this function
+ * will block, in milliseconds. Specifying a negative value
+ * means an infinite timeout. This parameter is passed to
+ * the poll() function.
+ *
+ * @return SSH_OK on success, SSH_ERROR otherwise.
*/
int ssh_handle_packets(ssh_session session, int timeout) {
ssh_poll_handle spoll;
@@ -323,10 +355,16 @@ int ssh_get_status(ssh_session session) {
return r;
}
-/** \brief get the disconnect message from the server
- * \param session ssh session
- * \return message sent by the server along with the disconnect, or NULL in which case the reason of the disconnect may be found with ssh_get_error.
- * \see ssh_get_error()
+/**
+ * @brief Get the disconnect message from the server.
+ *
+ * @param[in] session The ssh session to use.
+ *
+ * @return The message sent by the server along with the
+ * disconnect, or NULL in which case the reason of the
+ * disconnect may be found with ssh_get_error.
+ *
+ * @see ssh_get_error()
*/
const char *ssh_get_disconnect_message(ssh_session session) {
if (session == NULL) {
@@ -366,7 +404,8 @@ int ssh_get_version(ssh_session session) {
/**
* @internal
- * @brief handles a SSH_DISCONNECT packet
+ *
+ * @brief Handle a SSH_DISCONNECT packet.
*/
SSH_PACKET_CALLBACK(ssh_packet_disconnect_callback){
uint32_t code;
@@ -395,7 +434,8 @@ SSH_PACKET_CALLBACK(ssh_packet_disconnect_callback){
/**
* @internal
- * @brief handles a SSH_IGNORE and SSH_DEBUG packet
+ *
+ * @brief Handle a SSH_IGNORE and SSH_DEBUG packet.
*/
SSH_PACKET_CALLBACK(ssh_packet_ignore_callback){
(void)user;
@@ -405,5 +445,7 @@ SSH_PACKET_CALLBACK(ssh_packet_ignore_callback){
/* TODO: handle a graceful disconnect */
return SSH_PACKET_USED;
}
-/** @} */
+
+/* @} */
+
/* vim: set ts=2 sw=2 et cindent: */