summaryrefslogtreecommitdiff
path: root/source3/include/libsmbclient.h
diff options
context:
space:
mode:
Diffstat (limited to 'source3/include/libsmbclient.h')
-rw-r--r--source3/include/libsmbclient.h401
1 files changed, 320 insertions, 81 deletions
diff --git a/source3/include/libsmbclient.h b/source3/include/libsmbclient.h
index 4d78bb2568..28cad351de 100644
--- a/source3/include/libsmbclient.h
+++ b/source3/include/libsmbclient.h
@@ -155,6 +155,21 @@ typedef enum smbc_share_mode
} 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;
+
+
+typedef int smbc_bool;
+
+
#ifndef ENOATTR
# define ENOATTR ENOENT /* No such attribute */
#endif
@@ -214,11 +229,17 @@ typedef struct _SMBCCTX SMBCCTX;
/*
+ * Flags for SMBCCTX->flags
+ *
* NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
- * For these options, use smbc_option_set() and smbc_option_get().
+ * Instead, use:
+ * smbc_setOptionUseKerberos()
+ * smbc_getOptionUseKerberos()
+ * smbc_setOptionFallbackAfterKerberos()
+ * smbc_getOptionFallbackAFterKerberos()
+ * smbc_setOptionNoAutoAnonymousLogin()
+ * smbc_getOptionNoAutoAnonymousLogin()
*/
-
-/* 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)
@@ -398,48 +419,286 @@ typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
typedef int (*smbc_purge_cached_srv_fn) (SMBCCTX * c);
+
+/*****************************************
+ * Getters and setters for CONFIGURATION *
+ *****************************************/
+
/** Get the debug level */
-int smbc_getDebug(SMBCCTX *c);
+int
+smbc_getDebug(SMBCCTX *c);
/** Set the debug level */
-void smbc_setDebug(SMBCCTX *c, int debug);
+void
+smbc_setDebug(SMBCCTX *c, int debug);
/** Get the netbios name used for making connections */
-char * smbc_getNetbiosName(SMBCCTX *c);
+char *
+smbc_getNetbiosName(SMBCCTX *c);
/** Set the netbios name used for making connections */
-void smbc_setNetbiosName(SMBCCTX *c, char * netbios_name);
+void
+smbc_setNetbiosName(SMBCCTX *c, char * netbios_name);
/** Get the workgroup used for making connections */
-char * smbc_getWorkgroup(SMBCCTX *c);
+char *
+smbc_getWorkgroup(SMBCCTX *c);
/** Set the workgroup used for making connections */
void smbc_setWorkgroup(SMBCCTX *c, char * workgroup);
/** Get the username used for making connections */
-char * smbc_getUser(SMBCCTX *c);
+char *
+smbc_getUser(SMBCCTX *c);
/** Set the username used for making connections */
-void smbc_setUser(SMBCCTX *c, char * user);
+void
+smbc_setUser(SMBCCTX *c, char * user);
/**
* Get the timeout used for waiting on connections and response data
* (in milliseconds)
*/
-int smbc_getTimeout(SMBCCTX *c);
+int
+smbc_getTimeout(SMBCCTX *c);
/**
* Set the timeout used for waiting on connections and response data
* (in milliseconds)
*/
-void smbc_setTimeout(SMBCCTX *c, int timeout);
+void
+smbc_setTimeout(SMBCCTX *c, int timeout);
+
+
+
+/***********************************
+ * 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 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 the function for obtaining authentication data */
smbc_get_auth_data_fn smbc_getFunctionAuthData(SMBCCTX *c);
+
+
+
+/*************************************
+ * Getters and setters for FUNCTIONS *
+ *************************************/
+
/** Set the function for obtaining authentication data */
void smbc_setFunctionAuthData(SMBCCTX *c, smbc_get_auth_data_fn f);
+/** 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);
@@ -492,9 +751,12 @@ struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
void smbc_setServerCacheData(SMBCCTX *c, struct smbc_server_cache * cache);
-/**
- * Callable functions for files.
- */
+
+/*****************************************************************
+ * 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,
@@ -566,9 +828,12 @@ smbc_close_fn smbc_getFunctionClose(SMBCCTX *c);
void smbc_setFunctionClose(SMBCCTX *c, smbc_close_fn f);
-/**
- * Callable functions for directories.
- */
+
+/*****************************************************************
+ * 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);
@@ -621,9 +886,12 @@ smbc_fstatdir_fn smbc_getFunctionFstatdir(SMBCCTX *c);
void smbc_setFunctionFstatdir(SMBCCTX *c, smbc_fstatdir_fn f);
-/**
- * Callable functions applicable to both files and directories.
- */
+
+/*****************************************************************
+ * 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,
@@ -668,9 +936,12 @@ smbc_listxattr_fn smbc_getFunctionListxattr(SMBCCTX *c);
void smbc_setFunctionListxattr(SMBCCTX *c, smbc_listxattr_fn f);
-/**
- * Callable functions related to printing
- */
+
+/*****************************************************************
+ * 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,
@@ -2341,6 +2612,7 @@ struct _SMBCCTX {
/**
* debug level
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getDebug() and smbc_setDebug()
*/
int debug;
@@ -2348,6 +2620,7 @@ struct _SMBCCTX {
/**
* netbios name used for making connections
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getNetbiosName() and smbc_setNetbiosName()
*/
char * netbios_name;
@@ -2355,6 +2628,7 @@ struct _SMBCCTX {
/**
* workgroup name used for making connections
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getWorkgroup() and smbc_setWorkgroup()
*/
char * workgroup;
@@ -2362,6 +2636,7 @@ struct _SMBCCTX {
/**
* username used for making connections
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getUser() and smbc_setUser()
*/
char * user;
@@ -2370,6 +2645,7 @@ struct _SMBCCTX {
* timeout used for waiting on connections / response data (in
* milliseconds)
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getTimeout() and smbc_setTimeout()
*/
int timeout;
@@ -2379,6 +2655,8 @@ struct _SMBCCTX {
* callable functions for files:
* For usage and return values see the SMBC_* functions
*
+ * Manually setting/retrieving these values is deprecated.
+ *
* Use smbc_getFunction*() and smbc_setFunction*(), e.g.
* smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
*/
@@ -2433,6 +2711,7 @@ struct _SMBCCTX {
/**
* authentication function callback: called upon auth requests
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
*/
smbc_get_auth_data_fn get_auth_data_fn;
@@ -2440,6 +2719,7 @@ struct _SMBCCTX {
/**
* check if a server is still good
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getFunctionCheckServer(),
* smbc_setFunctionCheckServer()
*/
@@ -2448,6 +2728,7 @@ struct _SMBCCTX {
/**
* remove a server if unused
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getFunctionRemoveUnusedServer(),
* smbc_setFunctionCheckServer()
*/
@@ -2467,6 +2748,7 @@ struct _SMBCCTX {
/**
* server cache addition
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getFunctionAddCachedServer(),
* smbc_setFunctionAddCachedServer()
*/
@@ -2475,6 +2757,7 @@ struct _SMBCCTX {
/**
* server cache lookup
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getFunctionGetCachedServer(),
* smbc_setFunctionGetCachedServer()
*/
@@ -2483,6 +2766,7 @@ struct _SMBCCTX {
/**
* server cache removal
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getFunctionRemoveCachedServer(),
* smbc_setFunctionRemoveCachedServer()
*/
@@ -2492,6 +2776,7 @@ struct _SMBCCTX {
* server cache purging, try to remove all cached servers
* (disconnect)
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getFunctionPurgeCachedServers(),
* smbc_setFunctionPurgeCachedServers()
*/
@@ -2500,6 +2785,7 @@ struct _SMBCCTX {
/**
* Space to store private data of the server cache.
*
+ * Manually setting/retrieving this value is deprecated.
* Use smbc_getServerCacheData(), smbc_setServerCacheData()
*/
struct smbc_server_cache * server_cache_data;
@@ -2508,7 +2794,14 @@ struct _SMBCCTX {
/*
* Very old configuration options.
*
- * Use smbc_option_set() and smbc_option_get() instead.
+ * Manually setting/retrieving this value is deprecated.
+ * Use one of the following functions instead:
+ * smbc_setOptionUseKerberos()
+ * smbc_getOptionUseKerberos()
+ * smbc_setOptionFallbackAfterKerberos()
+ * smbc_getOptionFallbackAfterKerberos()
+ * smbc_setOptionNoAutoAnonymousLogin()
+ * smbc_getOptionNoAutoAnonymousLogin()
*/
struct
{
@@ -2521,66 +2814,12 @@ struct _SMBCCTX {
*
* NEW OPTIONS ARE NOT ADDED HERE!
*
- * We must maintain ABI backward compatibility. We now use
- * smbc_option_set() and smbc_option_get() for all newly added
- * options.
+ * To set and retrieve options, use the smbc_setOption*() and
+ * smbc_getOption*() functions.
*/
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;