Added commented/documented version of libsmbclient.h and fixed up a small

problem in libsmbclient.c where we no longer pass the workgroup.
(This used to be commit 3c6611434601a45ba448f0313397104c7cea616c)

1 files changed, 692 insertions, 160 deletions

diff --git a/source3/include/libsmbclient.h b/source3/include/libsmbclient.h
index fe383e845a..5440c690b8 100644
--- a/source3/include/libsmbclient.h
+++ b/source3/include/libsmbclient.h
@@ -1,4 +1,4 @@
-/* 
+/*=====================================================================
    Unix SMB/Netbios implementation.
    Version 2.0
    SMB client library API definitions
@@ -19,214 +19,746 @@
    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-*/
+=====================================================================*/
 
-#ifndef _SMBCLIENT_H
-#define _SMBCLIENT_H
+#ifndef SMBCLIENT_H_INCLUDED
+#define SMBCLIENT_H_INCLUDED
 
-/* Make sure we have the following includes for now ... */
+/*-------------------------------------------------------------------*/
+/* The following are special comments to instruct DOXYGEN (automated 
+ * documentation tool:
+*/
+/** \defgroup structure Data Structures Type and Constants
+*   Data structures, types, and constants
+*/
+/** \defgroup file File Functions
+*   Functions used to access individual file contents
+*/
+/** \defgroup directory Directory Functions
+*   Functions used to access directory entries
+*/
+/** \defgroup attribute Attributes Functions
+*   Functions used to view or change file and directory attributes
+*/
+/** \defgroup print Print Functions
+*   Functions used to access printing functionality
+*/
+/** \defgroup attribute Miscellaneous Functions
+*   Functions that don't fit in to other categories
+*/
+/*-------------------------------------------------------------------*/   
 
+/* Make sure we have the following includes for now ... */
 #include <sys/types.h>
 #include <sys/stat.h>
 #include <fcntl.h>
 
-#define SMBC_MAX_NAME 1023
-
-struct smbc_dirent {
-
-  uint smbc_type;  /* Type of entity, see below */
-  uint dirlen;     /* Convenience               */
-  uint namelen;
-  uint commentlen;
-  char *comment;   /* Points to the comment futher down */
-  char name[1];
-
-};
-
-#ifndef _CLIENT_H
-typedef unsigned short uint16;
-struct print_job_info {
-  uint16 id;
-  uint16 priority;
-  size_t size;
-  char user[128];
-  char name[128];
-  time_t t;
-};
-#endif
-
-/*
- * Entity types
- */
-#define SMBC_WORKGROUP     1
-#define SMBC_SERVER        2
-#define SMBC_FILE_SHARE    3
-#define SMBC_PRINTER_SHARE 4
-#define SMBC_COMMS_SHARE   5
-#define SMBC_IPC_SHARE     6
-#define SMBC_DIR           7
-#define SMBC_FILE          8
-#define SMBC_LINK          9
+#define SMBC_MAX_NAME       1023
+#define SMBC_WORKGROUP      1
+#define SMBC_SERVER         2
+#define SMBC_FILE_SHARE     3
+#define SMBC_PRINTER_SHARE  4
+#define SMBC_COMMS_SHARE    5
+#define SMBC_IPC_SHARE      6
+#define SMBC_DIR            7
+#define SMBC_FILE           8
+#define SMBC_LINK           9
 
 #define SMBC_FILE_MODE (S_IFREG | 0444)
 #define SMBC_DIR_MODE  (S_IFDIR | 0555)
 
