Update docos.

Author: michaelrsweet

cups/cups.h

@@ -288,10 +288,10 @@ typedef bool (*cups_cert_san_cb_t)(const char *common_name, const char *subject_
 typedef bool (*cups_dest_cb_t)(void *user_data, cups_dest_flags_t flags, cups_dest_t *dest);
 			      		// Destination enumeration callback
 
-typedef const char *(*cups_oauth_cb_t)(http_t *http, const char *realm, const char *scope, const char *resource, void *user_data);
+typedef const char *(*cups_oauth_cb_t)(http_t *http, const char *realm, const char *scope, const char *resource, void *cb_data);
 					// OAuth callback
 
-typedef const char *(*cups_password_cb_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data);
+typedef const char *(*cups_password_cb_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *cb_data);
 					// New password callback
 
 
@@ -393,12 +393,12 @@ extern size_t		cupsRemoveOption(const char *name, size_t num_options, cups_optio
 
 extern bool		cupsSaveCredentials(const char *path, const char *common_name, const char *credentials, const char *key) _CUPS_PUBLIC;
 extern http_status_t	cupsSendRequest(http_t *http, ipp_t *request, const char *resource, size_t length) _CUPS_PUBLIC;
-extern void		cupsSetOAuthCB(cups_oauth_cb_t cb, void *data) _CUPS_PUBLIC;
 extern bool		cupsSetClientCredentials(const char *credentials, const char *key) _CUPS_PUBLIC;
 extern void		cupsSetDefaultDest(const char *name, const char *instance, size_t num_dests, cups_dest_t *dests) _CUPS_PUBLIC;
 extern bool		cupsSetDests(http_t *http, size_t num_dests, cups_dest_t *dests) _CUPS_PUBLIC;
 extern void		cupsSetEncryption(http_encryption_t e) _CUPS_PUBLIC;
-extern void		cupsSetPasswordCB(cups_password_cb_t cb, void *user_data) _CUPS_PUBLIC;
+extern void		cupsSetOAuthCB(cups_oauth_cb_t cb, void *cb_data) _CUPS_PUBLIC;
+extern void		cupsSetPasswordCB(cups_password_cb_t cb, void *cb_data) _CUPS_PUBLIC;
 extern void		cupsSetServer(const char *server) _CUPS_PUBLIC;
 extern bool		cupsSetServerCredentials(const char *path, const char *common_name, bool auto_create) _CUPS_PUBLIC;
 extern void		cupsSetUser(const char *user) _CUPS_PUBLIC;

cups/cupspm.md

@@ -1120,7 +1120,8 @@ handle `HTTP_STATUS_UNAUTHORIZED` responses beyond simply calling
 
 ## Authentication Using Passwords
 
-When you call [`cupsDoAuthentication`](@@), CUPS normally requests a password
+When you call [`cupsDoAuthentication`](@@) and the HTTP server requires the
+"Basic" or "Digest" authentication schemes, CUPS normally requests a password
 from the console.  GUI applications should set a password callback using the
 [`cupsSetPasswordCB`](@@) function:
 
@@ -1149,16 +1150,50 @@ authenticated.  The password callback can call the [`httpGetField`](@@) and
 authentication challenge.
 
 The "method" argument specifies the HTTP method used for the request and is
-typically "POST".
+typically "GET", "POST", or "PUT".
 
-The "resource" argument specifies the path used for the request.
+The "resource" argument specifies the path or URI used for the request.
 
-The "cb_data" argument provides the user data pointer from the
+The "cb_data" argument provides the data pointer from the
 [`cupsSetPasswordCB`](@@) call.
 
 
 ## Authorization using OAuth/OpenID Connect
 
+When you call [`cupsDoAuthentication`](@@) and the HTTP server requires the
+"Bearer" authentication scheme, CUPS will call an OAuth callback that you
+register using the [`cupsSetOAuthCB`](@@) function:
+
+```c
+void
+cupsSetOAuthCB(cups_oauth_cb_t cb, void *cb_data);
+```
+
+The OAuth callback is called when needed and is responsible for performing any
+necessary authorization and returning an access token string:
+
+```c
+const char *
+cups_oauth_cb(http_t *http, const char *realm, const char *scope,
+              const char *resource, void *cb_data);
+```
+
+The "http" argument is the connection hosting the request that is being
+authenticated.  The OAuth callback can call the [`httpGetField`](@@) and
+[`httpGetSubField`](@@) functions to look for additional details concerning the
+authentication challenge.
+
+The "realm" and "scope" arguments provide the "realm" and "scope" parameters, if
+any, from the "WWW-Authenticate" header.
+
+The "resource" argument specifies the path or URI used for the request.
+
+The "cb_data" argument provides the data pointer from the
+[`cupsSetOAuthCB`](@@) call.
+
+
+### OAuth Client Functions
+
 CUPS provides a generic OAuth/OpenID client for authorizing access to printers
 and other network resources.  The following functions are provided:
 
@@ -1244,6 +1279,7 @@ if (access_token == NULL)
 
 // Set the Bearer token for authorization.
 httpSetAuthString(http, "Bearer", access_token);
+free(access_token);
 ```
 
 
@@ -1321,6 +1357,7 @@ if (access_token == NULL)
 
 // Set the Bearer token for authorization.
 httpSetAuthString(http, "Bearer", access_token);
+free(access_token);
 ```
 
 

cups/usersys.c

@@ -279,8 +279,7 @@ cupsSetEncryption(http_encryption_t e)	// I - New encryption preference
 // 'cupsSetOAuthCB()' - Set the OAuth 2.0 callback for CUPS.
 //
 // This function sets the OAuth 2.0 callback for the various CUPS APIs that
-// send HTTP requests. Pass `NULL` to restore the default (console-based)
-// callback.
+// send HTTP requests.  Pass `NULL` to disable OAuth authorization.
 //
 // The OAuth callback receives the HTTP connection, realm name, scope name (if
 // any), resource path, and the "user_data" pointer for each request that
@@ -296,19 +295,17 @@ cupsSetEncryption(http_encryption_t e)	// I - New encryption preference
 // program. Multi-threaded programs that override the callback need to do so in
 // each thread for the same callback to be used.
 //
-//
-//
 
 void
 cupsSetOAuthCB(
     cups_oauth_cb_t cb,			// I - Callback function
-    void            *user_data)		// I - User data pointer
+    void            *cb_data)		// I - Callback data pointer
 {
   _cups_globals_t *cg = _cupsGlobals();	// Pointer to library globals
 
 
   cg->oauth_cb   = cb;
-  cg->oauth_data = user_data;
+  cg->oauth_data = cb_data;
 }
 
 
@@ -326,7 +323,7 @@ cupsSetOAuthCB(
 void
 cupsSetPasswordCB(
     cups_password_cb_t cb,		// I - Callback function
-    void               *user_data)	// I - User data pointer
+    void               *cb_data)	// I - Callback data pointer
 {
   _cups_globals_t *cg = _cupsGlobals();	// Pointer to library globals
 
@@ -336,7 +333,7 @@ cupsSetPasswordCB(
   else
     cg->password_cb = cb;
 
-  cg->password_data = user_data;
+  cg->password_data = cb_data;
 }