Documents smb_trans2 functions. Adds stat_t opaque types definitions

include/bdsm/netbios_ns.h

@@ -143,7 +143,7 @@ int             netbios_ns_entry_count(netbios_ns_t *ns);
  * creation of the name service object or the last call to clear
  *
  * @param ns The nameservice object.
- * @param post The index/position of the item to access in the list. Must be <
+ * @param pos The index/position of the item to access in the list. Must be <
  * netbios_ns_entry_count(ns) or the pointer returned will be NULL.
  * @return A pointer to a opaque netbios_ns_entry_t structure
  */

include/bdsm/smb_file.h

@@ -16,11 +16,21 @@
 // published by Sam Hocevar. See the COPYING file for more details.
 //----------------------------------------------------------------------------
 
+/**
+ * @file smb_file.h
+ * @brief File operations
+ */
+
 #ifndef __BDSM_SMB_FILE_H_
 #define __BDSM_SMB_FILE_H_
 
 #include "bdsm/smb_session.h"
 
+/// Set the read pointer at the given position
+#define SMB_SEEK_SET 0
+/// Adjusts the read pointer relatively to the actual position
+#define SMB_SEEK_CUR 1
+
 /**
  * @brief Open a file on a share.
  * @details Use this function to obtain an smb_fd, necesary for file operations
@@ -28,7 +38,7 @@
  * @param s The session object
  * @param tid The tid of the share the file is in, obtained via smb_tree_connect()
  * @param path The path of the file to open
- * @param mod The access modes requested (example: SMB_MOD_RO)
+ * @param mod The access modes requested (example: #SMB_MOD_RO)
  * @return A smb file description that can be use for further file operations
  * or 0 in case of error
  *
@@ -36,8 +46,50 @@
  */
 smb_fd    smb_fopen(smb_session_t *s, smb_tid tid, const char *path,
                     uint32_t mod);
-void      smb_fclose(smb_session_t *s, smb_fd);
+
+/**
+ * @brief Close an open file
+ * @details The smb_fd is invalidated and MUST not be use it anymore. You can
+ * give it the 0 value.
+ *
+ * @param s The session object
+ * @param fd The SMB file descriptor
+ */
+void      smb_fclose(smb_session_t *s, smb_fd fd);
+
+/**
+ * @brief Read from an open file
+ * @details The semantics is basically the same that the unix read() one.
+ * At most 'buf_size' bytes are read from the current seek offset and copied into
+ * the memory pointed by 'buf' from the open file represented by the smb file
+ * descriptor 'fd'.
+ *
+ * @param[in] s The session object
+ * @param[in] fd [description]
+ * @param[out] buf [description]
+ * @param[in] buf_size [description]
+ * @return The number of bytes read or -1 in case of error.
+ */
 ssize_t   smb_fread(smb_session_t *s, smb_fd fd, void *buf, size_t buf_size);
+
+/**
+ * @brief Sets/Moves/Get the read pointer for a given file
+ * @details The behavior of this function is the same as the Unix fseek()
+ * function, except the SEEK_END argument isn't supported.
+ *
+ * This functions adjust the read the read pointer depending on the value of
+ * offset and whence.
+ *
+ * - If whence == #SMB_SEEK_SET, the read pointer is set at 'offset'
+ * - If whence == #SMB_SEEK_CUR, the read pointer is adjusted by 'offset'
+ *
+ * @param s The session object
+ * @param fd The file descriptors for which the read pointer is to be adjusted
+ * @param offset Set/Adjust quantity
+ * @param whence Which action to perform. Supported operations are
+ * #SMB_SEEK_SET and #SMB_SEEK_CUR
+ * @return The current read pointer position
+ */
 ssize_t   smb_fseek(smb_session_t *s, smb_fd fd, ssize_t offset, int whence);
 
 #endif

include/bdsm/smb_trans2.h

@@ -16,13 +16,53 @@
 // published by Sam Hocevar. See the COPYING file for more details.
 //----------------------------------------------------------------------------
 
+/**
+ * @file smb_trans2.h
+ * @brief SMB transactions operations: find(i.e. ls), stat
+ */
+
 #ifndef __BDSM_SMB_TRANS2_H_
 #define __BDSM_SMB_TRANS2_H_
 
 #include "bdsm/smb_defs.h"
 #include "bdsm/smb_session.h"
 
-smb_file_t  *smb_find(smb_session_t *s, smb_tid tid, const char *pattern);
-smb_file_t  *smb_stat(smb_session_t *s, smb_tid tid, const char *path);
+/**
+ * @struct smb_stat_list_t
+ * @brief An opaque structure containing a list of file status
+ */
+typedef smb_file_t *smb_stat_list_t;
+
+/**
+ * @struct smb_stat_t
+ * @brief An opaque structure containing info about a file
+ */
+typedef smb_file_t *smb_stat_t;
+
+/**
+ * @brief Returns infos about files matching a pattern
+ * @details This functions uses the FIND_FIRST2 SMB operations to list files
+ * matching a certain pattern. It's basically used to list folder contents
+ *
+ * @param s The session object
+ * @param tid The share inside of which we want to find files obtained by
+ * smb_tree_connect()
+ * @param pattern The pattern to match files. '\\*' will list all the files at
+ * the root of the share. '\\afolder\\*' will list all the files inside of the
+ * 'afolder' directory.
+ * @return A list of stat opaque object containing file status
+ */
+smb_stat_list_t   smb_find(smb_session_t *s, smb_tid tid, const char *pattern);
+
+/**
+ * @brief Get the status of a file from it's path inside of a share
+ *
+ * @param s The session object
+ * @param tid The tree id of a share obtained by smb_tree_connect()
+ * @param path The full path of the file relative to the root of the share
+ * (e.g. '\\folder\\file.ext')
+ * @return An opaque smb_stat_t file representing a file status (informations)
+ */
+smb_stat_t        smb_stat(smb_session_t *s, smb_tid tid, const char *path);
 
 #endif

src/smb_file.c

@@ -188,9 +188,9 @@ ssize_t   smb_fseek(smb_session_t *s, smb_fd fd, ssize_t offset, int whence)
   if (!fd || (file = smb_session_file_get(s, fd)) == NULL)
     return(0);
 
-  if (whence == SEEK_SET)
+  if (whence == SMB_SEEK_SET)
     file->readp = offset;
-  else if (whence == SEEK_CUR)
+  else if (whence == SMB_SEEK_CUR)
     file->readp += offset;
 
   return (file->readp);