1 <chapter id="printing">
4 <firstname>Gerald</firstname><surname>Carter</surname>
6 <pubdate>October 2002</pubdate>
10 <title>Samba Printing Internals</title>
14 <title>Abstract</title>
16 The purpose of this document is to provide some insight into
17 Samba's printing functionality and also to describe the semantics
18 of certain features of Windows client printing.
26 Printing Interface to Various Back ends
30 Samba uses a table of function pointers to seven functions. The
31 function prototypes are defined in the <varname>printif</varname> structure declared
32 in <filename>printing.h</filename>.
36 <listitem><para>retrieve the contents of a print queue</para></listitem>
37 <listitem><para>pause the print queue</para></listitem>
38 <listitem><para>resume a paused print queue</para></listitem>
39 <listitem><para>delete a job from the queue</para></listitem>
40 <listitem><para>pause a job in the print queue</para></listitem>
41 <listitem><para>result a paused print job in the queue</para></listitem>
42 <listitem><para>submit a job to the print queue</para></listitem>
46 Currently there are only two printing back end implementations
51 <listitem><para>a generic set of functions for working with standard UNIX
52 printing subsystems</para></listitem>
54 <listitem><para>a set of CUPS specific functions (this is only enabled if
55 the CUPS libraries were located at compile time).</para></listitem>
70 Samba provides periodic caching of the output from the "lpq command"
71 for performance reasons. This cache time is configurable in seconds.
72 Obviously the longer the cache time the less often smbd will be
73 required to exec a copy of lpq. However, the accuracy of the print
74 queue contents displayed to clients will be diminished as well.
78 The list of currently opened print queue TDB's can be found
79 be examining the list of tdb_print_db structures ( see print_db_head
80 in printing.c ). A queue TDB is opened using the wrapper function
81 printing.c:get_print_db_byname(). The function ensures that smbd
82 does not open more than MAX_PRINT_DBS_OPEN in an effort to prevent
83 a large print server from exhausting all available file descriptors.
84 If the number of open queue TDB's exceeds the MAX_PRINT_DBS_OPEN
85 limit, smbd falls back to a most recently used algorithm for maintaining
90 There are two ways in which a a print job can be entered into
91 a print queue's TDB. The first is to submit the job from a Windows
92 client which will insert the job information directly into the TDB.
93 The second method is to have the print job picked up by executing the
97 <para><programlisting>
98 /* included from printing.h */
100 pid_t pid; /* which process launched the job */
101 int sysjob; /* the system (lp) job number */
102 int fd; /* file descriptor of open file if open */
103 time_t starttime; /* when the job started spooling */
104 int status; /* the status of this job */
105 size_t size; /* the size of the job so far */
106 int page_count; /* then number of pages so far */
107 BOOL spooled; /* has it been sent to the spooler yet? */
108 BOOL smbjob; /* set if the job is a SMB job */
109 fstring filename; /* the filename used to spool the file */
110 fstring jobname; /* the job name given to us by the client */
111 fstring user; /* the user who started the job */
112 fstring queuename; /* service number of printer for this job */
113 NT_DEVICEMODE *nt_devmode;
115 </programlisting></para>
118 The current manifestation of the printjob structure contains a field
119 for the UNIX job id returned from the "lpq command" and a Windows job
120 ID (32-bit bounded by PRINT_MAX_JOBID). When a print job is returned
121 by the "lpq command" that does not match an existing job in the queue's
122 TDB, a 32-bit job ID above the <*vance doesn't know what word is missing here*> is generating by adding UNIX_JOB_START to
123 the id reported by lpq.
127 In order to match a 32-bit Windows jobid onto a 16-bit lanman print job
128 id, smbd uses an in memory TDB to match the former to a number appropriate
129 for old lanman clients.
133 When updating a print queue, smbd will perform the following
134 steps ( refer to <filename>print.c:print_queue_update()</filename> ):
138 <listitem><para>Check to see if another smbd is currently in
139 the process of updating the queue contents by checking the pid
140 stored in <constant>LOCK/<replaceable>printer_name</replaceable></constant>.
141 If so, then do not update the TDB.</para></listitem>
143 <listitem><para>Lock the mutex entry in the TDB and store our own pid.
144 Check that this succeeded, else fail.</para></listitem>
146 <listitem><para>Store the updated time stamp for the new cache
147 listing</para></listitem>
149 <listitem><para>Retrieve the queue listing via "lpq command"</para></listitem>
151 <listitem><para><programlisting>
152 foreach job in the queue
154 if the job is a UNIX job, create a new entry;
155 if the job has a Windows based jobid, then
157 Lookup the record by the jobid;
158 if the lookup failed, then
159 treat it as a UNIX job;
161 update the job status only
163 }</programlisting></para></listitem>
165 <listitem><para>Delete any jobs in the TDB that are not
166 in the in the lpq listing</para></listitem>
168 <listitem><para>Store the print queue status in the TDB</para></listitem>
170 <listitem><para>update the cache time stamp again</para></listitem>
175 Note that it is the contents of this TDB that is returned to Windows
176 clients and not the actual listing from the "lpq command".
180 The NT_DEVICEMODE stored as part of the printjob structure is used to
181 store a pointer to a non-default DeviceMode associated with the print
182 job. The pointer will be non-null when the client included a Device
183 Mode in the OpenPrinterEx() call and subsequently submitted a job for
184 printing on that same handle. If the client did not include a Device
185 Mode in the OpenPrinterEx() request, the nt_devmode field is NULL
186 and the job has the printer's device mode associated with it by default.
190 Only non-default Device Mode are stored with print jobs in the print
191 queue TDB. Otherwise, the Device Mode is obtained from the printer
192 object when the client issues a GetJob(level == 2) request.
202 ChangeID and Client Caching of Printer Information
206 [To be filled in later]
214 Windows NT/2K Printer Change Notify
218 When working with Windows NT+ clients, it is possible for a
219 print server to use RPC to send asynchronous change notification
220 events to clients for certain printer and print job attributes.
221 This can be useful when the client needs to know that a new
222 job has been added to the queue for a given printer or that the
223 driver for a printer has been changed. Note that this is done
224 entirely orthogonal to cache updates based on a new ChangeID for
229 The basic set of RPC's used to implement change notification are
233 <listitem><para>RemoteFindFirstPrinterChangeNotifyEx ( RFFPCN )</para></listitem>
234 <listitem><para>RemoteFindNextPrinterChangeNotifyEx ( RFNPCN )</para></listitem>
235 <listitem><para>FindClosePrinterChangeNotify( FCPCN )</para></listitem>
236 <listitem><para>ReplyOpenPrinter</para></listitem>
237 <listitem><para>ReplyClosePrinter</para></listitem>
238 <listitem><para>RouteRefreshPrinterChangeNotify ( RRPCN )</para></listitem>
242 One additional RPC is available to a server, but is never used by the
243 Windows spooler service:
247 <listitem><para>RouteReplyPrinter()</para></listitem>
251 The opnum for all of these RPC's are defined in include/rpc_spoolss.h
255 Windows NT print servers use a bizarre method of sending print
256 notification event to clients. The process of registering a new change
257 notification handle is as follows. The 'C' is for client and the
258 'S' is for server. All error conditions have been eliminated.
261 <para><programlisting>
262 C: Obtain handle to printer or to the printer
263 server via the standard OpenPrinterEx() call.
264 S: Respond with a valid handle to object
266 C: Send a RFFPCN request with the previously obtained
267 handle with either (a) set of flags for change events
268 to monitor, or (b) a PRINTER_NOTIFY_OPTIONS structure
269 containing the event information to monitor. The windows
270 spooler has only been observed to use (b).
271 S: The <* another missing word*> opens a new TCP session to the client (thus requiring
272 all print clients to be CIFS servers as well) and sends
273 a ReplyOpenPrinter() request to the client.
274 C: The client responds with a printer handle that can be used to
275 send event notification messages.
276 S: The server replies success to the RFFPCN request.
278 C: The windows spooler follows the RFFPCN with a RFNPCN
279 request to fetch the current values of all monitored
281 S: The server replies with an array SPOOL_NOTIFY_INFO_DATA
282 structures (contained in a SPOOL_NOTIFY_INFO structure).
284 C: If the change notification handle is ever released by the
285 client via a FCPCN request, the server sends a ReplyClosePrinter()
286 request back to the client first. However a request of this
287 nature from the client is often an indication that the previous
288 notification event was not marshalled correctly by the server
289 or a piece of data was wrong.
290 S: The server closes the internal change notification handle
291 (POLICY_HND) and does not send any further change notification
292 events to the client for that printer or job.
293 </programlisting></para>
296 The current list of notification events supported by Samba can be
297 found by examining the internal tables in srv_spoolss_nt.c
301 <listitem><para>printer_notify_table[]</para></listitem>
302 <listitem><para>job_notify_table[]</para></listitem>
306 When an event occurs that could be monitored, smbd sends a message
307 to itself about the change. The list of events to be transmitted
308 are queued by the smbd process sending the message to prevent an
309 overload of TDB usage and the internal message is sent during smbd's
310 idle loop (refer to printing/notify.c and the functions
311 send_spoolss_notify2_msg() and print_notify_send_messages() ).
315 The decision of whether or not the change is to be sent to connected
316 clients is made by the routine which actually sends the notification.
317 ( refer to srv_spoolss_nt.c:recieve_notify2_message() ).
321 Because it possible to receive a listing of multiple changes for
322 multiple printers, the notification events must be split into
323 categories by the printer name. This makes it possible to group
324 multiple change events to be sent in a single RPC according to the
325 printer handle obtained via a ReplyOpenPrinter().
329 The actual change notification is performed using the RRPCN request
330 RPC. This packet contains
336 <listitem><para>the printer handle registered with the
337 client's spooler on which the change occurred</para></listitem>
339 <listitem><para>The change_low value which was sent as part
340 of the last RFNPCN request from the client</para></listitem>
342 <listitem><para>The SPOOL_NOTIFY_INFO container with the event
343 information</para></listitem>
348 A <varname>SPOOL_NOTIFY_INFO</varname> contains:
353 <listitem><para>the version and flags field are predefined
354 and should not be changed</para></listitem>
356 <listitem><para>The count field is the number of entries
357 in the SPOOL_NOTIFY_INFO_DATA array</para></listitem>
362 The <varname>SPOOL_NOTIFY_INFO_DATA</varname> entries contain:
367 <listitem><para>The type defines whether or not this event
368 is for a printer or a print job</para></listitem>
370 <listitem><para>The field is the flag identifying the event</para></listitem>
372 <listitem><para>the notify_data union contains the new valuie of the
373 attribute</para></listitem>
375 <listitem><para>The enc_type defines the size of the structure for marshalling
376 and unmarshalling</para></listitem>
378 <listitem><para>(a) the id must be 0 for a printer event on a printer handle.
379 (b) the id must be the job id for an event on a printer job
380 (c) the id must be the matching number of the printer index used
381 in the response packet to the RFNPCN when using a print server
382 handle for notification. Samba currently uses the snum of
383 the printer for this which can break if the list of services
384 has been modified since the notification handle was registered.</para></listitem>
386 <listitem><para>The size is either (a) the string length in UNICODE for strings,
387 (b) the size in bytes of the security descriptor, or (c) 0 for
388 data values.</para></listitem>