aboutsummaryrefslogtreecommitdiff
path: root/libssh
diff options
context:
space:
mode:
authorAndreas Schneider <mail@cynapses.org>2010-04-04 17:33:06 +0200
committerAndreas Schneider <mail@cynapses.org>2010-04-04 17:37:05 +0200
commite5abc065aa444683524e27040a22ac922b9a76fe (patch)
treee5428831bd3eed372cb82dea6ba37f3790cda6b4 /libssh
parent4ce265b1057521740043400934a72df038775747 (diff)
downloadlibssh-e5abc065aa444683524e27040a22ac922b9a76fe.tar.gz
libssh-e5abc065aa444683524e27040a22ac922b9a76fe.tar.xz
libssh-e5abc065aa444683524e27040a22ac922b9a76fe.zip
Fixed the documentation of the scp functions.
Diffstat (limited to 'libssh')
-rw-r--r--libssh/scp.c255
1 files changed, 161 insertions, 94 deletions
diff --git a/libssh/scp.c b/libssh/scp.c
index 81c32908..52a28091 100644
--- a/libssh/scp.c
+++ b/libssh/scp.c
@@ -26,20 +26,29 @@
#include "libssh/priv.h"
#include "libssh/scp.h"
-/** @defgroup ssh_scp SSH-scp
- * @brief SCP protocol over SSH functions
- * @addtogroup ssh_scp
+
+/**
+ * @defgroup libssh_scp The SSH scp functions
+ * @ingroup libssh
+ *
+ * SCP protocol over SSH functions
+ *
* @{
-*/
+ */
-/** @brief Creates a new scp session
- * @param session the SSH session to use
- * @param mode one of SSH_SCP_WRITE or SSH_SCP_READ, depending if you need to drop files remotely or read them.
- * It is not possible to combine read and write.
- * @param location The directory in which write or read will be done. Any push or pull will be relative
- * to this place
- * @returns NULL if the creation was impossible.
- * @returns a ssh_scp handle if it worked.
+/**
+ * @brief Create a new scp session.
+ *
+ * @param[in] session The SSH session to use.
+ *
+ * @param[in] mode One of SSH_SCP_WRITE or SSH_SCP_READ, depending if you
+ * need to drop files remotely or read them.
+ * It is not possible to combine read and write.
+ *
+ * @param[in] location The directory in which write or read will be done. Any
+ * push or pull will be relative to this place.
+ *
+ * @returns A ssh_scp handle, NULL if the creation was impossible.
*/
ssh_scp ssh_scp_new(ssh_session session, int mode, const char *location){
ssh_scp scp=malloc(sizeof(struct ssh_scp_struct));
@@ -161,13 +170,19 @@ void ssh_scp_free(ssh_scp scp){
SAFE_FREE(scp);
}
-/** @brief creates a directory in a scp in sink mode
- * @param scp the scp handle.
- * @param dirname Name of the directory being created.
- * @param mode Unix permissions for the new directory, e.g. 0755.
- * @returns SSH_OK if the directory was created.
- * @returns SSH_ERROR if an error happened.
- * @see ssh_scp_leave_directory
+/**
+ * @brief Create a directory in a scp in sink mode.
+ *
+ * @param[in] scp The scp handle.
+ *
+ * @param[in] dirname The name of the directory being created.
+ *
+ * @param[in] mode The UNIX permissions for the new directory, e.g. 0755.
+ *
+ * @returns SSH_OK if the directory has been created, SSH_ERROR if
+ * an error occured.
+ *
+ * @see ssh_scp_leave_directory()
*/
int ssh_scp_push_directory(ssh_scp scp, const char *dirname, int mode){
char buffer[1024];
@@ -201,10 +216,12 @@ int ssh_scp_push_directory(ssh_scp scp, const char *dirname, int mode){
}
/**
- * @brief Leaves a directory
- * @returns SSH_OK if the directory was created.
- * @returns SSH_ERROR if an error happened.
- * @see ssh_scp_push_directory
+ * @brief Leave a directory.
+ *
+ * @returns SSH_OK if the directory has been left,SSH_ERROR if an
+ * error occured.
+ *
+ * @see ssh_scp_push_directory()
*/
int ssh_scp_leave_directory(ssh_scp scp){
char buffer[]="E\n";
@@ -230,14 +247,20 @@ int ssh_scp_push_directory(ssh_scp scp, const char *dirname, int mode){
return SSH_OK;
}
-
-/** @brief initializes the sending of a file to a scp in sink mode
- * @param scp the scp handle.
- * @param filename Name of the file being sent. It should not contain any path indicator
- * @param size Exact size in bytes of the file being sent.
- * @param mode Unix permissions for the new file, e.g. 0644
- * @returns SSH_OK if the file is ready to be sent.
- * @returns SSH_ERROR if an error happened.
+/**
+ * @brief Initialize the sending of a file to a scp in sink mode.
+ *
+ * @param[in] scp The scp handle.
+ *
+ * @param[in] filename The name of the file being sent. It should not contain
+ * any path indicator
+ *
+ * @param[in] size Exact size in bytes of the file being sent.
+ *
+ * @param[in] mode The UNIX permissions for the new file, e.g. 0644.
+ *
+ * @returns SSH_OK if the file is ready to be sent, SSH_ERROR if an
+ * error occured.
*/
int ssh_scp_push_file(ssh_scp scp, const char *filename, size_t size, int mode){
char buffer[1024];
@@ -274,12 +297,17 @@ int ssh_scp_push_file(ssh_scp scp, const char *filename, size_t size, int mode){
return SSH_OK;
}
-/** @brief waits for a response of the scp server
+/**
* @internal
- * @param response pointer where the response message must be
- * copied if any. This pointer must then be free'd.
- * @returns the return code.
- * @returns SSH_ERROR a error occured
+ *
+ * @brief Wait for a response of the scp server.
+ *
+ * @param[in] scp The scp handle.
+ *
+ * @param[out] response A pointer where the response message must be copied if
+ * any. This pointer must then be free'd.
+ *
+ * @returns The return code, SSH_ERROR a error occured.
*/
int ssh_scp_response(ssh_scp scp, char **response){
unsigned char code;
@@ -318,12 +346,17 @@ int ssh_scp_response(ssh_scp scp, char **response){
return SSH_ERROR;
}
-/** @brief Write into a remote scp file
- * @param scp the scp handle.
- * @param buffer the buffer to write
- * @param len the number of bytes to write
- * @returns SSH_OK the write was successful
- * @returns SSH_ERROR an error happened while writing
+/**
+ * @brief Write into a remote scp file.
+ *
+ * @param[in] scp The scp handle.
+ *
+ * @param[in] buffer The buffer to write.
+ *
+ * @param[in] len The number of bytes to write.
+ *
+ * @returns SSH_OK if the write was successful, SSH_ERROR an error
+ * occured while writing.
*/
int ssh_scp_write(ssh_scp scp, const void *buffer, size_t len){
int w;
@@ -367,14 +400,18 @@ int ssh_scp_write(ssh_scp scp, const void *buffer, size_t len){
}
/**
- * @brief reads a string on a channel, terminated by '\n'
- * @param scp the scp handle.
- * @param buffer pointer to a buffer to place the string
- * @param len size of the buffer in bytes. If the string is bigger
- * than len-1, only len-1 bytes are read and the string
- * is null-terminated.
- * @returns SSH_OK The string was read
- * @returns SSH_ERROR Error happened while reading
+ * @brief Read a string on a channel, terminated by '\n'
+ *
+ * @param[in] scp The scp handle.
+ *
+ * @param[out] buffer A pointer to a buffer to place the string.
+ *
+ * @param[in] len The size of the buffer in bytes. If the string is bigger
+ * than len-1, only len-1 bytes are read and the string is
+ * null-terminated.
+ *
+ * @returns SSH_OK if the string was read, SSH_ERROR if an error
+ * occured while reading.
*/
int ssh_scp_read_string(ssh_scp scp, char *buffer, size_t len){
size_t r=0;
@@ -399,14 +436,21 @@ int ssh_scp_read_string(ssh_scp scp, char *buffer, size_t len){
return err;
}
-/** @brief waits for a scp request (file, directory)
- * @returns SSH_ERROR Some error happened
- * @returns SSH_SCP_REQUEST_NEWFILE The other side is sending a file
- * @returns SSH_SCP_REQUEST_NEWDIRECTORY The other side is sending a directory
- * @returns SSH_SCP_REQUEST_END_DIRECTORY The other side has finished with the current directory
- * @see ssh_scp_read
- * @see ssh_scp_deny_request
- * @see ssh_scp_accept_request
+/**
+ * @brief Wait for a scp request (file, directory).
+ *
+ * @returns SSH_SCP_REQUEST_NEWFILE: The other side is sending
+ * a file
+ * SSH_SCP_REQUEST_NEWDIRECTORY: The other side is sending
+ * a directory
+ * SSH_SCP_REQUEST_END_DIRECTORY: The other side has
+ * finished with the current
+ * directory
+ * SSH_ERROR: Some error happened
+ *
+ * @see ssh_scp_read()
+ * @see ssh_scp_deny_request()
+ * @see ssh_scp_accept_request()
*/
int ssh_scp_pull_request(ssh_scp scp){
char buffer[4096];
@@ -495,13 +539,15 @@ int ssh_scp_pull_request(ssh_scp scp){
}
/**
- * @brief denies the transfer of a file or creation of a directory
- * coming from the remote party
- * @param scp the scp handle.
- * @param reason nul-terminated string with a human-readable explanation
- * of the deny
- * @returns SSH_OK the message was sent
- * @returns SSH_ERROR Error sending the message, or sending it in a bad state
+ * @brief Deny the transfer of a file or creation of a directory coming from the
+ * remote party.
+ *
+ * @param[in] scp The scp handle.
+ * @param[in] reason A nul-terminated string with a human-readable
+ * explanation of the deny.
+ *
+ * @returns SSH_OK if the message was sent, SSH_ERROR if the sending
+ * the message failed, or sending it in a bad state.
*/
int ssh_scp_deny_request(ssh_scp scp, const char *reason){
char buffer[4096];
@@ -524,11 +570,13 @@ int ssh_scp_deny_request(ssh_scp scp, const char *reason){
}
/**
- * @brief accepts transfer of a file or creation of a directory
- * coming from the remote party
- * @param scp the scp handle.
- * @returns SSH_OK the message was sent
- * @returns SSH_ERROR Error sending the message, or sending it in a bad state
+ * @brief Accepts transfer of a file or creation of a directory coming from the
+ * remote party.
+ *
+ * @param[in] scp The scp handle.
+ *
+ * @returns SSH_OK if the message was sent, SSH_ERROR if sending the
+ * message failed, or sending it in a bad state.
*/
int ssh_scp_accept_request(ssh_scp scp){
char buffer[]={0x00};
@@ -551,11 +599,14 @@ int ssh_scp_accept_request(ssh_scp scp){
}
/** @brief Read from a remote scp file
- * @param scp the scp handle.
- * @param buffer Destination buffer
- * @param size Size of the buffer
- * @returns Number of bytes read
- * @returns SSH_ERROR An error happened while reading
+ * @param[in] scp The scp handle.
+ *
+ * @param[in] buffer The destination buffer.
+ *
+ * @param[in] size The size of the buffer.
+ *
+ * @returns The nNumber of bytes read, SSH_ERROR if an error occured
+ * while reading.
*/
int ssh_scp_read(ssh_scp scp, void *buffer, size_t size){
int r;
@@ -601,9 +652,12 @@ int ssh_scp_read(ssh_scp scp, void *buffer, size_t size){
return r;
}
-/** @brief Gets the name of the directory or file being
- * pushed from the other party
- * @returns file name. Should not be freed.
+/**
+ * @brief Get the name of the directory or file being pushed from the other
+ * party.
+ *
+ * @returns The file name, NULL on error. The string should not be
+ * freed.
*/
const char *ssh_scp_request_get_filename(ssh_scp scp){
if(scp==NULL)
@@ -611,9 +665,11 @@ const char *ssh_scp_request_get_filename(ssh_scp scp){
return scp->request_name;
}
-/**@brief Gets the permissions of the directory or file being
- * pushed from the other party
- * @returns Unix permission, e.g 0644.
+/**
+ * @brief Get the permissions of the directory or file being pushed from the
+ * other party.
+ *
+ * @returns The UNIX permission, e.g 0644, -1 on error.
*/
int ssh_scp_request_get_permissions(ssh_scp scp){
if(scp==NULL)
@@ -621,9 +677,9 @@ int ssh_scp_request_get_permissions(ssh_scp scp){
return scp->request_mode;
}
-/** @brief Gets the size of the file being pushed
- * from the other party
- * @returns Numeric size of the file being read.
+/** @brief Get the size of the file being pushed from the other party.
+ *
+ * @returns The numeric size of the file being read.
*/
size_t ssh_scp_request_get_size(ssh_scp scp){
if(scp==NULL)
@@ -631,19 +687,25 @@ size_t ssh_scp_request_get_size(ssh_scp scp){
return scp->filelen;
}
-/** @brief Converts a scp text mode to an integer one
- * @param mode mode to convert, e.g. "0644"
- * @returns integer value, e.g. 420 for "0644"
+/**
+ * @brief Convert a scp text mode to an integer.
+ *
+ * @param[in] mode The mode to convert, e.g. "0644".
+ *
+ * @returns An integer value, e.g. 420 for "0644".
*/
int ssh_scp_integer_mode(const char *mode){
int value=strtoul(mode,NULL,8) & 0xffff;
return value;
}
-/** @brief Converts a unix mode into a scp string one.
- * @param mode mode to convert, e.g. 420 or 0644
- * @returns pointer to a malloc'ed string containing the scp mode,
- * e.g. "0644".
+/**
+ * @brief Convert a unix mode into a scp string.
+ *
+ * @param[in] mode The mode to convert, e.g. 420 or 0644.
+ *
+ * @returns A pointer to a malloc'ed string containing the scp mode,
+ * e.g. "0644".
*/
char *ssh_scp_string_mode(int mode){
char buffer[16];
@@ -651,10 +713,14 @@ char *ssh_scp_string_mode(int mode){
return strdup(buffer);
}
-/** @brief Gets the warning string
- * @returns Warning string. Should not be freed.
+/**
+ * @brief Get the warning string from a scp handle.
+ *
+ * @param[in] scp The scp handle.
+ *
+ * @returns A warning string, or NULL on error. The string should
+ * not be freed.
*/
-
const char *ssh_scp_request_get_warning(ssh_scp scp){
if(scp==NULL)
return NULL;
@@ -663,3 +729,4 @@ const char *ssh_scp_request_get_warning(ssh_scp scp){
/** @} */
+/* vim: set ts=4 sw=4 et cindent: */