diff options
Diffstat (limited to 'cups')
| -rw-r--r-- | cups/Makefile | 6 | ||||
| -rw-r--r-- | cups/dest-job.c | 4 | ||||
| -rw-r--r-- | cups/dest-options.c | 2 | ||||
| -rw-r--r-- | cups/dest.c | 79 | ||||
| -rw-r--r-- | cups/encode.c | 6 | ||||
| -rw-r--r-- | cups/http-addr.c | 12 | ||||
| -rw-r--r-- | cups/http-support.c | 14 | ||||
| -rw-r--r-- | cups/http.c | 39 | ||||
| -rw-r--r-- | cups/options.c | 6 | ||||
| -rw-r--r-- | cups/usersys.c | 6 |
10 files changed, 99 insertions, 75 deletions
diff --git a/cups/Makefile b/cups/Makefile index 28584bc41..962bee636 100644 --- a/cups/Makefile +++ b/cups/Makefile @@ -574,10 +574,8 @@ apihelp: $(RM) cupspm.xml mxmldoc --section "Programming" --body cupspm.md \ cupspm.xml \ - auth.c cups.h dest*.c encode.c \ - http.h http*.c ipp.h ipp*.c language.[ch] \ - notify.c options.c \ - tls-darwin.c usersys.c util.c \ + auth.c cups.h dest*.c encode.c http.h http*.c ipp.h ipp*.c \ + options.c tls-darwin.c usersys.c util.c \ --coverimage cupspm.png \ --epub ../doc/help/cupspm.epub mxmldoc --section "Programming" --body cupspm.md \ diff --git a/cups/dest-job.c b/cups/dest-job.c index 9fc0bdb9a..f12b1dc58 100644 --- a/cups/dest-job.c +++ b/cups/dest-job.c @@ -25,13 +25,13 @@ * The "job_id" is the number returned by cupsCreateDestJob. * * Returns @code IPP_STATUS_OK@ on success and - * @code IPP_STATUS_ERRPR_NOT_AUTHORIZED@ or + * @code IPP_STATUS_ERROR_NOT_AUTHORIZED@ or * @code IPP_STATUS_ERROR_FORBIDDEN@ on failure. * * @since CUPS 1.6/macOS 10.8@ */ -ipp_status_t +ipp_status_t /* O - Status of cancel operation */ cupsCancelDestJob(http_t *http, /* I - Connection to destination */ cups_dest_t *dest, /* I - Destination */ int job_id) /* I - Job ID */ diff --git a/cups/dest-options.c b/cups/dest-options.c index 2832055a4..4a3a03ab0 100644 --- a/cups/dest-options.c +++ b/cups/dest-options.c @@ -833,6 +833,8 @@ cupsFindDestSupported( /* * 'cupsFreeDestInfo()' - Free destination information obtained using * @link cupsCopyDestInfo@. + * + * @since CUPS 1.6/macOS 10.8@ */ void diff --git a/cups/dest.c b/cups/dest.c index 674d8d2da..0be2bbeb5 100644 --- a/cups/dest.c +++ b/cups/dest.c @@ -570,18 +570,19 @@ _cupsAppleSetUseLastPrinter( /* - * 'cupsConnectDest()' - Connect to the server for a destination. + * 'cupsConnectDest()' - Open a conection to the destination. * - * Connect to the destination, returning a new http_t connection object and - * optionally the resource path to use for the destination. These calls will - * block until a connection is made, the timeout expires, the integer pointed - * to by "cancel" is non-zero, or the callback function (or block) returns 0, - * The caller is responsible for calling httpClose() on the returned object. + * Connect to the destination, returning a new @code http_t@ connection object + * and optionally the resource path to use for the destination. These calls + * will block until a connection is made, the timeout expires, the integer + * pointed to by "cancel" is non-zero, or the callback function (or block) + * returns 0. The caller is responsible for calling @link httpClose@ on the + * returned connection. * * @since CUPS 1.6/macOS 10.8@ */ -http_t * /* O - Connection to server or @code NULL@ */ +http_t * /* O - Connection to destination or @code NULL@ */ cupsConnectDest( cups_dest_t *dest, /* I - Destination */ unsigned flags, /* I - Connection flags */ @@ -746,18 +747,18 @@ cupsConnectDest( #ifdef __BLOCKS__ /* - * 'cupsConnectDestBlock()' - Connect to the server for a destination. + * 'cupsConnectDestBlock()' - Open a connection to the destination. * - * Connect to the destination, returning a new http_t connection object and - * optionally the resource path to use for the destination. These calls will - * block until a connection is made, the timeout expires, the integer pointed - * to by "cancel" is non-zero, or the callback function (or block) returns 0, - * The caller is responsible for calling httpClose() on the returned object. + * Connect to the destination, returning a new @code http_t@ connection object + * and optionally the resource path to use for the destination. These calls + * will block until a connection is made, the timeout expires, the integer + * pointed to by "cancel" is non-zero, or the block returns 0. The caller is + * responsible for calling @link httpClose@ on the returned connection. * * @since CUPS 1.6/macOS 10.8@ @exclude all@ */ -http_t * /* O - Connection to server or @code NULL@ */ +http_t * /* O - Connection to destination or @code NULL@ */ cupsConnectDestBlock( cups_dest_t *dest, /* I - Destination */ unsigned flags, /* I - Connection flags */ @@ -1414,7 +1415,7 @@ cupsFreeDests(int num_dests, /* I - Number of destinations */ /* * 'cupsGetDest()' - Get the named destination from the list. * - * Use the @link cupsGetDests@ or @link cupsGetDests2@ functions to get a + * Use the @link cupsEnumDests@ or @link cupsGetDests2@ functions to get a * list of supported destinations for the current user. */ @@ -1943,12 +1944,18 @@ _cupsGetDests(http_t *http, /* I - Connection to server or * 'cupsGetDests()' - Get the list of destinations from the default server. * * Starting with CUPS 1.2, the returned list of destinations include the - * printer-info, printer-is-accepting-jobs, printer-is-shared, - * printer-make-and-model, printer-state, printer-state-change-time, - * printer-state-reasons, and printer-type attributes as options. CUPS 1.4 - * adds the marker-change-time, marker-colors, marker-high-levels, - * marker-levels, marker-low-levels, marker-message, marker-names, - * marker-types, and printer-commands attributes as well. + * "printer-info", "printer-is-accepting-jobs", "printer-is-shared", + * "printer-make-and-model", "printer-state", "printer-state-change-time", + * "printer-state-reasons", "printer-type", and "printer-uri-supported" + * attributes as options. + * + * CUPS 1.4 adds the "marker-change-time", "marker-colors", + * "marker-high-levels", "marker-levels", "marker-low-levels", "marker-message", + * "marker-names", "marker-types", and "printer-commands" attributes as options. + * + * CUPS 2.2 adds accessible IPP printers to the list of destinations that can + * be used. The "printer-uri-supported" option will be present for those IPP + * printers that have been recently used. * * Use the @link cupsFreeDests@ function to free the destination list and * the @link cupsGetDest@ function to find a particular destination. @@ -1967,17 +1974,23 @@ cupsGetDests(cups_dest_t **dests) /* O - Destinations */ * 'cupsGetDests2()' - Get the list of destinations from the specified server. * * Starting with CUPS 1.2, the returned list of destinations include the - * printer-info, printer-is-accepting-jobs, printer-is-shared, - * printer-make-and-model, printer-state, printer-state-change-time, - * printer-state-reasons, and printer-type attributes as options. CUPS 1.4 - * adds the marker-change-time, marker-colors, marker-high-levels, - * marker-levels, marker-low-levels, marker-message, marker-names, - * marker-types, and printer-commands attributes as well. + * "printer-info", "printer-is-accepting-jobs", "printer-is-shared", + * "printer-make-and-model", "printer-state", "printer-state-change-time", + * "printer-state-reasons", "printer-type", and "printer-uri-supported" + * attributes as options. + * + * CUPS 1.4 adds the "marker-change-time", "marker-colors", + * "marker-high-levels", "marker-levels", "marker-low-levels", "marker-message", + * "marker-names", "marker-types", and "printer-commands" attributes as options. + * + * CUPS 2.2 adds accessible IPP printers to the list of destinations that can + * be used. The "printer-uri-supported" option will be present for those IPP + * printers that have been recently used. * * Use the @link cupsFreeDests@ function to free the destination list and * the @link cupsGetDest@ function to find a particular destination. * - * @since CUPS 1.1.21/macOS 10.4@ @exclude all@ + * @since CUPS 1.1.21/macOS 10.4@ */ int /* O - Number of destinations */ @@ -2143,10 +2156,10 @@ cupsGetDests2(http_t *http, /* I - Connection to server or @code CUPS_HTTP_ * 'cupsGetNamedDest()' - Get options for the named destination. * * This function is optimized for retrieving a single destination and should - * be used instead of @link cupsGetDests@ and @link cupsGetDest@ when you either - * know the name of the destination or want to print to the default destination. - * If @code NULL@ is returned, the destination does not exist or there is no - * default destination. + * be used instead of @link cupsGetDests2@ and @link cupsGetDest@ when you + * either know the name of the destination or want to print to the default + * destination. If @code NULL@ is returned, the destination does not exist or + * there is no default destination. * * If "http" is @code CUPS_HTTP_DEFAULT@, the connection to the default print * server will be used. @@ -2383,6 +2396,8 @@ cupsSetDefaultDest( * * This function saves the destinations to /etc/cups/lpoptions when run * as root and ~/.cups/lpoptions when run as a normal user. + * + * @exclude all@ */ void diff --git a/cups/encode.c b/cups/encode.c index cf9ea8e88..94695d083 100644 --- a/cups/encode.c +++ b/cups/encode.c @@ -329,10 +329,8 @@ static int compare_ipp_options(_ipp_option_t *a, _ipp_option_t *b); * 'cupsEncodeOptions()' - Encode printer options into IPP attributes. * * This function adds operation, job, and then subscription attributes, - * in that order. Use the cupsEncodeOptions2() function to add attributes + * in that order. Use the @link cupsEncodeOptions2@ function to add attributes * for a single group. - * - * @exclude all@ */ void @@ -356,7 +354,7 @@ cupsEncodeOptions(ipp_t *ipp, /* I - Request to add to */ * 'cupsEncodeOptions2()' - Encode printer options into IPP attributes for a group. * * This function only adds attributes for a single group. Call this - * function multiple times for each group, or use cupsEncodeOptions() + * function multiple times for each group, or use @link cupsEncodeOptions@ * to add the standard groups. * * @since CUPS 1.2/macOS 10.5@ diff --git a/cups/http-addr.c b/cups/http-addr.c index 12d13a697..61c86384b 100644 --- a/cups/http-addr.c +++ b/cups/http-addr.c @@ -58,9 +58,9 @@ httpAddrAny(const http_addr_t *addr) /* I - Address to check */ * 'httpAddrClose()' - Close a socket created by @link httpAddrConnect@ or * @link httpAddrListen@. * - * Pass @code NULL@ for sockets created with @link httpAddrConnect@ and the - * listen address for sockets created with @link httpAddrListen@. This will - * ensure that domain sockets are removed when closed. + * Pass @code NULL@ for sockets created with @link httpAddrConnect2@ and the + * listen address for sockets created with @link httpAddrListen@. This function + * ensures that domain sockets are removed when closed. * * @since CUPS 2.0/OS 10.10@ */ @@ -648,6 +648,10 @@ httpAddrString(const http_addr_t *addr, /* I - Address to convert */ /* * 'httpGetAddress()' - Get the address of the connected peer of a connection. * + * For connections created with @link httpConnect2@, the address is for the + * server. For connections created with @link httpAccept@, the address is for + * the client. + * * Returns @code NULL@ if the socket is currently unconnected. * * @since CUPS 2.0/OS 10.10@ @@ -667,7 +671,7 @@ httpGetAddress(http_t *http) /* I - HTTP connection */ * 'httpGetHostByName()' - Lookup a hostname or IPv4 address, and return * address records for the specified name. * - * @deprecated@ + * @deprecated@ @exclude all@ */ struct hostent * /* O - Host entry */ diff --git a/cups/http-support.c b/cups/http-support.c index 3ab461e14..76dbb7dbf 100644 --- a/cups/http-support.c +++ b/cups/http-support.c @@ -566,6 +566,10 @@ httpDecode64(char *out, /* I - String to write to */ /* * 'httpDecode64_2()' - Base64-decode a string. * + * The caller must initialize "outlen" to the maximum size of the decoded + * string before calling @code httpDecode64_2@. On return "outlen" contains the + * decoded length of the string. + * * @since CUPS 1.1.21/macOS 10.4@ */ @@ -690,7 +694,7 @@ httpEncode64(char *out, /* I - String to write to */ char * /* O - Encoded string */ httpEncode64_2(char *out, /* I - String to write to */ - int outlen, /* I - Size of output string */ + int outlen, /* I - Maximum size of output string */ const char *in, /* I - String to read from */ int inlen) /* I - Size of input string */ { @@ -782,7 +786,7 @@ httpEncode64_2(char *out, /* I - String to write to */ */ const char * /* O - Date/time string */ -httpGetDateString(time_t t) /* I - UNIX time */ +httpGetDateString(time_t t) /* I - Time in seconds */ { _cups_globals_t *cg = _cupsGlobals(); /* Pointer to library globals */ @@ -798,7 +802,7 @@ httpGetDateString(time_t t) /* I - UNIX time */ */ const char * /* O - Date/time string */ -httpGetDateString2(time_t t, /* I - UNIX time */ +httpGetDateString2(time_t t, /* I - Time in seconds */ char *s, /* I - String buffer */ int slen) /* I - Size of string buffer */ { @@ -819,7 +823,7 @@ httpGetDateString2(time_t t, /* I - UNIX time */ * 'httpGetDateTime()' - Get a time value from a formatted date/time string. */ -time_t /* O - UNIX time */ +time_t /* O - Time in seconds */ httpGetDateTime(const char *s) /* I - Date/time string */ { int i; /* Looping var */ @@ -1419,7 +1423,7 @@ _httpStatus(cups_lang_t *lang, /* I - Language */ * 'httpStatus()' - Return a short string describing a HTTP status code. * * The returned string is localized to the current POSIX locale and is based - * on the status strings defined in RFC 2616. + * on the status strings defined in RFC 7231. */ const char * /* O - Localized status string */ diff --git a/cups/http.c b/cups/http.c index 15004b624..61b88c9db 100644 --- a/cups/http.c +++ b/cups/http.c @@ -439,7 +439,7 @@ http_t * /* O - New HTTP connection */ httpConnect2( const char *host, /* I - Host to connect to */ int port, /* I - Port number */ - http_addrlist_t *addrlist, /* I - List of addresses or NULL to lookup */ + http_addrlist_t *addrlist, /* I - List of addresses or @code NULL@ to lookup */ int family, /* I - Address family to use or @code AF_UNSPEC@ for any */ http_encryption_t encryption, /* I - Type of encryption to use */ int blocking, /* I - 1 for blocking connection, 0 for non-blocking */ @@ -609,7 +609,7 @@ httpFieldValue(const char *name) /* I - String name */ /* - * 'httpFlush()' - Flush data from a HTTP connection. + * 'httpFlush()' - Flush data read from a HTTP connection. */ void @@ -679,7 +679,7 @@ httpFlush(http_t *http) /* I - HTTP connection */ /* - * 'httpFlushWrite()' - Flush data in write buffer. + * 'httpFlushWrite()' - Flush data written to a HTTP connection. * * @since CUPS 1.2/macOS 10.5@ */ @@ -751,7 +751,7 @@ httpGet(http_t *http, /* I - HTTP connection */ /* * 'httpGetActivity()' - Get the most recent activity for a connection. * - * The return value is the UNIX time of the last read or write. + * The return value is the time in seconds of the last read or write. * * @since CUPS 2.0/OS 10.10@ */ @@ -766,10 +766,10 @@ httpGetActivity(http_t *http) /* I - HTTP connection */ /* * 'httpGetAuthString()' - Get the current authorization string. * - * The authorization string is set by cupsDoAuthentication() and - * httpSetAuthString(). Use httpGetAuthString() to retrieve the - * string to use with httpSetField() for the HTTP_FIELD_AUTHORIZATION - * value. + * The authorization string is set by @link cupsDoAuthentication@ and + * @link httpSetAuthString@. Use @link httpGetAuthString@ to retrieve the + * string to use with @link httpSetField@ for the + * @code HTTP_FIELD_AUTHORIZATION@ value. * * @since CUPS 1.3/macOS 10.5@ */ @@ -891,7 +891,7 @@ httpGetContentEncoding(http_t *http) /* I - HTTP connection */ * @since CUPS 1.1.19/macOS 10.3@ */ -const char * /* O - Cookie data or NULL */ +const char * /* O - Cookie data or @code NULL@ */ httpGetCookie(http_t *http) /* I - HTTP connection */ { return (http ? http->cookie : NULL); @@ -1150,7 +1150,7 @@ httpGetRemaining(http_t *http) /* I - HTTP connection */ * 'httpGets()' - Get a line of text from a HTTP connection. */ -char * /* O - Line or NULL */ +char * /* O - Line or @code NULL@ */ httpGets(char *line, /* I - Line to read into */ int length, /* I - Max length of buffer */ http_t *http) /* I - HTTP connection */ @@ -1349,7 +1349,7 @@ httpGetStatus(http_t *http) /* I - HTTP connection */ * @deprecated@ @exclude all@ */ -char * /* O - Value or NULL */ +char * /* O - Value or @code NULL@ */ httpGetSubField(http_t *http, /* I - HTTP connection */ http_field_t field, /* I - Field index */ const char *name, /* I - Name of sub-field */ @@ -1365,7 +1365,7 @@ httpGetSubField(http_t *http, /* I - HTTP connection */ * @since CUPS 1.2/macOS 10.5@ */ -char * /* O - Value or NULL */ +char * /* O - Value or @code NULL@ */ httpGetSubField2(http_t *http, /* I - HTTP connection */ http_field_t field, /* I - Field index */ const char *name, /* I - Name of sub-field */ @@ -1616,7 +1616,7 @@ httpOptions(http_t *http, /* I - HTTP connection */ * * This function copies available data from the given HTTP connection, reading * a buffer as needed. The data is still available for reading using - * @link httpRead@ or @link httpRead2@. + * @link httpRead2@. * * For non-blocking connections the usual timeouts apply. * @@ -2467,9 +2467,10 @@ httpReconnect2(http_t *http, /* I - HTTP connection */ * 'httpSetAuthString()' - Set the current authorization string. * * This function just stores a copy of the current authorization string in - * the HTTP connection object. You must still call httpSetField() to set - * HTTP_FIELD_AUTHORIZATION prior to issuing a HTTP request using httpGet(), - * httpHead(), httpOptions(), httpPost, or httpPut(). + * the HTTP connection object. You must still call @link httpSetField@ to set + * @code HTTP_FIELD_AUTHORIZATION@ prior to issuing a HTTP request using + * @link httpGet@, @link httpHead@, @link httpOptions@, @link httpPost@, or + * @link httpPut@. * * @since CUPS 1.3/macOS 10.5@ */ @@ -2820,7 +2821,7 @@ httpSetTimeout( http_t *http, /* I - HTTP connection */ double timeout, /* I - Number of seconds for timeout, must be greater than 0 */ - http_timeout_cb_t cb, /* I - Callback function or NULL */ + http_timeout_cb_t cb, /* I - Callback function or @code NULL@ */ void *user_data) /* I - User data pointer */ { if (!http || timeout <= 0.0) @@ -2864,6 +2865,8 @@ httpShutdown(http_t *http) /* I - HTTP connection */ /* * 'httpTrace()' - Send an TRACE request to the server. + * + * @exclude all@ */ int /* O - Status of call (0 = success) */ @@ -3898,7 +3901,7 @@ static http_t * /* O - HTTP connection */ http_create( const char *host, /* I - Hostname */ int port, /* I - Port number */ - http_addrlist_t *addrlist, /* I - Address list or NULL */ + http_addrlist_t *addrlist, /* I - Address list or @code NULL@ */ int family, /* I - Address family or AF_UNSPEC */ http_encryption_t encryption, /* I - Encryption to use */ int blocking, /* I - 1 for blocking mode */ diff --git a/cups/options.c b/cups/options.c index 901c75df3..9aa20f895 100644 --- a/cups/options.c +++ b/cups/options.c @@ -1,7 +1,7 @@ /* * Option routines for CUPS. * - * Copyright 2007-2014 by Apple Inc. + * Copyright 2007-2017 by Apple Inc. * Copyright 1997-2007 by Easy Software Products. * * These coded instructions, statements, and computer programs are the @@ -35,7 +35,7 @@ static int cups_find_option(const char *name, int num_options, * New option arrays can be initialized simply by passing 0 for the * "num_options" parameter. * - * @since CUPS 2.2.4@ + * @since CUPS 2.2.4/macOS 10.13@ */ int /* O - Number of options */ @@ -185,7 +185,7 @@ cupsFreeOptions( * INT_MIN is returned when the option does not exist, is not an integer, or * exceeds the range of values for the "int" type. * - * @since 2.2.4@ + * @since CUPS 2.2.4/macOS 10.13@ */ int /* O - Option value or @code INT_MIN@ */ diff --git a/cups/usersys.c b/cups/usersys.c index b4fa81f78..88cccfa23 100644 --- a/cups/usersys.c +++ b/cups/usersys.c @@ -147,7 +147,7 @@ cupsGetPassword(const char *prompt) /* I - Prompt string */ /* - * 'cupsGetPassword2()' - Get a password from the user using the advanced + * 'cupsGetPassword2()' - Get a password from the user using the current * password callback. * * Uses the current password callback function. Returns @code NULL@ if the @@ -155,8 +155,8 @@ cupsGetPassword(const char *prompt) /* I - Prompt string */ * * Note: The current password callback function is tracked separately for each * thread in a program. Multi-threaded programs that override the setting via - * the @link cupsSetPasswordCB@ or @link cupsSetPasswordCB2@ functions need to - * do so in each thread for the same function to be used. + * the @link cupsSetPasswordCB2@ function need to do so in each thread for the + * same function to be used. * * @since CUPS 1.4/macOS 10.6@ */ |