From: Michael R Sweet Date: Wed, 28 May 2025 16:38:30 +0000 (-0400) Subject: Fix typo in programming manual. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=05d62fc28d5c199dbe1b6575276c281c6da78823;p=thirdparty%2Fcups.git Fix typo in programming manual. --- diff --git a/cups/dest.c b/cups/dest.c index 2e84da340b..eafb241558 100644 --- a/cups/dest.c +++ b/cups/dest.c @@ -159,7 +159,7 @@ static void dnssd_error_cb(void *cb_data, const char *message); // returned unchanged. Adding a new instance of a destination creates // a copy of that destination's options. // -// Use the @link cupsSaveDests@ function to save the updated list of +// Use the @link cupsSetDests@ function to save the updated list of // destinations to the user's lpoptions file. // diff --git a/doc/help/cupspm.epub b/doc/help/cupspm.epub index 7a13ac93f1..7d3d48876a 100644 Binary files a/doc/help/cupspm.epub and b/doc/help/cupspm.epub differ diff --git a/doc/help/cupspm.html b/doc/help/cupspm.html index 782603d487..60d951462e 100644 --- a/doc/help/cupspm.html +++ b/doc/help/cupspm.html @@ -516,8 +516,10 @@ span.string {
  • cupsOAuthCopyUserId
  • cupsOAuthGetAuthorizationCode
  • cupsOAuthGetClientId
    • +
  • cupsOAuthGetJWKS
  • cupsOAuthGetMetadata
  • cupsOAuthGetTokens
    • +
  • cupsOAuthGetUserId
  • cupsOAuthMakeAuthorizationURL
  • cupsOAuthMakeBase64Random
  • cupsOAuthSaveClientData
    • @@ -615,6 +617,7 @@ span.string {
  • httpGetBlocking
  • httpGetContentEncoding
  • httpGetCookie
    • +
  • httpGetCookieValue
  • httpGetDateString2
  • httpGetDateTime
  • httpGetEncryption
    • @@ -628,6 +631,7 @@ span.string {
  • httpGetPending
  • httpGetReady
  • httpGetRemaining
    • +
  • httpGetSecurity
  • httpGetState
  • httpGetStatus
  • httpGetSubField2
    • @@ -1814,7 +1818,7 @@ If the named destination already exists, the destination list is returned unchanged. Adding a new instance of a destination creates a copy of that destination's options.

    -Use the cupsSaveDests function to save the updated list of +Use the cupsSetDests function to save the updated list of destinations to the user's lpoptions file.

     CUPS 2.3 cupsAddDestMediaOptions

    Add the option corresponding to the specified media size.

    @@ -3269,7 +3273,7 @@ resolve_cb( const char *fullname, const char *host, uint16_t port, - size_t num_txt, + int num_txt, cups_option_t *txt) { // Process resolved service @@ -5587,11 +5591,13 @@ JWK suitable for use when decrypting or verifying a JWE/JWS message.

     CUPS 2.5 cupsJWTNew

    Create a new, empty JSON Web Token.

    -cups_jwt_t *cupsJWTNew(const char *type);

    +cups_jwt_t *cupsJWTNew(const char *type, cups_json_t *claims);

    Parameters

    + +
    type JWT type or NULL for default ("JWT")
    claimsJSON claims or NULL for empty

    Return Value

    JWT object

    @@ -5917,7 +5923,7 @@ invalid if the destination information is deleted.

    The returned string must be freed by the caller using free.

    -

    cupsOAuthClearTokens

    +

     CUPS 2.5 cupsOAuthClearTokens

    Clear any cached authorization information.

    void cupsOAuthClearTokens(const char *auth_uri, const char *resource_uri);

    @@ -5930,8 +5936,10 @@ invalid if the destination information is deleted.

    Discussion

    This function clears cached authorization information for the given -Authorization Server "auth_uri" and Resource "resource_uri" combination.

    -

    cupsOAuthCopyAccessToken

    +Authorization Server "auth_uri" and Resource "resource_uri" combination. + +

    +

     CUPS 2.5 cupsOAuthCopyAccessToken

    Get a cached access token.

    char *cupsOAuthCopyAccessToken(const char *auth_uri, const char *resource_uri, time_t *access_expires);

    @@ -5952,8 +5960,10 @@ associated expiration time for the given Authorization Server "auth_uri&quo Resource "resource_uri" combination. The returned access token must be freed using the free function.

    -NULL is returned if no token is cached.

    -

    cupsOAuthCopyClientId

    +NULL is returned if no token is cached. + +

    +

     CUPS 2.5 cupsOAuthCopyClientId

    Get the cached client_id value.

    char *cupsOAuthCopyClientId(const char *auth_uri, const char *redirect_uri);

    @@ -5971,8 +5981,10 @@ using the free function.
    Authorization Server "auth_uri" and Redirection URI "resource_uri". The returned value must be freed using the free function.

    -NULL is returned if no client_id is cached.

    -

    cupsOAuthCopyRefreshToken

    +NULL is returned if no client_id is cached. + +

    +

     CUPS 2.5 cupsOAuthCopyRefreshToken

    Get a cached refresh token.

    char *cupsOAuthCopyRefreshToken(const char *auth_uri, const char *resource_uri);

    @@ -5991,8 +6003,10 @@ given Authorization Server "auth_uri" and Resource "resource_uri& combination. The returned refresh token must be freed using the free function.

    -NULL is returned if no refresh token is cached.

    -

    cupsOAuthCopyUserId

    +NULL is returned if no refresh token is cached. + +

    +

     CUPS 2.5 cupsOAuthCopyUserId

    Get cached user identification information.

    cups_jwt_t *cupsOAuthCopyUserId(const char *auth_uri, const char *resource_uri);

    @@ -6011,8 +6025,10 @@ given Authorization Server "auth_uri" and Resource "resource_uri& combination. The returned user information must be freed using the cupsJWTDelete function.

    -NULL is returned if no identification information is cached.

    -

    cupsOAuthGetAuthorizationCode

    +NULL is returned if no identification information is cached. + +

    +

     CUPS 2.5 cupsOAuthGetAuthorizationCode

    Authorize access using a web browser.

    char *cupsOAuthGetAuthorizationCode(const char *auth_uri, cups_json_t *metadata, const char *resource_uri, const char *scopes, const char *redirect_uri);

    @@ -6045,19 +6061,21 @@ file, etc.) that you which to access.

    The "scopes" parameter specifies zero or more whitespace-delimited scope names to request during authorization. The list of supported scope names are -available from the Authorization Server metadata, for example:
    -
    -The "redirect_uri" parameter specifies a 'http:' URL with a listen address, -port, and path to use. If NULL, 127.0.0.1 on a random port is used with a -path of "/". +available from the Authorization Server metadata, for example: 
     cups_json_t *metadata = cupsOAuthGetMetadata(auth_uri);
 cups_json_t *scopes_supported = cupsJSONFind(metadata, "scopes_supported");
    -The returned authorization code must be freed using the free function.

    -

    cupsOAuthGetClientId

    +The "redirect_uri" parameter specifies a 'http:' URL with a listen address, +port, and path to use. If NULL, 127.0.0.1 on a random port is used with a +path of "/".
    +
    +The returned authorization code must be freed using the free function. + +

    +

     CUPS 2.5 cupsOAuthGetClientId

    Register a client application and get its ID.

    char *cupsOAuthGetClientId(const char *auth_uri, cups_json_t *metadata, const char *redirect_uri, const char *logo_uri, const char *tos_uri);

    @@ -6096,8 +6114,34 @@ The returned "client_id" string must be freed using the free Note: This function should only be used to register WWW applications. The cupsOAuthGetAuthorizationCode function handles registration of -local/"native" applications for you.

    -

    cupsOAuthGetMetadata

    +local/"native" applications for you. + +

    +

     CUPS 2.5 cupsOAuthGetJWKS

    +

    Get the JWT key set for an Authorization Server.

    +

    +cups_json_t *cupsOAuthGetJWKS(const char *auth_uri, cups_json_t *metadata);

    +

    Parameters

    + + + + + +
    auth_uriAuthorization server URI
    metadataServer metadata
    +

    Return Value

    +

    JWKS or NULL on error

    +

    Discussion

    +

    This function gets the JWT key set for the specified Authorization Server +"auth_uri". The "metadata" value is obtained using the +cupsOAuthGetMetadata function. The returned key set is cached +per-user for better performance and must be freed using the +cupsJSONDelete function.
    +
    +The key set is typically used to validate JWT bearer tokens using the +cupsJWTHasValidSignature function. + +

    +

     CUPS 2.5 cupsOAuthGetMetadata

    Get the metadata for an Authorization Server.

    cups_json_t *cupsOAuthGetMetadata(const char *auth_uri);

    @@ -6109,11 +6153,14 @@ local/"native" applications for you.

    Return Value

    JSON metadata or NULL on error

    Discussion

    -

    This function gets the metadata for the specified Authorization Server URI -"auth_uri". Metadata is cached per-user for better performance.
    +

    This function gets the RFC 8414 or Open ID Connect metadata for the specified +OAuth Authorization Server URI "auth_uri".

    -The returned metadata must be freed using the cupsJSONDelete function.

    -

    cupsOAuthGetTokens

    +The returned metadata is cached per-user for better performance and must be +freed using the cupsJSONDelete function. + +

    +

     CUPS 2.5 cupsOAuthGetTokens

    Obtain access and refresh tokens.

    char *cupsOAuthGetTokens(const char *auth_uri, cups_json_t *metadata, const char *resource_uri, const char *grant_code, cups_ogrant_t grant_type, const char *redirect_uri, time_t *access_expires);

    @@ -6167,8 +6214,31 @@ When successful, the access token and expiration time are returned. The access token must be freed using the free function. The new refresh token and any user ID information can be obtained using the cupsOAuthCopyRefreshToken and cupsOAuthCopyUserId functions -respectively.

    -

    cupsOAuthMakeAuthorizationURL

    +respectively. + +

    +

     CUPS 2.5 cupsOAuthGetUserId

    +

    Get the user ID token associated with the given access token.

    +

    +cups_jwt_t *cupsOAuthGetUserId(const char *auth_uri, cups_json_t *metadata, const char *access_token);

    +

    Parameters

    + + + + + + + +
    auth_uriAuthorization Server URL
    metadataAuthorization Server metadata
    access_tokenAccess (Bearer) token
    +

    Return Value

    +

    Identification information or NULL if none

    +

    Discussion

    +

    This function retrieves the user ID token associated with a given access +token. The user ID information is cached until the token expires to minimize +the overhead of communicating with the Authorization Server. + +

    +

     CUPS 2.5 cupsOAuthMakeAuthorizationURL

    Make an authorization URL.

    char *cupsOAuthMakeAuthorizationURL(const char *auth_uri, cups_json_t *metadata, const char *resource_uri, const char *scopes, const char *client_id, const char *code_verifier, const char *nonce, const char *redirect_uri, const char *state);

    @@ -6235,8 +6305,10 @@ The "redirect_uri" parameter specifies the URI that will receive the authorization grant code.

    The "state" parameter is a unique (random) identifier for the authorization -request. It is provided to the redirection URI as a form parameter.

    -

    cupsOAuthMakeBase64Random

    +request. It is provided to the redirection URI as a form parameter. + +

    +

     CUPS 2.5 cupsOAuthMakeBase64Random

    Make a random data string.

    char *cupsOAuthMakeBase64Random(size_t len);

    @@ -6250,8 +6322,10 @@ request. It is provided to the redirection URI as a form parameter.

    Discussion

    This function creates a string containing random data that has been Base64URL encoded. "len" specifies the number of random bytes to include in the string. -The returned string must be freed using the free function.

    -

    cupsOAuthSaveClientData

    +The returned string must be freed using the free function. + +

    +

     CUPS 2.5 cupsOAuthSaveClientData

    Save client_id and client_secret values.

    void cupsOAuthSaveClientData(const char *auth_uri, const char *redirect_uri, const char *client_id, const char *client_secret);

    @@ -6270,8 +6344,10 @@ The returned string must be freed using the free function.

    This function saves the "client_id" and "client_secret" values for the given Authorization Server "auth_uri" and redirection URI "redirect_uri". If the "client_id" is NULL then any saved values are deleted from the per-user -store.

    -

    cupsOAuthSaveTokens

    +store. + +

    +

     CUPS 2.5 cupsOAuthSaveTokens

    Save authorization and refresh tokens.

    void cupsOAuthSaveTokens(const char *auth_uri, const char *resource_uri, const char *access_token, time_t access_expires, const char *user_id, const char *refresh_token);

    @@ -6294,7 +6370,9 @@ store.

    This function saves the access token "access_token", user ID "user_id", and refresh token "refresh_token" values for the given Authorization Server "auth_uri" and resource "resource_uri". Specifying NULL for any of the -values will delete the corresponding saved values from the per-user store.

    +values will delete the corresponding saved values from the per-user store. + +

    cupsParseOptions

    Parse options from a command-line argument.

    @@ -8059,7 +8137,7 @@ or in the response (for servers) in order to compress the content stream.

     CUPS 1.1.19 httpGetCookie

    -

    Get any cookie data from the response.

    +

    Get cookie data from the HTTP connection.

    const char *httpGetCookie(http_t *http);

    Parameters

    @@ -8069,6 +8147,35 @@ or in the response (for servers) in order to compress the content stream.

    Return Value

    Cookie data or NULL

    +

    Discussion

    +

    This function returns any HTTP "Set-Cookie:" or "Cookie:" header data for the +given HTTP connection as described in RFC 6265. Use the +httpGetCookieValue to get the value of a named "Cookie:" value. + +

    +

     CUPS 2.5 httpGetCookieValue

    +

    Get the value of a named cookie from the HTTP connection.

    +

    +char *httpGetCookieValue(http_t *http, const char *name, char *buffer, size_t bufsize);

    +

    Parameters

    + + + + + + + + + +
    httpHTTP connection
    nameCookie name
    bufferValue buffer
    bufsizeSize of value buffer
    +

    Return Value

    +

    Cookie value or NULL if not present

    +

    Discussion

    +

    This function copies the value of a named cookie in the HTTP "Cookie:" header +for the given HTTP connection as described in RFC 6265. Use the +httpGetCookie function to get the original "Cookie:" string. + +

     CUPS 1.2 httpGetDateString2

    Get a formatted date/time string from a time value.

    @@ -8250,6 +8357,28 @@ size_t httpGetRemaining(http_t *http);

    The httpIsChunked function can be used to determine whether the message body is chunked or fixed-length. +

    +

     CUPS 2.5 httpGetSecurity

    +

    Get the TLS version and cipher suite used by a connection.

    +

    +const char *httpGetSecurity(http_t *http, char *buffer, size_t bufsize);

    +

    Parameters

    + + + + + + + +
    httpHTTP connection
    bufferString buffer
    bufsizeSize of buffer
    +

    Return Value

    +

    Security information or NULL if not encrypted

    +

    Discussion

    +

    This function gets the TLS version and cipher suite being used by a +connection, if any. The string is copied to "buffer" and is of the form +"TLS/major.minor CipherSuite". If not encrypted, the buffer is cleared to +the empty string. +

    httpGetState

    Get the current state of the HTTP request.

    @@ -8589,16 +8718,25 @@ the HTTP connection object. You must still call h true for blocking, false for non-blocking

     CUPS 1.1.19 httpSetCookie

    -

    Set the cookie value(s).

    +

    Add Set-Cookie value(s).

    void httpSetCookie(http_t *http, const char *cookie);

    Parameters

    - +
    httpConnection
    HTTP cnnection
    cookie Cookie string
    +

    Discussion

    +

    This function adds one or more Set-Cookie header values that will be sent to +the client with the httpWriteResponse function. Each value conforms +to the format defined in RFC 6265. Multiple values can be passed in the +"cookie" string separated by a newline character.
    +
    +Call the httpClearCookies function to clear all Set-Cookie values. + +

     CUPS 1.7 httpSetDefaultField

    Set the default value of an HTTP header.