Additional revamped libsmbclient documentation

- Ensured that all public functions have documentation in libsmbclient.h
- Reformatted for "proper" indentation
- Re-added temporarily-disabled alternate authentication function capability

Derrell
(This used to be commit 64b7150d92849a1e1e2416b9dcc12fae8d6bea99)

1 files changed, 320 insertions, 81 deletions

diff --git a/source3/include/libsmbclient.h b/source3/include/libsmbclient.h
index 4d78bb2568a..28cad351dec 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;