Continued revamping of libsmbclient.

- James suggested using gcc's "deprecated" attribute to mark the context
  structure fields to generate warnings.  This creates a scenario with the
  best of all worlds.  I'm able to move to an organization that more easily
  allows future enhancements, while avoiding any mandatory changes by
  applications.  Thanks, James!

- Updated WHATSNEW.txt so that it accurately reflects the current state of
  affairs.

Derrell
(This used to be commit a67f96fbe9683b46c2149f7cb439d13f7f0e6ecd)

2 files changed, 122 insertions, 225 deletions

diff --git a/source3/include/libsmb_internal.h b/source3/include/libsmb_internal.h
index e687e24268..6930812b29 100644
--- a/source3/include/libsmb_internal.h
+++ b/source3/include/libsmb_internal.h
@@ -113,23 +113,6 @@ struct SMBC_internal_data {
 	/* True when this handle is initialized */
 	bool                                    initialized;
 
-#if 0 /* Left in libsmbclient.h for backward compatibility */
-        /* Netbios name used for making connections */
-        char *                                  netbios_name;
-
-        /* Workgroup used for making connections */
-        char *                                  workgroup;
-
-        /* Username used for making connections */
-        char *                                  user;
-
-        /* Debug level */
-        int                                     debug;
-
-        /* Connection timeout value */
-        int                                     timeout;
-#endif
-
         /* dirent pointer location
          *
          * Leave room for any urlencoded filename and the comment field.
@@ -192,88 +175,7 @@ struct SMBC_internal_data {
          */
         smbc_smb_encrypt_level                  smb_encryption_level;
 
-#if 0 /* Left in libsmbclient.h for backward compatibility */
-        /*
-         * 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.
-         */
-        bool                                    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.
-         */
-        bool                                    one_share_per_server;
-
-        /* Kerberos-related flags */
-        bool                                    use_kerberos;
-        bool                                    fallback_after_kerberos;
-
-        /* Don't try to do automatic anonymous login */
-        bool                                    no_auto_anonymous_login;
-
-        /* Server-related functions */
-        struct
-        {
-                smbc_get_auth_data_fn           get_auth_data_fn;
-                smbc_check_server_fn            check_server_fn;
-                smbc_remove_unused_server_fn    remove_unused_server_fn;
-        }               server;
-
-        /* Cache-related functions */
-        struct
-        {
-                struct smbc_server_cache *      server_cache_data;
-                smbc_add_cached_srv_fn          add_cached_server_fn;
-                smbc_get_cached_srv_fn          get_cached_server_fn;
-                smbc_remove_cached_srv_fn       remove_cached_server_fn;
-                smbc_purge_cached_srv_fn        purge_cached_server_fn;
-        }               cache;
-#endif
+        struct smbc_server_cache * server_cache;
 
         /* POSIX emulation functions */
         struct
diff --git a/source3/include/libsmbclient.h b/source3/include/libsmbclient.h
index bfed71de1c..a60c05fa7f 100644
--- a/source3/include/libsmbclient.h
+++ b/source3/include/libsmbclient.h
@@ -25,6 +25,13 @@
 #ifndef SMBCLIENT_H_INCLUDED
 #define SMBCLIENT_H_INCLUDED
 
+#undef _DEPRECATED_
+#if ! defined(__LIBSMBCLIENT_INTERNAL__) && defined(__GNUC__)
+# define _DEPRECATED_      __attribute__ ((deprecated))
+#else
+# define _DEPRECATED_
+#endif
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -416,7 +423,7 @@ 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_srv_fn)     (SMBCCTX * c);
+typedef int (*smbc_purge_cached_fn)     (SMBCCTX * c);
 
 
 
@@ -734,14 +741,14 @@ void smbc_setFunctionRemoveCachedServer(SMBCCTX *c,
  * Get the function for server cache purging.  This function tries to
  * remove all cached servers (e.g. on disconnect)
  */
-smbc_purge_cached_srv_fn smbc_getFunctionPurgeCachedServers(SMBCCTX *c);
+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_srv_fn fn);
+                                        smbc_purge_cached_fn fn);
 
 /** Get the function to store private data of the server cache */
 struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
