From 68ccc823484edec3cf3a4d78955946dd84c39d51 Mon Sep 17 00:00:00 2001 From: Kappuccino111 <120595108+Kappuccino111@users.noreply.github.com> Date: Thu, 19 Jan 2023 01:38:07 +0530 Subject: [PATCH 01/52] Update for better codedoc parsing --- pappl/win32-gettimeofday.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pappl/win32-gettimeofday.c b/pappl/win32-gettimeofday.c index c9ab9abe..d2d0e173 100644 --- a/pappl/win32-gettimeofday.c +++ b/pappl/win32-gettimeofday.c @@ -14,7 +14,7 @@ # include "base-private.h" -// +// @private@ // 'gettimeofday()' - Get the current date and time in seconds and microseconds. // From 50e6683a40f2384bde7487ce534dd35c634377d5 Mon Sep 17 00:00:00 2001 From: Kappuccino111 <120595108+Kappuccino111@users.noreply.github.com> Date: Thu, 19 Jan 2023 01:44:43 +0530 Subject: [PATCH 02/52] Update for better codedoc parsing --- pappl/win32-pthread.c | 48 +++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/pappl/win32-pthread.c b/pappl/win32-pthread.c index 66025cd6..eb97a7ca 100644 --- a/pappl/win32-pthread.c +++ b/pappl/win32-pthread.c @@ -40,7 +40,7 @@ static DWORD pthread_tls(void); static int pthread_wrapper(pthread_t t); -// +// @private@ // 'pthread_cancel()' - Cancel a child thread. // @@ -56,7 +56,7 @@ pthread_cancel(pthread_t t) // I - Thread ID } -// +// @private@ // 'pthread_cond_broadcast()' - Unblock all threads waiting on a condition // variable. // @@ -71,7 +71,7 @@ pthread_cond_broadcast( } -// +// @private@ // 'pthread_cond_destroy()' - Free memory associated with a condition variable. // @@ -84,7 +84,7 @@ pthread_cond_destroy(pthread_cond_t *c) // I - Condition variable } -// +// @private@ // 'pthread_cond_init()' - Initialize a condition variable. // @@ -100,7 +100,7 @@ pthread_cond_init(pthread_cond_t *c, // I - Condition variable } -// +// @private@ // 'pthread_cond_signal()' - Wake a single thread waiting on a condition // variable. // @@ -114,7 +114,7 @@ pthread_cond_signal(pthread_cond_t *c) // I - Condition variable } -// +// @private@ // 'pthread_cond_timedwait()' - Wait a specified amount of time for a condition // variable. // @@ -134,7 +134,7 @@ pthread_cond_timedwait( } -// +// @private@ // 'pthread_cond_wait()' - Wait indefinitely for a condition variable. // @@ -150,7 +150,7 @@ pthread_cond_wait(pthread_cond_t *c, // I - Condition variable } -// +// @private@ // 'pthread_create()' - Create a new child thread. // @@ -190,7 +190,7 @@ pthread_create( } -// +// @private@ // 'pthread_detach()' - Detach a child thread from its parent. // @@ -207,7 +207,7 @@ pthread_detach(pthread_t t) // I - Thread ID } -// +// @private@ // 'pthread_join()' - Wait for a child thread to complete. // @@ -235,7 +235,7 @@ pthread_join(pthread_t t, // I - Thread ID } -// +// @private@ // 'pthread_msec()' - Calculate milliseconds for a given time value. // @@ -250,7 +250,7 @@ pthread_msec(struct timespec *ts) // I - Time value } -// +// @private@ // 'pthread_mutex_destroy()' - Free memory used by a mutex. // @@ -267,7 +267,7 @@ pthread_mutex_destroy( } -// +// @private@ // 'pthread_mutex_init()' - Initialize a mutex. // @@ -287,7 +287,7 @@ pthread_mutex_init( } -// +// @private@ // 'pthread_mutex_lock()' - Lock a mutex. // @@ -303,7 +303,7 @@ pthread_mutex_lock(pthread_mutex_t *m) // I - Mutual exclusion lock } -// +// @private@ // 'pthread_mutex_unlock()' - Unlock a mutex. // @@ -319,7 +319,7 @@ pthread_mutex_unlock(pthread_mutex_t *m)// I - Mutual exclusion lock } -// +// @private@ // 'pthread_rwlock_destroy()' - Free all memory used by a reader/writer lock. // @@ -336,7 +336,7 @@ pthread_rwlock_destroy( } -// +// @private@ // 'pthread_rwlock_init()' - Initialize a reader/writer lock. // @@ -356,7 +356,7 @@ pthread_rwlock_init( } -// +// @private@ // 'pthread_rwlock_rdlock()' - Obtain a reader lock. // @@ -373,7 +373,7 @@ pthread_rwlock_rdlock( } -// +// @private@ // 'pthread_rwlock_unlock()' - Release a reader/writer lock. // @@ -398,7 +398,7 @@ pthread_rwlock_unlock( } -// +// @private@ // 'pthread_rwlock_wrlock()' - Obtain a writer lock. // @@ -415,7 +415,7 @@ pthread_rwlock_wrlock( } -// +// @private@ // 'pthread_self()' - Return the current thread. // @@ -447,7 +447,7 @@ pthread_self(void) } -// +// @private@ // 'pthread_testcancel()' - Mark a safe cancellation point. // @@ -463,7 +463,7 @@ pthread_testcancel(void) } -// +// @private@ // 'pthread_tls()' - Get the thread local storage key. // @@ -487,7 +487,7 @@ pthread_tls(void) } -// +// @private@ // 'pthread_wrapper()' - Wrapper function for a POSIX thread. // From b44151d154df5d71a64c48bef5aa9c00fb497b34 Mon Sep 17 00:00:00 2001 From: Kappuccino111 <120595108+Kappuccino111@users.noreply.github.com> Date: Thu, 19 Jan 2023 01:48:02 +0530 Subject: [PATCH 03/52] Update for better codedoc parsing --- pappl/base-private.h | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pappl/base-private.h b/pappl/base-private.h index 518ac163..c5bc1db6 100644 --- a/pappl/base-private.h +++ b/pappl/base-private.h @@ -6,7 +6,7 @@ // Licensed under Apache License v2.0. See the file "LICENSE" for more // information. // - +extern char **environ; #ifndef _PAPPL_BASE_PRIVATE_H_ # define _PAPPL_BASE_PRIVATE_H_ # include @@ -27,12 +27,12 @@ # include # include # include -extern char **environ; + # define O_BINARY 0 // I hate Windows... # endif // _WIN32 -// +// @private@ // The CUPS API is changed in CUPS v3... // @@ -87,6 +87,7 @@ typedef cups_raster_iocb_t cups_raster_cb_t; # define _PAPPL_LOOKUP_VALUE(keyword,strings) _papplLookupValue(keyword, sizeof(strings) / sizeof(strings[0]), strings) + // // Types and structures... // From 54290585e344435ccb35369b6a30fe813bfcd394 Mon Sep 17 00:00:00 2001 From: Kappuccino111 <120595108+Kappuccino111@users.noreply.github.com> Date: Thu, 19 Jan 2023 01:51:56 +0530 Subject: [PATCH 04/52] Update scanning implementations --- doc/pappl-body.md | 129 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 121 insertions(+), 8 deletions(-) diff --git a/doc/pappl-body.md b/doc/pappl-body.md index c8e4f5b8..88ccaad1 100644 --- a/doc/pappl-body.md +++ b/doc/pappl-body.md @@ -159,8 +159,9 @@ PAPPL provides five main objects: printer application; - [Clients](@) (`pappl_client_t`): The objects that manage client connections; - [Devices](@) (`pappl_device_t`): The objects that manage printer connections; -- [Printers](@) (`pappl_printer_t`): The objects that manage printers; and -- [Jobs](@) (`pappl_job_t`): The objects that manage print jobs. +- [Printers](@) (`pappl_printer_t`): The objects that manage printers; +- [Scanners](@) (`pappl_scanner_t`): The objects that manage scanners; and +- [Jobs](@) (`pappl_job_t`): The objects that manage print and scan jobs. ![PAPPL Block Diagram::100%](../doc/pappl-block.png) @@ -169,7 +170,7 @@ The System ---------- The system is an object of type [`pappl_system_t`](@@) that manages client and -device connections, listeners, the log, printers, and resources. It implements +device connections, listeners, the log, printers, scanners and resources. It implements a subset of the IPP System Service ([PWG 5100.22](https://ftp.pwg.org/pub/pwg/candidates/cs-ippsystem10-20191122-5100.22.pdf)) with each printer implementing IPP Everywhere™ @@ -187,6 +188,9 @@ functions: - [`papplSystemIteratePrinters`](@@): Iterates all print queues managed by the system. +Similarly [scanners](@) can be accessed using the following function: +- [`papplSystemFindScanner`](@@): Finds the named or numbered scan queue. + The [`papplSystemLoadState`](@@) function is often used to load system values and printers from a prior run which used the [`papplSystemSaveState`](@@) function. @@ -275,8 +279,7 @@ Similarly, the `papplSystemSet` functions set various system values: The PAPPL logging functions record messages to the configured log file. The [`papplLog`](@@) records messages applying to the system as a whole while -[`papplLogClient`](@@), [`papplLogJob`](@@), and [`papplLogPrinter`](@@) record -messages specific to a client connection, print job, or printer respectively. +[`papplLogClient`](@@), [`papplLogJob`](@@), [`papplLogPrinter`](@@), and [`papplLogScanner`](@@) record messages specific to a client connection, print job, or printer respectively. The "level" argument specifies a log level from debugging (`PAPPL_LOGLEVEL_DEBUG`) to fatal (`PAPPL_LOGLEVEL_FATAL`) and is used to @@ -349,7 +352,7 @@ localize your own dynamic content and/or main loop sub-command: - [`papplLocFormatString`](@@) formats a localized string from a given collection, - [`papplLocGetString`](@@) returns a localized string from a given - collection, and + collection, and - [`papplSystemFindLoc`](@@) finds the collection of localization strings for the specified language. @@ -357,6 +360,7 @@ Key to these functions is the [`pappl_loc_t`](@@) collection of localization strings, which combines the strings from the built-in PAPPL localizations and any strings file resources that have been added. + ### Web Interface Localization ### When localizing the web interface, PAPPL looks up strings for titles and labels @@ -391,6 +395,17 @@ and "contone" might be localized as: "smi32473-algorithm.ordered" = "À Motifs"; "smi32473-algorithm.contone" = "Tonalité Continue"; +Web pages can display a localized HTML banner for the resource path, for +example: + + /* English strings file */ + "/" = "Example text for the root web page."; + "/network" = "

