Copyright (C) Andrew Tridgell 1998
Copyright (C) Richard Sharpe 2000
Copyright (C) John Terpsra 2000
- Copyright (C) Tom Jansen (Ninja ISD) 2002
- Copyright (C) Derrell Lipman 2003
+ Copyright (C) Tom Jansen (Ninja ISD) 2002
+ Copyright (C) Derrell Lipman 2003-2008
+
-
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
+ the Free Software Foundation; either version 3 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.
+ along with this program; if not, see <http://www.gnu.org/licenses/>.
=====================================================================*/
#ifndef SMBCLIENT_H_INCLUDED
#define SMBCLIENT_H_INCLUDED
+#undef DEPRECATED_SMBC_INTERFACE
+#if ! defined(__LIBSMBCLIENT_INTERNAL__) && defined(__GNUC__)
+# define DEPRECATED_SMBC_INTERFACE __attribute__ ((deprecated))
+#else
+# define DEPRECATED_SMBC_INTERFACE
+#endif
+
#ifdef __cplusplus
extern "C" {
#endif
/*-------------------------------------------------------------------*/
-/* The following are special comments to instruct DOXYGEN (automated
+/* The following are special comments to instruct DOXYGEN (automated
* documentation tool:
*/
/** \defgroup libsmbclient
* \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 <sys/statvfs.h>
+#include <stdint.h>
#include <fcntl.h>
#include <utime.h>
* Structure that represents a directory entry.
*
*/
-struct smbc_dirent
+struct smbc_dirent
{
/** Type of entity.
SMBC_WORKGROUP=1,
- SMBC_SERVER=2,
+ 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;
+ SMBC_LINK=9,*/
+ unsigned int smbc_type;
/** Length of this smbc_dirent in bytes
*/
* null terminator)
*/
unsigned int commentlen;
- /** Points to the null terminated comment string
+ /** Points to the null terminated comment string
*/
char *comment;
/** The length of the name string in bytes (does not include
* null terminator)
*/
unsigned int namelen;
- /** Points to the null terminated name string
+ /** Points to the null terminated name string
*/
char name[1];
};
+/**@ingroup structure
+ * Structure that represents all attributes of a directory entry.
+ *
+ */
+struct libsmb_file_info
+{
+ /**
+ * Size of file
+ */
+ uint64_t size;
+ /**
+ * DOS attributes of file
+ */
+ uint16_t attrs;
+ /**
+ * User ID of file
+ */
+ uid_t uid;
+ /**
+ * Group ID of file
+ */
+ gid_t gid;
+ /**
+ * Birth/Create time of file (if supported by system)
+ * Otherwise the value will be 0
+ */
+ struct timespec btime_ts;
+ /**
+ * Modified time for the file
+ */
+ struct timespec mtime_ts;
+ /**
+ * Access time for the file
+ */
+ struct timespec atime_ts;
+ /**
+ * Change time for the file
+ */
+ struct timespec ctime_ts;
+ /**
+ * Name of file
+ */
+ char *name;
+ /**
+ * Short name of file
+ */
+ char *short_name;
+};
+
+/*
+ * Logging callback function
+ */
+typedef void (*smbc_debug_callback_fn)(void *private_ptr, int level, const char *msg);
+
/*
* Flags for smbc_setxattr()
* Specify a bitwise OR of these, or 0 to add or replace as necessary
#define SMBC_DOS_MODE_DIRECTORY 0x10
#define SMBC_DOS_MODE_ARCHIVE 0x20
+/*
+ * Valid values for the option "open_share_mode", when calling
+ * smbc_setOptionOpenShareMode()
+ */
+typedef enum smbc_share_mode
+{
+ SMBC_SHAREMODE_DENY_DOS = 0,
+ SMBC_SHAREMODE_DENY_ALL = 1,
+ SMBC_SHAREMODE_DENY_WRITE = 2,
+ SMBC_SHAREMODE_DENY_READ = 3,
+ SMBC_SHAREMODE_DENY_NONE = 4,
+ SMBC_SHAREMODE_DENY_FCB = 7
+} smbc_share_mode;
+
+
+/**
+ * Values for option SMB Encryption Level, as set and retrieved with
+ * smbc_setOptionSmbEncryptionLevel() and smbc_getOptionSmbEncryptionLevel()
+ */
+typedef enum smbc_smb_encrypt_level
+{
+ SMBC_ENCRYPTLEVEL_NONE = 0,
+ SMBC_ENCRYPTLEVEL_REQUEST = 1,
+ SMBC_ENCRYPTLEVEL_REQUIRE = 2
+} 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;
+
#ifndef ENOATTR
# define ENOATTR ENOENT /* No such attribute */
*
*/
#ifndef _CLIENT_H
-struct print_job_info
+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
*/
/**@ingroup structure
- * Server handle
+ * Server handle
*/
typedef struct _SMBCSRV SMBCSRV;
/**@ingroup structure
- * File or directory handle
+ * File or directory handle
*/
typedef struct _SMBCFILE SMBCFILE;
/**@ingroup structure
- * File or directory handle
+ * File or directory handle
*/
typedef struct _SMBCCTX SMBCCTX;
+/*
+ * Flags for SMBCCTX->flags
+ *
+ * NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
+ * Instead, use:
+ * smbc_setOptionUseKerberos()
+ * smbc_getOptionUseKerberos()
+ * smbc_setOptionFallbackAfterKerberos()
+ * 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)
/**@ingroup callback
- * Authentication callback function type.
- *
+ * Authentication callback function type (traditional method)
+ *
* Type for the the authentication function called by the library to
- * obtain authentication credentals
+ * obtain authentication credentials
+ *
+ * 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 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
+ * @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,
+typedef void (*smbc_get_auth_data_fn)(const char *srv,
const char *shr,
- char *wg, int wglen,
+ char *wg, int wglen,
char *un, int unlen,
char *pw, int pwlen);
+/**@ingroup callback
+ * Authentication callback function type (method that includes context)
+ *
+ * Type for the the authentication function called by the library to
+ * obtain authentication credentials
+ *
+ * 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
+ *
+ * @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_with_context_fn)(SMBCCTX *c,
+ const char *srv,
+ const char *shr,
+ char *wg, int wglen,
+ char *un, int unlen,
+ char *pw, int pwlen);
/**@ingroup callback
*
* @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
*
* @return 0 when connection is good. 1 on error.
*
- */
+ */
typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
/**@ingroup callback
*
* @return 0 on success. 1 on failure.
*
- */
+ */
typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
*
* @param srv pointer to server to add
*
- * @param server server name
+ * @param server server name
*
* @param share share name
*
*
* @return 0 on success. 1 on failure.
*
- */
-typedef int (*smbc_add_cached_srv_fn) (SMBCCTX * c, SMBCSRV *srv,
+ */
+typedef int (*smbc_add_cached_srv_fn) (SMBCCTX * c, SMBCSRV *srv,
const char * server, const char * share,
const char * workgroup, const char * username);
*
* @return pointer to SMBCSRV on success. NULL on failure.
*
- */
+ */
typedef SMBCSRV * (*smbc_get_cached_srv_fn) (SMBCCTX * c, const char * server,
const char * share, const char * workgroup,
const char * username);
*
* @return 0 when found and removed. 1 on failure.
*
- */
+ */
typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
*
* @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
+
+/*****************************************
+ * Getters and setters for CONFIGURATION *
+ *****************************************/
+
+/** Get the debug level */
+int
+smbc_getDebug(SMBCCTX *c);
+
+/** Set the debug level */
+void
+smbc_setDebug(SMBCCTX *c, int debug);
+
+/**
+ * set log callback function to capture logs from libsmbclient, this
+ * is applied at global level
*/
-struct _SMBCCTX {
- /** debug level
- */
- int debug;
-
- /** netbios name used for making connections
- */
- char * netbios_name;
+void
+smbc_setLogCallback(SMBCCTX *c, void *private_ptr,
+ smbc_debug_callback_fn fn);
- /** workgroup name used for making connections
- */
- char * workgroup;
+/** set configuration file, this is applied at global level */
+int
+smbc_setConfiguration(SMBCCTX *c, const char *file);
- /** username used for making connections
- */
- char * user;
+/** Get the netbios name used for making connections */
+const char *
+smbc_getNetbiosName(SMBCCTX *c);
- /** 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);
+/** Set the netbios name used for making connections */
+void
+smbc_setNetbiosName(SMBCCTX *c, const char *netbios_name);
- /** 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);
+/** Get the workgroup used for making connections */
+const char *
+smbc_getWorkgroup(SMBCCTX *c);
+/** Set the workgroup used for making connections */
+void smbc_setWorkgroup(SMBCCTX *c, const char *workgroup);
- /** 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;
+/** Get the username used for making connections */
+const char *
+smbc_getUser(SMBCCTX *c);
- /** remove a server if unused
- */
- smbc_remove_unused_server_fn remove_unused_server_fn;
+/** Set the username used for making connections */
+void
+smbc_setUser(SMBCCTX *c, const char *user);
- /** Cache subsystem
- * For an example cache system see samba/source/libsmb/libsmb_cache.c
- * Cache subsystem functions follow.
- */
+/**
+ * Get the timeout used for waiting on connections and response data
+ * (in milliseconds)
+ */
+int
+smbc_getTimeout(SMBCCTX *c);
- /** server cache addition
- */
- smbc_add_cached_srv_fn add_cached_srv_fn;
+/**
+ * Set the timeout used for waiting on connections and response data
+ * (in milliseconds)
+ */
+void
+smbc_setTimeout(SMBCCTX *c, int timeout);
- /** 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;
+/**
+ * Get the TCP port used to connect (0 means default).
+ */
+uint16_t
+smbc_getPort(SMBCCTX *c);
+/**
+ * Set the TCP port used to connect (0 means default).
+ */
+void
+smbc_setPort(SMBCCTX *c, uint16_t port);
- /** 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;
+/***********************************
+ * Getters and setters for OPTIONS *
+ ***********************************/
+
+/** Get whether to log to standard error instead of standard output */
+smbc_bool
+smbc_getOptionDebugToStderr(SMBCCTX *c);
+
+/** Set whether to log to standard error instead of standard output */
+void
+smbc_setOptionDebugToStderr(SMBCCTX *c, smbc_bool b);
+
+/**
+ * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
+ * than the old-style names such as M_TIME. This allows also setting/getting
+ * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
+ * was supposed to be CHANGE_TIME but was confused and sometimes referred to
+ * CREATE_TIME.)
+ */
+smbc_bool
+smbc_getOptionFullTimeNames(SMBCCTX *c);
+
+/**
+ * Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
+ * than the old-style names such as M_TIME. This allows also setting/getting
+ * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
+ * was supposed to be CHANGE_TIME but was confused and sometimes referred to
+ * CREATE_TIME.)
+ */
+void
+smbc_setOptionFullTimeNames(SMBCCTX *c, smbc_bool b);
+
+/**
+ * Get the share mode to use for files opened with SMBC_open_ctx(). The
+ * default is SMBC_SHAREMODE_DENY_NONE.
+ */
+smbc_share_mode
+smbc_getOptionOpenShareMode(SMBCCTX *c);
+
+/**
+ * Set the share mode to use for files opened with SMBC_open_ctx(). The
+ * default is SMBC_SHAREMODE_DENY_NONE.
+ */
+void
+smbc_setOptionOpenShareMode(SMBCCTX *c, smbc_share_mode share_mode);
+
+/** Retrieve a previously saved user data handle */
+void *
+smbc_getOptionUserData(SMBCCTX *c);
+
+/** Save a user data handle */
+void
+smbc_setOptionUserData(SMBCCTX *c, void *user_data);
+
+/** Get the encoded value for encryption level. */
+smbc_smb_encrypt_level
+smbc_getOptionSmbEncryptionLevel(SMBCCTX *c);
+
+/** Set the encoded value for encryption level. */
+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
+ * 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
+smbc_getOptionBrowseMaxLmbCount(SMBCCTX *c);
+
+/**
+ * Set 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).
+ */
+void
+smbc_setOptionBrowseMaxLmbCount(SMBCCTX *c, int count);
+
+/**
+ * Get whether to url-encode readdir entries.
+ *
+ * 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.
+ */
+smbc_bool
+smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX *c);
+
+/**
+ * Set whether to url-encode readdir entries.
+ *
+ * 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.
+ */
+void
+smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX *c, smbc_bool b);
+
+/**
+ * Get whether to use the same connection for all shares on a server.
+ *
+ * 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.
+ */
+smbc_bool
+smbc_getOptionOneSharePerServer(SMBCCTX *c);
+
+/**
+ * Set whether to use the same connection for all shares on a server.
+ *
+ * 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.
+ */
+void
+smbc_setOptionOneSharePerServer(SMBCCTX *c, smbc_bool b);
+
+/** Get whether to enable use of kerberos */
+smbc_bool
+smbc_getOptionUseKerberos(SMBCCTX *c);
+
+/** Set whether to enable use of kerberos */
+void
+smbc_setOptionUseKerberos(SMBCCTX *c, smbc_bool b);
+
+/** Get whether to fallback after kerberos */
+smbc_bool
+smbc_getOptionFallbackAfterKerberos(SMBCCTX *c);
+
+/** Set whether to fallback after kerberos */
+void
+smbc_setOptionFallbackAfterKerberos(SMBCCTX *c, smbc_bool b);
+
+/** Get whether to automatically select anonymous login */
+smbc_bool
+smbc_getOptionNoAutoAnonymousLogin(SMBCCTX *c);
+
+/** Set whether to automatically select anonymous login */
+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);
+
+
+
+/*************************************
+ * Getters and setters for FUNCTIONS *
+ *************************************/
+
+/** Get the function for obtaining authentication data */
+smbc_get_auth_data_fn smbc_getFunctionAuthData(SMBCCTX *c);
+
+/** Set the function for obtaining authentication data */
+void smbc_setFunctionAuthData(SMBCCTX *c, smbc_get_auth_data_fn fn);
+
+/** Get the new-style authentication function which includes the context. */
+smbc_get_auth_data_with_context_fn
+smbc_getFunctionAuthDataWithContext(SMBCCTX *c);
+
+/** Set the new-style authentication function which includes the context. */
+void
+smbc_setFunctionAuthDataWithContext(SMBCCTX *c,
+ smbc_get_auth_data_with_context_fn fn);
+
+/** Get the function for checking if a server is still good */
+smbc_check_server_fn smbc_getFunctionCheckServer(SMBCCTX *c);
+
+/** Set the function for checking if a server is still good */
+void smbc_setFunctionCheckServer(SMBCCTX *c, smbc_check_server_fn fn);
+
+/** Get the function for removing a server if unused */
+smbc_remove_unused_server_fn smbc_getFunctionRemoveUnusedServer(SMBCCTX *c);
+
+/** Set the function for removing a server if unused */
+void smbc_setFunctionRemoveUnusedServer(SMBCCTX *c,
+ smbc_remove_unused_server_fn fn);
+
+/** Get the function for adding a cached server */
+smbc_add_cached_srv_fn smbc_getFunctionAddCachedServer(SMBCCTX *c);
+
+/** Set the function for adding a cached server */
+void smbc_setFunctionAddCachedServer(SMBCCTX *c, smbc_add_cached_srv_fn fn);
+
+/** Get the function for server cache lookup */
+smbc_get_cached_srv_fn smbc_getFunctionGetCachedServer(SMBCCTX *c);
+
+/** Set the function for server cache lookup */
+void smbc_setFunctionGetCachedServer(SMBCCTX *c, smbc_get_cached_srv_fn fn);
+
+/** Get the function for server cache removal */
+smbc_remove_cached_srv_fn smbc_getFunctionRemoveCachedServer(SMBCCTX *c);
+
+/** Set the function for server cache removal */
+void smbc_setFunctionRemoveCachedServer(SMBCCTX *c,
+ smbc_remove_cached_srv_fn fn);
+
+/**
+ * Get the function for server cache purging. This function tries to
+ * remove all cached servers (e.g. on disconnect)
+ */
+smbc_purge_cached_fn smbc_getFunctionPurgeCachedServers(SMBCCTX *c);
+
+/**
+ * Set the function for server cache purging. This function tries to
+ * remove all cached servers (e.g. on disconnect)
+ */
+void smbc_setFunctionPurgeCachedServers(SMBCCTX *c,
+ smbc_purge_cached_fn fn);
+
+/** Get the function to store private data of the server cache */
+struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
+
+/** Set the function to store private data of the server cache */
+void smbc_setServerCacheData(SMBCCTX *c, struct smbc_server_cache * cache);
+
+
+
+/*****************************************************************
+ * Callable functions for files. *
+ * Each callable has a function signature typedef, a declaration *
+ * for the getter, and a declaration for the setter. *
+ *****************************************************************/
+
+typedef SMBCFILE * (*smbc_open_fn)(SMBCCTX *c,
+ const char *fname,
+ int flags,
+ mode_t mode);
+smbc_open_fn smbc_getFunctionOpen(SMBCCTX *c);
+void smbc_setFunctionOpen(SMBCCTX *c, smbc_open_fn fn);
+
+typedef SMBCFILE * (*smbc_creat_fn)(SMBCCTX *c,
+ const char *path,
+ mode_t mode);
+smbc_creat_fn smbc_getFunctionCreat(SMBCCTX *c);
+void smbc_setFunctionCreat(SMBCCTX *c, smbc_creat_fn);
+
+typedef ssize_t (*smbc_read_fn)(SMBCCTX *c,
+ SMBCFILE *file,
+ void *buf,
+ size_t count);
+smbc_read_fn smbc_getFunctionRead(SMBCCTX *c);
+void smbc_setFunctionRead(SMBCCTX *c, smbc_read_fn fn);
+
+typedef ssize_t (*smbc_write_fn)(SMBCCTX *c,
+ SMBCFILE *file,
+ const void *buf,
+ size_t count);
+smbc_write_fn smbc_getFunctionWrite(SMBCCTX *c);
+void smbc_setFunctionWrite(SMBCCTX *c, smbc_write_fn fn);
+
+typedef off_t (*smbc_splice_fn)(SMBCCTX *c,
+ SMBCFILE *srcfile,
+ SMBCFILE *dstfile,
+ off_t count,
+ int (*splice_cb)(off_t n, void *priv),
+ void *priv);
+smbc_splice_fn smbc_getFunctionSplice(SMBCCTX *c);
+void smbc_setFunctionSplice(SMBCCTX *c, smbc_splice_fn fn);
+
+typedef int (*smbc_unlink_fn)(SMBCCTX *c,
+ const char *fname);
+smbc_unlink_fn smbc_getFunctionUnlink(SMBCCTX *c);
+void smbc_setFunctionUnlink(SMBCCTX *c, smbc_unlink_fn fn);
+
+typedef int (*smbc_rename_fn)(SMBCCTX *ocontext,
+ const char *oname,
+ SMBCCTX *ncontext,
+ const char *nname);
+smbc_rename_fn smbc_getFunctionRename(SMBCCTX *c);
+void smbc_setFunctionRename(SMBCCTX *c, smbc_rename_fn fn);
+
+typedef off_t (*smbc_lseek_fn)(SMBCCTX *c,
+ SMBCFILE * file,
+ off_t offset,
+ int whence);
+smbc_lseek_fn smbc_getFunctionLseek(SMBCCTX *c);
+void smbc_setFunctionLseek(SMBCCTX *c, smbc_lseek_fn fn);
+
+typedef int (*smbc_stat_fn)(SMBCCTX *c,
+ const char *fname,
+ struct stat *st);
+smbc_stat_fn smbc_getFunctionStat(SMBCCTX *c);
+void smbc_setFunctionStat(SMBCCTX *c, smbc_stat_fn fn);
+
+typedef int (*smbc_fstat_fn)(SMBCCTX *c,
+ SMBCFILE *file,
+ struct stat *st);
+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);
+smbc_ftruncate_fn smbc_getFunctionFtruncate(SMBCCTX *c);
+void smbc_setFunctionFtruncate(SMBCCTX *c, smbc_ftruncate_fn fn);
+
+typedef int (*smbc_close_fn)(SMBCCTX *c,
+ SMBCFILE *file);
+smbc_close_fn smbc_getFunctionClose(SMBCCTX *c);
+void smbc_setFunctionClose(SMBCCTX *c, smbc_close_fn fn);
+
+
+
+/*****************************************************************
+ * Callable functions for directories. *
+ * Each callable has a function signature typedef, a declaration *
+ * for the getter, and a declaration for the setter. *
+ *****************************************************************/
+
+typedef SMBCFILE * (*smbc_opendir_fn)(SMBCCTX *c,
+ const char *fname);
+smbc_opendir_fn smbc_getFunctionOpendir(SMBCCTX *c);
+void smbc_setFunctionOpendir(SMBCCTX *c, smbc_opendir_fn fn);
+
+typedef int (*smbc_closedir_fn)(SMBCCTX *c,
+ SMBCFILE *dir);
+smbc_closedir_fn smbc_getFunctionClosedir(SMBCCTX *c);
+void smbc_setFunctionClosedir(SMBCCTX *c, smbc_closedir_fn fn);
+
+typedef struct smbc_dirent * (*smbc_readdir_fn)(SMBCCTX *c,
+ SMBCFILE *dir);
+smbc_readdir_fn smbc_getFunctionReaddir(SMBCCTX *c);
+void smbc_setFunctionReaddir(SMBCCTX *c, smbc_readdir_fn fn);
+
+typedef const struct libsmb_file_info * (*smbc_readdirplus_fn)(SMBCCTX *c,
+ SMBCFILE *dir);
+smbc_readdirplus_fn smbc_getFunctionReaddirPlus(SMBCCTX *c);
+void smbc_setFunctionReaddirPlus(SMBCCTX *c, smbc_readdirplus_fn fn);
+
+typedef int (*smbc_getdents_fn)(SMBCCTX *c,
+ SMBCFILE *dir,
+ struct smbc_dirent *dirp,
+ int count);
+smbc_getdents_fn smbc_getFunctionGetdents(SMBCCTX *c);
+void smbc_setFunctionGetdents(SMBCCTX *c, smbc_getdents_fn fn);
+
+typedef int (*smbc_mkdir_fn)(SMBCCTX *c,
+ const char *fname,
+ mode_t mode);
+smbc_mkdir_fn smbc_getFunctionMkdir(SMBCCTX *c);
+void smbc_setFunctionMkdir(SMBCCTX *c, smbc_mkdir_fn fn);
+
+typedef int (*smbc_rmdir_fn)(SMBCCTX *c,
+ const char *fname);
+smbc_rmdir_fn smbc_getFunctionRmdir(SMBCCTX *c);
+void smbc_setFunctionRmdir(SMBCCTX *c, smbc_rmdir_fn fn);
+
+typedef off_t (*smbc_telldir_fn)(SMBCCTX *c,
+ SMBCFILE *dir);
+smbc_telldir_fn smbc_getFunctionTelldir(SMBCCTX *c);
+void smbc_setFunctionTelldir(SMBCCTX *c, smbc_telldir_fn fn);
+
+typedef int (*smbc_lseekdir_fn)(SMBCCTX *c,
+ SMBCFILE *dir,
+ off_t offset);
+smbc_lseekdir_fn smbc_getFunctionLseekdir(SMBCCTX *c);
+void smbc_setFunctionLseekdir(SMBCCTX *c, smbc_lseekdir_fn fn);
+
+typedef int (*smbc_fstatdir_fn)(SMBCCTX *c,
+ SMBCFILE *dir,
+ struct stat *st);
+smbc_fstatdir_fn smbc_getFunctionFstatdir(SMBCCTX *c);
+void smbc_setFunctionFstatdir(SMBCCTX *c, smbc_fstatdir_fn fn);
+
+#define SMBC_NOTIFY_ACTION_ADDED 1
+#define SMBC_NOTIFY_ACTION_REMOVED 2
+#define SMBC_NOTIFY_ACTION_MODIFIED 3
+#define SMBC_NOTIFY_ACTION_OLD_NAME 4
+#define SMBC_NOTIFY_ACTION_NEW_NAME 5
+#define SMBC_NOTIFY_ACTION_ADDED_STREAM 6
+#define SMBC_NOTIFY_ACTION_REMOVED_STREAM 7
+#define SMBC_NOTIFY_ACTION_MODIFIED_STREAM 8
+
+struct smbc_notify_callback_action {
+ uint32_t action;
+ const char *filename;
};
-/* 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 */
+typedef int (*smbc_notify_callback_fn)(
+ const struct smbc_notify_callback_action *actions,
+ size_t num_actions, void *private_data);
+
+typedef int (*smbc_notify_fn)(SMBCCTX *c, SMBCFILE *dir, smbc_bool recursive,
+ uint32_t completion_filter,
+ unsigned callback_timeout_ms,
+ smbc_notify_callback_fn cb, void *private_data);
+smbc_notify_fn smbc_getFunctionNotify(SMBCCTX *c);
+void smbc_setFunctionNotify(SMBCCTX *c, smbc_notify_fn fn);
+
+
+/*****************************************************************
+ * Callable functions applicable to both files and directories. *
+ * Each callable has a function signature typedef, a declaration *
+ * for the getter, and a declaration for the setter. *
+ *****************************************************************/
+
+typedef int (*smbc_chmod_fn)(SMBCCTX *c,
+ const char *fname,
+ mode_t mode);
+smbc_chmod_fn smbc_getFunctionChmod(SMBCCTX *c);
+void smbc_setFunctionChmod(SMBCCTX *c, smbc_chmod_fn fn);
+
+typedef int (*smbc_utimes_fn)(SMBCCTX *c,
+ const char *fname,
+ struct timeval *tbuf);
+smbc_utimes_fn smbc_getFunctionUtimes(SMBCCTX *c);
+void smbc_setFunctionUtimes(SMBCCTX *c, smbc_utimes_fn fn);
+
+typedef int (*smbc_setxattr_fn)(SMBCCTX *context,
+ const char *fname,
+ const char *name,
+ const void *value,
+ size_t size,
+ int flags);
+smbc_setxattr_fn smbc_getFunctionSetxattr(SMBCCTX *c);
+void smbc_setFunctionSetxattr(SMBCCTX *c, smbc_setxattr_fn fn);
+
+typedef int (*smbc_getxattr_fn)(SMBCCTX *context,
+ const char *fname,
+ const char *name,
+ const void *value,
+ size_t size);
+smbc_getxattr_fn smbc_getFunctionGetxattr(SMBCCTX *c);
+void smbc_setFunctionGetxattr(SMBCCTX *c, smbc_getxattr_fn fn);
+
+typedef int (*smbc_removexattr_fn)(SMBCCTX *context,
+ const char *fname,
+ const char *name);
+smbc_removexattr_fn smbc_getFunctionRemovexattr(SMBCCTX *c);
+void smbc_setFunctionRemovexattr(SMBCCTX *c, smbc_removexattr_fn fn);
+
+typedef int (*smbc_listxattr_fn)(SMBCCTX *context,
+ const char *fname,
+ char *list,
+ size_t size);
+smbc_listxattr_fn smbc_getFunctionListxattr(SMBCCTX *c);
+void smbc_setFunctionListxattr(SMBCCTX *c, smbc_listxattr_fn fn);
+
+
+
+/*****************************************************************
+ * Callable functions for printing. *
+ * Each callable has a function signature typedef, a declaration *
+ * for the getter, and a declaration for the setter. *
+ *****************************************************************/
+
+typedef int (*smbc_print_file_fn)(SMBCCTX *c_file,
+ const char *fname,
+ SMBCCTX *c_print,
+ const char *printq);
+smbc_print_file_fn smbc_getFunctionPrintFile(SMBCCTX *c);
+void smbc_setFunctionPrintFile(SMBCCTX *c, smbc_print_file_fn fn);
+
+typedef SMBCFILE * (*smbc_open_print_job_fn)(SMBCCTX *c,
+ const char *fname);
+smbc_open_print_job_fn smbc_getFunctionOpenPrintJob(SMBCCTX *c);
+void smbc_setFunctionOpenPrintJob(SMBCCTX *c,
+ smbc_open_print_job_fn fn);
+
+typedef int (*smbc_list_print_jobs_fn)(SMBCCTX *c,
+ const char *fname,
+ smbc_list_print_job_fn fn);
+smbc_list_print_jobs_fn smbc_getFunctionListPrintJobs(SMBCCTX *c);
+void smbc_setFunctionListPrintJobs(SMBCCTX *c,
+ smbc_list_print_jobs_fn fn);
+
+typedef int (*smbc_unlink_print_job_fn)(SMBCCTX *c,
+ const char *fname,
+ int id);
+smbc_unlink_print_job_fn smbc_getFunctionUnlinkPrintJob(SMBCCTX *c);
+void smbc_setFunctionUnlinkPrintJob(SMBCCTX *c,
+ smbc_unlink_print_job_fn fn);
+
/**@ingroup misc
* Create a new SBMCCTX (a context).
*
*
* @return Returns 0 on succes. Returns 1 on failure with errno set:
- * - EBUSY Server connections are still used, Files are open or cache
+ * - EBUSY Server connections are still used, Files are open or cache
* could not be purged
* - EBADF context == NULL
*
int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
+/**@ingroup misc
+ *
+ * @deprecated. Use smbc_setOption*() functions instead.
+ */
+void
+smbc_option_set(SMBCCTX *context,
+ char *option_name,
+ ... /* option_value */);
+
+/*
+ * @deprecated. Use smbc_getOption*() functions instead.
+ */
+void *
+smbc_option_get(SMBCCTX *context,
+ char *option_name);
+
/**@ingroup misc
* Initialize a SBMCCTX (a context).
*
*
* @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:
+ * @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.
+ * @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);
* 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
+ *
+ * @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
/**@ingroup file
* Open a file on an SMB server.
*
- * @param furl The smb url of the file to be opened.
+ * @param furl The smb url of the file to be opened.
*
- * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
+ * @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
+ * 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_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
+ * 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
+ * @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)
+ * of the created file are (mode & ~umask)
*
* Not currently use, but there for future use.
* We will map this to SYSTEM, HIDDEN, etc bits
*
* @return Valid file handle, < 0 on error with errno set:
* - ENOMEM Out of memory
- * - EINVAL if an invalid parameter passed, like no
+ * - EINVAL if an invalid parameter passed, like no
* file, or smbc_init not called.
- * - EEXIST pathname already exists and O_CREAT and
+ * - EEXIST pathname already exists and O_CREAT and
* O_EXCL were used.
- * - EISDIR pathname refers to a directory and
+ * - EISDIR pathname refers to a directory and
* the access requested involved writing.
- * - EACCES The requested access to the file is not
- * allowed
+ * - 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
+ * - ENOENT A directory component in pathname does
* not exist.
*
* @see smbc_creat()
* 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
+ * try again with an empty username and password. This
* often gets mapped to the guest account on some machines.
*/
/**@ingroup file
* Create a file on an SMB server.
*
- * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
- *
+ * 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
+ *
+ * @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
+ * 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
+ * - 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
+ * allowed
+ * - ENOENT A directory component in pathname does
* not exist.
* - ENODEV The requested share does not exist.
* @see smbc_open()
*
* @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.
- * - EINVAL fd is attached to an object which is
- * unsuitable for reading, or no buffer passed or
- * smbc_init not called.
+ * - 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()
*
*
* @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
+ * - EBADF fd is not a valid file descriptor or
* is not open for reading.
- * - EINVAL fd is attached to an object which is
+ * - 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);
+ssize_t smbc_write(int fd, const 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
+ * - SEEK_CUR The offset is set to current location
* plus offset bytes.
- * - SEEK_END The offset is set to the size of the
+ * - 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
+ * @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
+ * 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);
* @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
+ * - 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
/**@ingroup directory
* Rename or move a file or directory.
- *
- * @param ourl The original smb url (source url) of file or
+ *
+ * @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,
+ * - EEXIST nurl is a non-empty directory,
* i.e., contains entries other than "." and ".."
- * - EINVAL The new url contained a path prefix
+ * - 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,
+ * - 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
+ * - 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
+ * - ENOENT A directory component in ourl or nurl
* does not exist.
* - EXDEV Rename across shares not supported.
* - ENOMEM Insufficient kernel memory was available.
* - 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.
+ * - 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.
/**@ingroup directory
* Get multiple directory entries.
*
- * smbc_getdents() reads as many dirent structures from the an open
+ * 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
*/
struct smbc_dirent* smbc_readdir(unsigned int dh);
+/**@ingroup directory
+ * Works similar as smbc_readdir but returns more information about file.
+ *
+ * @param dh Valid directory as returned by smbc_opendir()
+ *
+ * @return A const pointer to a libsmb_file_info 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_open(), smbc_readdir()
+ */
+const struct libsmb_file_info *smbc_readdirplus(unsigned int dh);
+
/**@ingroup directory
* Get the current directory offset.
*
* @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
+ * 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
* 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
*
* @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
+ * 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
/**@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:
* - ENOTEMPTY directory contains entries.
* - ENOMEM Insufficient kernel memory was available.
*
- * @see smbc_mkdir(), smbc_unlink()
+ * @see smbc_mkdir(), smbc_unlink()
*
* @todo Are errno values complete and correct?
*/
int smbc_rmdir(const char *durl);
+/**@ingroup directory
+ * Request directory notifications
+ *
+ * @param dh Valid directory as returned by smbc_opendir()
+ *
+ * @param recursive Are changes in subdirectories wanted?
+ *
+ * @param completion_filter Bitwise-or of the SMBC_NOTIFY_CHANGE_*
+ * events that are interesting
+ *
+ * @param callback_timeout_ms If set to non-zero, interval in milliseconds
+ * that "cb" will be called with 0 actions.
+ * This gives "cb" the chance to cancel the
+ * smbc_notify call.
+ *
+ * @param cb Callback functions taking events. If "cb"
+ * returns nonzero, smbc_notify will return.
+ *
+ * @param private_data Pointer given to "cb"
+ *
+ * @return 0 on success, -1 on error with errno set
+ *
+ * @see smbc_opendir(), smbc_closedir()
+ */
+
+#define SMBC_NOTIFY_CHANGE_FILE_NAME 0x001
+#define SMBC_NOTIFY_CHANGE_DIR_NAME 0x002
+#define SMBC_NOTIFY_CHANGE_ATTRIBUTES 0x004
+#define SMBC_NOTIFY_CHANGE_SIZE 0x008
+#define SMBC_NOTIFY_CHANGE_LAST_WRITE 0x010
+#define SMBC_NOTIFY_CHANGE_LAST_ACCESS 0x020
+#define SMBC_NOTIFY_CHANGE_CREATION 0x040
+#define SMBC_NOTIFY_CHANGE_EA 0x080
+#define SMBC_NOTIFY_CHANGE_SECURITY 0x100
+#define SMBC_NOTIFY_CHANGE_STREAM_NAME 0x200
+#define SMBC_NOTIFY_CHANGE_STREAM_SIZE 0x400
+#define SMBC_NOTIFY_CHANGE_STREAM_WRITE 0x800
+
+int smbc_notify(int dh, smbc_bool recursive, uint32_t completion_filter,
+ unsigned callback_timeout_ms,
+ smbc_notify_callback_fn cb, void *private_data);
/**@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
+ * @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:
/**@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
+ * @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
int smbc_fstat(int fd, struct stat *st);
-/**@ingroup attribue
- * Change the ownership of a file or directory.
+/**@ingroup attribute
+ * Get file system information for a specified path.
+ *
+ * @param url The smb url to get information for
+ *
+ * @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
+ *
+ * @see Unix fstatvfs()
*
- * @param url The smb url of the file or directory to change
- * ownership of.
+ */
+int
+smbc_statvfs(char *url,
+ struct statvfs *st);
+
+/**@ingroup attribute
+ * Get file system information via an file descriptor.
*
- * @param owner I have no idea?
+ * @param fd Open file handle from smbc_open(), smbc_creat(),
+ * or smbc_opendir()
*
- * @param group I have not idea?
+ * @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:
- * - 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
+ * - 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 fstatvfs()
+ *
+ */
+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()
*
- * @todo Are we actually going to be able to implement this function
+ * @param size size to truncate the file to
*
- * @todo How do we abstract owner and group uid and gid?
+ * @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()
*
*/
-int smbc_chown(const char *url, uid_t owner, gid_t group);
+int smbc_ftruncate(int fd, off_t size);
/**@ingroup attribute
*
* @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!
*
*/
int smbc_chmod(const char *url, mode_t mode);
-/**@ingroup attribute
+/**
+ * @ingroup attribute
* Change the last modification time on a file
*
* @param url The smb url of the file or directory to change
* the modification time of
- *
- * @param tbuf A timeval structure which contains the desired
- * modification time. NOTE: Only the tv_sec field is
+ *
+ * @param tbuf An array of two timeval structures which contains,
+ * respectively, the desired access and modification times.
+ * NOTE: Only the tv_sec field off each timeval structure is
* used. The tv_usec (microseconds) portion is ignored.
*
* @return 0 on success, < 0 on error with errno set:
int smbc_utimes(const char *url, struct timeval *tbuf);
#ifdef HAVE_UTIME_H
-/**@ingroup attribute
+/**
+ * @ingroup attribute
* Change the last modification time on a file
*
* @param url The smb url of the file or directory to change
* the modification time of
- *
- * @param utbuf A utimebuf structure which contains the desired
- * modification time. NOTE: Although the structure contains
- * an access time as well, the access time value is ignored.
+ *
+ * @param utbuf A pointer to a utimebuf structure which contains the
+ * desired access and modification times.
*
* @return 0 on success, < 0 on error with errno set:
* - EINVAL The client library is not properly initialized
*
* @param url The smb url of the file or directory to set extended
* attributes for.
- *
+ *
* @param name The name of an attribute to be changed. Names are of
* one of the following forms:
*
*
* @param url The smb url of the file or directory to set extended
* attributes for.
- *
+ *
* @param name The name of an attribute to be changed. Names are of
* one of the following forms:
*
* @param fd A file descriptor associated with an open file (as
* previously returned by smbc_open(), to get extended
* attributes for.
- *
+ *
* @param name The name of an attribute to be changed. Names are of
* one of the following forms:
*
*
* @param url The smb url of the file or directory to get extended
* attributes for.
- *
+ *
* @param name The name of an attribute to be retrieved. Names are of
* one of the following forms:
*
* may also be zero, in which case the size of the buffer
* required to hold the attribute value will be returned,
* but nothing will be placed into the value buffer.
- *
+ *
* @return 0 on success, < 0 on error with errno set:
* - EINVAL The client library is not properly initialized
* or one of the parameters is not of a correct
*
* @param url The smb url of the file or directory to get extended
* attributes for.
- *
+ *
* @param name The name of an attribute to be retrieved. Names are of
* one of the following forms:
*
* may also be zero, in which case the size of the buffer
* required to hold the attribute value will be returned,
* but nothing will be placed into the value buffer.
- *
+ *
* @return 0 on success, < 0 on error with errno set:
* - EINVAL The client library is not properly initialized
* or one of the parameters is not of a correct
* @param fd A file descriptor associated with an open file (as
* previously returned by smbc_open(), to get extended
* attributes for.
- *
+ *
* @param name The name of an attribute to be retrieved. Names are of
* one of the following forms:
*
* may also be zero, in which case the size of the buffer
* required to hold the attribute value will be returned,
* but nothing will be placed into the value buffer.
- *
+ *
* @return 0 on success, < 0 on error with errno set:
* - EINVAL The client library is not properly initialized
* or one of the parameters is not of a correct
*
* @param url The smb url of the file or directory to remove the extended
* attributes for.
- *
+ *
* @param name The name of an attribute to be removed. Names are of
* one of the following forms:
*
*
* @param url The smb url of the file or directory to remove the extended
* attributes for.
- *
+ *
* @param name The name of an attribute to be removed. Names are of
* one of the following forms:
*
* @param fd A file descriptor associated with an open file (as
* previously returned by smbc_open(), to get extended
* attributes for.
- *
+ *
* @param name The name of an attribute to be removed. Names are of
* one of the following forms:
*
* may also be zero, in which case the size of the buffer
* required to hold all of the attribute names will be
* returned, but nothing will be placed into the list buffer.
- *
+ *
* @return 0 on success, < 0 on error with errno set:
* - EINVAL The client library is not properly initialized
* - ENOMEM No memory was available for internal needs
* extended attributes
*
* @note This function always returns all attribute names supported
- * by NT file systems, regardless of wether the referenced
+ * by NT file systems, regardless of whether the referenced
* file system supports extended attributes (e.g. a Windows
* 2000 machine supports extended attributes if NTFS is used,
* but not if FAT is used, and Windows 98 doesn't support
* may also be zero, in which case the size of the buffer
* required to hold all of the attribute names will be
* returned, but nothing will be placed into the list buffer.
- *
+ *
* @return 0 on success, < 0 on error with errno set:
* - EINVAL The client library is not properly initialized
* - ENOMEM No memory was available for internal needs
* @param fd A file descriptor associated with an open file (as
* previously returned by smbc_open(), to get extended
* attributes for.
- *
+ *
* @param list A pointer to a buffer in which the list of attributes for
* the specified file or directory will be placed (unless
* size is zero).
* may also be zero, in which case the size of the buffer
* required to hold all of the attribute names will be
* returned, but nothing will be placed into the list buffer.
- *
+ *
* @return 0 on success, < 0 on error with errno set:
* - EINVAL The client library is not properly initialized
* - ENOMEM No memory was available for internal needs
/**@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:
+ * @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
int smbc_open_print_job(const char *fname);
/**@ingroup print
- * List the print jobs on a print share, for the moment, pass a callback
+ * 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:
+ *
+ * @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
+ * 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:
+ * @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?
* @param dest A pointer to a buffer in which the resulting decoded
* string should be placed. This may be a pointer to the
* same buffer as src_segment.
- *
+ *
* @param src A pointer to the buffer containing the URL to be decoded.
* Any %xx sequences herein are converted to their single
* character equivalent. Each 'x' must be a valid hexadecimal
*
* @param max_dest_len
* The size of the buffer pointed to by dest_segment.
- *
+ *
* @return The number of % sequences which could not be converted
* due to lack of two following hexadecimal digits.
*/
* @param dest A pointer to a buffer in which the resulting encoded
* string should be placed. Unlike smbc_urldecode(), this
* must be a buffer unique from src.
- *
+ *
* @param src A pointer to the buffer containing the string to be encoded.
* Any character not specifically allowed in a URL is converted
* into its hexadecimal value and encoded as %xx.
*
* @param max_dest_len
* The size of the buffer pointed to by dest_segment.
- *
+ *
* @returns The remaining buffer length.
*/
#ifdef __cplusplus
}
#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
+ * This structure is known as SMBCCTX
+ *
+ * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE! The data in the context
+ * structure should all be considered private to the library. It remains here
+ * only for backward compatibility.
+ *
+ * See the comments herein for use of the setter and getter functions which
+ * should now be used for manipulating these values. New features, functions,
+ * etc., are not added here but rather in _internal where they are not
+ * directly visible to applications. This makes it much easier to maintain
+ * ABI compatibility.
+ */
+struct _SMBCCTX
+{
+ /**
+ * debug level
+ *
+ * DEPRECATED:
+ * Use smbc_getDebug() and smbc_setDebug()
+ */
+ int debug DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * netbios name used for making connections
+ *
+ * DEPRECATED:
+ * Use smbc_getNetbiosName() and smbc_setNetbiosName()
+ */
+ char * netbios_name DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * workgroup name used for making connections
+ *
+ * DEPRECATED:
+ * Use smbc_getWorkgroup() and smbc_setWorkgroup()
+ */
+ char * workgroup DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * username used for making connections
+ *
+ * DEPRECATED:
+ * Use smbc_getUser() and smbc_setUser()
+ */
+ char * user DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * timeout used for waiting on connections / response data (in
+ * milliseconds)
+ *
+ * DEPRECATED:
+ * Use smbc_getTimeout() and smbc_setTimeout()
+ */
+ int timeout DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * callable functions for files:
+ * For usage and return values see the SMBC_* functions
+ *
+ * DEPRECATED:
+ *
+ * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
+ * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
+ */
+ 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_INTERFACE;
+ smbc_opendir_fn opendir DEPRECATED_SMBC_INTERFACE;
+ smbc_closedir_fn closedir DEPRECATED_SMBC_INTERFACE;
+ smbc_readdir_fn readdir DEPRECATED_SMBC_INTERFACE;
+ smbc_readdirplus_fn readdirplus 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_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:
+ *
+ * See the comment above each field, for the getter and setter
+ * functions that should now be used.
+ */
+ struct _smbc_callbacks
+ {
+ /**
+ * authentication function callback: called upon auth requests
+ *
+ * DEPRECATED:
+ * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
+ */
+ smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * check if a server is still good
+ *
+ * DEPRECATED:
+ * Use smbc_getFunctionCheckServer(),
+ * smbc_setFunctionCheckServer()
+ */
+ smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * remove a server if unused
+ *
+ * DEPRECATED:
+ * Use smbc_getFunctionRemoveUnusedServer(),
+ * smbc_setFunctionCheckServer()
+ */
+ smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE;
+
+ /** Cache subsystem
+ *
+ * For an example cache system see
+ * samba/source/libsmb/libsmb_cache.c
+ *
+ * Cache subsystem * functions follow.
+ */
+
+ /**
+ * server cache addition
+ *
+ * DEPRECATED:
+ * Use smbc_getFunctionAddCachedServer(),
+ * smbc_setFunctionAddCachedServer()
+ */
+ smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * server cache lookup
+ *
+ * DEPRECATED:
+ * Use smbc_getFunctionGetCachedServer(),
+ * smbc_setFunctionGetCachedServer()
+ */
+ smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * server cache removal
+ *
+ * DEPRECATED:
+ * Use smbc_getFunctionRemoveCachedServer(),
+ * smbc_setFunctionRemoveCachedServer()
+ */
+ smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * server cache purging, try to remove all cached servers
+ * (disconnect)
+ *
+ * DEPRECATED:
+ * Use smbc_getFunctionPurgeCachedServers(),
+ * smbc_setFunctionPurgeCachedServers()
+ */
+ smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE;
+ } callbacks;
+
+ /**
+ * Space where the private data of the server cache used to be
+ *
+ * DEPRECATED:
+ * Use smbc_getServerCacheData(), smbc_setServerCacheData()
+ */
+ void * reserved DEPRECATED_SMBC_INTERFACE;
+
+ /*
+ * Very old configuration options.
+ *
+ * DEPRECATED:
+ * Use one of the following functions instead:
+ * smbc_setOptionUseKerberos()
+ * smbc_getOptionUseKerberos()
+ * smbc_setOptionFallbackAfterKerberos()
+ * smbc_getOptionFallbackAfterKerberos()
+ * smbc_setOptionNoAutoAnonymousLogin()
+ * smbc_getOptionNoAutoAnonymousLogin()
+ */
+ int flags DEPRECATED_SMBC_INTERFACE;
+
+ /**
+ * user options selections that apply to this session
+ *
+ * NEW OPTIONS ARE NOT ADDED HERE!
+ *
+ * DEPRECATED:
+ * To set and retrieve options, use the smbc_setOption*() and
+ * smbc_getOption*() functions.
+ */
+ struct _smbc_options {
+ 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 !
+ */
+ struct SMBC_internal_data * internal;
+};
+
#endif /* SMBCLIENT_H_INCLUDED */
git.samba.org / metze / samba / wip.git / blobdiff