This commit was generated by cvs2svn to compensate for changes in r30,

which included commits to RCS files with non-trunk default branches.
(This used to be commit 3a69cffb062d4f1238b8cae10481c1f2ea4d3d8b)

1 files changed, 1073 insertions, 0 deletions

diff --git a/source4/include/libsmbclient.h b/source4/include/libsmbclient.h
new file mode 100644
index 0000000000..0c905edcbc
--- /dev/null
+++ b/source4/include/libsmbclient.h
@@ -0,0 +1,1073 @@
+/*=====================================================================
+  Unix SMB/Netbios implementation.
+  SMB client library API definitions
+  Copyright (C) Andrew Tridgell 1998
+  Copyright (C) Richard Sharpe 2000
+  Copyright (C) John Terpsra 2000
+  Copyright (C) Tom Jansen (Ninja ISD) 2002 
+
+   
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+   
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+   
+  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_INCLUDED
+#define SMBCLIENT_H_INCLUDED
+
+/*-------------------------------------------------------------------*/
+/* The following are special comments to instruct DOXYGEN (automated 
+ * documentation tool:
+*/
+/** \defgroup libsmbclient
+*/
+/** \defgroup structure Data Structures Type and Constants
+*   \ingroup libsmbclient
+*   Data structures, types, and constants
+*/
+/** \defgroup callback Callback function types
+*   \ingroup libsmbclient
+*   Callback functions
+*/
+/** \defgroup file File Functions
+*   \ingroup libsmbclient
+*   Functions used to access individual file contents
+*/
+/** \defgroup directory Directory Functions
+*   \ingroup libsmbclient
+*   Functions used to access directory entries
+*/
+/** \defgroup attribute Attributes Functions
+*   \ingroup libsmbclient
+*   Functions used to view or change file and directory attributes
+*/
+/** \defgroup print Print Functions
+*   \ingroup libsmbclient
+*   Functions used to access printing functionality
+*/
+/** \defgroup misc Miscellaneous Functions
+*   \ingroup libsmbclient
+*   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_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
+
+/**@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,*/ 
+	unsigned int smbc_type; 
+
+	/** Length of this smbc_dirent in bytes
+	 */
+	unsigned int dirlen;
+	/** The length of the comment string in bytes (includes null 
+	 *  terminator)
+	 */
+	unsigned int commentlen;
+	/** Points to the null terminated comment string 
+	 */
+	char *comment;
+	/** The length of the name string in bytes (includes null 
+	 *  terminator)
+	 */
+	unsigned int namelen;
+	/** Points to the null terminated name string 
+	 */
+	char name[1];
+};
+
+
+/**@ingroup structure
+ * Structure that represents a print job.
+ *
+ */
+#ifndef _CLIENT_H
+struct print_job_info 
+{
+	/** numeric ID of the print job
+	 */
+	unsigned short id;
+    
+	/** represents print job priority (lower numbers mean higher priority)
+	 */
+	unsigned short 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. This will have no name if an anonymous print
+	 *  file was opened. Ie smb://server/printer
+	 */
+	char name[128];
+
+	/** Time the print job was spooled
+	 */
+	time_t t;
+};
+#endif /* _CLIENT_H */
+
+
+/**@ingroup structure
+ * Server handle 
+ */
+typedef struct _SMBCSRV  SMBCSRV;
+
+/**@ingroup structure
+ * File or directory handle 
+ */
+typedef struct _SMBCFILE SMBCFILE;
+
+/**@ingroup structure
+ * File or directory handle 
+ */
+typedef struct _SMBCCTX SMBCCTX;
+
+
+
+
+
+/**@ingroup callback
+ * 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 in
+ *                  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 in 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
+ *           
+ */
+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 callback
+ * Print job info callback function type.
+ *
+ * @param i         pointer to print job information structure
+ *
+ */ 
+typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
+		
+
+/**@ingroup callback
+ * Check if a server is still good
+ *
+ * @param c         pointer to smb context
+ *
+ * @param srv       pointer to server to check
+ *
+ * @return          0 when connection is good. 1 on error.
+ *
+ */ 
+typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
+
+/**@ingroup callback
+ * Remove a server if unused
+ *
+ * @param c         pointer to smb context
+ *
+ * @param srv       pointer to server to remove
+ *
+ * @return          0 on success. 1 on failure.
+ *
+ */ 
+typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
+
+
+/**@ingroup callback
+ * Add a server to the cache system
+ *
+ * @param c         pointer to smb context
+ *
+ * @param srv       pointer to server to add
+ *
+ * @param server    server name 
+ *
+ * @param share     share name
+ *
+ * @param workgroup workgroup used to connect
+ *
+ * @param username  username used to connect
+ *
+ * @return          0 on success. 1 on failure.
+ *
+ */ 
+typedef int (*smbc_add_cached_srv_fn)   (SMBCCTX * c, SMBCSRV *srv, 
+				    char * server, char * share, 
+				    char * workgroup, char * username);
+
+
+/**@ingroup callback
+ * Look up a server in the cache system
+ *
+ * @param c         pointer to smb context
+ *
+ * @param server    server name to match
+ *
+ * @param share     share name to match
+ *
+ * @param workgroup workgroup to match
+ *
+ * @param username  username to match
+ *
+ * @return          pointer to SMBCSRV on success. NULL on failure.
+ *
+ */ 
+typedef SMBCSRV * (*smbc_get_cached_srv_fn)   (SMBCCTX * c, char * server, 
+					       char * share, char * workgroup, char * username);
+
+
+/**@ingroup callback
+ * Check if a server is still good
+ *
+ * @param c         pointer to smb context
+ *
+ * @param srv       pointer to server to remove
+ *
+ * @return          0 when found and removed. 1 on failure.
+ *
+ */ 
+typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
+
+
+/**@ingroup callback
+ * Try to remove all servers from the cache system and disconnect
+ *
+ * @param c         pointer to smb context
+ *
+ * @return          0 when found and removed. 1 on failure.
+ *
+ */ 
+typedef int (*smbc_purge_cached_fn)     (SMBCCTX * c);
+
+
+
+
+/**@ingroup structure
+ * Structure that contains a client context information 
+ * This structure is know as SMBCCTX
+ */
+struct _SMBCCTX {
+	/** debug level 
+	 */
+	int     debug;
+	
+	/** netbios name used for making connections
+	 */
+	char * netbios_name;
+
+	/** workgroup name used for making connections 
+	 */
+	char * workgroup;
+
+	/** username used for making connections 
+	 */
+	char * user;
+
+	/** timeout used for waiting on connections / response data (in milliseconds)
+	 */
+	int timeout;
+
+	/** callable functions for files:
+	 * For usage and return values see the smbc_* functions
+	 */ 
+	SMBCFILE * (*open)    (SMBCCTX *c, const char *fname, int flags, mode_t mode);
+	SMBCFILE * (*creat)   (SMBCCTX *c, const char *path, mode_t mode);
+	ssize_t    (*read)    (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
+	ssize_t    (*write)   (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
+	int        (*unlink)  (SMBCCTX *c, const char *fname);
+	int        (*rename)  (SMBCCTX *ocontext, const char *oname, 
+			       SMBCCTX *ncontext, const char *nname);
+	off_t      (*lseek)   (SMBCCTX *c, SMBCFILE * file, off_t offset, int whence);
+	int        (*stat)    (SMBCCTX *c, const char *fname, struct stat *st);
+	int        (*fstat)   (SMBCCTX *c, SMBCFILE *file, struct stat *st);
+	int        (*close)   (SMBCCTX *c, SMBCFILE *file);
+
+	/** callable functions for dirs
+	 */ 
+	SMBCFILE * (*opendir) (SMBCCTX *c, const char *fname);
+	int        (*closedir)(SMBCCTX *c, SMBCFILE *dir);
+	struct smbc_dirent * (*readdir)(SMBCCTX *c, SMBCFILE *dir);
+	int        (*getdents)(SMBCCTX *c, SMBCFILE *dir, 
+			       struct smbc_dirent *dirp, int count);
+	int        (*mkdir)   (SMBCCTX *c, const char *fname, mode_t mode);
+	int        (*rmdir)   (SMBCCTX *c, const char *fname);
+	off_t      (*telldir) (SMBCCTX *c, SMBCFILE *dir);
+	int        (*lseekdir)(SMBCCTX *c, SMBCFILE *dir, off_t offset);
+	int        (*fstatdir)(SMBCCTX *c, SMBCFILE *dir, struct stat *st);
+
+	/** callable functions for printing
+	 */ 
+	int        (*print_file)(SMBCCTX *c_file, const char *fname, 
+				 SMBCCTX *c_print, const char *printq);
+	SMBCFILE * (*open_print_job)(SMBCCTX *c, const char *fname);
+	int        (*list_print_jobs)(SMBCCTX *c, const char *fname, smbc_list_print_job_fn fn);
+	int        (*unlink_print_job)(SMBCCTX *c, const char *fname, int id);
+
+
+	/** Callbacks
+	 * These callbacks _always_ have to be initialized because they will not be checked
+	 * at dereference for increased speed.
+	 */
+	struct _smbc_callbacks {
+		/** authentication function callback: called upon auth requests
+		 */
+		smbc_get_auth_data_fn auth_fn;
+		
+		/** check if a server is still good
+		 */
+		smbc_check_server_fn check_server_fn;
+
+		/** remove a server if unused
+		 */
+		smbc_remove_unused_server_fn remove_unused_server_fn;
+
+		/** Cache subsystem
+		 * For an example cache system see samba/source/libsmb/libsmb_cache.c
+		 * Cache subsystem functions follow.
+		 */
+
+		/** server cache addition 
+		 */
+		smbc_add_cached_srv_fn add_cached_srv_fn;
+
+		/** server cache lookup 
+		 */
+		smbc_get_cached_srv_fn get_cached_srv_fn;
+
+		/** server cache removal
+		 */
+		smbc_remove_cached_srv_fn remove_cached_srv_fn;
+		
+		/** server cache purging, try to remove all cached servers (disconnect)
+		 */
+		smbc_purge_cached_fn purge_cached_fn;
+	} callbacks;
+
+
+	/** Space to store private data of the server cache.
+	 */
+	struct smbc_server_cache * server_cache;
+
+	/** INTERNAL DATA
+	 * do _NOT_ touch this from your program !
+	 */
+	struct smbc_internal_data * internal;
+	
+};
+
+
+/**@ingroup misc
+ * Create a new SBMCCTX (a context).
+ *
+ * Must be called before the context is passed to smbc_context_init()
+ *
+ * @return          The given SMBCCTX pointer on success, NULL on error with errno set:
+ *                  - ENOMEM Out of memory
+ *
+ * @see             smbc_free_context(), smbc_init_context()
+ *
+ * @note            Do not forget to smbc_init_context() the returned SMBCCTX pointer !
+ */
+SMBCCTX * smbc_new_context(void);
+
+/**@ingroup misc
+ * Delete a SBMCCTX (a context) acquired from smbc_new_context().
+ *
+ * The context will be deleted if possible.
+ *
+ * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
+ *
+ * @param shutdown_ctx   If 1, all connections and files will be closed even if they are busy.
+ *
+ *
+ * @return          Returns 0 on succes. Returns 1 on failure with errno set:
+ *                  - EBUSY Server connections are still used, Files are open or cache 
+ *                          could not be purged
+ *                  - EBADF context == NULL
+ *
+ * @see             smbc_new_context()
+ *
+ * @note            It is advised to clean up all the contexts with shutdown_ctx set to 1
+ *                  just before exit()'ing. When shutdown_ctx is 0, this function can be
+ *                  use in periodical cleanup functions for example.
+ */
+int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
+
+
+/**@ingroup misc
+ * Initialize a SBMCCTX (a context).
+ *
+ * Must be called before using any SMBCCTX API function
+ *
+ * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
+ *
+ * @return          A pointer to the given SMBCCTX on success, NULL on error with errno set:
+ *                  - EBADF  NULL context given
+ *                  - ENOMEM Out of memory
+ *                  - ENOENT The smb.conf file would not load
+ *
+ * @see             smbc_new_context()
+ *
+ * @note            my_context = smbc_init_context(smbc_new_context()) is perfectly safe, 
+ *                  but it might leak memory on smbc_context_init() failure. Avoid this.
+ *                  You'll have to call smbc_free_context() yourself on failure.  
+ */
+
+SMBCCTX * smbc_init_context(SMBCCTX * context);
+
+/**@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. Allows caller to set
+ *                  debugging if no smb.conf.
+ *   
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - ENOMEM Out of memory
+ *                  - ENOENT The smb.conf file would not load
+ *
+ */
+
+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.
+ *                  We will map this to SYSTEM, HIDDEN, etc bits
+ *                  that reverses the mapping that smbc_fstat does.
+ *
+ * @return          Valid file handle, < 0 on error with errno set:
+ *                  - ENOMEM  Out of memory
+ *                  - EINVAL if an invalid parameter passed, like no 
+ *                  file, or smbc_init not called.
+ *                  - 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 
+ *                  - ENODEV The requested share does not exist
+ *                  - ENOTDIR A file on the path is not a directory
+ *                  - ENOENT  A directory component in pathname does 
+ *                  not exist.
+ *
+ * @see             smbc_creat()
+ *
+ * @note            This call uses an underlying routine that may create
+ *                  a new connection to the server specified in the URL.
+ *                  If the credentials supplied in the URL, or via the
+ *                  auth_fn in the smbc_init call, fail, this call will
+ *                  try again with an empty username and password. This 
+ *                  often gets mapped to the guest account on some machines.
+ */
+
+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)
+ *
+ *                  NOTE, the above is not true. We are dealing with 
+ *                  an SMB server, which has no concept of a umask!
+ *      
+ * @return          Valid file handle, < 0 on error with errno set:
+ *                  - ENOMEM  Out of memory
+ *                  - EINVAL if an invalid parameter passed, like no 
+ *                  file, or smbc_init not called.
+ *                  - 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.
+ *                  - ENODEV The requested share does not exist.
+ * @see             smbc_open()
+ *
+ */
+
+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, or no buffer passed or
+ *		    smbc_init not called.
+ *
+ * @see             smbc_open(), smbc_write()
+ *
+ */
+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, or no buffer passed or
+ *		    smbc_init not called.
+ *
+ * @see             smbc_open(), smbc_read()
+ *
+ */
+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 or smbc_init
+ *		      not 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);
+
+
+/**@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
+ *                  - EINVAL smbc_init() failed or has not been called
+ *
+ * @see             smbc_open(), smbc_creat()
+ */
+int smbc_close(int fd);
+
+
+/**@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
+ *                  - EINVAL NULL was passed in the file param or
+ *		      smbc_init not called.
+ *                  - EACCES You do not have access to the file
+ *                  - ENOMEM Insufficient kernel memory was available
+ *
+ * @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
+ *		    or smbc_init not called.
+ *                  - 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.
+ *                  - EXDEV Rename across shares not supported.
+ *                  - ENOMEM Insufficient kernel memory was available.
+ *                  - EEXIST The target file, nurl, already exists.
+ *
+ *
+ * @todo Are we going to support copying when urls are not on the same
+ *       share?  I say no... NOTE. I agree for the moment.
+ *
+ */
+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.
+ *                  - EINVAL A NULL file/URL was passed, or the URL would
+ *                  not parse, or was of incorrect form or smbc_init not
+ *                  called.
+ *                  - ENOENT durl does not exist, or name is an 
+ *                  - ENOMEM Insufficient memory to complete the 
+ *                  operation.                              
+ *                  - ENOTDIR name is not a directory.
+ *                  - EPERM the workgroup could not be found.
+ *                  - ENODEV the workgroup or server could not be found.
+ *
+ * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
+ *
+ */
+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 as many dirent structures from the an open 
+ * directory handle into a specified memory area as will fit.
+ *
+ * @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         If any dirents returned, return will indicate the
+ *                  total size. If there were no more dirents available,
+ *                  0 is returned. < 0 indicates an error.
+ *                  - EBADF  Invalid directory handle
+ *                  - EINVAL Result buffer is too small or smbc_init
+ *		    not called.
+ *                  - ENOENT No such directory.
+ * @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_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
+ *                  - EINVAL 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.  The current location is not
+ *                  an offset. Becuase of the implementation, it is a 
+ *                  handle that allows the library to find the entry
+ *                  later.
+ *                  - EBADF dh is not a valid directory handle
+ *                  - EINVAL smbc_init() failed or has not been called
+ *                  - ENOTDIR if dh is not a directory
+ *
+ * @see             smbc_readdir()
+ *
+ */
+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, NULL))
+ *
+ * @param fd        Valid directory as returned by smbc_opendir()
+ * 
+ * @param offset    The offset (as returned by smbc_telldir). Can be
+ *                  NULL, in which case we will rewind
+ *
+ * @return          0 on success, -1 on failure
+ *                  - EBADF dh is not a valid directory handle
+ *                  - ENOTDIR if dh is not a directory
+ *                  - EINVAL offset did not refer to a valid dirent or
+ *		      smbc_init not called.
+ *
+ * @see             smbc_telldir()
+ *
+ *
+ * @todo In what does the reture and errno values mean?
+ */
+int smbc_lseekdir(int fd, off_t offset);
+
+/**@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.
+ *                  - EINVAL NULL durl passed or smbc_init not called.
+ *                  - ENOMEM Insufficient memory was available.
+ *
+ * @see             smbc_rmdir()
+ *
+ */
+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.
+ *                  - EINVAL durl is NULL or smbc_init not called.
+ *                  - ENOENT A directory component in pathname does not
+ *                  exist.
+ *                  - ENOTEMPTY directory contains entries.
+ *                  - ENOMEM Insufficient kernel memory was available.
+ *
+ * @see             smbc_mkdir(), smbc_unlink() 
+ *
+ * @todo Are errno values complete and correct?
+ */
+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.
+ *                  - EINVAL a NULL url was passed or smbc_init not called.
+ *                  - EACCES Permission denied.
+ *                  - ENOMEM Out of memory
+ *                  - ENOTDIR The target dir, url, is not a directory.
+ *
+ * @see             Unix stat()
+ *
+ */
+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.
+ *                  - EBADF fd is not a valid file descriptor
+ *                  - EINVAL Problems occurred in the underlying routines
+ *		      or smbc_init not called.
+ *                  - ENOMEM Out of memory
+ *
+ * @see             smbc_stat(), Unix stat()
+ *
+ */
+int smbc_fstat(int fd, struct stat *st);
+
+
+/**@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?
+ *
+ */
+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);
+
+
+/**@ingroup print
+ * Print a file given the name in fname. It would be a URL ...
+ * 
+ * @param fname     The URL of a file on a remote SMB server that the
+ *                  caller wants printed
+ *
+ * @param printq    The URL of the print share to print the file to.
+ *
+ * @return          0 on success, < 0 on error with errno set:         
+ *
+ *                  - EINVAL fname or printq was NULL or smbc_init not
+ * 		      not called.
+ *                  and errors returned by smbc_open
+ *
+ */                                     
+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     The URL of the print share to print to?
+ *
+ * @returns         A file handle for the print file if successful.
+ *                  Returns -1 if an error ocurred and errno has the values
+ *                  - EINVAL fname was NULL or smbc_init not called.
+ *                  - all errors returned by smbc_open
+ *
+ */
+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: 
+ *                  - EINVAL fname was NULL or smbc_init not called
+ *                  - EACCES ???
+ */
+int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn 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: 
+ *                  - EINVAL fname was NULL or smbc_init not called
+ *
+ * @todo    what errno values are possible here?
+ */
+int smbc_unlink_print_job(const char *purl, int id);
+
+
+#endif /* SMBCLIENT_H_INCLUDED */