r14664: r13868@cabra: derrell | 2006-03-22 17:04:30 -0500

 Implement enhancement request 3505.  Two additional features are added here.
 There is now a method of saving an opaque user data handle in the smbc_
 context, and there is now a way to request that the context be passed to the
 authentication function.  See examples/libsmbclient/testbrowse.c for an example
 of using these features.
(This used to be commit 203b4911c16bd7e10198a6f0e63960f2813025ef)

1 files changed, 86 insertions, 10 deletions

diff --git a/source3/include/libsmbclient.h b/source3/include/libsmbclient.h
index 6d3a0cda09..ba92259f70 100644
--- a/source3/include/libsmbclient.h
+++ b/source3/include/libsmbclient.h
@@ -204,7 +204,7 @@ typedef struct _SMBCCTX SMBCCTX;
 
 
 /**@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
@@ -237,6 +237,43 @@ typedef void (*smbc_get_auth_data_fn)(const char *srv,
                                       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 credentals
+ *
+ * @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
@@ -422,14 +459,15 @@ struct _SMBCCTX {
 	int        (*unlink_print_job)(SMBCCTX *c, const char *fname, int id);
 
 
-	/** Callbacks
-	 * These callbacks _always_ have to be initialized because they will not be checked
-	 * at dereference for increased speed.
-	 */
+        /*
+        ** 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;
+                smbc_get_auth_data_fn auth_fn;
 		
 		/** check if a server is still good
 		 */
@@ -579,22 +617,60 @@ int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
 
 
 /**@ingroup misc
+ * Each time the context structure is changed, we have binary backward
+ * compatibility issues.  Instead of modifying the public portions of the
+ * context structure to add new options, instead, we put them in the internal
+ * portion of the context structure and provide a set function for these new
+ * options.
+ *
+ * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
+ *
+ * @param option_name
+ *                  The name of the option for which the value is to be set
+ *
+ * @param option_value
+ *                  The new value of the option being set
+ *
+ */
+void
+smbc_option_set(SMBCCTX *context,
+                char *option_name,
+                void *option_value);
+/*
+ * Retrieve the current value of an option
+ *
+ * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
+ *
+ * @param option_name
+ *                  The name of the option for which the value is to be
+ *                  retrieved
+ *
+ * @return          The value of the specified option.
+ */
+void *
+smbc_option_get(SMBCCTX *context,
+                char *option_name);
+
+/**@ingroup misc
  * Initialize a SBMCCTX (a context).
  *
  * Must be called before using any SMBCCTX API function
  *
  * @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);