!=
!= Samba Printing Internals
-!=
+!=
!= Author : Gerald Carter <jerry@samba.org>
!=
!===================================================================
Samba's printing functionality and also to describe the semantics
of certain features of Windows client printing.
+
+Printing Interface to Various Backends
+--------------------------------------
+
+Samba uses a table of function pointers to seven functions. The
+function prototypes are defined in the printif structure declared
+in printing.h.
+
+ * retrieve the contents of a print queue
+ * pause the print queue
+ * resume a paused print queue
+ * delete a job from the queue
+ * pause a job in the print queue
+ * result a paused print job in the queue
+ * submit a jobn to the print queue
+
+Currently there are only two printing backend implementations
+defined.
+
+ * a generic set of functions for working with standard UNIX
+ printing subsystems
+ * a set of CUPS specific functions (this is only enabled if
+ the CUPS libraries were located at compile time).
+
+
+
Print Queue TDB's
------------------
-* matching lanman jobids, spoolss jobids, & lpd jobids
-* why ?
-* caching time
+Samba provides periodic caching of the output from the "lpq command"
+for performance reasons. This cache time is configurable in seconds.
+Obviously the longer the cache time the less often smbd will be
+required to exec a copy of lpq. However, the accuracy of the print
+queue contents displayed to clients will be diminished as well.
+
+The list of currently opened print queue TDB's can eb found
+be examining the list of tdb_print_db structures ( see print_db_head
+in printing.c ). A queue TDB is opened using the wrapper function
+printing.c:get_print_db_byname(). The function ensures that smbd
+does not open more than MAX_PRINT_DBS_OPEN in an effort to prevent
+a large print server from exhausting all available file descriptors.
+If the number of open queue TDB's exceeds the MAX_PRINT_DBS_OPEN
+limit, smbd falls back to a most recently used algorithm for maintaining
+a list of open TDB's.
+
+There are two ways in which a a print job can be entered into
+a print queue's TDB. The first is to submit the job from a Windows
+client which will insert the job information directly into the TDB.
+The second method is to have the print job picked up by executing the
+"lpq command".
+
+/* included from printing.h */
+struct printjob {
+ pid_t pid; /* which process launched the job */
+ int sysjob; /* the system (lp) job number */
+ int fd; /* file descriptor of open file if open */
+ time_t starttime; /* when the job started spooling */
+ int status; /* the status of this job */
+ size_t size; /* the size of the job so far */
+ int page_count; /* then number of pages so far */
+ BOOL spooled; /* has it been sent to the spooler yet? */
+ BOOL smbjob; /* set if the job is a SMB job */
+ fstring filename; /* the filename used to spool the file */
+ fstring jobname; /* the job name given to us by the client */
+ fstring user; /* the user who started the job */
+ fstring queuename; /* service number of printer for this job */
+ NT_DEVICEMODE *nt_devmode;
+};
+
+The current manifestation of the printjob structure contains a field
+for the UNIX job id returned from the "lpq command" and a Windows job
+ID (32-bit bounded by PRINT_MAX_JOBID). When a print job is returned
+by the "lpq command" that does not match an existing job in th queue's
+TDB, a 32-bit job ID above the is generating by adding UNIX_JOB_START to
+the id reported by lpq.
+
+In order to match a 32-bit Windows jobid onto a 16-bit lanman print job
+id, smbd uses an in memory TDB to match the former to a number approriate
+for old lanman clients.
+
+When updating a print queue, smbd will performs the following
+steps ( refer to print.c:print_queue_update() ):
+
+ 1) Check to see if another sbmd is currently in the process of
+ updating the queue contents by checking the pid stored in
+ "LOCK/<printer_name>". If so, then do not update the TDB.
+ 2) Lock the mutex entry in the TDB and store our own pid.
+ Check that this succeeded, else fail.
+ 3) Store the updated time stamp for the new cache listing
+ 4) Retrieve the queue listing via "lpq command"
+ 5) foreach job in the queue
+ {
+ if the job is a UNIX job, create a new entry;
+ if the job has a Windows based jobid, then
+ {
+ Lookup the record by the jobid;
+ if the lookup failed, then
+ treat it as a UNIX job;
+ else
+ update the job status only
+ }
+ }
+ 6) Delete any jobs in the TDB that are not in the in the lpq
+ listing
+ 7) Store the print queue status in the TDB
+ 8) update the cache time stamp again
+
+Note that it is the contents of this TDB that is returned to Windows
+clients and not the actual listing from the "lpq command".
+
+The NT_DEVICEMODE stored as part of the printjob structure is used to
+store a pointer to a non-default DeviceMode associated with the print
+job. The pointer will be non-null when the client included a Device
+Mode in the OpePrinterEx() call and subsequently submitted a job for
+printing on that sam handle. If the client did not include a Device
+Mode in the OpenPrinterEx() request, the nt_devmode field is NULL
+and the job has the printer's device mode associated with it by default.
+
+Only non-default Device Mode are stored with print jobs in the print
+queue TDB. Otherwise, the Device Mode is obtained from the printer
+object when the client issues a GetJob(level == 2) request.
+
+
+
+
ChangeID & Client Caching of Printer Information
------------------------------------------------
-[To be filled in later]
+ [To be filled in later]
Windows NT/2K Printer Change Notify
git.samba.org / vlendec / samba-autobuild / .git / commitdiff