@@ -1010,7 +1017,7 @@ int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
 
 /**@ingroup misc
  *
- * @DEPRECATED.  Use smbc_setOption*() functions instead.
+ * @deprecated.  Use smbc_setOption*() functions instead.
  */
 void
 smbc_option_set(SMBCCTX *context,
@@ -1018,7 +1025,7 @@ smbc_option_set(SMBCCTX *context,
                 ... /* option_value */);
 
 /*
- * @DEPRECATED.  Use smbc_getOption*() functions instead.
+ * @deprecated.  Use smbc_getOption*() functions instead.
  */
 void *
 smbc_option_get(SMBCCTX *context,
@@ -2570,7 +2577,6 @@ smbc_version(void);
 }
 #endif
 
-
 /**
  * @ingroup structure
  * Structure that contains a client context information 
@@ -2586,137 +2592,129 @@ smbc_version(void);
  * directly visible to applications.  This makes it much easier to maintain
  * ABI compatibility.
  */
-struct _SMBCCTX {
-        struct
-        {
-                /**
-                 * debug level
-                 *
-                 * Manually setting/retrieving this value is deprecated.
-                 * Use smbc_getDebug() and smbc_setDebug()
-                 */
-                int     debug;
+struct _SMBCCTX
+{
+        /**
+         * debug level
+         *
+         * DEPRECATED:
+         * Use smbc_getDebug() and smbc_setDebug()
+         */
+        int     debug _DEPRECATED_;
 	
-                /**
-                 * netbios name used for making connections
-                 *
-                 * Manually setting/retrieving this value is deprecated.
-                 * Use smbc_getNetbiosName() and smbc_setNetbiosName()
-                 */
-                char * netbios_name;
+        /**
+         * netbios name used for making connections
+         *
+         * DEPRECATED:
+         * Use smbc_getNetbiosName() and smbc_setNetbiosName()
+         */
+        char * netbios_name _DEPRECATED_;
 
-                /**
-                 * workgroup name used for making connections
-                 *
-                 * Manually setting/retrieving this value is deprecated.
-                 * Use smbc_getWorkgroup() and smbc_setWorkgroup()
-                 */
-                char * workgroup;
+        /**
+         * workgroup name used for making connections
+         *
+         * DEPRECATED:
+         * Use smbc_getWorkgroup() and smbc_setWorkgroup()
+         */
+        char * workgroup _DEPRECATED_;
 
-                /**
-                 * username used for making connections
-                 *
-                 * Manually setting/retrieving this value is deprecated.
-                 * Use smbc_getUser() and smbc_setUser()
-                 */
-                char * user;
-
-                /**
-                 * 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;
-        } config;
+        /**
+         * username used for making connections
+         *
+         * DEPRECATED:
+         * Use smbc_getUser() and smbc_setUser()
+         */
+        char * user _DEPRECATED_;
+
+        /**
+         * timeout used for waiting on connections / response data (in
+         * milliseconds)
+         *
+         * DEPRECATED:
+         * Use smbc_getTimeout() and smbc_setTimeout()
+         */
+        int timeout _DEPRECATED_;
 
 	/**
          * callable functions for files:
 	 * For usage and return values see the SMBC_* functions
          *
-         * Manually setting/retrieving these values is deprecated.
+         * DEPRECATED:
          *
          * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
          * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
 	 */ 
-        struct
-        {
-                smbc_open_fn                    open_fn;
-                smbc_creat_fn                   creat_fn;
-                smbc_read_fn                    read_fn;
-                smbc_write_fn                   write_fn;
-                smbc_unlink_fn                  unlink_fn;
-                smbc_rename_fn                  rename_fn;
-                smbc_lseek_fn                   lseek_fn;
-                smbc_stat_fn                    stat_fn;
-                smbc_fstat_fn                   fstat_fn;
+        smbc_open_fn                    open _DEPRECATED_;
+        smbc_creat_fn                   creat _DEPRECATED_;
+        smbc_read_fn                    read _DEPRECATED_;
+        smbc_write_fn                   write _DEPRECATED_;
+        smbc_unlink_fn                  unlink _DEPRECATED_;
+        smbc_rename_fn                  rename _DEPRECATED_;
+        smbc_lseek_fn                   lseek _DEPRECATED_;
+        smbc_stat_fn                    stat _DEPRECATED_;
+        smbc_fstat_fn                   fstat _DEPRECATED_;
 #if 0 /* internal */
-                smbc_ftruncate_fn               ftruncate_fn;
+        smbc_ftruncate_fn               ftruncate_fn;
 #endif
-                smbc_close_fn                   close_fn;
-                smbc_opendir_fn                 opendir_fn;
-                smbc_closedir_fn                closedir_fn;
-                smbc_readdir_fn                 readdir_fn;
-                smbc_getdents_fn                getdents_fn;
-                smbc_mkdir_fn                   mkdir_fn;
-                smbc_rmdir_fn                   rmdir_fn;
-                smbc_telldir_fn                 telldir_fn;
-                smbc_lseekdir_fn                lseekdir_fn;
-                smbc_fstatdir_fn                fstatdir_fn;
-                smbc_chmod_fn                   chmod_fn;
-                smbc_utimes_fn                  utimes_fn;
-                smbc_setxattr_fn                setxattr_fn;
-                smbc_getxattr_fn                getxattr_fn;
-                smbc_removexattr_fn             removexattr_fn;
-                smbc_listxattr_fn               listxattr_fn;
-        }               posix_emu;
+        smbc_close_fn                   close_fn _DEPRECATED_;
+        smbc_opendir_fn                 opendir _DEPRECATED_;
+        smbc_closedir_fn                closedir _DEPRECATED_;
+        smbc_readdir_fn                 readdir _DEPRECATED_;
+        smbc_getdents_fn                getdents _DEPRECATED_;
+        smbc_mkdir_fn                   mkdir _DEPRECATED_;
+        smbc_rmdir_fn                   rmdir _DEPRECATED_;
+        smbc_telldir_fn                 telldir _DEPRECATED_;
+        smbc_lseekdir_fn                lseekdir _DEPRECATED_;
+        smbc_fstatdir_fn                fstatdir _DEPRECATED_;
+        smbc_chmod_fn                   chmod _DEPRECATED_;
+        smbc_utimes_fn                  utimes _DEPRECATED_;
+        smbc_setxattr_fn                setxattr _DEPRECATED_;
+        smbc_getxattr_fn                getxattr _DEPRECATED_;
+        smbc_removexattr_fn             removexattr _DEPRECATED_;
+        smbc_listxattr_fn               listxattr _DEPRECATED_;
 
         /* Printing-related functions */
-        struct
-        {
-                smbc_print_file_fn              print_file_fn;
-                smbc_open_print_job_fn          open_print_job_fn;
-                smbc_list_print_jobs_fn         list_print_jobs_fn;
-                smbc_unlink_print_job_fn        unlink_print_job_fn;
-        }               printing;
+        smbc_print_file_fn              print_file _DEPRECATED_;
+        smbc_open_print_job_fn          open_print_job _DEPRECATED_;
+        smbc_list_print_jobs_fn         list_print_jobs _DEPRECATED_;
+        smbc_unlink_print_job_fn        unlink_print_job _DEPRECATED_;
 
         /*
         ** Callbacks
-        * These callbacks _always_ have to be initialized because they will
-        * not be checked at dereference for increased speed.
+        *
+        * DEPRECATED:
+        *
+        * See the comment above each field, for the getter and setter
+        * functions that should now be used.
         */
-	struct
+	struct _smbc_callbacks
         {
 		/**
                  * authentication function callback: called upon auth requests
                  *
-                 * Manually setting/retrieving this value is deprecated.
+                 * DEPRECATED:
                  * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
 		 */
-                smbc_get_auth_data_fn get_auth_data_fn;
+                smbc_get_auth_data_fn auth_fn _DEPRECATED_;
 		
 		/**
                  * check if a server is still good
                  *
-                 * Manually setting/retrieving this value is deprecated.
+                 * DEPRECATED:
                  * Use smbc_getFunctionCheckServer(),
                  * smbc_setFunctionCheckServer()
 		 */
-		smbc_check_server_fn check_server_fn;
+		smbc_check_server_fn check_server_fn _DEPRECATED_;
 
 		/**
                  * remove a server if unused
                  *
-                 * Manually setting/retrieving this value is deprecated.
+                 * DEPRECATED:
                  * Use smbc_getFunctionRemoveUnusedServer(),
                  * smbc_setFunctionCheckServer()
 		 */
-		smbc_remove_unused_server_fn remove_unused_server_fn;
-        } server;
+		smbc_remove_unused_server_fn remove_unused_server_fn _DEPRECATED_;
 
-        struct
-        {
 		/** Cache subsystem
                  *
 		 * For an example cache system see
@@ -2728,53 +2726,53 @@ struct _SMBCCTX {
 		/**
                  * server cache addition 
                  *
-                 * Manually setting/retrieving this value is deprecated.
+                 * DEPRECATED:
                  * Use smbc_getFunctionAddCachedServer(),
                  * smbc_setFunctionAddCachedServer()
 		 */
-		smbc_add_cached_srv_fn add_cached_server_fn;
+		smbc_add_cached_srv_fn add_cached_srv_fn _DEPRECATED_;
 
 		/**
                  * server cache lookup 
                  *
-                 * Manually setting/retrieving this value is deprecated.
+                 * DEPRECATED:
                  * Use smbc_getFunctionGetCachedServer(),
                  * smbc_setFunctionGetCachedServer()
 		 */
-		smbc_get_cached_srv_fn get_cached_server_fn;
+		smbc_get_cached_srv_fn get_cached_srv_fn _DEPRECATED_;
 
 		/**
                  * server cache removal
                  *
-                 * Manually setting/retrieving this value is deprecated.
+                 * DEPRECATED:
                  * Use smbc_getFunctionRemoveCachedServer(),
                  * smbc_setFunctionRemoveCachedServer()
 		 */
-		smbc_remove_cached_srv_fn remove_cached_server_fn;
+		smbc_remove_cached_srv_fn remove_cached_srv_fn _DEPRECATED_;
 		
 		/**
                  * server cache purging, try to remove all cached servers
                  * (disconnect)
                  *
-                 * Manually setting/retrieving this value is deprecated.
+                 * DEPRECATED:
                  * Use smbc_getFunctionPurgeCachedServers(),
                  * smbc_setFunctionPurgeCachedServers()
 		 */
-		smbc_purge_cached_srv_fn purge_cached_servers_fn;
+		smbc_purge_cached_fn purge_cached_fn _DEPRECATED_;
+	} callbacks;
 
-                /**
-                 * 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;
-	} cache;
+        /**
+         * Space where the private data of the server cache used to be
+         *
+         * DEPRECATED:
+         * Use smbc_getServerCacheData(), smbc_setServerCacheData()
+         */
+        void * reserved; /* space where server_cache_data used to be */
 
         /*
          * Very old configuration options.
          * 
-         * Manually setting/retrieving this value is deprecated.
+         * DEPRECATED:
          * Use one of the following functions instead:
          *   smbc_setOptionUseKerberos()
          *   smbc_getOptionUseKerberos()
@@ -2783,24 +2781,21 @@ struct _SMBCCTX {
          *   smbc_setOptionNoAutoAnonymousLogin()
          *   smbc_getOptionNoAutoAnonymousLogin()
          */
-        struct
-        {
-                int bits;
-        } flags;
+        int flags _DEPRECATED_;
 	
-        /** user options selections that apply to this session
-         *
-         *  NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
+        /**
+         * user options selections that apply to this session
          *
-         *  NEW OPTIONS ARE NOT ADDED HERE!
+         * NEW OPTIONS ARE NOT ADDED HERE!
          *
-         *  To set and retrieve options, use the smbc_setOption*() and
-         *  smbc_getOption*() functions.
+         * DEPRECATED:
+         * To set and retrieve options, use the smbc_setOption*() and
+         * smbc_getOption*() functions.
          */
         struct _smbc_options {
-                int browse_max_lmb_count;
-                int urlencode_readdir_entries;
-                int one_share_per_server;
+                int browse_max_lmb_count _DEPRECATED_;
+                int urlencode_readdir_entries _DEPRECATED_;
+                int one_share_per_server _DEPRECATED_;
         } options;
 	
 	/** INTERNAL DATA