Move existing samba4 documentation to Samba-docs trunk

(This used to be commit ee3dfdcf09d6a657cf7e7325f10aa3154867c351)

1 files changed, 395 insertions, 0 deletions

diff --git a/docs/Samba3-Developers-Guide/printing.xml b/docs/Samba3-Developers-Guide/printing.xml
new file mode 100644
index 0000000000..fc0a1ee4b7
--- /dev/null
+++ b/docs/Samba3-Developers-Guide/printing.xml
@@ -0,0 +1,395 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<chapter id="printing">
+<chapterinfo>
+	<author>
+		<firstname>Gerald</firstname><surname>Carter</surname>
+	</author>
+	<pubdate>October 2002</pubdate>
+</chapterinfo>
+
+
+<title>Samba Printing Internals</title>
+
+
+<sect1>
+<title>Abstract</title>
+<para>
+The purpose of this document is to provide some insight into
+Samba's printing functionality and also to describe the semantics
+of certain features of Windows client printing.
+</para>
+</sect1>
+
+
+
+<sect1>
+<title>
+Printing Interface to Various Back ends
+</title>
+
+<para>
+Samba uses a table of function pointers to seven functions.  The
+function prototypes are defined in the <varname>printif</varname> structure declared
+in <filename>printing.h</filename>.
+</para>
+
+<itemizedlist>
+	<listitem><para>retrieve the contents of a print queue</para></listitem>
+	<listitem><para>pause the print queue</para></listitem>
+	<listitem><para>resume a paused print queue</para></listitem>
+	<listitem><para>delete a job from the queue</para></listitem>
+	<listitem><para>pause a job in the print queue</para></listitem>
+	<listitem><para>result a paused print job in the queue</para></listitem>
+	<listitem><para>submit a job to the print queue</para></listitem>
+</itemizedlist>
+
+<para>
+Currently there are only two printing back end implementations
+defined.
+</para>
+
+<itemizedlist>
+	<listitem><para>a generic set of functions for working with standard UNIX
+	printing subsystems</para></listitem>
+
+	<listitem><para>a set of CUPS specific functions (this is only enabled if
+	the CUPS libraries were located at compile time).</para></listitem>
+</itemizedlist>
+
+</sect1>
+
+
+
+
+<sect1>
+<title>
+Print Queue TDB's
+</title>
+
+
+<para>
+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.
+</para>
+
+<para>
+The list of currently opened print queue TDB's can be 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.
+</para>
+
+<para>
+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".
+</para>
+
+<para><programlisting>
+/* 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;
+};
+</programlisting></para>
+
+<para>
+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 the queue's
+TDB, a 32-bit job ID above the &lt;*vance doesn't know what word is missing here*&gt; is generating by adding UNIX_JOB_START to
+the id reported by lpq.
+</para>
+
+<para>
+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 appropriate
+for old lanman clients.
+</para>
+
+<para>
+When updating a print queue, smbd will perform the following
+steps ( refer to <filename>print.c:print_queue_update()</filename> ):
+</para>
+
+<orderedlist>
+	<listitem><para>Check to see if another smbd is currently in 
+	the process of updating the queue contents by checking the pid 
+	stored in <constant>LOCK/<replaceable>printer_name</replaceable></constant>.  
+	If so, then do not update the TDB.</para></listitem>
+	
+	<listitem><para>Lock the mutex entry in the TDB and store our own pid.
+	Check that this succeeded, else fail.</para></listitem>
+
+	<listitem><para>Store the updated time stamp for the new cache
+	listing</para></listitem>
+
+	<listitem><para>Retrieve the queue listing via "lpq command"</para></listitem>
+
+	<listitem><para><programlisting>
+	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
+		}
+	}</programlisting></para></listitem>
+
+	<listitem><para>Delete any jobs in the TDB that are not
+	in the in the lpq listing</para></listitem>
+
+	<listitem><para>Store the print queue status in the TDB</para></listitem>
+	
+	<listitem><para>update the cache time stamp again</para></listitem>
+	
+</orderedlist>
+
+<para>
+Note that it is the contents of this TDB that is returned to Windows
+clients and not the actual listing from the "lpq command".
+</para>
+
+<para>
+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 OpenPrinterEx() call and subsequently submitted a job for
+printing on that same 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.
+</para>
+
+<para>
+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.
+</para>
+
+</sect1>
+
+
+
+
+<sect1>
+<title>
+ChangeID and Client Caching of Printer Information
+</title>
+
+<para>
+[To be filled in later]
+</para>
+</sect1>
+
+
+
+<sect1>
+<title>
+Windows NT/2K Printer Change Notify
+</title>
+
+<para>
+When working with Windows NT+ clients, it is possible for a
+print server to use RPC to send asynchronous change notification
+events to clients for certain printer and print job attributes.
+This can be useful when the client needs to know that a new
+job has been added to the queue for a given printer or that the
+driver for a printer has been changed.  Note that this is done
+entirely orthogonal to cache updates based on a new ChangeID for
+a printer object.
+</para>
+
+<para>
+The basic set of RPC's used to implement change notification are
+</para>
+
+<itemizedlist>
+	<listitem><para>RemoteFindFirstPrinterChangeNotifyEx ( RFFPCN )</para></listitem>
+	<listitem><para>RemoteFindNextPrinterChangeNotifyEx ( RFNPCN )</para></listitem>
+	<listitem><para>FindClosePrinterChangeNotify( FCPCN )</para></listitem>
+	<listitem><para>ReplyOpenPrinter</para></listitem>
+	<listitem><para>ReplyClosePrinter</para></listitem>
+	<listitem><para>RouteRefreshPrinterChangeNotify ( RRPCN )</para></listitem>
+</itemizedlist>
+
+<para>
+One additional RPC is available to a server, but is never used by the
+Windows spooler service:
+</para>
+
+<itemizedlist>
+	<listitem><para>RouteReplyPrinter()</para></listitem>
+</itemizedlist>
+
+<para>
+The opnum for all of these RPC's are defined in include/rpc_spoolss.h
+</para>
+
+<para>
+Windows NT print servers use a bizarre method of sending print
+notification event to clients.  The process of registering a new change
+notification handle is as follows.  The 'C' is for client and the
+'S' is for server.  All error conditions have been eliminated.
+</para>
+
+<para><programlisting>
+C:	Obtain handle to printer or to the printer
+	server via the standard OpenPrinterEx() call.
+S:	Respond with a valid handle to object
+
+C:	Send a RFFPCN request with the previously obtained
+	handle with either (a) set of flags for change events
+	to monitor, or (b) a PRINTER_NOTIFY_OPTIONS structure
+	containing the event information to monitor.  The windows
+	spooler has only been observed to use (b).
+S:	The &lt;* another missing word*&gt; opens a new TCP session to the client (thus requiring
+	all print clients to be CIFS servers as well) and sends
+	a ReplyOpenPrinter() request to the client.
+C:	The client responds with a printer handle that can be used to
+	send event notification messages.
+S:	The server replies success to the RFFPCN request.
+
+C:	The windows spooler follows the RFFPCN with a RFNPCN
+	request to fetch the current values of all monitored
+	attributes.
+S:	The server replies with an array SPOOL_NOTIFY_INFO_DATA
+	structures (contained in a SPOOL_NOTIFY_INFO structure).
+
+C:	If the change notification handle is ever released by the
+	client via a FCPCN request, the server sends a ReplyClosePrinter()
+	request back to the client first.  However a request of this
+	nature from the client is often an indication that the previous
+	notification event was not marshalled correctly by the server
+	or a piece of data was wrong.
+S:	The server closes the internal change notification handle
+	(POLICY_HND) and does not send any further change notification
+	events to the client for that printer or job.
+</programlisting></para>
+
+<para>
+The current list of notification events supported by Samba can be
+found by examining the internal tables in srv_spoolss_nt.c
+</para>
+
+<itemizedlist>
+	<listitem><para>printer_notify_table[]</para></listitem>
+	<listitem><para>job_notify_table[]</para></listitem>
+</itemizedlist>
+
+<para>
+When an event occurs that could be monitored, smbd sends a message
+to itself about the change.  The list of events to be transmitted
+are queued by the smbd process sending the message to prevent an
+overload of TDB usage and the internal message is sent during smbd's
+idle loop (refer to printing/notify.c and the functions
+send_spoolss_notify2_msg() and print_notify_send_messages() ).
+</para>
+
+<para>
+The decision of whether or not the change is to be sent to connected
+clients is made by the routine which actually sends the notification.
+( refer to srv_spoolss_nt.c:recieve_notify2_message() ).
+</para>
+
+<para>
+Because it possible to receive a listing of multiple changes for
+multiple printers, the notification events must be split into
+categories by the printer name.  This makes it possible to group
+multiple change events to be sent in a single RPC according to the
+printer handle obtained via a ReplyOpenPrinter().
+</para>
+
+<para>
+The actual change notification is performed using the RRPCN request
+RPC.  This packet contains
+</para>
+
+
+<itemizedlist>
+	
+<listitem><para>the printer handle registered with the
+client's spooler on which the change occurred</para></listitem>
+
+<listitem><para>The change_low value which was sent as part
+of the last RFNPCN request from the client</para></listitem>
+
+<listitem><para>The SPOOL_NOTIFY_INFO container with the event
+information</para></listitem>
+
+</itemizedlist>
+
+<para>
+A <varname>SPOOL_NOTIFY_INFO</varname> contains:
+</para>
+
+<itemizedlist>
+
+<listitem><para>the version and flags field are predefined
+and should not be changed</para></listitem>
+
+<listitem><para>The count field is the number of entries
+in the SPOOL_NOTIFY_INFO_DATA array</para></listitem>
+
+</itemizedlist>
+
+<para>
+The <varname>SPOOL_NOTIFY_INFO_DATA</varname> entries contain:
+</para>
+
+<itemizedlist>
+
+<listitem><para>The type defines whether or not this event
+is for a printer or a print job</para></listitem>
+
+<listitem><para>The field is the flag identifying the event</para></listitem>
+
+<listitem><para>the notify_data union contains the new valuie of the
+attribute</para></listitem>
+
+<listitem><para>The enc_type defines the size of the structure for marshalling
+and unmarshalling</para></listitem>
+
+<listitem><para>(a) the id must be 0 for a printer event on a printer handle.
+(b) the id must be the job id for an event on a printer job
+(c) the id must be the matching number of the printer index used
+in the response packet to the RFNPCN when using a print server
+handle for notification.  Samba currently uses the snum of
+the printer for this which can break if the list of services
+has been modified since the notification handle was registered.</para></listitem>
+
+<listitem><para>The size is either (a) the string length in UNICODE for strings,
+(b) the size in bytes of the security descriptor, or (c) 0 for
+data values.</para></listitem>
+
+</itemizedlist>
+
+</sect1>
+</chapter>