From a2b150ee89f7d05ecc819801d01fb202e06b9ede Mon Sep 17 00:00:00 2001 From: Gerald Carter Date: Mon, 30 Sep 2002 04:58:55 +0000 Subject: This is an initial draft of printing internals. Not done (not really even started), and not in SGML. Plain ASCII right now, but I'll do some more work on it tomorrow. (This used to be commit d60afa48e3214a4fa4c0a937635c3acf2a4b4a65) --- docs/docbook/devdoc/printing.sgml | 73 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/docbook/devdoc/printing.sgml (limited to 'docs/docbook/devdoc') diff --git a/docs/docbook/devdoc/printing.sgml b/docs/docbook/devdoc/printing.sgml new file mode 100644 index 0000000000..3cce7ab99c --- /dev/null +++ b/docs/docbook/devdoc/printing.sgml @@ -0,0 +1,73 @@ +!= +!= Samba Printing Internals +!= +!= Author : Gerald Carter +!= +!=================================================================== + +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. + +Print Queue TDB's +------------------ + +* matching lanman jobids, spoolss jobids, & lpd jobids +* why ? +* caching time + + +ChangeID & Client Caching of Printer Information +------------------------------------------------ + +[To be filled in later] + + +Windows NT/2K Printer Change Notify +----------------------------------- + +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. + +The basic set of RPC's used to implement change notification are + + * RemoteFindFirstPrinterChangeNotifyEx ( RFFPCN ) + * RemoteFindNextPrinterChangeNotifyEx ( RFNPCN ) + * FindClosePrinterChangeNotify( FCPCN ) + * ReplyOpenPrinter + * ReplyClosePrinter + * RouteRefreshPrinterChangeNotify ( RRPCN ) + +One additional RPC is available to a server, but is never used by the +Windows spooler service: + + * RouteReplyPrinter() + +The opnum for all of these RPC's are defined in include/rpc_spoolss.h + +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. + +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) + + + +* Back Channel +* Methods of sending an event +* Id numbers (print server handles, jobids, & printer handles ) +* event types ( jobs & printer attributes ) +* aggegating notifications + -- cgit From bf556da1e2d6df48520e17c9318eb431c7abb78c Mon Sep 17 00:00:00 2001 From: Gerald Carter Date: Mon, 30 Sep 2002 16:51:35 +0000 Subject: more details opn change notification (This used to be commit a4a3469ffb44061c58bbcd807a9585ae13326f7b) --- docs/docbook/devdoc/printing.sgml | 89 +++++++++++++++++++++++++++++++++++---- 1 file changed, 80 insertions(+), 9 deletions(-) (limited to 'docs/docbook/devdoc') 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 - -- cgit From ae61c575babe9488b190481e8f3a10754c876f06 Mon Sep 17 00:00:00 2001 From: Gerald Carter Date: Mon, 30 Sep 2002 19:52:11 +0000 Subject: more updates--printing backend inmterface & Print queue tdb's (This used to be commit a42414fe5aff8a9e0fccd1c73a86e3b472f2c149) --- docs/docbook/devdoc/printing.sgml | 129 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 124 insertions(+), 5 deletions(-) (limited to 'docs/docbook/devdoc') diff --git a/docs/docbook/devdoc/printing.sgml b/docs/docbook/devdoc/printing.sgml index 1d4085bb88..2e9d429439 100644 --- a/docs/docbook/devdoc/printing.sgml +++ b/docs/docbook/devdoc/printing.sgml @@ -1,6 +1,6 @@ != != Samba Printing Internals -!= +!= != Author : Gerald Carter != !=================================================================== @@ -9,18 +9,137 @@ 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. + +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/". 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 -- cgit From d64e0e9772e3fd1b4c5af2ff8fd6aa0b89f0fcb6 Mon Sep 17 00:00:00 2001 From: Gerald Carter Date: Mon, 30 Sep 2002 20:18:12 +0000 Subject: * add the Developers guide to the repository * fix syntax errors in developer's docs * update Makefile.in to place HTML files in htmldocs & text files in textdocs/ (This used to be commit cb96e1a1d9a07314bb60e431484cfd05aef83de6) --- docs/docbook/devdoc/internals.sgml | 1 + docs/docbook/devdoc/parsing.sgml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/docbook/devdoc') diff --git a/docs/docbook/devdoc/internals.sgml b/docs/docbook/devdoc/internals.sgml index 79524347b6..982cfd2e10 100644 --- a/docs/docbook/devdoc/internals.sgml +++ b/docs/docbook/devdoc/internals.sgml @@ -26,6 +26,7 @@ telling if a particular char* is in dos codepage or unix codepage. This led to a nightmare of code that tried to cope with particular cases without handlingt the general case. + The new functions diff --git a/docs/docbook/devdoc/parsing.sgml b/docs/docbook/devdoc/parsing.sgml index 0121935d26..8d929617f5 100644 --- a/docs/docbook/devdoc/parsing.sgml +++ b/docs/docbook/devdoc/parsing.sgml @@ -196,7 +196,7 @@ terminating character, and the rest of the line is ignored. The lines <section> :== <section header> { <parameter line> } <section header> :== '[' NAME ']' <parameter line> :== NAME '=' VALUE NL - + Basically, this means that -- cgit From 834b89cc49dc0be1a7f2b8ed4c6f070cc223896e Mon Sep 17 00:00:00 2001 From: Gerald Carter Date: Mon, 30 Sep 2002 21:07:37 +0000 Subject: * working on Makefile * converting printing internal doc to SGML (This used to be commit bc74170cd982e520421e8b930710671923d65208) --- docs/docbook/devdoc/dev-doc.sgml | 4 +- docs/docbook/devdoc/printing.sgml | 352 ++++++++++++++++++++++++++------------ 2 files changed, 244 insertions(+), 112 deletions(-) (limited to 'docs/docbook/devdoc') diff --git a/docs/docbook/devdoc/dev-doc.sgml b/docs/docbook/devdoc/dev-doc.sgml index c1ffb735ba..965d7a1ea8 100644 --- a/docs/docbook/devdoc/dev-doc.sgml +++ b/docs/docbook/devdoc/dev-doc.sgml @@ -8,6 +8,7 @@ + ]> @@ -25,7 +26,7 @@ Abstract -Last Update : Mon aug 26 12:41:19 CEST 2002 +Last Update : Mon Sep 30 15:23:53 CDT 2002 @@ -58,5 +59,6 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt diff --git a/docs/docbook/devdoc/printing.sgml b/docs/docbook/devdoc/printing.sgml index 2e9d429439..c95d5460b7 100644 --- a/docs/docbook/devdoc/printing.sgml +++ b/docs/docbook/devdoc/printing.sgml @@ -1,49 +1,80 @@ -!= -!= Samba Printing Internals -!= -!= Author : Gerald Carter -!= -!=================================================================== + + + + GeraldCarter + + October 2002 + + +Samba Printing Internals + + + +Abstract + 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. + + + + + 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 - +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). + + + - * 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 ------------------- + + + 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 @@ -53,13 +84,17 @@ 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 */ @@ -77,187 +112,282 @@ struct printjob { 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/". 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 - +steps ( refer to print.c:print_queue_update() ): + + + + 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. + + Lock the mutex entry in the TDB and store our own pid. + Check that this succeeded, else fail. + + Store the updated time stamp for the new cache + listing + + Retrieve the queue listing via "lpq command" + + + 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 + } + } + + Delete any jobs in the TDB that are not + in the in the lpq listing + + Store the print queue status in the TDB + + 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 + +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 +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 ------------------------------------ + + 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 +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. + + The basic set of RPC's used to implement change notification are - - * RemoteFindFirstPrinterChangeNotifyEx ( RFFPCN ) - * RemoteFindNextPrinterChangeNotifyEx ( RFNPCN ) - * FindClosePrinterChangeNotify( FCPCN ) - * ReplyOpenPrinter - * ReplyClosePrinter - * RouteRefreshPrinterChangeNotify ( RRPCN ) - + + + + RemoteFindFirstPrinterChangeNotifyEx ( RFFPCN ) + RemoteFindNextPrinterChangeNotifyEx ( RFNPCN ) + FindClosePrinterChangeNotify( FCPCN ) + ReplyOpenPrinter + ReplyClosePrinter + RouteRefreshPrinterChangeNotify ( RRPCN ) + + + One additional RPC is available to a server, but is never used by the Windows spooler service: + - * RouteReplyPrinter() + + RouteReplyPrinter() + + The opnum for all of these RPC's are defined in include/rpc_spoolss.h + + 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. + + 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 + 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 +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 + 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 +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 + 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 +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 + +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[] + + 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 +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 + +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() ). +( refer to srv_spoolss_nt.c:recieve_notify2_message() ). + -Because it possible to recieve a listing of multiple changes for + +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 +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 + + + + +A SPOOL_NOTIFY_INFO contains: + + + + +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 + + + + +The SPOOL_NOTIFY_INFO_DATA entries contain: + + + + +The type defines whether or not this event +is for a printer or a print job + +The field is the flag identifying the event + +the notify_data union contains the new valuie of the +attribute + +The enc_type defines the size of the structure for marshalling +and unmarshalling + +(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. -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. +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. + + + -- cgit From 8ea9c80a6e2ab8a7012f4b22c585a156f0e5c121 Mon Sep 17 00:00:00 2001 From: Gerald Carter Date: Mon, 30 Sep 2002 21:55:17 +0000 Subject: * adding some notes on the wins failover stuff * fixing some typos after running printing.sgml through ispell (This used to be commit d20be2e868015266ef3b33f353e1c9a2e6d6b7e1) --- docs/docbook/devdoc/dev-doc.sgml | 2 + docs/docbook/devdoc/printing.sgml | 14 +++---- docs/docbook/devdoc/wins.sgml | 79 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 88 insertions(+), 7 deletions(-) create mode 100644 docs/docbook/devdoc/wins.sgml (limited to 'docs/docbook/devdoc') diff --git a/docs/docbook/devdoc/dev-doc.sgml b/docs/docbook/devdoc/dev-doc.sgml index 965d7a1ea8..5191ddcb93 100644 --- a/docs/docbook/devdoc/dev-doc.sgml +++ b/docs/docbook/devdoc/dev-doc.sgml @@ -9,6 +9,7 @@ + ]> @@ -60,5 +61,6 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt diff --git a/docs/docbook/devdoc/printing.sgml b/docs/docbook/devdoc/printing.sgml index c95d5460b7..8259fead5f 100644 --- a/docs/docbook/devdoc/printing.sgml +++ b/docs/docbook/devdoc/printing.sgml @@ -23,7 +23,7 @@ of certain features of Windows client printing. -Printing Interface to Various Backends +Printing Interface to Various Back ends @@ -39,11 +39,11 @@ in printing.h. 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 + submit a job to the print queue -Currently there are only two printing backend implementations +Currently there are only two printing back end implementations defined. @@ -75,7 +75,7 @@ queue contents displayed to clients will be diminished as well. -The list of currently opened print queue TDB's can eb found +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 @@ -125,7 +125,7 @@ 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 +id, smbd uses an in memory TDB to match the former to a number appropriate for old lanman clients. @@ -180,8 +180,8 @@ 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() 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. diff --git a/docs/docbook/devdoc/wins.sgml b/docs/docbook/devdoc/wins.sgml new file mode 100644 index 0000000000..4b5f1e07c4 --- /dev/null +++ b/docs/docbook/devdoc/wins.sgml @@ -0,0 +1,79 @@ + + + + GeraldCarter + + October 2002 + + + +Samba WINS Internals + + + +WINS Failover + + + +The current Samba codebase possesses the capability to use groups of WINS +servers that share a common namespace for NetBIOS name registration and +resolution. The formal parameter syntax is + + + + WINS_SERVER_PARAM = SERVER [ SEPARATOR SERVER_LIST ] + WINS_SERVER_PARAM = "wins server" + SERVER = ADDR[:TAG] + ADDR = ip_addr | fqdn + TAG = string + SEPARATOR = comma | \s+ + SERVER_LIST = SERVER [ SEPARATOR SERVER_LIST ] + + + +A simple example of a valid wins server setting is + + + +[global] + wins server = 192.168.1.2 192.168.1.3 + + + +In the event that no TAG is defined in for a SERVER in the list, smbd assigns a default +TAG of "*". A TAG is used to group servers of a shared NetBIOS namespace together. Upon +startup, nmbd will attempt to register the netbios name value with one server in each +tagged group. + + + +An example using tags to group WINS servers together is show here. Note that the use of +interface names in the tags is only by convention and is not a technical requirement. + + + + +[global] + wins server = 192.168.1.2:eth0 192.1:eth0 192.168.2.2:eth1 + + + +Using this configuration, nmbd would attempt to registry the server's NetBIOS name +with one WINS server in each group. Because the "eth0" group has two servers, the +second server would only be used when a registration (or resolution) request to +the first server in that group timed out. + + + +NetBIOS name resolution follows a similar pattern as name registration. When resolving +a NetBIOS name via WINS, smbd and other Samba programs will attempt to query a single WINS +server in a tagged group until either a positive response is obtained at least once or +until a server from every tagged group has responded negatively to the name query request. +If a timeout occurs when querying a specific WINS server, that server is marked as down to +prevent further timeouts and the next server in the WINS group is contacted. Once marked as +dead, Samba will not attempt to contact that server for name registration/resolution queries +for a period of 10 minutes. + + + + -- cgit From 5de642fc6c476f7631b8caaebd1eda5c4d50df57 Mon Sep 17 00:00:00 2001 From: Gerald Carter Date: Tue, 1 Oct 2002 01:06:37 +0000 Subject: fixing typos spotted by eagle-eye-vance (This used to be commit 5bae773e0270c31ba936ef651dda149601ac6ecd) --- docs/docbook/devdoc/printing.sgml | 20 ++++++++++---------- docs/docbook/devdoc/wins.sgml | 4 ++-- 2 files changed, 12 insertions(+), 12 deletions(-) (limited to 'docs/docbook/devdoc') diff --git a/docs/docbook/devdoc/printing.sgml b/docs/docbook/devdoc/printing.sgml index 8259fead5f..2ef64353e1 100644 --- a/docs/docbook/devdoc/printing.sgml +++ b/docs/docbook/devdoc/printing.sgml @@ -118,8 +118,8 @@ struct printjob { 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 +by the "lpq command" that does not match an existing job in the queue's +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 the id reported by lpq. @@ -130,12 +130,12 @@ for old lanman clients. -When updating a print queue, smbd will performs the following +When updating a print queue, smbd will perform the following steps ( refer to print.c:print_queue_update() ): - Check to see if another sbmd is currently in + Check to see if another smbd 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. @@ -268,7 +268,7 @@ C: Send a RFFPCN request with the previously obtained 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 +S: The <* another missing word*> 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 @@ -282,7 +282,7 @@ 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() + 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 @@ -303,9 +303,9 @@ found by examining the internal tables in srv_spoolss_nt.c -When an event occurs that could be monitored, smbd sends a messages +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 and +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() ). @@ -318,8 +318,8 @@ clients is made by the routine which actually sends the notification. -Because it possible to recieve a listing of multiple changes for -multiple printers the notification events must be split into +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(). diff --git a/docs/docbook/devdoc/wins.sgml b/docs/docbook/devdoc/wins.sgml index 4b5f1e07c4..53410316c5 100644 --- a/docs/docbook/devdoc/wins.sgml +++ b/docs/docbook/devdoc/wins.sgml @@ -54,11 +54,11 @@ interface names in the tags is only by convention and is not a technical require [global] - wins server = 192.168.1.2:eth0 192.1:eth0 192.168.2.2:eth1 + wins server = 192.168.1.2:eth0 192.168.1.3:eth0 192.168.2.2:eth1 -Using this configuration, nmbd would attempt to registry the server's NetBIOS name +Using this configuration, nmbd would attempt to register the server's NetBIOS name with one WINS server in each group. Because the "eth0" group has two servers, the second server would only be used when a registration (or resolution) request to the first server in that group timed out. -- cgit