home *** CD-ROM | disk | FTP | other *** search
/ ftp.microsoft.com / 2002-07-02_ftp.microsoft.com.zip / developr / drg / CIFS / cifsprt.txt < prev    next >
Text File  |  1997-01-29  |  71KB  |  1,861 lines
  1.  
  2.  
  3.  
  4.                       CIFS Printing Specification
  5.  
  6.  
  7. Network Working Group                           Paul J. Leach, Microsoft
  8. INTERNET-DRAFT                                  Dilip C. Naik, Microsoft
  9. draft-leach-cifs-print-spec-00.txt
  10. Category: Informational
  11. Expires June 31, 1997                       January 31, 1997
  12.  
  13.                       CIFS Printing Specification
  14.                            Preliminary Draft
  15.  
  16.  
  17.  
  18.  
  19. STATUS OF THIS MEMO
  20.  
  21. THIS IS A PRELIMINARY DRAFT OF AN INTERNET-DRAFT.  IT DOES NOT REPRESENT
  22. THE CONSENSUS OF ANY WORKING GROUP.
  23.  
  24. This document is an Internet-Draft. Internet-Drafts are working
  25. documents of the Internet Engineering Task Force (IETF), its areas, and
  26. its working groups. Note that other groups may also distribute working
  27. documents as Internet-Drafts.
  28.  
  29. Internet-Drafts are draft documents valid for a maximum of six months
  30. and may be updated, replaced, or obsoleted by other documents at any
  31. time. It is inappropriate to use Internet-Drafts as reference material
  32. or to cite them other than as "work in progress".
  33.  
  34. To learn the current status of any Internet-Draft, please check the
  35. "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
  36. Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
  37. munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
  38. ftp.isi.edu (US West Coast).
  39.  
  40. Distribution of this document is unlimited.  Please send comments to the
  41. authors or the CIFS mailing list at <cifs@listserv.msn.com>.
  42. Discussions of the mailing list are archived at
  43. <URL:http://microsoft.ease.lsoft.com/archives/cifs.html>.
  44.  
  45.  
  46. ABSTRACT
  47.  
  48. This specification defines how clients may submit print requests to a
  49. server using SMBs . The specification also details how clients may
  50. administer printing of the print requests they create, using SMBs
  51. defined  in the Common Internet File System specification.
  52.  
  53.  
  54. Table of Contents
  55.  
  56.  
  57. 1. OBJECTIVE...........................................................3
  58.  
  59.  
  60. 2. PREREQUISITES AND SUGGESTED READING.................................3
  61.  
  62.  
  63. Leach, Naik                                                            1
  64.  
  65.  
  66.                       CIFS Printing Specification
  67.  
  68.  
  69. 3. PRINTING OVERVIEW...................................................3
  70.  
  71.  
  72. 4. CREATING A PRINT JOB................................................3
  73.  
  74.  4.1 OPEN_PRINT_FILE: CREATE PRINT SPOOL FILE .........................4
  75.  4.2 CLOSE_PRINT_FILE:  CLOSE AND SPOOL PRINT JOB .....................5
  76.  
  77. 5. REMOTE ADMINISTRATION PROTOCOL AND DOCUMENTATION CONVENTIONS........5
  78.  
  79.  
  80. 6. PRINT QUEUES AND RELATED FUNCTIONS..................................6
  81.  
  82.  6.1 DATA STRUCTURES RELATED TO PRINT QUEUES ..........................6
  83.   6.1.1 Printer Queue Information (Level 3) ...........................6
  84.   6.1.2 Printer Queue Information (Level 4) ...........................7
  85.   6.1.3 Printer Queue Information (Level 5) ...........................8
  86.  6.2 DOSPRINTQENUM ....................................................8
  87.  6.3 DOSPRINTQGETINFO ................................................10
  88.  
  89. 7. PRINT JOBS AND MANIPULATING PRINT JOBS.............................12
  90.  
  91.  7.1 DATA STRUCTURES RELATED TO PRINT JOBS ...........................12
  92.  7.2 DOSPRINTJOBENUM .................................................14
  93.  7.3 DOSPRINTJOBGETINFO ..............................................16
  94.  7.4 DOSPRINTJOBCONTINUE .............................................19
  95.  7.5 DOSPRINTJOBDEL ..................................................20
  96.  
  97. 8. AUTHOR'S ADDRESSES.................................................21
  98.  
  99.  
  100. 9. REMOTE ADMINISTRATION PROTOCOL OVERVIEW............................21
  101.  
  102.  
  103. 10. APPENDIX A - REMOTE ADMINISTRATION PROTOCOL.......................22
  104.  
  105.  10.1 NOTATION .......................................................23
  106.  10.2 DESCRIPTORS ....................................................23
  107.   10.2.1 Request Parameter Descriptors ...............................23
  108.   10.2.2 Response Parameter Descriptors ..............................24
  109.   10.2.3 Data Descriptors ............................................24
  110.  10.3 TRANSACTION REQUEST PARAMETERS SECTION .........................25
  111.  10.4 TRANSACTION REQUEST DATA SECTION ...............................25
  112.  10.5 TRANSACTION RESPONSE PARAMETERS SECTION ........................26
  113.  10.6 TRANSACTION RESPONSE DATA SECTION ..............................26
  114.  
  115. 11. APPENDIX B........................................................26
  116.  
  117.   11.1.1 TRANSACTIONS ................................................28
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125. Leach, Naik                                                            2
  126.  
  127.  
  128.                       CIFS Printing Specification
  129.  
  130.  
  131.  
  132.  
  133.  
  134. 1. Objective
  135. This document describes
  136. . how CIFS clients accomplish printing on CIFS servers acting as print
  137.   servers.
  138. . how CIFS clients administer printing on CIFS servers.
  139.  
  140. For convenience, some sections from the CIFS specification have been
  141. reproduced in part within this document. Note that the CIFS
  142. specification should be considered to be the authoritative reference, in
  143. case of any doubts, rather than this document.
  144.  
  145. 2. Prerequisites and suggested reading
  146. . Familiarity with Common Internet File Systems specification (CIFS) in
  147.   general and the CIFS Remote Administration Protocol in particular.
  148.  
  149. 3. Printing overview
  150. A CIFS client opens a print file on a CIFS server in a manner similar to
  151. opening an ordinary file, but using a different SMB (described in
  152. section 4.1). The CIFS client then writes to the file. When the CIFS
  153. client closes the file, the CIFS print server considers the file to be a
  154. print job or print request that needs to be printed.
  155.  
  156. The CIFS print server implements a concept of print queues. A print
  157. queue is simply an ordered set of print requests or print jobs. Every
  158. print job is associated with a print queue. A client can control which
  159. print queue a print job is associated with. A printer queue stores print
  160. jobs and sends them one by one to a printer. A print queue may have
  161. multiple physical printers associated with it. Different queues may
  162. share the same printer. Print queues allow administrative convenience
  163. such as selection of a printer, priority assignment for printing,
  164. controlling times during which jobs may print, etc. .
  165.  
  166. Section 4 describes how a client may generate a print job.
  167.  
  168. Section 6 describes how a client may enumerate print queues and retrieve
  169. information about a particular print queue.
  170.  
  171. Section 7 describes how a client may manipulate print jobs, causing
  172. print jobs to be paused, resumed or deleted.
  173.  
  174. Print queues and print jobs are manipulated using the CIFS Remote
  175. Administration protocol. The CIFS specification includes details on
  176. Remote Administration protocol. For convenience, details have been
  177. duplicated (from the CIFS specification) into Appendix A and Appendix B.
  178. Note that the CIFS specification should be considered a more
  179. authoriative source of information, as compared to Appendix A and B.
  180.  
  181. 4. Creating a Print Job
  182.  
  183. A CIFS client creates a print job (or a print request) by opening a
  184. print file, writing to the print file and then closing it.  A print file
  185.  
  186.  
  187. Leach, Naik                                                            3
  188.  
  189.  
  190.                       CIFS Printing Specification
  191.  
  192.  
  193. differs from an ordinary file in that a CIFS server tracks a print file
  194. and deletes it automatically when the printing is complete.
  195.  
  196. A print job is associcated with a print queue. Different print queues
  197. may have different characteristics and may print on different printers.
  198. A client can control which print queue a print job (created by the
  199. client) is associated with. The CIFS print server shares different
  200. queues. A client first creates a connection via a SessionSetupAndX
  201. followed by a TreConnectAndX SMB, specifying the appropriate print queue
  202. share in the TreeConnectAndX SMB. Refer to the CIFS document for details
  203. on the TreeConnectAndX SMB. The TreeConnectAndX will return a Tree Id
  204. (Tid) if the SMB succeeds. This Tid is used when opening a print file.
  205.  
  206.  
  207. 4.1 OPEN_PRINT_FILE: Create Print Spool file
  208.  
  209. This message is sent to create a new printer file which will be deleted
  210. once it has been closed and printed. Complete understanding of this
  211. message requires familiarity with the CIFS specification.
  212.  
  213.  
  214. Client Request                      Description
  215. ==================================  =================================
  216.  
  217. UCHAR WordCount;                    Count of parameter words = 2
  218. USHORT SetupLength;                 Length of printer setup data
  219. USHORT Mode;                        0 = Text mode (DOS expands TABs)
  220.                                     1 = Graphics mode
  221. USHORT ByteCount;                   Count of data bytes;  min = 2
  222. UCHAR BufferFormat;                 0x04
  223. STRING IdentifierString[];          Identifier string
  224.  
  225.  
  226. TID in the SMB header must refer to a printer resource type.
  227.  
  228. SETUPLENGTH is the number of bytes in the first part of the resulting
  229. print spool file which contains printer-specific control strings.
  230.  
  231.  
  232. MODE can have the following values:
  233.      0     Text mode.  The server may optionally
  234.            expand tabs to a series of spaces.
  235.      1     Graphics mode.  No conversion of data
  236.            should be done by the server.
  237.  
  238. IDENTIFIERSTRING can be used by the server to provide some sort of per-
  239. client identifying component to the print file.
  240.  
  241.  
  242. Server Response                     Description
  243. ==================================  =================================
  244.  
  245. UCHAR WordCount;                    Count of parameter words = 1
  246. USHORT Fid;                         File handle
  247.  
  248.  
  249. Leach, Naik                                                            4
  250.  
  251.  
  252.                       CIFS Printing Specification
  253.  
  254.  
  255. USHORT ByteCount;                   Count of data bytes = 0
  256.  
  257.  
  258. FID is the returned handle which may be used by subsequent write and
  259. close operations.  When the file is finally closed, it will be sent to
  260. the spooler and printed.
  261.  
  262. 4.2 CLOSE_PRINT_FILE:  Close and Spool Print Job
  263.  
  264. This message invalidates the specified file handle and queues the file
  265. for printing. Complete understanding of this message requires
  266. familiarity with the CIFS specification.
  267.  
  268.  
  269.  
  270. Client Request                      Description
  271. ==================================  =================================
  272.  
  273. UCHAR WordCount;                    Count of parameter words = 1
  274. USHORT Fid;                         File handle
  275. USHORT ByteCount;                   Count of data bytes = 0
  276.  
  277.  
  278. FID refers to a file previously created with SMB_COM_OPEN_PRINT_FILE.
  279. On successful completion of this request, the file is queued for
  280. printing by the server.
  281.  
  282.  
  283. Server Response                     Description
  284. ==================================  =================================
  285.  
  286. UCHAR WordCount;                    Count of parameter words = 0
  287. USHORT ByteCount;                   Count of data bytes = 0
  288.  
  289.  
  290. Servers which negotiate dialects of LANMAN1.0 and newer allow all the
  291. other types of FID closing requests to invalidate the FID and begin
  292. spooling.
  293.  
  294.  
  295. 5. Remote Administration Protocol and Documentation Conventions
  296.  
  297. Print queue and print job related management functions are accomplished
  298. using the CIFS  Remote Administration Protocol (RAP). Complete details
  299. may be found in the CIFS specification and in Appendix A. Persons
  300. unfamiliar with the RAP specification are strongly advised to read the
  301. CIFS specification or at least Appendix A at this stage. Sections that
  302. follow describe how a CIFS client queries information about print queues
  303. and print jobs and administers print jobs These descriptions assume
  304. knowledge of the CIFS RAP specification.
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311. Leach, Naik                                                            5
  312.  
  313.  
  314.                       CIFS Printing Specification
  315.  
  316.  
  317. 6. Print Queues and related functions
  318.  
  319. A CIFS server can enumerate all print queues on a given server using the
  320. DosPrintQEnum function. Once the CIFS client knows the names of each
  321. print queue, the CIFS client can then obtain information about each
  322. print queue using the DosPrintQGetInfo function. Both of these functions
  323. are executed on the remote print server using the CIFS Remote
  324. Administration Protocol, fully detailed in the CIFS document as well as
  325. Appendix A and Appendix B.
  326.  
  327. 6.1 Data structures related to Print queues
  328.  
  329. This section describes data structures used to describe print queues.
  330. Data structures corresponding to print queue levels 0 , 1 and 2 are
  331. obsolete.
  332.  
  333. 6.1.1 Printer Queue Information (Level 3)
  334.  
  335. The PRQINFO_3 data structure describes a particular printer queue. The
  336. DosPrintQEnum and DosPrintQGetInfo functions (described below) return
  337. data in this format when the desired level of information is set to
  338. level 3.
  339.  
  340.     struct  PRQINFO_3 {
  341.         char            *pszName;
  342.         unsigned short  Priority;
  343.         unsigned short  Starttime;
  344.         unsigned short  UntilTime;
  345.         unsigned short  Pad1;
  346.         char            *pszSepFile;
  347.         char            *pszPrProc;
  348.         char            *pszParms;
  349.         char            *pszComment;
  350.         unsigned short  Status;
  351.         AUXCOUNT        cJobs;
  352.         char            *pszPrinters;
  353.         char            *pszDriverName
  354.         void            *pDriverData;
  355.     }
  356.  
  357. where:
  358.  
  359.    pszName points to a null terminated ASCII string that contains the
  360.    queue name.
  361.  
  362.    Priority contains an unsigned short integer specifying the printer
  363.    queue priority. The value can range from 1(highest) to 9 (lowest).
  364.    When two printer queues print to the same printer, the print jobs
  365.    from the one with the higher priority print first.
  366.  
  367.    Untiltime contains an unsigned short integer specifying the time
  368.    of day a printer queue becomes inactive and stops sending print
  369.    jobs to printers. This value represents the number of minutes
  370.    since midnight (00:00).
  371.  
  372.  
  373. Leach, Naik                                                            6
  374.  
  375.  
  376.                       CIFS Printing Specification
  377.  
  378.  
  379.  
  380.    Starttime contains an unsigned short integer specifying the time
  381.    of day a printer queue can start sending print jobs to printers.
  382.    This value represents the number of minutes since midnight
  383.    (00:00).
  384.  
  385.    pszSepFile  points to a null terminated ASCII string that
  386.    represents the pathname to a seperator page file. The seperator
  387.    page contains formatting information about the pages that separate
  388.    print jobs.
  389.  
  390.    pszPrProc  points to a null terminated ASCII string that
  391.    represents the name of the print preprocessor. A null pointer or
  392.    null string inidcates the default print preprocessor.
  393.  
  394.    pszDestinations points to a null terminated ASCII string that
  395.    contains a list of print destinations for the print queue. This is
  396.    a multi-valued property and the values are separated by spaces.
  397.  
  398.    pszParms points to a null terminated ASCII string that contains
  399.    parameters required by printer queues.
  400.  
  401.    pszComment points to a null terminated ASCII string that contains
  402.    a comment about the print queue.
  403.  
  404.    Status contains an unsigned short integer that specifies the
  405.    status of a printer queue. Possible values are:
  406.  
  407.  
  408.   Code           Value   Description
  409.  
  410.   PRQ_ACTIVE     0       Active
  411.   PRQ_PAUSE      1       Paused
  412.   PRQ_ERROR      2       Error Occurred
  413.   PRQ_PENDING    3       Deletion pending
  414.  
  415.  
  416.    cJobs contains an unsigned short integer representing the number
  417.    of print jobs currently in the print queue.
  418.  
  419.    pszDriverName points to a null terminated ASCII string
  420.    representing the default device driver for the queue. If this
  421.    field is null, the pDriverData field is not used.
  422.  
  423.    pDriverData points to the device driver data for the default
  424.    driver.
  425.  
  426. 6.1.2 Printer Queue Information (Level 4)
  427.  
  428. At this level, the returned information consists of a level 3 print
  429. queue data structure (as described in section 5.1.1) followed by a
  430. PRJINFO_2 data structure for each print job in the queue. The PRJINFO_2
  431. data structure is described in section 7.1.
  432.  
  433.  
  434.  
  435. Leach, Naik                                                            7
  436.  
  437.  
  438.                       CIFS Printing Specification
  439.  
  440.  
  441. 6.1.3 Printer Queue Information (Level 5)
  442.  
  443. At level 5, the returned data structure is defined as:
  444.  
  445.     struct  PRQINFO_5 {
  446.         char    *pszName;
  447.     }
  448.  
  449. where:
  450.    pszName points to a null terminated ASCII string that contains the
  451.    queue name.
  452.  
  453. 6.2 DosPrintQEnum
  454.  
  455.  The DosPrintQEnum function lists all printer queues on a server. The
  456.  definition is:
  457.  
  458.     unsigned short DosPrintQEnum(
  459.         unsigned short      sLevel;
  460.         RCVBUF              pbBuffer;
  461.         RCVBUFLEN           cbBuffer;
  462.         ENTCOUNT            pcReturned;
  463.         unsigned short      *pcTotalAvail;
  464.     );
  465.  
  466.  where:
  467.  
  468.    sLevel specifies the level of detail returned.  Legal values are
  469.    3, 4 and 5 .
  470.  
  471.    pbBuffer points to the buffer to receive the returned data.
  472.  
  473.    cbBuffer specifies the size, in bytes, of the buffer pointed to by
  474.    the pbBuffer parameter.
  475.  
  476.    pcReturned points to a 16 bit variable that receives a count of
  477.    the total number of entries (queues) returned. This count is valid
  478.    only if DosPrintQEnum returns the NERR_Success or ERROR_MORE_DATA
  479.    values.
  480.  
  481.    pcTotalAvail points to a 16 bit variable that receives a count of
  482.    the total number of entries (queues) available. This count is
  483.    valid only if DosPrintQEnum returns the NERR_Success or
  484.    ERROR_MORE_DATA values.
  485.  
  486.  
  487.  Transaction Request Parameters section
  488.  
  489. The Transaction request parameters section in this instance contains:
  490.  
  491. . The function number for DosPrintQEnum which is 69.
  492. . The parameter descriptor string which is _WrLeh_
  493. . The data descriptor string for the returned data is _zWWWWzzzzWWzzl_
  494.   if sLevel (the level of desired information) is 3. This corresponds
  495.  
  496.  
  497. Leach, Naik                                                            8
  498.  
  499.  
  500.                       CIFS Printing Specification
  501.  
  502.  
  503.   to the data structure PRQINFO_3There is no auxiliary data in the
  504.   response when the level of desired information is 3.
  505. . The data descriptor string for the returned data is _zWWWWzzzzWNzzl_
  506.   if sLevel (the level of desired information) is 4. This corresponds
  507.   to the data structure PRQINFO_3. The descriptor for the auxiliary
  508.   data returned  is  _WWzWWDDzz_ when the level of desired information
  509.   is 4. This corresponds to the PRJINFO_2 data structure.
  510. . The data descriptor string for the returned data is _z_ if sLevel
  511.   (the level of desired information) is 5. The _z_ indicates a null
  512.   terminated ASCII string representing the name of the print queue. .
  513.   There is no auxiliary data descriptor for this level of information.
  514. . The actual parameters as described by the parameter descriptor
  515.   string. These are:
  516. " A 16 bit integer with a value of 3, 4 or 5 (corresponding to the _W_
  517.   in the parameter descriptor string. This represents the level of
  518.   detail the server is expected to return
  519. " A 16 bit integer that contains the size of the receive buffer.
  520.  
  521.  
  522. Transaction Request Data section
  523.  
  524. There is no data or auxiliary data to send as part of the request.
  525.  
  526. Transaction Response Parameters section
  527.  
  528. The transaction response parameters section consists of:
  529. . A 16 bit word indicating the return status. The possible values are:
  530.  
  531. Code                     Value   Description
  532.  NERR_Success            0       No errors encountered
  533. ERROR_ACCESS_DENIED      5       The user does not have required
  534.                                  priveleges
  535. ERROR_MORE_DATA          234     Additional data is available
  536. NERR_SpoolerNotLoaded    2161    The spooler is not started on
  537.                                  the remote server
  538. NERR_BadTransactConfig   2141    The server is not configured
  539.                                  for transactions, IPC$ is not
  540.                                  shared
  541.  
  542. . A 16 bit _converter_ word.
  543. . A 16 bit number representing the number of entries returned.
  544. . A 16 bit number representing the total number of available entries.
  545.   If the supplied buffer is large enough, this will equal the number of
  546.   entries returned.
  547.  
  548. Transaction Response Data section
  549.  
  550. The Transaction response data section consists of a series of data
  551. structures. The number of the data structures is equal to the number or
  552. entries being returned, which is the third value in the Transaction
  553. response parameter section.
  554.  
  555. At information level 3, a series of PRQINFO_3 data structures are
  556. returned. There is no auxiliary data at this information level.
  557.  
  558.  
  559. Leach, Naik                                                            9
  560.  
  561.  
  562.                       CIFS Printing Specification
  563.  
  564.  
  565.  
  566. At information level 4, a series of PRQINFO_3 data structures are
  567. returned. There is also auxiliary data present in this case. For each
  568. print job in each print queue, a PRJINFO_2 structure is returned in the
  569. auxiliary data. For each print queue, the data descriptor string element
  570. _N_ denotes the number of PRJINFO_2 data structures present in the
  571. auxiliary data for that queue. This also denotes the number of print
  572. jobs associated with that print queue.
  573.  
  574. At information level 5, a PRQINFO_5 data structure is returned for each
  575. print queue. There is no auxiliary data in the response when the level
  576. of desired information is 5.
  577.  
  578. As per the  RAP specification, all pointers in any of the data
  579. structures returned need to be treated specially in the prescribed
  580. manner.
  581.  
  582. 6.3 DosPrintQGetInfo
  583.  
  584. The DosPrintQGetInfo function retrieves information about a particular
  585. print queue on a CIFS server. The definition is:
  586.  
  587.     unsigned short DosPrintQGetInfo(
  588.         char            *pszQueueName;
  589.         short           sLevel;
  590.         RCVBUF              pbBuffer;
  591.         RCVBUFLEN       cbBuffer;
  592.         unsigned short      *pcbTotalAvail;
  593.     );
  594.  
  595. where:
  596.  
  597.   pszQueueName points to an ASCII  null-terminated string specifying the
  598.   name of the queue for which information should be retrieved.
  599.  
  600.   sLevel specifies the level of detail returned.  (Legal values are 3,
  601.   4,  and 5 )
  602.  
  603.   pbBuffer points to the buffer to receive the returned data.
  604.  
  605.   cbBuffer specifies the size, in bytes, of the buffer pointed to by the
  606.   pbBuffer parameter.
  607.  
  608.   pcbTotalAvail points to a 16-bit variable that receives a count of the
  609.   total number of bytes of information available. This count is valid
  610.   only if DosPrintQGetInfo returns the NERR_Success or ERROR_MORE_DATA
  611.   values.
  612.  
  613.  Transaction Request Parameters section
  614.  
  615. The Transaction request parameters section in this instance contains:
  616.  
  617. . The function number for DosPrintQGetInfo which is 70.
  618. . The parameter descriptor string which is _zWrLh_
  619.  
  620.  
  621. Leach, Naik                                                           10
  622.  
  623.  
  624.                       CIFS Printing Specification
  625.  
  626.  
  627. . The data descriptor string for the returned data is _zWWWWzzzzWWzzl_
  628.   if sLevel (the level of desired information) is 3. This corresponds
  629.   to the data structure PRQINFO_3. There is no auxiliary data in the
  630.   response when the level of desired information is 3.
  631. . The data descriptor string for the returned data is _zWWWWzzzzWNzzl_
  632.   if sLevel (the level of desired information) is 4. This corresponds
  633.   to the data structure PRQINFO_3. The descriptor for the auxiliary
  634.   data returned  is  _WWzWWDDzz_ when the level of desired information
  635.   is 4. This corresponds to the PRJINFO_2 data structure.
  636. . The data descriptor string for the returned data is _z_ if sLevel
  637.   (the level of desired information) is 5. The _z_ indicates a null
  638.   terminated ASCII string representing the name of the print queue. .
  639.   There is no auxiliary data descriptor for this level of information.
  640. . The actual parameters as described by the parameter descriptor
  641.   string. These are:
  642.         . A null terminated ASCII string denoting the name of the print
  643.           queue for which information should be retrieved.
  644.         . A 16 bit integer with a value of 3, 4 or 5 . This represents
  645.           the level of detail the server is expected to return
  646.         . A 16 bit integer that contains the size of the receive
  647.           buffer.
  648.  
  649.  
  650. Transaction Request Data section
  651.  
  652. There is no data or auxiliary data to send as part of the request.
  653.  
  654. Transaction Response Parameters section
  655.  
  656. The transaction response parameters section consists of:
  657. . A 16 bit word indicating the return status. The possible values are:
  658.  
  659.  
  660. Code                   Value   Description
  661.  NERR_Success          0       No errors encountered
  662. ERROR_ACCESS_DENIED    5        User has insufficient
  663.                                privilege
  664. ERROR_MORE_DATA        234     Additional data is
  665.                                available
  666. NERR_QNotFound         2150    The specified queue name
  667.                                is invalid
  668. NERR_SpoolerNotLoaded  2161    The spooler is not started
  669.                                on the remote server
  670.  
  671.  
  672. . A 16 bit _converter_ word. The value is up to the server to decide.
  673. . A 16 bit number representing the total number of available bytes.
  674.   This has meaning only if the return status is NERR_Success,
  675.   ERROR_MORE_DATA or NERR_BufTooSmall
  676.  
  677. Transaction Response Data Section
  678.  
  679. The Transaction response data section consists of a single data
  680. structure
  681.  
  682.  
  683. Leach, Naik                                                           11
  684.  
  685.  
  686.                       CIFS Printing Specification
  687.  
  688.  
  689.  
  690. At information level 3, a  PRQINFO_3 data structure is returned. There
  691. is no auxiliary data at this information level.
  692.  
  693. At information level 4, a PRQINFO_3 data structure is returned. This
  694. data structure describes the print queue of interest. There is also
  695. auxiliary data present in this case. For each print job in the print
  696. queue, a PRJINFO_2 structure is returned in the auxiliary data. The data
  697. descriptor string element _N_ denotes the number of PRJINFO_2 data
  698. structures present in the auxiliary data for that queue. This also
  699. denotes the number of print jobs associated with that print queue.
  700.  
  701. At information level 5, a PRQINFO_5 data structure is returned for each
  702. print queue. There is no auxiliary data in the response when the level
  703. of desired information is 5.
  704.  
  705. As per the  RAP specification, all pointers in any of the data
  706. structures returned need to be treated specially in the prescribed
  707. manner.
  708.  
  709.  
  710. 7. Print Jobs and manipulating Print Jobs
  711.  
  712. Once a CIFS client has located a print queue, the client can then
  713. enumerate jobs within that queue using the DosPrintJobEnum function. A
  714. CIFS client may also obtain print job information by means of the
  715. DosPrintQEnum and DosPrintQGetInfo services, specifying  a desired
  716. information level of 4. Once the CIFS client has a list of job
  717. identifiers, it can obtain detailed information about any print job
  718. using the DosPrintJobGetInfo function.  For print jobs initiated by the
  719. client, and which are not yet printing, the CIFS client can pause,
  720. resume or delete the print jobs using DosPrintJobPause,
  721. DosPrintJobContinue and DosPrintJobDel functions respectively. All of
  722. these DosPrintJobX services are executed on the remote print server
  723. using the CIFS Remote Administration Protocol described in the CIFS
  724. document as well as in Appendix A and Appendix B.
  725.  
  726. 7.1 Data Structures related to Print Jobs
  727.  
  728.     struct PRJINFO_0 {
  729.         unsigned short  JobId
  730.     }
  731.  
  732.  
  733. where:
  734.  
  735.    JobId is a 16 bit integer that uniquely specifies a print job
  736.    within a printer queue. The JobID is unique on a server. A
  737.    combination of the server name and JobId is sufficient to uniquely
  738.    identify a particular print job.
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745. Leach, Naik                                                           12
  746.  
  747.  
  748.                       CIFS Printing Specification
  749.  
  750.  
  751.     struct PRJINFO_2 {
  752.         unsigned short      JobId;
  753.         unsigned short      Priority;
  754.         char            *pszUserName;
  755.         unsigned short      Position;
  756.         unsigned short      Status;
  757.         unsigned long       Submitted;
  758.         unsigned long       Size;
  759.         char            *pszComment;
  760.         char            *pszDocument;
  761.     }
  762.  
  763. where:
  764.  
  765.    JobId is a 16 bit integer that uniquely specifies a print job
  766.    within a printer queue. The JobID is unique on a server. A
  767.    combination of the server name and JobId is sufficient to uniquely
  768.    identify a particular print job.
  769.  
  770.    Priority is a 16 bit integer that specifies the print job
  771.    priority. This varies from a value of 1 (lowest priority) to 99
  772.    (highest priority. Higher priority jobs print first. When 2 jobs
  773.    have the same priority, the older job prints first.
  774.  
  775.    pszUserName is a pointer to a null terminated ASCII string that
  776.    specifies the name of the user who submitted the print job.
  777.  
  778.    Position specifies the position of the print job within the print
  779.    queue. If the value is 1, this print job prints next.
  780.  
  781.    Status is an integer used as a status flag. The values and
  782.    meanings of the various bits are:
  783.  
  784. Bits  Code             Value  Description
  785. 0-1   PRJ_QS_QUEUED    0      Print job is queued
  786. 0-1   PRJ_QS_PAUSED    1      Print job is paused
  787. 0-1   PRJ_QS_SPOOLING  2      Print job is spooling
  788. 0-1   PRJ_QS_PRINTING  3      Print job is printing,
  789.                               bits 2-11 are valid
  790.  
  791. Bit  Code             Value   Description
  792. 2    PRJ_COMPLETE     0x0004  Print job is complete
  793. 3    PRJ_INTERV       0x0008  an error occurred, pszStatus
  794.                               may contain a comment explaining
  795.                               the error
  796. 4    PRJ_ERROR        0x0010  Print job is spooling
  797. 5    PRJ_DESTOFFLINE  0x0020  The print destination is offline
  798. 6    PRJ_DESTPAUSED   0x0040  The print destination is paused
  799. 7    PRJ_NOTIFY       0x0080  An alert is raised
  800. 8    PRJ_DESTNOPAPER  0x0100  The print destination is out of
  801.                               paper
  802. 9    PRJ_DESTFORMCHG  0x0200  The printer is waiting for a
  803.                               form change
  804. 10   PRJ_DESTCRTCHG   0x0400  The printer is waiting for a
  805.  
  806.  
  807. Leach, Naik                                                           13
  808.  
  809.  
  810.                       CIFS Printing Specification
  811.  
  812.  
  813.                               cartridge change
  814. 11   PRJ_DESTENCHG    0x0800  The printer is waiting for a pen
  815.                               change
  816. 15   PRJ_ PRINTING    0x8000  An alert indicates the job was
  817.                               deleted
  818.  
  819.  
  820.    pszStatus points to an ASCII string that contains a comment about
  821.    the status of the job. This element contains valid data only when
  822.    the job is printing and an error occurs. This element may be null
  823.    or point to a null string.
  824.  
  825.    Submitted contains an unsigned long integer specifying when the
  826.    user submitted the job. This is stored as the number of seconds
  827.    elapsed since 00:00:00 Jan 1st, 1970.
  828.  
  829.    Size contains an unsigned long integer that specifies the size of
  830.    the print job in terms of number of bytes.
  831.  
  832.    pszComment points to a null terminated ASCII string that contains
  833.    a comment about the print job.
  834.  
  835.    pszDocument points to a null terminated ASCII string that contains
  836.    the name of the document.
  837.  
  838.  
  839. 7.2 DosPrintJobEnum
  840.  
  841. The DosPrintJobEnum service lists print jobs in the specified printer
  842. queue. The definition is:
  843.  
  844.     unsigned short DosPrintJobEnum(
  845.         char                *pszQueueName;
  846.         short           sLevel;
  847.         RCVBUF              pbBuffer;
  848.         RCVBUFLEN           cbBuffer;
  849.         unsigned short      *pcbTotalAvail;
  850.     );
  851.  
  852.  where:
  853.  
  854.    pszQueuename points to a null-terminated string specifying the
  855.    name of the print queue for which print jobs should be enumerated.
  856.  
  857.    sLevel specifies the level of detail returned.  (Legal values are
  858.    0 and 2)
  859.  
  860.    pbBuffer points to the buffer to receive the returned data.
  861.  
  862.    cbBuffer specifies the size, in bytes, of the buffer pointed to by
  863.    the pbBuffer parameter.
  864.  
  865.  
  866.  
  867.  
  868.  
  869. Leach, Naik                                                           14
  870.  
  871.  
  872.                       CIFS Printing Specification
  873.  
  874.  
  875.    pcbTotalAvail points to a 16 bit variable that receives a count of
  876.    the total number of bytes of information available. This count is
  877.    valid only if the return value is NERR_Success or ERROR_MORE_DATA .
  878.  
  879.  
  880. Transaction Request Parameters section
  881.  
  882. The Transaction request parameters section in this instance contains:
  883.  
  884. . The function number for DosPrintJobEnum which is 76.
  885. . The parameter descriptor string which is _zWrLeh_
  886. . The data descriptor string for the returned data is _z_ if sLevel
  887.   (the level of desired information) is 0. This corresponds to the data
  888.   structure PRJINFO_0 already described.
  889. . The data descriptor string for the returned data is  _WWzWWDDzz_ if
  890.   sLevel (the level of desired information) is 2. This corresponds to
  891.   the PRJINFO_2 data structure.already described.
  892. . The actual parameters as described by the parameter descriptor
  893.   string. These are:
  894.         . A null terminated ASCII string denoting the name of the print
  895.           queue which contains the print job of interest.
  896.         . A 16 bit integer with a value of 0 or 2 . This represents the
  897.           level of detail the server is expected to return
  898.         . A 16 bit integer that contains the size of the receive
  899.           buffer.
  900.  
  901. There is no data or auxiliary data that is sent as part of the
  902. Transaction request.
  903.  
  904.  
  905. Transaction Request Data section
  906.  
  907. There is no data or auxiliary data to send as part of the request.
  908.  
  909. Transaction Response Parameters section
  910.  
  911. The transaction response parameters section consists of:
  912. . A 16 bit word indicating the return status. The possible values are:
  913.  
  914.  
  915.   Code                     Value    Description
  916.  
  917.    NERR_Success            0        No errors encountered
  918.   ERROR_ACCESS_DENIED      5         User has insufficient
  919.                                          privilege
  920.   ERROR_MORE_DATA          234      Additional data is
  921.                                          available
  922.   NERR_QNotFound           2150     The specified queue name
  923.                                          is invalid
  924.   NERR_SpoolerNotLoaded    2161     The spooler is not started
  925.                                          on the remote server
  926.  
  927. . A 16 bit _converter_ word.
  928.  
  929.  
  930.  
  931. Leach, Naik                                                           15
  932.  
  933.  
  934.                       CIFS Printing Specification
  935.  
  936.  
  937. . A 16 bit number representing the total number of available entries.
  938.   This has meaning only if the return status is NERR_Success,
  939.   ERROR_MORE_DATA or NERR_BufTooSmall
  940.  
  941.  
  942. Transaction Response Data Section
  943.  
  944. The Transaction response data section consists of a data structures.
  945.  
  946. At information level 0, a  series of PRJINFO_0 data structures are
  947. returned. The number of structure is equal to the value in the third
  948. parameter in the response parameter section. There is no auxiliary data
  949. at this information level.
  950.  
  951. At information level 2, a  series of PRJINFO_2 data structures are
  952. returned. The number of such data structures returned is equal to the
  953. value in the third parameter of the response parameter section. There is
  954. no auxiliary data present in this case.
  955.  
  956. As per the  RAP specification, all pointers in any of the data
  957. structures returned need to be treated specially in the prescribed
  958. manner.
  959.  
  960. There is no auxiliary data in the response.
  961.  
  962.  
  963. 7.3 DosPrintJobGetInfo
  964.  
  965.  
  966. The DosPrintJobGetInfo service retrieves information about a particular
  967. print job. The definition is:
  968.  
  969.     unsigned short DosPrintJobGetInfo(
  970.         unsigned short  JobId;
  971.         unsigned short  sLevel;
  972.         RCVBUF          pbBuffer;
  973.         RCVBUFLEN           cbBuffer;
  974.         unsigned short      *pcbTotalAvail;
  975.     );
  976.  
  977.  where:
  978.  
  979.    JobId specifies identity of the print job for which information
  980.    should be retrieved.
  981.  
  982.    Level specifies the level of detail returned.  (Legal values are 0
  983.    and 2)
  984.  
  985.    pbBuffer points to the buffer to receive the returned data.
  986.  
  987.    cbBuffer specifies the size, in bytes, of the buffer pointed to by
  988.    the pbBuffer parameter.
  989.  
  990.  
  991.  
  992.  
  993. Leach, Naik                                                           16
  994.  
  995.  
  996.                       CIFS Printing Specification
  997.  
  998.  
  999.    pcbTotalAvail points to a 16 bit variable that receives a count of
  1000.    the total number of bytes of information available. This count is
  1001.    valid only if DosPrintJobGetInfo returns the
  1002.    NERR_Success or ERROR_MORE_DATA values.
  1003.  
  1004.  
  1005. Transaction Request Parameters section
  1006.  
  1007. The Transaction request parameters section in this instance contains:
  1008.  
  1009. . The function number for DosPrintJobGetInfo which is 77.
  1010. . The parameter descriptor string which is _WWrLh_
  1011. . The data descriptor string for the returned data is _z_ if sLevel
  1012.   (the level of desired information) is 0. This corresponds to the data
  1013.   structure PRJINFO_0 already described.
  1014. . The data descriptor string for the returned data is  _WWzWWDDzz_ if
  1015.   sLevel (the level of desired information) is 2. This corresponds to
  1016.   the PRJINFO_2 data structure.already described.
  1017. . The actual parameters as described by the parameter descriptor
  1018.   string. These are:
  1019.         . A 16 bit integer specifying the identity of the job for which
  1020.           information should be retrieved.
  1021.         . A 16 bit integer with a value of 0 or 2 . This represents the
  1022.           level of detail the server is expected to return
  1023.         . A 16 bit integer that contains the size of the receive
  1024.           buffer.
  1025.  
  1026. There is no data or auxiliary data that is sent as part of the
  1027. Transaction request.
  1028.  
  1029.  
  1030. Transaction Request Data section
  1031.  
  1032. There is no data or auxiliary data to send as part of the request.
  1033.  
  1034. Transaction Response Parameters section
  1035.  
  1036. The transaction response parameters section consists of:
  1037. . A 16 bit word indicating the return status. The possible values are:
  1038. Code                     Value Description
  1039.  NERR_Success            0     No errors encountered
  1040. ERROR_ACCESS_DENIED      5     The user does not have required
  1041.                                priveleges
  1042. ERROR_MORE_DATA          234   Additional data is available
  1043. NERR_SpoolerNotLoaded    2161  The spooler is not started on the
  1044.                                remote server
  1045. NERR_BadTransactConfig   2141  The server is not configured for
  1046.                                transactions, IPC$ is not shared
  1047.  
  1048. . A 16 bit _converter_ word.
  1049. . A 16 bit number representing the total number of available bytes.
  1050.   This has meaning only if the return status is NERR_Success,
  1051.   ERROR_MORE_DATA or NERR_BufTooSmall
  1052.  
  1053.  
  1054.  
  1055. Leach, Naik                                                           17
  1056.  
  1057.  
  1058.                       CIFS Printing Specification
  1059.  
  1060.  
  1061. Transaction Response Data Section
  1062.  
  1063. The return data section consists of a PRJINFO_0 data structure if the
  1064. desired level of information is 0. The return data section consists of a
  1065. PRJINFO_2 data structure if the desired level of information is 2. These
  1066. have already been detailed.
  1067.  
  1068. Note that the pointers in the data structure in data structure PRJINFO_2
  1069. need to be treated specially. The high 16 bit word needs to be ignored.
  1070. The converter word returned in the response parameters section needs to
  1071. be subtracted from the low 16 bit value to locate the actual offset of
  1072. the item within the response buffer sent by the server.
  1073.  
  1074. There is no auxiliary data to receive.
  1075.  
  1076.  
  1077. DosPrintJobPause
  1078.  
  1079. DosPrintJobPause  pauses a print job in a printer queue. The definition
  1080. is:
  1081.  
  1082.     unsigned short DosPrintJobPause(
  1083.         unsigned short JobId;
  1084.     );
  1085.  
  1086.  where:
  1087.  
  1088.    JobId specifies the identity of the print job that should be
  1089.    paused
  1090.  
  1091. Transaction Request Parameters section
  1092.  
  1093. The Transaction request parameters section in this instance contains:
  1094.  
  1095. . The function number for DosPrintJobPause which is 82.
  1096. . The parameter descriptor string which is _W_
  1097. . The data descriptor string is null.
  1098. . The actual parameters as described by the parameter descriptor
  1099.   string. This consists of just a 16 bit integer representing the
  1100.   JobId, identifying the job to be paused.
  1101.  
  1102.  
  1103. Transaction Request Data section
  1104.  
  1105. There is no data or auxiliary data to send as part of the request.
  1106.  
  1107. Transaction Response Parameters section
  1108.  
  1109. The transaction response parameters section consists of:
  1110. . A 16 bit word indicating the return status. The possible values are:
  1111.  
  1112. Code                           Value   Description
  1113.  NERR_Success                  0       No errors encountered
  1114. ERROR_ACCESS_DENIED            5        User has insufficient
  1115.  
  1116.  
  1117. Leach, Naik                                                           18
  1118.  
  1119.  
  1120.                       CIFS Printing Specification
  1121.  
  1122.  
  1123.                                        privilege
  1124. ERROR_NETWORK_ACCESS_DENIED    65      Network access is denied
  1125. NERR_BadTransactConfig         2141    The server is not configured
  1126.                                        for transactions, IPC$ is not
  1127.                                        shared
  1128. NERR_JobNotFound               2151    The specified print job could
  1129.                                        not be located
  1130. NERR_SpoolerNotLoaded          2161    The spooler is not started on
  1131.                                        the remote server
  1132. NERR_JobInvalidState           2164    The operation cannot be
  1133.                                        performed on the job in it's
  1134.                                        current state(job is already
  1135.                                        printing)
  1136.  
  1137.  
  1138. Transaction Response Data Section
  1139.  
  1140. There is no data or auxiliary data in the response.
  1141.  
  1142.  
  1143. 7.4 DosPrintJobContinue
  1144.  
  1145. DosPrintJobContinue allows a paused print job to resume printing. The
  1146. definition is:
  1147.  
  1148.     unsigned short DosPrintJobContinue(
  1149.         unsigned short JobId;
  1150.     );
  1151.  
  1152.  where:
  1153.  
  1154.    JobId specifies the identity of the print job that should resume
  1155.    printing
  1156.  
  1157.  
  1158. Transaction Request Parameters section
  1159.  
  1160. The Transaction request parameters section in this instance contains:
  1161.  
  1162. . The function number for DosPrintJobContinue which is 83.
  1163. . The parameter descriptor string which is _W_
  1164. . The data descriptor string is null.
  1165. . The actual parameters as described by the parameter descriptor
  1166.   string. This consists of just a 16 bit integer representing the JobId
  1167.   (identifies job to be paused)
  1168.  
  1169.  
  1170. Transaction Request Data section
  1171.  
  1172. There is no data or auxiliary data to send as part of the request.
  1173.  
  1174. Transaction Response Parameters section
  1175.  
  1176. The transaction response parameters section consists of:
  1177.  
  1178.  
  1179. Leach, Naik                                                           19
  1180.  
  1181.  
  1182.                       CIFS Printing Specification
  1183.  
  1184.  
  1185. . A 16 bit word indicating the return status. The possible values are:
  1186.  
  1187. Code                          Value   Description
  1188.  NERR_Success                 0       No errors encountered
  1189. ERROR_ACCESS_DENIED           5        User has insufficient
  1190.                                       privilege
  1191. ERROR_NETWORK_ACCESS_DENIED   65      Network access is denied
  1192. NERR_BadTransactConfig        2141    The server is not configured
  1193.                                       for transactions, IPC$ is not
  1194.                                       shared
  1195. NERR_JobNotFound              2151    The specified print job could
  1196.                                       not be located
  1197. NERR_SpoolerNotLoaded         2161    The spooler is not started on
  1198.                                       the remote server
  1199. NERR_JobInvalidStatus         2164    The operation cannot be
  1200.                                       performed on the print job in
  1201.                                       it's current state
  1202.  
  1203.  
  1204. Transaction Response Data Section
  1205.  
  1206. There is no data or auxiliary data in the response.
  1207.  
  1208.  
  1209. 7.5 DosPrintJobDel
  1210.  
  1211. DosPrintJobDel deletes a print job from a printer queue. The definition
  1212. is:
  1213.  
  1214.     unsigned short DosPrintJobDel(
  1215.         unsigned short JobId;
  1216.     );
  1217.  
  1218.  where:
  1219.  
  1220.    JobId specifies the identity of the print job that should be
  1221.    deleted
  1222.  
  1223. Transaction Request Parameters section
  1224.  
  1225. The Transaction request parameters section in this instance contains:
  1226.  
  1227. . The function number for DosPrintJobDel which is 81.
  1228. . The parameter descriptor string which is _W_
  1229. . The data descriptor string is null.
  1230. . The actual parameters as described by the parameter descriptor
  1231.   string. This consists of just a 16 bit integer representing the JobId
  1232.   , identifying the job to be paused.
  1233.  
  1234. Transaction Request Data section
  1235.  
  1236. There is no data or auxiliary data to send as part of the request.
  1237.  
  1238. Transaction Response Parameters section
  1239.  
  1240.  
  1241. Leach, Naik                                                           20
  1242.  
  1243.  
  1244.                       CIFS Printing Specification
  1245.  
  1246.  
  1247. The transaction response parameters section consists of:
  1248. . A 16 bit word indicating the return status. The possible values are:
  1249.  
  1250.  
  1251.   Code                           Value   Description
  1252.  
  1253.    NERR_Success                  0       No errors encountered
  1254.   ERROR_ACCESS_DENIED            5        User has insufficient
  1255.                                               privilege
  1256.   ERROR_NETWORK_ACCESS_DENIED    65      Network access is denied
  1257.   NERR_BadTransactConfig         2141    The server is not
  1258.                                               configured for
  1259.                                               transactions, IPC$
  1260.                                               is not shared
  1261.   NERR_JobNotFound               2151    The specified print job
  1262.                                               could not be located
  1263.   NERR_ProcNotRespond            2160    The print process is not
  1264.                                               responding
  1265.   NERR_SpoolerNotLoaded          2161    The spooler is not
  1266.                                               started on the
  1267.                                               remote server
  1268.  
  1269.  
  1270. Transaction Response Data Section
  1271.  
  1272. There is no data or auxiliary data in the response.
  1273.  
  1274.  
  1275. 8. Author's Addresses
  1276.  
  1277. Paul Leach
  1278. Dilip Naik
  1279. Microsoft
  1280. 1 Microsoft Way
  1281. Redmond, WA  98052
  1282.  paulle@microsoft.com
  1283. v-dilipn@microsoft.com
  1284.  
  1285.  
  1286.  
  1287. 9. Remote Administration Protocol overview
  1288. The Remote Administration Protocol (RAP) is similar to an RPC protocol,
  1289. in that:
  1290. . it is an at-most-once synchronous request-response protocol
  1291. . it is a framework that can be used for remotely requesting many
  1292.   different kinds of services
  1293. . it is designed  to allow (but not require) the programming interface
  1294.   to the protocol to be that of remotely executed procedure calls _
  1295.   which means that one thinks if the protocol in terms of marshaling
  1296.   and unmarshaling procedure call input and output arguments into
  1297.   messages and reliably transporting the messages to and from the
  1298.   client and server
  1299. Each RAP request is characterized by a set of ASCII descriptor strings
  1300. that are sufficient to be used to interpretively drive the marshaling
  1301.  
  1302.  
  1303. Leach, Naik                                                           21
  1304.  
  1305.  
  1306.                       CIFS Printing Specification
  1307.  
  1308.  
  1309. and unmarshaling process, if an implementation wanted to use them for
  1310. that purpose. These descriptor strings are included in each request
  1311. packet, and make the requests self-describing.
  1312.  
  1313. RAP is layered on the CIFS Transact2 SMB, which provides reliable
  1314. message delivery, security, and messages larger than the underlying
  1315. network maximum packet size. When used for RAP, the name field in the
  1316. Transact2 SMB is always set to "\PIPE\LANMAN". The Transact2 SMB is sent
  1317. on a session/connection that is established to the remote server using a
  1318. SessionSetupAndX SMB, and using a TID obtained by doing a
  1319. TreeConnectAndX SMB to a share named "IPC$".
  1320.  
  1321. [Refer to the CIFS specification for complete details on SMBs in
  1322. general, and the Transact2 SMB in particular. For convenience, relevant
  1323. portions from the CIFS specification have been reproduced here in
  1324. Appendix A. Note that the CIFS specification should be considered the
  1325. authoritative source of information, rather than Appendix A as far as
  1326. details on the Transact2 SMB are concerned.]
  1327.  
  1328. The model of a RAP service is that there are a few parameters as inputs
  1329. and outputs to the service, exactly one of which may be a buffer
  1330. descriptor that indicates the presence of a potentially much larger
  1331. input or output data buffer. An argument may be a scalar, pointer, fixed
  1332. length small array or struct, or a buffer descriptor. The data buffer
  1333. consists of entries followed by a heap. An entry consists of a primary
  1334. data struct and a sequence of  0 or more auxiliary data structs. An
  1335. input buffer must contain exactly one entry; an output buffer may
  1336. contain 0 or more. The heap is where data is stored that is referenced
  1337. by pointers in the entries. The parameters are described by a parameter
  1338. descriptor string; the primary data struct by a data descriptor string;
  1339. and the auxiliary data structs by an auxiliary data descriptor string.
  1340.  
  1341.  
  1342. 10. Appendix A - Remote Administration Protocol
  1343. A RAP service request is sent to the server encapsulated in a Transact2
  1344. request SMB and the server sends back a Transact2 SMB response. An
  1345. attribute of the Transact2 SMB is that it divides the payload of request
  1346. and response messages into two sections: a parameters section and a data
  1347. section. As might be expected from the nomenclature, RAP service
  1348. parameters are sent in the parameters section of a Transact2 SMB, and
  1349. the data buffer in the data section. Therefore, to define a service
  1350. protocol, it is necessary to define the formats of the parameter and
  1351. data sections of the Transact2 request and response.
  1352.  
  1353. This is done in two stages. First, a C-like declaration notation is used
  1354. to define descriptor strings, and then the descriptor strings define the
  1355. formats of the  parameter and data sections.. Note well: even though the
  1356. declarations may look like a programming interface, they are not: they
  1357. are a notation for describing the contents of RAP requests and
  1358. responses; an implementation on any particular system can use any
  1359. programming interface to RAP services that is appropriate to that
  1360. system.
  1361.  
  1362.  
  1363.  
  1364.  
  1365. Leach, Naik                                                           22
  1366.  
  1367.  
  1368.                       CIFS Printing Specification
  1369.  
  1370.  
  1371. 10.1 Notation
  1372. Parameter descriptor strings are defined using a C-like function
  1373. declaration; data descriptor and auxiliary data descriptor strings are
  1374. defined using a C-like structure declaration.
  1375.  
  1376. Parameter descriptor strings are defined with the following C-like
  1377. function declaration syntax:
  1378.     rap-service     = "unsigned short" service-name "(" parameters ");"
  1379.     service-name        = <upper and lower case alpha and numeric>
  1380. The return type of the function is always "unsigned short", and
  1381. represents the status code from the function. The service-name is for
  1382. documentation purposes.
  1383.     parameters      = parameter [ ";" parameter ]
  1384. The parameter descriptor string for the service is the concatenation of
  1385. the descriptor characters for the parameters.
  1386.     parameter       = [ "const" ] param-data-type parameter-name
  1387.                       [ "[" size "]" ]
  1388.     param-data-type = <from parameter descriptor tables below>
  1389.     parameter-name      = <upper and lower case alpha and numeric>
  1390.     size                = <string of ASCII 0-9>
  1391. The descriptor character for a parameter is determined by looking up the
  1392. data-type in the tables below for request or response parameter
  1393. descriptors. The parameter-name is for documentation purposes. If there
  1394. is a size following the parameter-name, then it is placed in the
  1395. descriptor string following the descriptor character.
  1396.  
  1397. Data and auxiliary data descriptor strings are defined  with the
  1398. following C-like structure declaration syntax:
  1399.     rap-struct      = "struct" struct-name "{" members "}"
  1400. The descriptor string for the struct is the concatenation of the
  1401. descriptor characters for the members. The struct-name is for
  1402. documentation purposes.
  1403.     members         = member [  ";" member ]
  1404.     member          = member-data-type member-name [ "[" size "]" ]
  1405.     member-data-type    = <from data descriptor tables below>
  1406. The descriptor character for a member is determined by looking up the
  1407. data-type in the tables below for data descriptors. The member-name is
  1408. for documentation purposes. If there is a size following the member-
  1409. name, then it is placed in the descriptor string following the
  1410. descriptor character.
  1411.  
  1412. 10.2 Descriptors
  1413. The following section contain tables that specify the descriptor
  1414. character and the notation for each data type for that data type.
  1415.  
  1416. 10.2.1 Request Parameter Descriptors
  1417.  
  1418.  
  1419. Descriptor  Data Type        Format
  1420. ==========  =========        =====
  1421. W           unsigned short   indicates parameter type of 16 bit integer
  1422.                              (word).
  1423. D           unsigned long    indicates parameter type of 32 bit integer
  1424.                              (dword).
  1425.  
  1426.  
  1427. Leach, Naik                                                           23
  1428.  
  1429.  
  1430.                       CIFS Printing Specification
  1431.  
  1432.  
  1433. b           BYTE             indicates bytes (octets). May be followed
  1434.                              by an ASCII number indicating number of
  1435.                              bytes..
  1436. O           NULL             indicates a NULL pointer
  1437. z           char             indicates a NULL terminated ASCII string
  1438.                              present in the parameter area
  1439. F           PAD              indicates Pad bytes (octets). May be
  1440.                              followed by an ASCII number indicating the
  1441.                              number of bytes
  1442. r           RCVBUF           pointer to receive data buffer in response
  1443.                              parameter section
  1444. L           RCVBUFLEN        16 bit integer containing length of
  1445.                              receive data buffer in (16 bit) words
  1446. s           SNDBUF           pointer to send data buffer in request
  1447.                              parameter section
  1448. T           SNDBUFLEN        16 bit integer containing length of send
  1449.                              data buffer in words
  1450.  
  1451.  
  1452. 10.2.2 Response Parameter Descriptors
  1453.  
  1454.  
  1455. Descriptor  Data Type        Format
  1456. ==========  =========        =====
  1457. g           BYTE *           indicates a byte is  to be received. May
  1458.                              be followed by an ASCII number indicating
  1459.                              number of bytes to receive
  1460. h           unsigned short * indicates a word is to be received
  1461. i           unsigned long *  indicates  a dword is to be received
  1462. e           ENTCOUNT         indicates a word is to be received  which
  1463.                              indicates the number of entries returned
  1464.  
  1465.  
  1466. 10.2.3 Data Descriptors
  1467.  
  1468.  
  1469. Descriptor  Data Type        Format
  1470. ==========  =========        =====
  1471. W           unsigned short   indicates data type of 16 bit integer
  1472.                              (word). Descriptor char may be followed by
  1473.                              an ASCII number indicating the number of
  1474.                              16 bit words present
  1475. D           unsigned long    indicates data type of 32 bit integer
  1476.                              (dword). Descriptor char may be followed
  1477.                              by an ASCII number indicating the number
  1478.                              of 32 bit words present
  1479. B           BYTE             indicates item of data type 8 bit byte
  1480.                              (octet). The indicated number of bytes are
  1481.                              present  in the data. Descriptor char may
  1482.                              be followed by an ASCII number indicating
  1483.                              the number of 8 bit bytes present
  1484. O           NULL             indicates a NULL pointer
  1485. z           char *           indicates a 32 bit pointer to a NULL
  1486.                              terminated ASCII string is present in the
  1487.  
  1488.  
  1489. Leach, Naik                                                           24
  1490.  
  1491.  
  1492.                       CIFS Printing Specification
  1493.  
  1494.  
  1495.                              response parameter area. The actual string
  1496.                              is in the response data area and the
  1497.                              pointer in the parameter area points to
  1498.                              the string in the data area. The high word
  1499.                              of the pointer should be ignored. The
  1500.                              converter word present in the response
  1501.                              parameter section should be subtracted
  1502.                              from the low 16 bit value to obtain an
  1503.                              offset into the data area indicating where
  1504.                              the data area resides.
  1505. N           AUXCOUNT         indicates number of auxiliary data
  1506.                              structures. The transaction response data
  1507.                              section contains an unsigned 16 bit number
  1508.                              corresponding to this data item.
  1509.  
  1510.  
  1511. 10.3 Transaction Request Parameters section
  1512. The parameters and data being sent and received are described by ASCII
  1513. descriptor strings. These descriptor strings are described in section
  1514. 4.2.
  1515.  
  1516. The parameters section of the Transact2 SMB request contains the
  1517. following (in the order described)
  1518. . The function number: an unsigned short 16 bit integer identifying the
  1519.   function being remoted
  1520. . The parameter descriptor string: a null terminated ASCII string
  1521. . The data descriptor string: a null terminated ASCII string.
  1522. . The request parameters, as described by the parameter descriptor
  1523.   string, in the order that the request parameter descriptor characters
  1524.   appear in the parameter descriptor string
  1525. . An optional auxiliary data descriptor string: a null terminated ASCII
  1526.   string. It will be present if there is an auxiliary data structure
  1527.   count in the primary data struct (an "N" descriptor in the data
  1528.   descriptor string).
  1529.  
  1530. RAP requires that the length of the return parameters be less than or
  1531. equal to the length of the parameters being sent; this requirement is
  1532. made to simply buffer management in implementations. This is reasonable
  1533. as the functions were designed to return data in the data section and
  1534. use the return parameters for items like data length, handles, etc. If
  1535. need be, this restriction can be circumvented by filling in some pad
  1536. bytes into the parameters being sent.
  1537.  
  1538. 10.4 Transaction Request Data section
  1539. The Data section for the transaction request is present if the parameter
  1540. description string contains an "s" (SENDBUF) descriptor. If present, it
  1541. contains:
  1542. . A primary data struct, as described by the data descriptor string
  1543. . Zero or more instances of the auxiliary data struct, as described by
  1544.   the auxiliary data descriptor string. The number of instances is
  1545.   determined by the value of the an auxiliary data structure count
  1546.   member of the primary data struct, indicated by the "N" (AUXCOUNT)
  1547.   descriptor. The auxiliary data is present only if the auxiliary data
  1548.   descriptor string is non null.
  1549.  
  1550.  
  1551. Leach, Naik                                                           25
  1552.  
  1553.  
  1554.                       CIFS Printing Specification
  1555.  
  1556.  
  1557. . Possibly some pad bytes
  1558. . The heap: the data referenced by pointers in the primary and
  1559.   auxiliary data structs.
  1560.  
  1561. 10.5 Transaction Response Parameters section
  1562. The response sent by the server contains a parameter section which
  1563. consists of:
  1564. . A 16 bit integer indicating the status or return code. The possible
  1565.   values for different functions are different.
  1566. . A 16 bit converter word, used adjust pointers to information in the
  1567.   response data section. Pointers returned within the response buffer
  1568.   are 32 bit pointers. The high order 16 bit word should be ignored.
  1569.   The converter word needs to be subtracted from the low order  16 bit
  1570.   word to arrive at an offset into the response buffer.
  1571. . The response parameters, as described by the parameter descriptor
  1572.   string, in the order that the response parameter descriptor
  1573.   characters appear in the parameter descriptor string.
  1574.  
  1575. 10.6 Transaction Response Data section
  1576. The Data section for the transaction response is present if the
  1577. parameter description string contains an "r" (RCVBUF) descriptor. If
  1578. present, it contains:
  1579. . Zero or more entries. The number of entries is determined by the
  1580.   value of the entry count parameter, indicated by the "e"(ENTCOUNT)
  1581.   descriptor. Each entry contains:
  1582.         . A primary data struct, as described by the data descriptor
  1583.           string
  1584.         . Zero or more instances of the auxiliary data struct, as
  1585.           described by the auxiliary data descriptor string. The number
  1586.           of instances is determined by the value of the AUXCOUNT
  1587.           member of the primary data struct (whose descriptor is "N").
  1588.           The auxiliary data is present only if the auxiliary data
  1589.           descriptor string is non null.
  1590. . Possibly some pad bytes
  1591. . The heap: the data referenced by pointers in the primary and
  1592.   auxiliary data structs.
  1593.  
  1594. 11. Appendix B
  1595. Transaction SMBs
  1596.  
  1597. These SMBs are used both to retrieve bulk data from the server (e.g.:
  1598. enumerate shares, etc.) and to change the server's state (EG: add a new
  1599. share, change file permissions, etc.)  Transaction requests are also
  1600. unusual because they can have a multiple part request and/or a multiple
  1601. part response.  For this reason, transactions are handled as a set of
  1602. sequenced commands to the server.  Each part of a request is sent as a
  1603. sequenced command using the same Mid value and an increasing Seq value.
  1604. The server responds to each request piece except the last one with a
  1605. response indicating that the server is ready for the next piece.  The
  1606. last piece is responded to with the first piece of the result data.  The
  1607. client then sends a transaction secondary SMB with ParameterDisplacement
  1608. set to the number of parameter bytes received so far and
  1609. DataDisplacement set to the number of data bytes received so far and
  1610. ParameterCount, ParameterOffset, DataCount, and DataOffset set to zero
  1611.  
  1612.  
  1613. Leach, Naik                                                           26
  1614.  
  1615.  
  1616.                       CIFS Printing Specification
  1617.  
  1618.  
  1619. (0).  The server responds with the next piece of the transaction result.
  1620. The process is repeated until all of the response information has been
  1621. received.  When the transaction has been completed, the redirector must
  1622. send another sequenced command (an echo SMB will do fine) to the server
  1623. to allow the server to know that the final piece was received and that
  1624. resources allocated to the transaction command may be released.
  1625. The flow is as follows, where (S) is the SequenceNumber,  (N) is the
  1626. number of request packets to be sent from the client to the server, and
  1627. (M) is the number of response packets to be sent by the server to the
  1628. client:
  1629.  
  1630.  
  1631.   Client                    <-> Server
  1632.   =======================   === ===========================
  1633.  
  1634.   SMB(S)  Transact          ->
  1635.                             <-  OK (S) send more data
  1636.    [ repeat N-1 times:
  1637.      SMB(S+1) Transact      ->
  1638.      secondary
  1639.                             <-  OK (S+1) send more data
  1640.      SMB(S+N-1)
  1641.    ]
  1642.                             <-  OK (S+N-1) transaction
  1643.                                 response (1)
  1644.    [ repeat M-1 times:
  1645.      SMB(S+N) Transact      ->
  1646.      secondary
  1647.                             <-  OK (S+N) transaction
  1648.                                 response (2)
  1649.      SMB(S+N+M-2) Transact  ->
  1650.      secondary
  1651.                             <-  OK (S+N+M-2] transaction
  1652.                                 response (M)
  1653.     ]
  1654.   SMB(S+N+M-1) Echo         ->
  1655.                             <-  OK (S+N+M-1) echoed
  1656.  
  1657.  
  1658. In order to allow the server to detect clients which have been powered
  1659. off, have crashed, etc., the client must send commands to the server
  1660. periodically if it has resources open on the server.  If nothing has
  1661. been received from a client for awhile, the server will assume that the
  1662. client is no longer running and disconnect the client.  This includes
  1663. closing any files that the client had open at the time and releasing any
  1664. resources being used on behalf of the client.  Clients should at least
  1665. send an echo SMB to the server every four (4) minutes if there is
  1666. nothing else to send.  The server will disconnect clients after a
  1667. configurable amount of time which cannot be less than five (5) minutes.
  1668. (Note: the NT server has a default timeout value of 15 minutes.)
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675. Leach, Naik                                                           27
  1676.  
  1677.  
  1678.                       CIFS Printing Specification
  1679.  
  1680.  
  1681. 11.1.1 TRANSACTIONS
  1682.  
  1683. SMB_COM_TRANSACTION performs a symbolically named transaction.  This
  1684. transaction is known only by a name (no file handle used).
  1685. SMB_COM_TRANSACTION2 likewise performs a transaction, but a word
  1686. parameter is used to identify the transaction instead of a name.
  1687. SMB_COM_NT_TRANSACTION is used for commands that potentially need to
  1688. transfer a large amount of data (greater than 64K bytes).
  1689.  
  1690. 11.1.1.1 SMB_COM_TRANSACTION AND SMB_COM_TRANSACTION2 FORMATS
  1691.  
  1692.  
  1693.  Primary Client Request           Description
  1694.  ===============================  ====================================
  1695.  
  1696.  Command                          SMB_COM_TRANSACTION or
  1697.                                   SMB_COM_TRANSACTION2
  1698.  
  1699.  UCHAR WordCount;                 Count of parameter words;   value =
  1700.                                   (14 + SetupCount)
  1701.  USHORT TotalParameterCount;      Total parameter bytes being sent
  1702.  USHORT TotalDataCount;           Total data bytes being sent
  1703.  USHORT MaxParameterCount;        Max parameter bytes to return
  1704.  USHORT MaxDataCount;             Max data bytes to return
  1705.  UCHAR MaxSetupCount;             Max setup words to return
  1706.  UCHAR Reserved;
  1707.  USHORT Flags;                    Additional information:
  1708.                                     bit 0 - also disconnect TID in TID
  1709.                                     bit 1 - one-way transaction (no
  1710.                                     resp)
  1711.  ULONG Timeout;
  1712.  USHORT Reserved2;
  1713.  USHORT ParameterCount;           Parameter bytes sent this buffer
  1714.  USHORT ParameterOffset;          Offset (from header start) to
  1715.                                   Parameters
  1716.  USHORT DataCount;                Data bytes sent this buffer
  1717.  USHORT DataOffset;               Offset (from header start) to data
  1718.  UCHAR SetupCount;                Count of setup words
  1719.  UCHAR Reserved3;                 Reserved (pad above to word)
  1720.  USHORT Setup[SetupCount];        Setup words (# = SetupWordCount)
  1721.  USHORT ByteCount;                Count of data bytes
  1722.  STRING Name[];                   Name of transaction (NULL if
  1723.                                   SMB_COM_TRANSACTION2)
  1724.  UCHAR Pad[];                     Pad to SHORT or LONG
  1725.  UCHAR Parameters[                Parameter bytes (# = ParameterCount)
  1726.  ParameterCount];
  1727.  UCHAR Pad1[];                    Pad to SHORT or LONG
  1728.  UCHAR Data[ DataCount ];         Data bytes (# = DataCount)
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737. Leach, Naik                                                           28
  1738.  
  1739.  
  1740.                       CIFS Printing Specification
  1741.  
  1742.  
  1743.  
  1744.  Interim Server Response          Description
  1745.  ===============================  ====================================
  1746.  
  1747.  UCHAR WordCount;                 Count of parameter words = 0
  1748.  USHORT ByteCount;                Count of data bytes = 0
  1749.  
  1750.  
  1751.  
  1752.  Secondary Client Request         Description
  1753.  ===============================  ====================================
  1754.  
  1755.  Command                          SMB_COM_TRANSACTION_SECONDARY
  1756.  
  1757.  UCHAR WordCount;                 Count of parameter words = 8
  1758.  USHORT TotalParameterCount;      Total parameter bytes being sent
  1759.  USHORT TotalDataCount;           Total data bytes being sent
  1760.  USHORT ParameterCount;           Parameter bytes sent this buffer
  1761.  USHORT ParameterOffset;          Offset (from header start) to
  1762.                                   Parameters
  1763.  USHORT ParameterDisplacement;    Displacement of these Parameter
  1764.                                   bytes
  1765.  USHORT DataCount;                Data bytes sent this buffer
  1766.  USHORT DataOffset;               Offset (from header start) to data
  1767.  USHORT DataDisplacement;         Displacement of these data bytes
  1768.  USHORT Fid;                      FID for handle based requests, else
  1769.                                   0xFFFF.  This field is present only
  1770.                                   if this is an SMB_COM_TRANSACTION2
  1771.                                   request.
  1772.  USHORT ByteCount;                Count of data bytes
  1773.  UCHAR Pad[];                     Pad to SHORT or LONG
  1774.  UCHAR                            Parameter bytes (# = ParameterCount)
  1775.  Parameters[ParameterCount];
  1776.  UCHAR Pad1[];                    Pad to SHORT or LONG
  1777.  UCHAR Data[DataCount];           Data bytes (# = DataCount)
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799. Leach, Naik                                                           29
  1800.  
  1801.  
  1802.                       CIFS Printing Specification
  1803.  
  1804.  
  1805.  
  1806.  Server Response                  Description
  1807.  ===============================  ====================================
  1808.  
  1809.  UCHAR WordCount;                 Count of data bytes; value = 10 +
  1810.                                   SETUPCOUNT
  1811.  USHORT TotalParameterCount;      Total parameter bytes being sent
  1812.  USHORT TotalDataCount;           Total data bytes being sent
  1813.  USHORT Reserved;
  1814.  USHORT ParameterCount;           Parameter bytes sent this buffer
  1815.  USHORT ParameterOffset;          Offset (from header start) to
  1816.                                   Parameters
  1817.  USHORT ParameterDisplacement;    Displacement of these Parameter
  1818.                                   bytes
  1819.  USHORT DataCount;                Data bytes sent this buffer
  1820.  USHORT DataOffset;               Offset (from header start) to data
  1821.  USHORT DataDisplacement;         Displacement of these data bytes
  1822.  UCHAR SetupCount;                Count of setup words
  1823.  UCHAR Reserved2;                 Reserved (pad above to word)
  1824.  USHORT Setup[SetupWordCount];    Setup words (# = SetupWordCount)
  1825.  USHORT ByteCount;                Count of data bytes
  1826.  UCHAR Pad[];                     Pad to SHORT or LONG
  1827.  UCHAR                            Parameter bytes (# = ParameterCount)
  1828.  Parameters[ParameterCount];
  1829.  UCHAR Pad1[];                    Pad to SHORT or LONG
  1830.  UCHAR Data[DataCount];           Data bytes (# = DataCount)
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.  
  1858.  
  1859.  
  1860.  
  1861. Leach, Naik                                                           30