-typedef void (*smbc_get_auth_data_fn)(char *server, char *share,
-				      char *workgroup, int wgmaxlen, 
-				      char *username, int unmaxlen,
-				      char *password, int pwmaxlen);
-
-/*
- * Init the smbc package
- */
-int smbc_init(smbc_get_auth_data_fn fn, const char *workgroup, int debug);
-
-/*
- * Open a file on an SMB server, this has the same form as normal open
- * but the fname is a URL of the form smb://server/share/path
- */
-
-int smbc_open(const char *fname, int flags, mode_t mode);
-
-/*
- * Create a file on an SMB server, similar to smbc_open
- */
-
-int smbc_creat(const char *fname, mode_t mode);
-
-/*
- * Read from a file, what about pread?
- */
-
-ssize_t smbc_read(int fd, void *buf, size_t count);
-
-/* 
- * Write to a file, what about pwrite?
- */
-
-ssize_t smbc_write(int fd, void *buf, size_t count);
+/**@ingroup structure
+ * Structure that represents a directory entry.
+ *
+*/
+struct smbc_dirent 
+{
+    /** Type of entity.
+    SMBC_WORKGROUP=1,
+    SMBC_SERVER=2, 
+    SMBC_FILE_SHARE=3,
+    SMBC_PRINTER_SHARE=4,
+    SMBC_COMMS_SHARE=5,
+    SMBC_IPC_SHARE=6,
+    SMBC_DIR=7,
+    SMBC_FILE=8,
+    SMBC_LINK=9,*/ 
+    uint smbc_type; 
+
+    /** Length of this smbc_dirent in bytes
+     */
+    uint dirlen;
+    /** The length of the comment string in bytes (includes null 
+     *  terminator)
+     */
+    uint commentlen;
+    /** Points to the null terminated comment string 
+     */
+    char *comment;
+    /** The length of the name string in bytes (includes null 
+     *  terminator)
+     */
+    uint namelen;
+    /** Points to the null terminated name string 
+     */
+    char name[1];
+};
 
-/*
- * Close a file by fd
- */
 
-int smbc_close(int fd);
+#ifndef _CLIENT_H
+typedef unsigned short uint16;
 
-/*
- * Unlink a file on server, share, dir, file ...
+/**@ingroup structure
+ * Structure that represents a print job.
+ *
+ * @todo    Make sure the discriptions of structure members are correct.
  */
+struct print_job_info 
+{
+    /** numeric ID of the print job
+     */
+    uint16 id;
+    
+    /** represents print job priority (lower numbers mean higher priority?)
+     */
+    uint16 priority;
+    
+    /** Size of the print job
+     */
+    size_t size;
+    
+    /** Name of the user that owns the print job
+     */
+    char user[128];
+  
+    /** Name of the print job
+     */
+    char name[128];
+
+    /** Time the print job was spooled?
+    */
+    time_t t;
+};
+#endif
 
-int smbc_unlink(const char *fname);
 
-/*
- * rename oname to nname ... probably need to be on the same
- * server initially. Later can copy between servers ...
+/**@ingroup structure
+ * Authentication callback function type.
+ * 
+ * Type for the the authentication function called by the library to
+ * obtain authentication credentals
+ *
+ * @param srv       Server being authenticated to
+ *
+ * @param shr       Share being authenticated to
+ *
+ * @param wg        Pointer to buffer containing a "hint" for the
+ *                  workgroup to be authenticated.  Should be filled
+ *                  with the correct workgroup if the hint is wrong.
+ * 
+ * @param wglen     The size of the workgroup buffer in bytes
+ *
+ * @param un        Pointer to buffer containing a "hint" for the
+ *                  user name to be use for authentication. Should be
+ *                  filled with the correct workgroup if the hint is
+ *                  wrong.
+ * 
+ * @param unlen     The size of the username buffer in bytes
+ *
+ * @param pw        Pointer to buffer containing to which password 
+ *                  copied
+ * 
+ * @param pwlen     The size of the password buffer in bytes
+ *           
  */
