more details opn change notification

(This used to be commit a4a3469ffb44061c58bbcd807a9585ae13326f7b)

1 files changed, 80 insertions, 9 deletions

diff --git a/docs/docbook/devdoc/printing.sgml b/docs/docbook/devdoc/printing.sgml
index 3cce7ab99c..1d4085bb88 100644
--- a/docs/docbook/devdoc/printing.sgml
+++ b/docs/docbook/devdoc/printing.sgml
@@ -60,14 +60,85 @@ 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 and either (a)
+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 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 PCPCN 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.
+
+The current list of notification events supported by Samba can be 
+found by examining the internal tables in srv_spoolss_nt.c
+
+  * printer_notify_table[]
+  * job_notify_table[]
+
+When an event occurs that could be monitored, smbd sends a messages
+to itself about the change.  The list of events to be transmitted 
+are queued by the smbd process sending the message to prevent and 
+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() ).
+
+
+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() ).  
+
+Because it possible to recieve 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().
+
+The actual change notification is performed using the RRPCN request 
+RPC.  This packet contains 
+
+  * the printer handle registered with the client's spooler on 
+    which the change occurred
+  * The change_low value which was sent as part of the last 
+    RFNPCN request from the client
+  * The SPOOL_NOTIFY_INFO container with the event information
+    - the version and flags field are predefined and should not 
+      be changed
+    - The count field is the number of entries in the 
+      SPOOL_NOTIFY_INFO_DATA array
+      o The type defines whether or not this event is for a printer 
+        or a print job
+      o The field is the flag identifying the event
+      o the notify_data union contains the new valuie of the attribute
+      o The enc_type defines the size of the structure for marshalling
+        and unmarshalling
+      o (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.
+       o 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.
 
 
-
-* Back Channel
-* Methods of sending an event
-* Id numbers (print server handles, jobids, & printer handles )
-* event types ( jobs & printer attributes )
-* aggegating notifications
-