libsmbclient.h

samba-3.0.22.tar.gz 编译smb服务器的源码

 *
 */ 
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_fn) (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);
        int        (*chmod)(SMBCCTX *c, const char *fname, mode_t mode);
        int        (*utimes)(SMBCCTX *c,
                             const char *fname, struct timeval *tbuf);
        int        (*setxattr)(SMBCCTX *context,
                               const char *fname,
                               const char *name,
                               const void *value,
                               size_t size,
                               int flags);
        int        (*getxattr)(SMBCCTX *context,
                               const char *fname,
                               const char *name,
                               const void *value,
                               size_t size);
        int        (*removexattr)(SMBCCTX *context,
                                  const char *fname,
                                  const char *name);
        int        (*listxattr)(SMBCCTX *context,
                                const char *fname,
                                char *list,
                                size_t size);

	/** 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;

	int flags;
	
        /** user options selections that apply to this session
         */
        struct _smbc_options {

                /*
                 * From how many local master browsers should the list of
                 * workgroups be retrieved?  It can take up to 12 minutes or
                 * longer after a server becomes a local master browser, for
                 * it to have the entire browse list (the list of
                 * workgroups/domains) from an entire network.  Since a client
                 * never knows which local master browser will be found first,
                 * the one which is found first and used to retrieve a browse
                 * list may have an incomplete or empty browse list.  By
                 * requesting the browse list from multiple local master
                 * browsers, a more complete list can be generated.  For small
                 * networks (few workgroups), it is recommended that this
                 * value be set to 0, causing the browse lists from all found
                 * local master browsers to be retrieved and merged.  For
                 * networks with many workgroups, a suitable value for this
                 * variable is probably somewhere around 3. (Default: 3).
                 */
                int browse_max_lmb_count;

                /*
                 * There is a difference in the desired return strings from
                 * smbc_readdir() depending upon whether the filenames are to
                 * be displayed to the user, or whether they are to be
                 * appended to the path name passed to smbc_opendir() to call
                 * a further smbc_ function (e.g. open the file with
                 * smbc_open()).  In the former case, the filename should be
                 * in "human readable" form.  In the latter case, the smbc_
                 * functions expect a URL which must be url-encoded.  Those
                 * functions decode the URL.  If, for example, smbc_readdir()
                 * returned a file name of "abc%20def.txt", passing a path
                 * with this file name attached to smbc_open() would cause
                 * smbc_open to attempt to open the file "abc def.txt" since
                 * the %20 is decoded into a space.
                 *
                 * Set this option to True if the names returned by
                 * smbc_readdir() should be url-encoded such that they can be
                 * passed back to another smbc_ call.  Set it to False if the
                 * names returned by smbc_readdir() are to be presented to the
                 * user.
                 *
                 * For backwards compatibility, this option defaults to False.
                 */
                int urlencode_readdir_entries;

                /*
                 * Some Windows versions appear to have a limit to the number
                 * of concurrent SESSIONs and/or TREE CONNECTions.  In
                 * one-shot programs (i.e. the program runs and then quickly
                 * ends, thereby shutting down all connections), it is
                 * probably reasonable to establish a new connection for each
                 * share.  In long-running applications, the limitation can be
                 * avoided by using only a single connection to each server,
                 * and issuing a new TREE CONNECT when the share is accessed.
                 */
                int one_share_per_server;
        } options;
	
	/** INTERNAL DATA
	 * do _NOT_ touch this from your program !
	 */
	struct smbc_internal_data * internal;
};

/* Flags for SMBCCTX->flags */
#define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
#define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
#define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */

/**@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 misc
 * Set or retrieve the compatibility library's context pointer
 *
 * @param context   New context to use, or NULL.  If a new context is provided,
 *                  it must have allocated with smbc_new_context() and
 *                  initialized with smbc_init_context(), followed, optionally,
 *                  by some manual changes to some of the non-internal fields.
 *
 * @return          The old context.
 *
 * @see             smbc_new_context(), smbc_init_context(), smbc_init()
 *
 * @note            This function may be called prior to smbc_init() to force
 *                  use of the next context without any internal calls to
 *                  smbc_new_context() or smbc_init_context().  It may also
 *                  be called after smbc_init() has already called those two
 *                  functions, to replace the existing context with a new one.
 *                  Care should be taken, in this latter case, to ensure that
 *                  the server cache and any data allocated by the
 *                  authentication functions have been freed, if necessary.
 */

SMBCCTX * smbc_set_context(SMBCCTX * new_context);

/**@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.
 *