-
-int smbc_rename(const char *oname, const char *nname);
-
-/*
- * Seek to a specific location in a file on an SMB server 
+typedef void (*smbc_get_auth_data_fn)(const char *srv, 
+                                      const char *shr,
+                                      char *wg, int wglen, 
+                                      char *un, int unlen,
+                                      char *pw, int pwlen);
+
+
+/**@ingroup structure
+ * Print job info callback function type.
+ *
+ * @param i         pointer to print job information structure
+ *
+ */ 
+typedef void (*smbc_get_print_job_info)(struct print_job_info *i);
+
+
+/**@ingroup misc
+ * Initialize the samba client library.
+ *
+ * Must be called before using any of the smbclient API function
+ *  
+ * @param fn        The function that will be called to obtaion 
+ *                  authentication credentials.
+ *
+ * @param debug     Allows caller to set the debug level. Can be
+ *                  changed in smb.conf file.
+ *   
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - ENOMEM Out of memory
+ *
+ * @todo Why do we need to pass in debug information?
  */
-
+int smbc_init(smbc_get_auth_data_fn fn, int debug);
+
+
+/**@ingroup file
+ * Open a file on an SMB server.
+ *
+ * @param furl      The smb url of the file to be opened. 
+ *
+ * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which 
+ *                  request opening  the  file  read-only,write-only
+ *                  or read/write. flags may also be bitwise-or'd with
+ *                  one or  more of  the following: 
+ *                  O_CREAT - If the file does not exist it will be 
+ *                  created.
+ *                  O_EXCL - When  used with O_CREAT, if the file 
+ *                  already exists it is an error and the open will 
+ *                  fail. 
+ *                  O_TRUNC - If the file already exists it will be
+ *                  truncated.
+ *                  O_APPEND The  file  is  opened  in  append mode 
+ *
+ * @param mode      mode specifies the permissions to use if a new 
+ *                  file is created.  It  is  modified  by  the 
+ *                  process's umask in the usual way: the permissions
+ *                  of the created file are (mode & ~umask) 
+ *
+ *                  Not currently use, but there for future use
+ *                  when we figure this out.
+ *
+ * @return          Valid file handle, < 0 on error with errno set:
+ *                  - ENOMEM  Out of memory
+ *                  - EEXIST  pathname already exists and O_CREAT and 
+ *                  O_EXCL were used.
+ *                  - EISDIR  pathname  refers  to  a  directory  and  
+ *                  the access requested involved writing.
+ *                  - EACCES  The requested access to the file is not 
+ *                  allowed 
+ *                  - ENOENT  A directory component in pathname does 
+ *                  not exist.
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @see             smbc_creat()
+ *
+ * @todo Mode needs to be better explained if there is any differences
+ *       from standard open().
+ *
+ * @todo Are errno values complete and correct? They look OK.
+ *
+*/
+int smbc_open(const char *furl, int flags, mode_t mode);
+
+
+/**@ingroup file
+ * Create a file on an SMB server.
+ *
+ * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC 
+ *   
+ * @param furl      The smb url of the file to be created
+ *  
+ * @param mode      mode specifies the permissions to use if  a  new  
+ *                  file is created.  It  is  modified  by  the 
+ *                  process's umask in the usual way: the permissions
+ *                  of the created file are (mode & ~umask)
+ *      
+ * @return          Valid file handle, < 0 on error with errno set:
+ *                  - ENOMEM  Out of memory
+ *                  - EEXIST  pathname already exists and O_CREAT and
+ *                  O_EXCL were used.
+ *                  - EISDIR  pathname  refers  to  a  directory  and
+ *                  the access requested involved writing.
+ *                  - EACCES  The requested access to the file is not
+ *                  allowed 
+ *                  - ENOENT  A directory component in pathname does 
+ *                  not exist.
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ * @see             smbc_open()
+ *
+ * @todo Are errno values complete and correct?
+*/
+int smbc_creat(const char *furl, mode_t mode);
+
+
+/**@ingroup file
+ * Read from a file using an opened file handle.
+ *
+ * @param fd        Open file handle from smbc_open() or smbc_creat()
+ *
+ * @param buf       Pointer to buffer to recieve read data
+ *
+ * @param bufsize   Size of buf in bytes
+ *
+ * @return          Number of bytes read, < 0 on error with errno set:
+ *                  - EISDIR fd refers to a directory
+ *                  - EBADF  fd  is  not  a valid file descriptor or 
+ *                  is not open for reading.
+ *                  - EINVAL fd is attached to an object which is 
+ *                  unsuitable for reading.
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @see             smbc_open(), smbc_write()
+ *
+ * @todo Are errno values complete and correct?
+*/
+ssize_t smbc_read(int fd, void *buf, size_t bufsize);
+
+
+/**@ingroup file
+ * Write to a file using an opened file handle.
+ *
+ * @param fd        Open file handle from smbc_open() or smbc_creat()
+ *
+ * @param buf       Pointer to buffer to recieve read data
+ *
+ * @param bufsize   Size of buf in bytes
+ *
+ * @return          Number of bytes written, < 0 on error with errno set:
+ *                  - EISDIR fd refers to a directory.
+ *                  - EBADF  fd  is  not  a valid file descriptor or 
+ *                  is not open for reading.
+ *                  - EINVAL fd is attached to an object which is 
+ *                  unsuitable for reading.
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ * @see             smbc_open(), smbc_read()
+ *
+ * @todo Are errno values complete and correct?
+*/
+ssize_t smbc_write(int fd, void *buf, size_t bufsize);
+
+
+/**@ingroup file
+ * Seek to a specific location in a file.
+ *
+ * @param fd        Open file handle from smbc_open() or smbc_creat()
+ * 
+ * @param offset    Offset in bytes from whence
+ * 
+ * @param whence    A location in the file:
+ *                  - SEEK_SET The offset is set to offset bytes from
+ *                  the beginning of the file
+ *                  - SEEK_CUR The offset is set to current location 
+ *                  plus offset bytes.
+ *                  - SEEK_END The offset is set to the size of the 
+ *                  file plus offset bytes.
+ *
+ * @return          Upon successful completion, lseek returns the 
+ *                  resulting offset location as measured in bytes 
+ *                  from the beginning  of the file. Otherwise, a value
+ *                  of (off_t)-1 is returned and errno is set to 
+ *                  indicate the error:
+ *                  - EBADF  Fildes is not an open file descriptor.
+ *                  - EINVAL Whence is not a proper value.  
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @todo Are all the whence values really supported?
+ * 
+ * @todo Are errno values complete and correct?
+*/
 off_t smbc_lseek(int fd, off_t offset, int whence);
 