Example text for the network web page.

"; + + /* French strings file */ + "/" = "Exemple de texte pour la page Web racine."; + "/network" = "

Exemple de texte pour la page Web du réseau.

"; + Clients ------- @@ -619,7 +634,9 @@ When necessary, the device associated with a printer can be opened with the ### Controlling Printers ### Printers are stopped using the [`papplPrinterPause`](@@) function and started -using the [`papplPrinterResume`](@@) function. +using the [`papplPrinterResume`](@@) function. New jobs can be held using the +[`papplPrinterHoldNewJobs`](@@) function and later released for printing using +the [`papplPrinterReleaseHeldNewJobs`](@@) function. ### Navigation Links ### @@ -628,6 +645,98 @@ Navigation links can be added to the web interface using the [`papplPrinterAddLink`](@@) function and removed using the [`papplPrinterRemoveLink`](@@) function. +Scanners +---- +Scanners are managed by the system and are represented by the +[`pappl_scanner_t`](@@) type. + +Scanners are created using the [`papplScannerCreate`](@@) function and deleted +using the [`papplScannerDelete`](@@) function. Each scanner has zero or more +jobs that are pending, processing (scanning), or completed which can be access +using any of the following functions: + +- [`papplScannerIterateActiveJobs`](@@): Iterates active scan jobs managed by + the scanner, +- [`papplScannerIterateAllJobs`](@@): Iterates all scan jobs managed by the + scanner, and +- [`papplScannerIterateCompletedJobs`](@@): Iterates completed scan jobs + managed by the scanner. + +The `papplScannerGet` functions get various scanner values: + +- [`papplScannerGetContact`](@@): Gets the contact information, +- [`papplScannerGetDeviceID`](@@): Gets the IEEE-1284 device ID, +- [`papplScannerGetDeviceURI`](@@): Gets the device URI, +- [`papplScannerGetDNSSDName`](@@): Gets the DNS-SD service instance name, +- [`papplScannerGetDriverAttributes`](@@): Gets a copy of the current driver attributes, +- [`papplScannerGetDriverData`](@@): Gets the current scan driver data, +- [`papplScannerGetDriverName`](@@): Gets the driver name for a scanner, +- [`papplScannerGetGeoLocation`](@@): Gets the geographic location as a "geo:" + URI, +- [`papplScannerGetID`](@@): Gets the ID number, +- [`papplScannerGetImpressionsCompleted`](@@): Gets the number of impressions + (sides) that have been scanned, +- [`papplScannerGetLocation`](@@): Gets the human-readable location, +- [`papplScannerGetMaxActiveJobs`](@@): Gets the maximum number of simultaneous + active (queued) jobs, +- [`papplScannnerGetMaxCompletedJobs`](@@): Gets the maximum number of completed + jobs for the job history, +- [`papplScannerGetName`](@@): Gets the name, +- [`papplScannerGetNextJobID`](@@): Gets the ID number of the next job that is + created, +- [`papplScannerGetNumberOfActiveJobs`](@@): Gets the current number of active + jobs, +- [`papplScannnerGetNumberOfCompletedJobs`](@@): Gets the current number of + completed jobs in the job history, +- [`papplScannerGetNumberOfJobs`](@@): Gets the total number of jobs in memory, +- [`papplScannerGetOrganization`](@@): Gets the organization name, +- [`papplScannerGetOrganizationalUnit`](@@): Gets the organizational unit name, +- [`papplScannerGetPath`](@@): Gets the path of a scanner web page, +- [`papplScannerGetScanGroup`](@@): Gets the scan authorization group name, +- [`papplScannerGetReasons`](@@): Gets the "scanner-state-reasons" bitfield, +- [`papplScannerGetState`](@@): Gets the "scanner-state" value, +- [`papplScannerGetSystem`](@@): Gets the system managing the scanner. + +Similarly, the `papplScannerSet` functions set those values: + +- [`papplScannerSetContact`](@@): Sets the contact information, +- [`papplScannerSetDNSSDName`](@@): Sets the DNS-SD service instance name, +- [`papplScannerSetDriverData`](@@): Sets the current scan driver data, +- [`papplScannerSetDriverDefaults`](@@): Sets the driver name for a scanner, +- [`papplScannerSetGeoLocation`](@@): Sets the geographic location as a "geo:" + URI, +- [`papplScannerSetImpressionsCompleted`](@@): Sets the number of impressions + that have been scanned, +- [`papplScannerSetLocation`](@@): Sets the human-readable location, +- [`papplScannerSetMaxActiveJobs`](@@): Sets the maximum number of jobs that can + be queued, +- [`papplScannerSetMaxCompletedJobs`](@@): Sets the maximum number of completed + jobs that are kept in the job history, +- [`papplScannerSetMaxPreservedJobs`](@@): Sets the maximum number of preserved + jobs (with document data) that are kept in the job history, +- [`papplScannerSetNextJobID`](@@): Sets the ID number of the next job that is + created, +- [`papplScannerSetOrganization`](@@): Sets the organization name, +- [`papplScannnerSetOrganizationalUnit`](@@): Sets the organizational unit name, +- [`papplScannerSetReadyMedia`](@@): Sets the ready (loaded) media, and +- [`papplScannerSetReasons`](@@): Sets or clears "scanner-state-reasons" values. + +### Accessing the Scanner Device ### + +When necessary, the device associated with a scanner can be opened with the +[`papplScannerOpenDevice`](@@) function and subsequently closed using the +[`papplScannerCloseDevice`](@@) function. + + +### Controlling Scanners ### + +Scanners are stopped using the [`papplScannerPause`](@@) function and started +using the [`papplScannerResume`](@@) function. + +### Navigation Links ### + +Navigation links can be added to the web interface using the +[`papplScannerAddLink`](@@) function. Jobs ---- @@ -676,7 +785,11 @@ a job: The [`papplJobCancel`](@@) function cancels processing of a job while the [`papplJobIsCanceled`](@@) function returns whether a job is in the canceled -state (`IPP_JSTATE_CANCELED`) or is in the process of being canceled (`IPP_JSTATE_PROCESSING` and `PAPPL_JREASON_PROCESSING_TO_STOP_POINT`). +state (`IPP_JSTATE_CANCELED`) or is in the process of being canceled +(`IPP_JSTATE_PROCESSING` and `PAPPL_JREASON_PROCESSING_TO_STOP_POINT`). + +The [`papplJobHold`](@@) function holds a job while the [`papplJobRelease`](@@) +function releases a job for printing. ### Processing Jobs ### From ed10846645acd216b8389ffc126f98403679d425 Mon Sep 17 00:00:00 2001 From: Kappuccino111 <120595108+Kappuccino111@users.noreply.github.com> Date: Thu, 19 Jan 2023 01:55:06 +0530 Subject: [PATCH 05/52] Update for scanning implementation using codedoc Body of this file has been built upon updated pappl-body.md --- doc/pappl.html | 1630 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 1545 insertions(+), 85 deletions(-) diff --git a/doc/pappl.html b/doc/pappl.html index ec717368..c2e29a43 100644 --- a/doc/pappl.html +++ b/doc/pappl.html @@ -1,13 +1,13 @@ -PAPPL v1.2 Programmers Manual +PAPPL v1.3 Programmers Manual - + - +