#ifndef SMBCLIENT_H_INCLUDED
#define SMBCLIENT_H_INCLUDED
-#undef _DEPRECATED_
+#undef DEPRECATED_SMBC_INTERFACE
#if ! defined(__LIBSMBCLIENT_INTERNAL__) && defined(__GNUC__)
-# define _DEPRECATED_ __attribute__ ((deprecated))
+# define DEPRECATED_SMBC_INTERFACE __attribute__ ((deprecated))
#else
-# define _DEPRECATED_
+# define DEPRECATED_SMBC_INTERFACE
#endif
#ifdef __cplusplus
/* Make sure we have the following includes for now ... */
#include <sys/types.h>
#include <sys/stat.h>
+#include <sys/statvfs.h>
#include <fcntl.h>
#include <utime.h>
} smbc_smb_encrypt_level;
+/**
+ * Capabilities set in the f_flag field of struct statvfs, from
+ * smbc_statvfs(). These may be OR-ed together to reflect a full set of
+ * available capabilities.
+ */
+typedef enum smbc_vfs_feature
+{
+ /* Defined by POSIX or in Linux include files (low-order bits) */
+ SMBC_VFS_FEATURE_RDONLY = (1 << 0),
+
+ /* Specific to libsmbclient (high-order bits) */
+ SMBC_VFS_FEATURE_DFS = (1 << 28),
+ SMBC_VFS_FEATURE_CASE_INSENSITIVE = (1 << 29),
+ SMBC_VFS_FEATURE_NO_UNIXCIFS = (1 << 30)
+} smbc_vfs_feature;
+
typedef int smbc_bool;
* smbc_getOptionFallbackAFterKerberos()
* smbc_setOptionNoAutoAnonymousLogin()
* smbc_getOptionNoAutoAnonymousLogin()
+ * smbc_setOptionUseCCache()
+ * smbc_getOptionUseCCache()
*/
# 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)
+# define SMB_CTX_FLAG_USE_CCACHE (1 << 3)
* Type for the the authentication function called by the library to
* obtain authentication credentals
*
+ * For kerberos support the function should just be called without
+ * prompting the user for credentials. Which means a simple 'return'
+ * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
+ * and examples/libsmbclient/testbrowse.c.
+ *
* @param srv Server being authenticated to
*
* @param shr Share being authenticated to
* Type for the the authentication function called by the library to
* obtain authentication credentals
*
+ * For kerberos support the function should just be called without
+ * prompting the user for credentials. Which means a simple 'return'
+ * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
+ * and examples/libsmbclient/testbrowse.c.
+ *
* @param c Pointer to the smb context
*
* @param srv Server being authenticated to
void
smbc_setOptionSmbEncryptionLevel(SMBCCTX *c, smbc_smb_encrypt_level level);
+/**
+ * Get whether to treat file names as case-sensitive if we can't determine
+ * when connecting to the remote share whether the file system is case
+ * sensitive. This defaults to FALSE since it's most likely that if we can't
+ * retrieve the file system attributes, it's a very old file system that does
+ * not support case sensitivity.
+ */
+smbc_bool
+smbc_getOptionCaseSensitive(SMBCCTX *c);
+
+/**
+ * Set whether to treat file names as case-sensitive if we can't determine
+ * when connecting to the remote share whether the file system is case
+ * sensitive. This defaults to FALSE since it's most likely that if we can't
+ * retrieve the file system attributes, it's a very old file system that does
+ * not support case sensitivity.
+ */
+void
+smbc_setOptionCaseSensitive(SMBCCTX *c, smbc_bool b);
+
+
/**
* Get 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
void
smbc_setOptionNoAutoAnonymousLogin(SMBCCTX *c, smbc_bool b);
+/** Get whether to enable use of the winbind ccache */
+smbc_bool
+smbc_getOptionUseCCache(SMBCCTX *c);
+
+/** Set whether to enable use of the winbind ccache */
+void
+smbc_setOptionUseCCache(SMBCCTX *c, smbc_bool b);
+
+/** Get indication that the password supplied is the NT hash */
+smbc_bool
+smbc_getOptionUseNTHash(SMBCCTX *c);
+
+/** Set indication that the password supplied is the NT hash */
+void
+smbc_setOptionUseNTHash(SMBCCTX *c, smbc_bool b);
+
/*************************************
typedef ssize_t (*smbc_write_fn)(SMBCCTX *c,
SMBCFILE *file,
- void *buf,
+ const void *buf,
size_t count);
smbc_write_fn smbc_getFunctionWrite(SMBCCTX *c);
void smbc_setFunctionWrite(SMBCCTX *c, smbc_write_fn fn);
smbc_fstat_fn smbc_getFunctionFstat(SMBCCTX *c);
void smbc_setFunctionFstat(SMBCCTX *c, smbc_fstat_fn fn);
+typedef int (*smbc_statvfs_fn)(SMBCCTX *c,
+ char *path,
+ struct statvfs *st);
+smbc_statvfs_fn smbc_getFunctionStatVFS(SMBCCTX *c);
+void smbc_setFunctionStatVFS(SMBCCTX *c, smbc_statvfs_fn fn);
+
+typedef int (*smbc_fstatvfs_fn)(SMBCCTX *c,
+ SMBCFILE *file,
+ struct statvfs *st);
+smbc_fstatvfs_fn smbc_getFunctionFstatVFS(SMBCCTX *c);
+void smbc_setFunctionFstatVFS(SMBCCTX *c, smbc_fstatvfs_fn fn);
+
typedef int (*smbc_ftruncate_fn)(SMBCCTX *c,
SMBCFILE *f,
off_t size);
*
* @param fd Open file handle from smbc_open() or smbc_creat()
*
- * @param buf Pointer to buffer to recieve read data
+ * @param buf Pointer to buffer to receive read data
*
* @param bufsize Size of buf in bytes
*
- * @return Number of bytes read, < 0 on error with errno set:
+ * @return Number of bytes read;
+ * 0 upon EOF;
+ * < 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.
+ * 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.
+ * unsuitable for reading, or no buffer passed or
+ * smbc_init not called.
*
* @see smbc_open(), smbc_write()
*
* @see smbc_open(), smbc_read()
*
*/
-ssize_t smbc_write(int fd, void *buf, size_t bufsize);
+ssize_t smbc_write(int fd, const void *buf, size_t bufsize);
/**@ingroup file
* @param st pointer to a buffer that will be filled with
* standard Unix struct stat information.
*
- * @return EBADF filedes is bad.
+ * @return 0 on success, < 0 on error with errno set:
+ * - EBADF filedes is bad.
* - EACCES Permission denied.
* - EBADF fd is not a valid file descriptor
* - EINVAL Problems occurred in the underlying routines
/**@ingroup attribute
- * Truncate a file given a file descriptor
+ * Get file system information for a specified path.
*
- * @param fd Open file handle from smbc_open() or smbc_creat()
+ * @param url The smb url to get information for
*
- * @param size size to truncate the file to
+ * @param st pointer to a buffer that will be filled with
+ * standard Unix struct statvfs information.
*
- * @return EBADF filedes is bad.
+ * @return 0 on success, < 0 on error with errno set:
+ * - 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 , Unix ftruncate()
+ * @see Unix fstatvfs()
*
*/
-int smbc_ftruncate(int fd, off_t size);
-
+int
+smbc_statvfs(char *url,
+ struct statvfs *st);
-/**@ingroup attribue
- * Change the ownership of a file or directory.
+/**@ingroup attribute
+ * Get file system information via an file descriptor.
+ *
+ * @param fd Open file handle from smbc_open(), smbc_creat(),
+ * or smbc_opendir()
*
- * @param url The smb url of the file or directory to change
- * ownership of.
+ * @param st pointer to a buffer that will be filled with
+ * standard Unix struct statvfs information.
+ *
+ * @return 0 on success, < 0 on error with errno set:
+ * - 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
*
- * @param owner I have no idea?
+ * @see Unix fstatvfs()
*
- * @param group I have not idea?
+ */
+int
+smbc_fstatvfs(int fd,
+ struct statvfs *st);
+
+
+/**@ingroup attribute
+ * Truncate a file given a file descriptor
+ *
+ * @param fd Open file handle from smbc_open() or smbc_creat()
*
+ * @param size size to truncate the file to
+ *
* @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
+ * - 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
*
- * @todo How do we abstract owner and group uid and gid?
+ * @see , Unix ftruncate()
*
*/
-int smbc_chown(const char *url, uid_t owner, gid_t group);
+int smbc_ftruncate(int fd, off_t size);
/**@ingroup attribute
}
#endif
+/**@ingroup misc
+ * Set the users credentials globally so they can be used for DFS
+ * referrals. Probably best to use this function in the smbc_get_auth_data_fn
+ * callback.
+ *
+ * @param workgroup Workgroup of the user.
+ *
+ * @param user Username of user.
+ *
+ * @param password Password of user.
+ *
+ * @param use_kerberos Whether to use Kerberos
+ *
+ * @param signing_state One of these strings (all equivalents on same line):
+ * "off", "no", "false"
+ * "on", "yes", "true", "auto"
+ * "force", "required", "forced"
+ */
+
+void
+smbc_set_credentials(const char *workgroup,
+ const char *user,
+ const char *password,
+ smbc_bool use_kerberos,
+ const char *signing_state);
+
+/*
+ * Wrapper around smbc_set_credentials.
+ * Used to set correct credentials that will
+ * be used to connect to DFS target share
+ * in libsmbclient
+ */
+
+void
+smbc_set_credentials_with_fallback(SMBCCTX *ctx,
+ const char *workgroup,
+ const char *user,
+ const char *password);
+
+
+/**
+ * @ingroup threads
+ *
+ * Initialize for threads using the Posix Threads (pthread)
+ * implementation. This is a built-in implementation, avoiding the need to
+ * implement the component functions of the thread interface. If this function
+ * is used, it is not necessary to call smbc_thread_impl().
+ *
+ * @return {void}
+ */
+void
+smbc_thread_posix(void);
+
+/**
+ * @ingroup threads
+ *
+ * Initialize for an arbitrary thread implementation. The caller should
+ * provide, as parameters, pointers to functions to implement the requisite
+ * low-level thread functionality. A function must be provided for each
+ * parameter; none may be null.
+ *
+ * If the thread implementation is POSIX Threads (pthreads), then the much
+ * simpler smbc_thread_pthread() function may be used instead of this one.
+ *
+ * @param create_mutex
+ * Create a mutex. This function should expect three parameters: lockname,
+ * pplock, and location. It should create a unique mutex for each unique
+ * lockname it is provided, and return the mutex identifier in *pplock. The
+ * location parameter can be used for debugging, as it contains the
+ * compiler-provided __location__ of the call.
+ *
+ * @param destroy_mutex
+ * Destroy a mutex. This function should expect two parameters: plock and
+ * location. It should destroy the mutex associated with the identifier
+ * plock. The location parameter can be used for debugging, as it contains
+ * the compiler-provided __location__ of the call.
+ *
+ * @param lock_mutex
+ * Lock a mutex. This function should expect three parameters: plock,
+ * lock_type, and location. The mutex aassociated with identifier plock
+ * should be locked if lock_type is 1, and unlocked if lock_type is 2. The
+ * location parameter can be used for debugging, as it contains the
+ * compiler-provided __location__ of the call.
+ *
+ * @param create_tls
+ * Create thread local storage. This function should expect three
+ * parameters: keyname, ppkey, and location. It should allocate an
+ * implementation-specific amount of memory and assign the pointer to that
+ * allocated memory to *ppkey. The location parameter can be used for
+ * debugging, as it contains the compiler-provided __location__ of the
+ * call. This function should return 0 upon success, non-zero upon failure.
+ *
+ * @param destroy_tls
+ * Destroy thread local storage. This function should expect two parameters:
+ * ppkey and location. The ppkey parameter points to a variable containing a
+ * thread local storage key previously provided by the create_tls
+ * function. The location parameter can be used for debugging, as it
+ * contains the compiler-provided __location__ of the call.
+ *
+ * @param set_tls
+ * Set a thread local storage variable's value. This function should expect
+ * three parameters: pkey, pval, and location. The pkey parameter is a
+ * thread local storage key previously provided by the create_tls
+ * function. The (void *) pval parameter contains the value to be placed in
+ * the thread local storage variable identified by pkey. The location
+ * parameter can be used for debugging, as it contains the compiler-provided
+ * __location__ of the call. This function should return 0 upon success;
+ * non-zero otherwise.
+ *
+ * @param get_tls
+ * Retrieve a thread local storage variable's value. This function should
+ * expect two parameters: pkey and location. The pkey parameter is a thread
+ * local storage key previously provided by the create_tls function, and
+ * which has previously been used in a call to the set_tls function to
+ * initialize a thread local storage variable. The location parameter can be
+ * used for debugging, as it contains the compiler-provided __location__ of
+ * the call. This function should return the (void *) value stored in the
+ * variable identified by pkey.
+ *
+ * @return {void}
+ */
+void
+smbc_thread_impl(
+ /* Mutex functions. */
+ int (*create_mutex)(const char *lockname,
+ void **pplock,
+ const char *location),
+ void (*destroy_mutex)(void *plock,
+ const char *location),
+ int (*lock_mutex)(void *plock,
+ int lock_type,
+ const char *location),
+
+ /* Thread local storage. */
+ int (*create_tls)(const char *keyname,
+ void **ppkey,
+ const char *location),
+ void (*destroy_tls)(void **ppkey,
+ const char *location),
+ int (*set_tls)(void *pkey,
+ const void *pval,
+ const char *location),
+ void *(*get_tls)(void *pkey,
+ const char *location)
+ );
+
+
+
/**
* @ingroup structure
* Structure that contains a client context information
* DEPRECATED:
* Use smbc_getDebug() and smbc_setDebug()
*/
- int debug _DEPRECATED_;
+ int debug DEPRECATED_SMBC_INTERFACE;
/**
* netbios name used for making connections
* DEPRECATED:
* Use smbc_getNetbiosName() and smbc_setNetbiosName()
*/
- char * netbios_name _DEPRECATED_;
+ char * netbios_name DEPRECATED_SMBC_INTERFACE;
/**
* workgroup name used for making connections
* DEPRECATED:
* Use smbc_getWorkgroup() and smbc_setWorkgroup()
*/
- char * workgroup _DEPRECATED_;
+ char * workgroup DEPRECATED_SMBC_INTERFACE;
/**
* username used for making connections
* DEPRECATED:
* Use smbc_getUser() and smbc_setUser()
*/
- char * user _DEPRECATED_;
+ char * user DEPRECATED_SMBC_INTERFACE;
/**
* timeout used for waiting on connections / response data (in
* DEPRECATED:
* Use smbc_getTimeout() and smbc_setTimeout()
*/
- int timeout _DEPRECATED_;
+ int timeout DEPRECATED_SMBC_INTERFACE;
/**
* callable functions for files:
* Use smbc_getFunction*() and smbc_setFunction*(), e.g.
* smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
*/
- smbc_open_fn open _DEPRECATED_;
- smbc_creat_fn creat _DEPRECATED_;
- smbc_read_fn read _DEPRECATED_;
- smbc_write_fn write _DEPRECATED_;
- smbc_unlink_fn unlink _DEPRECATED_;
- smbc_rename_fn rename _DEPRECATED_;
- smbc_lseek_fn lseek _DEPRECATED_;
- smbc_stat_fn stat _DEPRECATED_;
- smbc_fstat_fn fstat _DEPRECATED_;
+ smbc_open_fn open DEPRECATED_SMBC_INTERFACE;
+ smbc_creat_fn creat DEPRECATED_SMBC_INTERFACE;
+ smbc_read_fn read DEPRECATED_SMBC_INTERFACE;
+ smbc_write_fn write DEPRECATED_SMBC_INTERFACE;
+ smbc_unlink_fn unlink DEPRECATED_SMBC_INTERFACE;
+ smbc_rename_fn rename DEPRECATED_SMBC_INTERFACE;
+ smbc_lseek_fn lseek DEPRECATED_SMBC_INTERFACE;
+ smbc_stat_fn stat DEPRECATED_SMBC_INTERFACE;
+ smbc_fstat_fn fstat DEPRECATED_SMBC_INTERFACE;
#if 0 /* internal */
smbc_ftruncate_fn ftruncate_fn;
#endif
- smbc_close_fn close_fn _DEPRECATED_;
- smbc_opendir_fn opendir _DEPRECATED_;
- smbc_closedir_fn closedir _DEPRECATED_;
- smbc_readdir_fn readdir _DEPRECATED_;
- smbc_getdents_fn getdents _DEPRECATED_;
- smbc_mkdir_fn mkdir _DEPRECATED_;
- smbc_rmdir_fn rmdir _DEPRECATED_;
- smbc_telldir_fn telldir _DEPRECATED_;
- smbc_lseekdir_fn lseekdir _DEPRECATED_;
- smbc_fstatdir_fn fstatdir _DEPRECATED_;
- smbc_chmod_fn chmod _DEPRECATED_;
- smbc_utimes_fn utimes _DEPRECATED_;
- smbc_setxattr_fn setxattr _DEPRECATED_;
- smbc_getxattr_fn getxattr _DEPRECATED_;
- smbc_removexattr_fn removexattr _DEPRECATED_;
- smbc_listxattr_fn listxattr _DEPRECATED_;
+ smbc_close_fn close_fn DEPRECATED_SMBC_INTERFACE;
+ smbc_opendir_fn opendir DEPRECATED_SMBC_INTERFACE;
+ smbc_closedir_fn closedir DEPRECATED_SMBC_INTERFACE;
+ smbc_readdir_fn readdir DEPRECATED_SMBC_INTERFACE;
+ smbc_getdents_fn getdents DEPRECATED_SMBC_INTERFACE;
+ smbc_mkdir_fn mkdir DEPRECATED_SMBC_INTERFACE;
+ smbc_rmdir_fn rmdir DEPRECATED_SMBC_INTERFACE;
+ smbc_telldir_fn telldir DEPRECATED_SMBC_INTERFACE;
+ smbc_lseekdir_fn lseekdir DEPRECATED_SMBC_INTERFACE;
+ smbc_fstatdir_fn fstatdir DEPRECATED_SMBC_INTERFACE;
+ smbc_chmod_fn chmod DEPRECATED_SMBC_INTERFACE;
+ smbc_utimes_fn utimes DEPRECATED_SMBC_INTERFACE;
+ smbc_setxattr_fn setxattr DEPRECATED_SMBC_INTERFACE;
+ smbc_getxattr_fn getxattr DEPRECATED_SMBC_INTERFACE;
+ smbc_removexattr_fn removexattr DEPRECATED_SMBC_INTERFACE;
+ smbc_listxattr_fn listxattr DEPRECATED_SMBC_INTERFACE;
/* Printing-related functions */
- smbc_print_file_fn print_file _DEPRECATED_;
- smbc_open_print_job_fn open_print_job _DEPRECATED_;
- smbc_list_print_jobs_fn list_print_jobs _DEPRECATED_;
- smbc_unlink_print_job_fn unlink_print_job _DEPRECATED_;
+ smbc_print_file_fn print_file DEPRECATED_SMBC_INTERFACE;
+ smbc_open_print_job_fn open_print_job DEPRECATED_SMBC_INTERFACE;
+ smbc_list_print_jobs_fn list_print_jobs DEPRECATED_SMBC_INTERFACE;
+ smbc_unlink_print_job_fn unlink_print_job DEPRECATED_SMBC_INTERFACE;
/*
** Callbacks
* DEPRECATED:
* Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
*/
- smbc_get_auth_data_fn auth_fn _DEPRECATED_;
+ smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE;
/**
* check if a server is still good
* Use smbc_getFunctionCheckServer(),
* smbc_setFunctionCheckServer()
*/
- smbc_check_server_fn check_server_fn _DEPRECATED_;
+ smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE;
/**
* remove a server if unused
* Use smbc_getFunctionRemoveUnusedServer(),
* smbc_setFunctionCheckServer()
*/
- smbc_remove_unused_server_fn remove_unused_server_fn _DEPRECATED_;
+ smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE;
/** Cache subsystem
*
* Use smbc_getFunctionAddCachedServer(),
* smbc_setFunctionAddCachedServer()
*/
- smbc_add_cached_srv_fn add_cached_srv_fn _DEPRECATED_;
+ smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
/**
* server cache lookup
* Use smbc_getFunctionGetCachedServer(),
* smbc_setFunctionGetCachedServer()
*/
- smbc_get_cached_srv_fn get_cached_srv_fn _DEPRECATED_;
+ smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
/**
* server cache removal
* Use smbc_getFunctionRemoveCachedServer(),
* smbc_setFunctionRemoveCachedServer()
*/
- smbc_remove_cached_srv_fn remove_cached_srv_fn _DEPRECATED_;
+ smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
/**
* server cache purging, try to remove all cached servers
* Use smbc_getFunctionPurgeCachedServers(),
* smbc_setFunctionPurgeCachedServers()
*/
- smbc_purge_cached_fn purge_cached_fn _DEPRECATED_;
+ smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE;
} callbacks;
/**
* DEPRECATED:
* Use smbc_getServerCacheData(), smbc_setServerCacheData()
*/
- void * reserved _DEPRECATED_;
+ void * reserved DEPRECATED_SMBC_INTERFACE;
/*
* Very old configuration options.
* smbc_setOptionNoAutoAnonymousLogin()
* smbc_getOptionNoAutoAnonymousLogin()
*/
- int flags _DEPRECATED_;
+ int flags DEPRECATED_SMBC_INTERFACE;
/**
* user options selections that apply to this session
* smbc_getOption*() functions.
*/
struct _smbc_options {
- int browse_max_lmb_count _DEPRECATED_;
- int urlencode_readdir_entries _DEPRECATED_;
- int one_share_per_server _DEPRECATED_;
- } options _DEPRECATED_;
+ int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE;
+ int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE;
+ int one_share_per_server DEPRECATED_SMBC_INTERFACE;
+ } options DEPRECATED_SMBC_INTERFACE;
/** INTERNAL DATA
* do _NOT_ touch this from your program !
git.samba.org / kai / samba.git / blobdiff