-/*
- * Stat a file to get info via file name
- */
-
-int smbc_stat(const char *fname, struct stat *st);
-
-/*
- * Stat a file to get info via an fd
- */
-
-int smbc_fstat(int fd, struct stat *st);
-
-/* 
- * Chown a file 
- */
-
-int smbc_chown(const char *fname, uid_t owner, gid_t group);
 
-/*
- * Chmod a file
- */
-
-int smbc_chmod(const char *fname, mode_t newmode);
-
-/*
- * Open a directory on a URL (server and share and dir)
- */
+/**@ingroup file
+ * Close an open file handle.
+ *
+ * @param fd        The file handle to close
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EBADF  fd isn't a valid open file descriptor
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @see             smbc_open(), smbc_creat()
+*/
+int smbc_close(int fd);
 
-int smbc_opendir(const char *fname);
 
-/*
- * Close a directory
+/**@ingroup directory
+ * Unlink (delete) a file or directory.
+ *
+ * @param furl      The smb url of the file to delete
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EACCES or EPERM Write  access  to the directory 
+ *                  containing pathname is not allowed or one  
+ *                  of  the  directories in pathname did not allow
+ *                  search (execute) permission
+ *                  - ENOENT A directory component in pathname does
+ *                  not exist
+ *                  - ENOMEM Insufficient kernel memory was availabl
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @see             smbc_rmdir()s
+ *
+ * @todo Are errno values complete and correct?
+*/
+int smbc_unlink(const char *furl);
+
+
+/**@ingroup directory
+ * Rename or move a file or directory.
+ * 
+ * @param ourl      The original smb url (source url) of file or 
+ *                  directory to be moved
+ * 
+ * @param nurl      The new smb url (destination url) of the file
+ *                  or directory after the move.  Currently nurl must
+ *                  be on the same share as ourl.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EISDIR nurl is an existing directory, but ourl is
+ *                  not a directory.
+ *                  - EEXIST nurl is  a  non-empty directory, 
+ *                  i.e., contains entries other than "." and ".."
+ *                  - EINVAL The  new  url  contained  a path prefix 
+ *                  of the old, or, more generally, an  attempt was
+ *                  made  to make a directory a subdirectory of itself.
+ *                  - ENOTDIR A component used as a directory in ourl 
+ *                  or nurl path is not, in fact, a directory.  Or, 
+ *                  ourl  is a directory, and newpath exists but is not
+ *                  a directory.
+ *                  - EACCES or EPERM Write access to the directory 
+ *                  containing ourl or nurl is not allowed for the 
+ *                  process's effective uid,  or  one of the 
+ *                  directories in ourl or nurl did not allow search
+ *                  (execute) permission,  or ourl  was  a  directory
+ *                  and did not allow write permission.
+ *                  - ENOENT A  directory component in ourl or nurl 
+ *                  does not exist.
+ *                  - ENOMEM Insufficient kernel memory was available.
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @todo Are errno values complete and correct?
+ *
+ * @todo Are we going to support copying when urls are not on the same
+ *       share?  I say no...
+ *
+*/
+int smbc_rename(const char *ourl, const char *nurl);
+
+
+/**@ingroup directory
+ * Open a directory used to obtain directory entries.
+ *
+ * @param durl      The smb url of the directory to open
+ *
+ * @return          Valid directory handle. < 0 on error with errno set:
+ *                  - EACCES Permission denied.
+ *                  - ENOENT durl does not exist, or name is an 
+ *                  - ENOMEM Insufficient memory to complete the 
+ *                  operation.                              
+ *                  - ENOTDIR name is not a directory.
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
+ *
+ * @todo Are errno values complete and correct?
+*/
+int smbc_opendir(const char *durl);
+
+
+/**@ingroup directory
+ * Close a directory handle opened by smbc_opendir().
+ *
+ * @param dh        Directory handle to close
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EBADF dh is an invalid directory handle
+ *
+ * @see             smbc_opendir()
+*/
+int smbc_closedir(int dh);
+
+
+/**@ingroup directory
+ * Get multiple directory entries.
+ *
+ * smbc_getdents() reads several dirent structures from the an open 
+ * directory handle into a specified memory area.
+ *
+ * @param dh        Valid directory as returned by smbc_opendir()
+ *
+ * @param dirp      pointer to buffer that will receive the directory
+ *                  entries.
+ * 
+ * @param count     The size of the dirp buffer in bytes
+ *
+ * @returns         - EBADF  Invalid directory handle
+ *                  - EINVAL Result buffer is too small
+ *                  - ENOENT No such directory.
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ * @see             , smbc_dirent, smbc_readdir(), smbc_open()
+ *
+ * @todo Are errno values complete and correct?
+ *
+ * @todo Add example code so people know how to parse buffers.
  */
-
-int smbc_closedir(int fd);
-
-/* 
- * Get a directory entry
+int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
+
+
+/**@ingroup directory
+ * Get a single directory entry.
+ *
+ * @param dh        Valid directory as returned by smbc_opendir()
+ *
+ * @return          A pointer to a smbc_dirent structure, or NULL if an
+ *                  error occurs or end-of-directory is reached:
+ *                  - EBADF Invalid directory handle
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @see             smbc_dirent, smbc_getdents(), smbc_open()
+*/
+struct smbc_dirent* smbc_readdir(unsigned int dh);
+
+
+/**@ingroup directory
+ * Get the current directory offset.
+ *
+ * smbc_telldir() may be used in conjunction with smbc_readdir() and
+ * smbc_lseekdir().
+ *
+ * @param dh        Valid directory as returned by smbc_opendir()
+ *
+ * @return          The current location in the directory stream or -1
+ *                  if an error occur.
+ *                  - EBADF dh is not a valid directory handle
+ *
+ * @see             smbc_readdir()
+ *
+ * @todo What in the is the offset related to bytes or directory entry
+ *       number?
+*/
+off_t smbc_telldir(int dh);
+
+
+/**@ingroup directory
+ * lseek on directories.
+ *
+ * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
+ * smbc_telldir(). (rewind by smbc_lseekdir(fd, 0, SEEK_SET))
+ *
+ * @param dh        Valid directory as returned by smbc_opendir()
+ * 
+ * @param offset    The offset (as returned by smbc_telldir) from
+ *                  whence
+ *
+ * @param whence    A location in the directory stream:
+ *                  - SEEK_SET this is the only one that makes sense...
+ *                  - SEEK_CUR ???
+ *                  - SEEK_END ???
+ *
+ * @return          I have no idea?
+ *
+ * @see             smbc_telldir()
+ *
+ * @todo What in the is the offset related to?  Bytes or directory 
+ *       entry number?
+ *
+ * @todo In what do SEEK_SET and friends really mean?
+ *
+ * @todo In what does the reture and errno values mean?
  */
-
-int smbc_getdents(unsigned int fd, struct smbc_dirent *dirp, int count);
-
-/*
- * Read a dirent in the old way
+int smbc_lseekdir(int dh, off_t offset, int whence);
+
+
+/**@ingroup directory
+ * Create a directory.
+ *
+ * @param durl      The url of the directory to create
+ *
+ * @param mode      Specifies  the  permissions to use. It is modified
+ *                  by the process's umask in the usual way: the 
+ *                  permissions of the created file are (mode & ~umask).
+ * 
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EEXIST directory url already exists
+ *                  - EACCES The parent directory does not allow write
+ *                  permission to the process, or one of the directories
+ *                  - ENOENT A directory component in pathname does not
+ *                  exist.
+ *                  - ENOMEM Insufficient memory was available.
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @see             smbc_rmdir()
+ *
+ * @todo Are errno values complete and correct?
+*/
+int smbc_mkdir(const char *durl, mode_t mode);
+
+
+/**@ingroup directory
+ * Remove a directory.
+ * 
+ * @param durl      The smb url of the directory to remove
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EACCES or EPERM Write access to the directory
+ *                  containing pathname was not allowed.
+ *                  - ENOENT A directory component in pathname does not
+ *                  exist.
+ *                  - ENOTEMPTY directory contains entries.
+ *                  - ENOMEM Insufficient kernel memory was available.
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @see             smbc_mkdir(), smbc_unlink() 
+ *
+ * @todo Are errno values complete and correct?
  */
-
-struct smbc_dirent *smbc_readdir(unsigned int fd);
-
-/* 
- * Create a directory on a server, share, dir in fname URL
+int smbc_rmdir(const char *durl);
+
+
+/**@ingroup attribute
+ * Get information about a file or directory.
+ *
+ * @param url       The smb url to get information for
+ *
+ * @param st        pointer to a buffer that will be filled with 
+ *                  standard Unix struct stat information.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - ENOENT A component of the path file_name does not
+ *                  exist.
+ *                  - EACCES Permission denied.
+ *                  - ENOMEM Out of memory
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @see             Unix stat()
+ *
+ * @todo Are errno values complete and correct?
  */
-
-int smbc_mkdir(const char *fname, mode_t mode);
-
-/*
- * Remove a directory on a server
+int smbc_stat(const char *url, struct stat *st);
+
+
+/**@ingroup attribute
+ * Get file information via an file descriptor.
+ * 
+ * @param fd        Open file handle from smbc_open() or smbc_creat()
+ *
+ * @param st        pointer to a buffer that will be filled with 
+ *                  standard Unix struct stat information.
+ * 
+ * @return          EBADF  filedes is bad.
+ *                  -EACCES Permission denied.
+ *                  -ENOMEM Out of memory
+ *                  - EUCLEAN smbc_init() failed or has not been called
+ *
+ * @see             smbc_stat(), Unix stat()
  */
+int smbc_fstat(int fd, struct stat *st);
 
-int smbc_rmdir(const char *fname);
 
-/*
- * Get the current directory offset
+/**@ingroup attribue
+ * Change the ownership of a file or directory.
+ *
+ * @param url       The smb url of the file or directory to change 
+ *                  ownership of.
+ *
+ * @param owner     I have no idea?
+ *
+ * @param group     I have not idea?
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EPERM  The effective UID does not match the owner
+ *                  of the file, and is not zero; or the owner or group
+ *                  were specified incorrectly.
+ *                  - ENOENT The file does not exist.
+ *                  - ENOMEM Insufficient was available.
+ *                  - ENOENT file or directory does not exist
+ *
+ * @todo Are we actually going to be able to implement this function
+ *
+ * @todo How do we abstract owner and group uid and gid?
+ *
  */
-
-off_t smbc_telldir(int fd);
-
-/* 
- * lseek on directories, rewind by smbc_lseekdir(fd, 0, SEEK_SET)
+int smbc_chown(const char *url, uid_t owner, gid_t group);
+
+
+/**@ingroup attribute
+ * Change the permissions of a file.
+ *
+ * @param url       The smb url of the file or directory to change
+ *                  permissions of
+ * 
+ * @param mode      The permissions to set:
+ *                  - Put good explaination of permissions here!
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EPERM  The effective UID does not match the owner
+ *                  of the file, and is not zero
+ *                  - ENOENT The file does not exist.
+ *                  - ENOMEM Insufficient was available.
+ *                  - ENOENT file or directory does not exist
+ *
+ * @todo Actually implement this fuction?
+ *
+ * @todo Are errno values complete and correct?
  */
+int smbc_chmod(const char *url, mode_t mode);
 
-int smbc_lseekdir(int fd, off_t offset, int whence);
 
-/* 
+/**@ingroup print
  * Print a file given the name in fname. It would be a URL ...
- */
-
+ * 
+ * @param fname     I do not know what this is it the url of the file 
+ *                  to print?
+ *
+ * @param printq    I do not know what this is, is it the url of the
+ *                  printer to print to?
+ *
+  * @return          0 on success, < 0 on error with errno set:         
+ *
+ * @todo I have no idea what this does.  What is fname?  What is 
+ *       printq?
+ *
+ * @todo What errno values are possible here
+ */                                     
 int smbc_print_file(const char *fname, const char *printq);
 
-/* 
+/**@ingroup print
  * Open a print file that can be written to by other calls. This simply
  * does an smbc_open call after checking if there is a file name on the
  * URI. If not, a temporary name is added ...
+ *
+ * @param fname     Is this the url of a print share?
+ *
+ * @returns         A file handle right?
+ *
+ * @todo    What errno values are possible here
+ *
+ * @todo    What is fname is it the url of a print share?
  */
-
 int smbc_open_print_job(const char *fname);
 
-/*
+/**@ingroup print
  * List the print jobs on a print share, for the moment, pass a callback 
+ *
+ * @param purl      The url of the print share to list the jobs of
+ * 
+ * @param fn        Callback function the receives printjob info
+ * 
+ * @return          0 on success, < 0 on error with errno set: 
+ *
+ * @todo    what errno values are possible here?
  */
 
-int smbc_list_print_jobs(const char *fname, void (*fn)(struct print_job_info *));
+int smbc_list_print_jobs(const char *purl, smbc_get_print_job_info fn);
 
-/* 
+/**@ingroup print
  * Delete a print job 
+ *
+ * @param purl      Url of the print share
+ *
+ * @param id        The id of the job to delete
+ *
+ * @return          0 on success, < 0 on error with errno set: 
+ *
+ * @todo    what errno values are possible here?
  */
+int smbc_unlink_print_job(const char *purl, int id);
 
-int smbc_unlink_print_job(const char *fname, int id);
 
-#endif
+#endif /* SMBCLIENT_H_INCLUDED */