idnits 2.17.1 draft-leach-cifs-print-spec-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == The page length should not exceed 58 lines per page, but there was 30 longer pages, the longest (page 1) being 62 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 44 has weird spacing: '...defined in th...' == Line 312 has weird spacing: '...SepFile point...' == Line 317 has weird spacing: '...zPrProc point...' == Line 420 has weird spacing: '...eturned is _...' == Line 533 has weird spacing: '...eturned is _...' == (14 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 31, 1997) is 9946 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Missing reference section? 'SetupCount' on line 1469 looks like a reference -- Missing reference section? 'ParameterCount' on line 1536 looks like a reference -- Missing reference section? 'DataCount' on line 1538 looks like a reference -- Missing reference section? 'SetupWordCount' on line 1532 looks like a reference Summary: 8 errors (**), 0 flaws (~~), 7 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CIFS Printing Specification 4 Network Working Group Paul J. Leach, Microsoft 5 INTERNET-DRAFT Dilip C. Naik, Microsoft 6 draft-leach-cifs-print-spec-00.txt 7 Category: Informational 8 Expires June 31, 1997 January 31, 1997 10 CIFS Printing Specification 11 Preliminary Draft 13 STATUS OF THIS MEMO 15 THIS IS A PRELIMINARY DRAFT OF AN INTERNET-DRAFT. IT DOES NOT REPRESENT 16 THE CONSENSUS OF ANY WORKING GROUP. 18 This document is an Internet-Draft. Internet-Drafts are working 19 documents of the Internet Engineering Task Force (IETF), its areas, and 20 its working groups. Note that other groups may also distribute working 21 documents as Internet-Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference material 26 or to cite them other than as "work in progress". 28 To learn the current status of any Internet-Draft, please check the 29 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 30 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 31 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 32 ftp.isi.edu (US West Coast). 34 Distribution of this document is unlimited. Please send comments to the 35 authors or the CIFS mailing list at . 36 Discussions of the mailing list are archived at 37 . 39 ABSTRACT 41 This specification defines how clients may submit print requests to a 42 server using SMBs . The specification also details how clients may 43 administer printing of the print requests they create, using SMBs 44 defined in the Common Internet File System specification. 46 Table of Contents 48 1. OBJECTIVE...........................................................3 50 2. PREREQUISITES AND SUGGESTED READING.................................3 51 CIFS Printing Specification 53 3. PRINTING OVERVIEW...................................................3 55 4. CREATING A PRINT JOB................................................3 57 4.1 OPEN_PRINT_FILE: CREATE PRINT SPOOL FILE .........................4 58 4.2 CLOSE_PRINT_FILE: CLOSE AND SPOOL PRINT JOB .....................5 60 5. REMOTE ADMINISTRATION PROTOCOL AND DOCUMENTATION CONVENTIONS........5 62 6. PRINT QUEUES AND RELATED FUNCTIONS..................................6 64 6.1 DATA STRUCTURES RELATED TO PRINT QUEUES ..........................6 65 6.1.1 Printer Queue Information (Level 3) ...........................6 66 6.1.2 Printer Queue Information (Level 4) ...........................7 67 6.1.3 Printer Queue Information (Level 5) ...........................8 68 6.2 DOSPRINTQENUM ....................................................8 69 6.3 DOSPRINTQGETINFO ................................................10 71 7. PRINT JOBS AND MANIPULATING PRINT JOBS.............................12 73 7.1 DATA STRUCTURES RELATED TO PRINT JOBS ...........................12 74 7.2 DOSPRINTJOBENUM .................................................14 75 7.3 DOSPRINTJOBGETINFO ..............................................16 76 7.4 DOSPRINTJOBCONTINUE .............................................19 77 7.5 DOSPRINTJOBDEL ..................................................20 79 8. AUTHOR'S ADDRESSES.................................................21 81 9. REMOTE ADMINISTRATION PROTOCOL OVERVIEW............................21 83 10. APPENDIX A - REMOTE ADMINISTRATION PROTOCOL.......................22 85 10.1 NOTATION .......................................................23 86 10.2 DESCRIPTORS ....................................................23 87 10.2.1 Request Parameter Descriptors ...............................23 88 10.2.2 Response Parameter Descriptors ..............................24 89 10.2.3 Data Descriptors ............................................24 90 10.3 TRANSACTION REQUEST PARAMETERS SECTION .........................25 91 10.4 TRANSACTION REQUEST DATA SECTION ...............................25 92 10.5 TRANSACTION RESPONSE PARAMETERS SECTION ........................26 93 10.6 TRANSACTION RESPONSE DATA SECTION ..............................26 95 11. APPENDIX B........................................................26 97 11.1.1 TRANSACTIONS ................................................28 98 CIFS Printing Specification 100 1. Objective 101 This document describes 102 . how CIFS clients accomplish printing on CIFS servers acting as print 103 servers. 104 . how CIFS clients administer printing on CIFS servers. 106 For convenience, some sections from the CIFS specification have been 107 reproduced in part within this document. Note that the CIFS 108 specification should be considered to be the authoritative reference, in 109 case of any doubts, rather than this document. 111 2. Prerequisites and suggested reading 112 . Familiarity with Common Internet File Systems specification (CIFS) in 113 general and the CIFS Remote Administration Protocol in particular. 115 3. Printing overview 116 A CIFS client opens a print file on a CIFS server in a manner similar to 117 opening an ordinary file, but using a different SMB (described in 118 section 4.1). The CIFS client then writes to the file. When the CIFS 119 client closes the file, the CIFS print server considers the file to be a 120 print job or print request that needs to be printed. 122 The CIFS print server implements a concept of print queues. A print 123 queue is simply an ordered set of print requests or print jobs. Every 124 print job is associated with a print queue. A client can control which 125 print queue a print job is associated with. A printer queue stores print 126 jobs and sends them one by one to a printer. A print queue may have 127 multiple physical printers associated with it. Different queues may 128 share the same printer. Print queues allow administrative convenience 129 such as selection of a printer, priority assignment for printing, 130 controlling times during which jobs may print, etc. . 132 Section 4 describes how a client may generate a print job. 134 Section 6 describes how a client may enumerate print queues and retrieve 135 information about a particular print queue. 137 Section 7 describes how a client may manipulate print jobs, causing 138 print jobs to be paused, resumed or deleted. 140 Print queues and print jobs are manipulated using the CIFS Remote 141 Administration protocol. The CIFS specification includes details on 142 Remote Administration protocol. For convenience, details have been 143 duplicated (from the CIFS specification) into Appendix A and Appendix B. 144 Note that the CIFS specification should be considered a more 145 authoriative source of information, as compared to Appendix A and B. 147 4. Creating a Print Job 149 A CIFS client creates a print job (or a print request) by opening a 150 print file, writing to the print file and then closing it. A print file 151 CIFS Printing Specification 153 differs from an ordinary file in that a CIFS server tracks a print file 154 and deletes it automatically when the printing is complete. 156 A print job is associcated with a print queue. Different print queues 157 may have different characteristics and may print on different printers. 158 A client can control which print queue a print job (created by the 159 client) is associated with. The CIFS print server shares different 160 queues. A client first creates a connection via a SessionSetupAndX 161 followed by a TreConnectAndX SMB, specifying the appropriate print queue 162 share in the TreeConnectAndX SMB. Refer to the CIFS document for details 163 on the TreeConnectAndX SMB. The TreeConnectAndX will return a Tree Id 164 (Tid) if the SMB succeeds. This Tid is used when opening a print file. 166 4.1 OPEN_PRINT_FILE: Create Print Spool file 168 This message is sent to create a new printer file which will be deleted 169 once it has been closed and printed. Complete understanding of this 170 message requires familiarity with the CIFS specification. 172 Client Request Description 173 ================================== ================================= 175 UCHAR WordCount; Count of parameter words = 2 176 USHORT SetupLength; Length of printer setup data 177 USHORT Mode; 0 = Text mode (DOS expands TABs) 178 1 = Graphics mode 179 USHORT ByteCount; Count of data bytes; min = 2 180 UCHAR BufferFormat; 0x04 181 STRING IdentifierString[]; Identifier string 183 TID in the SMB header must refer to a printer resource type. 185 SETUPLENGTH is the number of bytes in the first part of the resulting 186 print spool file which contains printer-specific control strings. 188 MODE can have the following values: 189 0 Text mode. The server may optionally 190 expand tabs to a series of spaces. 191 1 Graphics mode. No conversion of data 192 should be done by the server. 194 IDENTIFIERSTRING can be used by the server to provide some sort of per- 195 client identifying component to the print file. 197 Server Response Description 198 ================================== ================================= 200 UCHAR WordCount; Count of parameter words = 1 201 USHORT Fid; File handle 202 CIFS Printing Specification 204 USHORT ByteCount; Count of data bytes = 0 206 FID is the returned handle which may be used by subsequent write and 207 close operations. When the file is finally closed, it will be sent to 208 the spooler and printed. 210 4.2 CLOSE_PRINT_FILE: Close and Spool Print Job 212 This message invalidates the specified file handle and queues the file 213 for printing. Complete understanding of this message requires 214 familiarity with the CIFS specification. 216 Client Request Description 217 ================================== ================================= 219 UCHAR WordCount; Count of parameter words = 1 220 USHORT Fid; File handle 221 USHORT ByteCount; Count of data bytes = 0 223 FID refers to a file previously created with SMB_COM_OPEN_PRINT_FILE. 224 On successful completion of this request, the file is queued for 225 printing by the server. 227 Server Response Description 228 ================================== ================================= 230 UCHAR WordCount; Count of parameter words = 0 231 USHORT ByteCount; Count of data bytes = 0 233 Servers which negotiate dialects of LANMAN1.0 and newer allow all the 234 other types of FID closing requests to invalidate the FID and begin 235 spooling. 237 5. Remote Administration Protocol and Documentation Conventions 239 Print queue and print job related management functions are accomplished 240 using the CIFS Remote Administration Protocol (RAP). Complete details 241 may be found in the CIFS specification and in Appendix A. Persons 242 unfamiliar with the RAP specification are strongly advised to read the 243 CIFS specification or at least Appendix A at this stage. Sections that 244 follow describe how a CIFS client queries information about print queues 245 and print jobs and administers print jobs These descriptions assume 246 knowledge of the CIFS RAP specification. 248 CIFS Printing Specification 250 6. Print Queues and related functions 252 A CIFS server can enumerate all print queues on a given server using the 253 DosPrintQEnum function. Once the CIFS client knows the names of each 254 print queue, the CIFS client can then obtain information about each 255 print queue using the DosPrintQGetInfo function. Both of these functions 256 are executed on the remote print server using the CIFS Remote 257 Administration Protocol, fully detailed in the CIFS document as well as 258 Appendix A and Appendix B. 260 6.1 Data structures related to Print queues 262 This section describes data structures used to describe print queues. 263 Data structures corresponding to print queue levels 0 , 1 and 2 are 264 obsolete. 266 6.1.1 Printer Queue Information (Level 3) 268 The PRQINFO_3 data structure describes a particular printer queue. The 269 DosPrintQEnum and DosPrintQGetInfo functions (described below) return 270 data in this format when the desired level of information is set to 271 level 3. 273 struct PRQINFO_3 { 274 char *pszName; 275 unsigned short Priority; 276 unsigned short Starttime; 277 unsigned short UntilTime; 278 unsigned short Pad1; 279 char *pszSepFile; 280 char *pszPrProc; 281 char *pszParms; 282 char *pszComment; 283 unsigned short Status; 284 AUXCOUNT cJobs; 285 char *pszPrinters; 286 char *pszDriverName 287 void *pDriverData; 288 } 290 where: 292 pszName points to a null terminated ASCII string that contains the 293 queue name. 295 Priority contains an unsigned short integer specifying the printer 296 queue priority. The value can range from 1(highest) to 9 (lowest). 297 When two printer queues print to the same printer, the print jobs 298 from the one with the higher priority print first. 300 Untiltime contains an unsigned short integer specifying the time 301 of day a printer queue becomes inactive and stops sending print 302 jobs to printers. This value represents the number of minutes 303 since midnight (00:00). 305 CIFS Printing Specification 307 Starttime contains an unsigned short integer specifying the time 308 of day a printer queue can start sending print jobs to printers. 309 This value represents the number of minutes since midnight 310 (00:00). 312 pszSepFile points to a null terminated ASCII string that 313 represents the pathname to a seperator page file. The seperator 314 page contains formatting information about the pages that separate 315 print jobs. 317 pszPrProc points to a null terminated ASCII string that 318 represents the name of the print preprocessor. A null pointer or 319 null string inidcates the default print preprocessor. 321 pszDestinations points to a null terminated ASCII string that 322 contains a list of print destinations for the print queue. This is 323 a multi-valued property and the values are separated by spaces. 325 pszParms points to a null terminated ASCII string that contains 326 parameters required by printer queues. 328 pszComment points to a null terminated ASCII string that contains 329 a comment about the print queue. 331 Status contains an unsigned short integer that specifies the 332 status of a printer queue. Possible values are: 334 Code Value Description 336 PRQ_ACTIVE 0 Active 337 PRQ_PAUSE 1 Paused 338 PRQ_ERROR 2 Error Occurred 339 PRQ_PENDING 3 Deletion pending 341 cJobs contains an unsigned short integer representing the number 342 of print jobs currently in the print queue. 344 pszDriverName points to a null terminated ASCII string 345 representing the default device driver for the queue. If this 346 field is null, the pDriverData field is not used. 348 pDriverData points to the device driver data for the default 349 driver. 351 6.1.2 Printer Queue Information (Level 4) 353 At this level, the returned information consists of a level 3 print 354 queue data structure (as described in section 5.1.1) followed by a 355 PRJINFO_2 data structure for each print job in the queue. The PRJINFO_2 356 data structure is described in section 7.1. 358 CIFS Printing Specification 360 6.1.3 Printer Queue Information (Level 5) 362 At level 5, the returned data structure is defined as: 364 struct PRQINFO_5 { 365 char *pszName; 366 } 368 where: 369 pszName points to a null terminated ASCII string that contains the 370 queue name. 372 6.2 DosPrintQEnum 374 The DosPrintQEnum function lists all printer queues on a server. The 375 definition is: 377 unsigned short DosPrintQEnum( 378 unsigned short sLevel; 379 RCVBUF pbBuffer; 380 RCVBUFLEN cbBuffer; 381 ENTCOUNT pcReturned; 382 unsigned short *pcTotalAvail; 383 ); 385 where: 387 sLevel specifies the level of detail returned. Legal values are 388 3, 4 and 5 . 390 pbBuffer points to the buffer to receive the returned data. 392 cbBuffer specifies the size, in bytes, of the buffer pointed to by 393 the pbBuffer parameter. 395 pcReturned points to a 16 bit variable that receives a count of 396 the total number of entries (queues) returned. This count is valid 397 only if DosPrintQEnum returns the NERR_Success or ERROR_MORE_DATA 398 values. 400 pcTotalAvail points to a 16 bit variable that receives a count of 401 the total number of entries (queues) available. This count is 402 valid only if DosPrintQEnum returns the NERR_Success or 403 ERROR_MORE_DATA values. 405 Transaction Request Parameters section 407 The Transaction request parameters section in this instance contains: 409 . The function number for DosPrintQEnum which is 69. 410 . The parameter descriptor string which is _WrLeh_ 411 . The data descriptor string for the returned data is _zWWWWzzzzWWzzl_ 412 if sLevel (the level of desired information) is 3. This corresponds 413 CIFS Printing Specification 415 to the data structure PRQINFO_3There is no auxiliary data in the 416 response when the level of desired information is 3. 417 . The data descriptor string for the returned data is _zWWWWzzzzWNzzl_ 418 if sLevel (the level of desired information) is 4. This corresponds 419 to the data structure PRQINFO_3. The descriptor for the auxiliary 420 data returned is _WWzWWDDzz_ when the level of desired information 421 is 4. This corresponds to the PRJINFO_2 data structure. 422 . The data descriptor string for the returned data is _z_ if sLevel 423 (the level of desired information) is 5. The _z_ indicates a null 424 terminated ASCII string representing the name of the print queue. . 425 There is no auxiliary data descriptor for this level of information. 426 . The actual parameters as described by the parameter descriptor 427 string. These are: 428 " A 16 bit integer with a value of 3, 4 or 5 (corresponding to the _W_ 429 in the parameter descriptor string. This represents the level of 430 detail the server is expected to return 431 " A 16 bit integer that contains the size of the receive buffer. 433 Transaction Request Data section 435 There is no data or auxiliary data to send as part of the request. 437 Transaction Response Parameters section 439 The transaction response parameters section consists of: 440 . A 16 bit word indicating the return status. The possible values are: 442 Code Value Description 443 NERR_Success 0 No errors encountered 444 ERROR_ACCESS_DENIED 5 The user does not have required 445 priveleges 446 ERROR_MORE_DATA 234 Additional data is available 447 NERR_SpoolerNotLoaded 2161 The spooler is not started on 448 the remote server 449 NERR_BadTransactConfig 2141 The server is not configured 450 for transactions, IPC$ is not 451 shared 453 . A 16 bit _converter_ word. 454 . A 16 bit number representing the number of entries returned. 455 . A 16 bit number representing the total number of available entries. 456 If the supplied buffer is large enough, this will equal the number of 457 entries returned. 459 Transaction Response Data section 461 The Transaction response data section consists of a series of data 462 structures. The number of the data structures is equal to the number or 463 entries being returned, which is the third value in the Transaction 464 response parameter section. 466 At information level 3, a series of PRQINFO_3 data structures are 467 returned. There is no auxiliary data at this information level. 469 CIFS Printing Specification 471 At information level 4, a series of PRQINFO_3 data structures are 472 returned. There is also auxiliary data present in this case. For each 473 print job in each print queue, a PRJINFO_2 structure is returned in the 474 auxiliary data. For each print queue, the data descriptor string element 475 _N_ denotes the number of PRJINFO_2 data structures present in the 476 auxiliary data for that queue. This also denotes the number of print 477 jobs associated with that print queue. 479 At information level 5, a PRQINFO_5 data structure is returned for each 480 print queue. There is no auxiliary data in the response when the level 481 of desired information is 5. 483 As per the RAP specification, all pointers in any of the data 484 structures returned need to be treated specially in the prescribed 485 manner. 487 6.3 DosPrintQGetInfo 489 The DosPrintQGetInfo function retrieves information about a particular 490 print queue on a CIFS server. The definition is: 492 unsigned short DosPrintQGetInfo( 493 char *pszQueueName; 494 short sLevel; 495 RCVBUF pbBuffer; 496 RCVBUFLEN cbBuffer; 497 unsigned short *pcbTotalAvail; 498 ); 500 where: 502 pszQueueName points to an ASCII null-terminated string specifying the 503 name of the queue for which information should be retrieved. 505 sLevel specifies the level of detail returned. (Legal values are 3, 506 4, and 5 ) 508 pbBuffer points to the buffer to receive the returned data. 510 cbBuffer specifies the size, in bytes, of the buffer pointed to by the 511 pbBuffer parameter. 513 pcbTotalAvail points to a 16-bit variable that receives a count of the 514 total number of bytes of information available. This count is valid 515 only if DosPrintQGetInfo returns the NERR_Success or ERROR_MORE_DATA 516 values. 518 Transaction Request Parameters section 520 The Transaction request parameters section in this instance contains: 522 . The function number for DosPrintQGetInfo which is 70. 523 . The parameter descriptor string which is _zWrLh_ 524 CIFS Printing Specification 526 . The data descriptor string for the returned data is _zWWWWzzzzWWzzl_ 527 if sLevel (the level of desired information) is 3. This corresponds 528 to the data structure PRQINFO_3. There is no auxiliary data in the 529 response when the level of desired information is 3. 530 . The data descriptor string for the returned data is _zWWWWzzzzWNzzl_ 531 if sLevel (the level of desired information) is 4. This corresponds 532 to the data structure PRQINFO_3. The descriptor for the auxiliary 533 data returned is _WWzWWDDzz_ when the level of desired information 534 is 4. This corresponds to the PRJINFO_2 data structure. 535 . The data descriptor string for the returned data is _z_ if sLevel 536 (the level of desired information) is 5. The _z_ indicates a null 537 terminated ASCII string representing the name of the print queue. . 538 There is no auxiliary data descriptor for this level of information. 539 . The actual parameters as described by the parameter descriptor 540 string. These are: 541 . A null terminated ASCII string denoting the name of the print 542 queue for which information should be retrieved. 543 . A 16 bit integer with a value of 3, 4 or 5 . This represents 544 the level of detail the server is expected to return 545 . A 16 bit integer that contains the size of the receive 546 buffer. 548 Transaction Request Data section 550 There is no data or auxiliary data to send as part of the request. 552 Transaction Response Parameters section 554 The transaction response parameters section consists of: 555 . A 16 bit word indicating the return status. The possible values are: 557 Code Value Description 558 NERR_Success 0 No errors encountered 559 ERROR_ACCESS_DENIED 5 User has insufficient 560 privilege 561 ERROR_MORE_DATA 234 Additional data is 562 available 563 NERR_QNotFound 2150 The specified queue name 564 is invalid 565 NERR_SpoolerNotLoaded 2161 The spooler is not started 566 on the remote server 568 . A 16 bit _converter_ word. The value is up to the server to decide. 569 . A 16 bit number representing the total number of available bytes. 570 This has meaning only if the return status is NERR_Success, 571 ERROR_MORE_DATA or NERR_BufTooSmall 573 Transaction Response Data Section 575 The Transaction response data section consists of a single data 576 structure 577 CIFS Printing Specification 579 At information level 3, a PRQINFO_3 data structure is returned. There 580 is no auxiliary data at this information level. 582 At information level 4, a PRQINFO_3 data structure is returned. This 583 data structure describes the print queue of interest. There is also 584 auxiliary data present in this case. For each print job in the print 585 queue, a PRJINFO_2 structure is returned in the auxiliary data. The data 586 descriptor string element _N_ denotes the number of PRJINFO_2 data 587 structures present in the auxiliary data for that queue. This also 588 denotes the number of print jobs associated with that print queue. 590 At information level 5, a PRQINFO_5 data structure is returned for each 591 print queue. There is no auxiliary data in the response when the level 592 of desired information is 5. 594 As per the RAP specification, all pointers in any of the data 595 structures returned need to be treated specially in the prescribed 596 manner. 598 7. Print Jobs and manipulating Print Jobs 600 Once a CIFS client has located a print queue, the client can then 601 enumerate jobs within that queue using the DosPrintJobEnum function. A 602 CIFS client may also obtain print job information by means of the 603 DosPrintQEnum and DosPrintQGetInfo services, specifying a desired 604 information level of 4. Once the CIFS client has a list of job 605 identifiers, it can obtain detailed information about any print job 606 using the DosPrintJobGetInfo function. For print jobs initiated by the 607 client, and which are not yet printing, the CIFS client can pause, 608 resume or delete the print jobs using DosPrintJobPause, 609 DosPrintJobContinue and DosPrintJobDel functions respectively. All of 610 these DosPrintJobX services are executed on the remote print server 611 using the CIFS Remote Administration Protocol described in the CIFS 612 document as well as in Appendix A and Appendix B. 614 7.1 Data Structures related to Print Jobs 616 struct PRJINFO_0 { 617 unsigned short JobId 618 } 620 where: 622 JobId is a 16 bit integer that uniquely specifies a print job 623 within a printer queue. The JobID is unique on a server. A 624 combination of the server name and JobId is sufficient to uniquely 625 identify a particular print job. 627 CIFS Printing Specification 629 struct PRJINFO_2 { 630 unsigned short JobId; 631 unsigned short Priority; 632 char *pszUserName; 633 unsigned short Position; 634 unsigned short Status; 635 unsigned long Submitted; 636 unsigned long Size; 637 char *pszComment; 638 char *pszDocument; 639 } 641 where: 643 JobId is a 16 bit integer that uniquely specifies a print job 644 within a printer queue. The JobID is unique on a server. A 645 combination of the server name and JobId is sufficient to uniquely 646 identify a particular print job. 648 Priority is a 16 bit integer that specifies the print job 649 priority. This varies from a value of 1 (lowest priority) to 99 650 (highest priority. Higher priority jobs print first. When 2 jobs 651 have the same priority, the older job prints first. 653 pszUserName is a pointer to a null terminated ASCII string that 654 specifies the name of the user who submitted the print job. 656 Position specifies the position of the print job within the print 657 queue. If the value is 1, this print job prints next. 659 Status is an integer used as a status flag. The values and 660 meanings of the various bits are: 662 Bits Code Value Description 663 0-1 PRJ_QS_QUEUED 0 Print job is queued 664 0-1 PRJ_QS_PAUSED 1 Print job is paused 665 0-1 PRJ_QS_SPOOLING 2 Print job is spooling 666 0-1 PRJ_QS_PRINTING 3 Print job is printing, 667 bits 2-11 are valid 669 Bit Code Value Description 670 2 PRJ_COMPLETE 0x0004 Print job is complete 671 3 PRJ_INTERV 0x0008 an error occurred, pszStatus 672 may contain a comment explaining 673 the error 674 4 PRJ_ERROR 0x0010 Print job is spooling 675 5 PRJ_DESTOFFLINE 0x0020 The print destination is offline 676 6 PRJ_DESTPAUSED 0x0040 The print destination is paused 677 7 PRJ_NOTIFY 0x0080 An alert is raised 678 8 PRJ_DESTNOPAPER 0x0100 The print destination is out of 679 paper 680 9 PRJ_DESTFORMCHG 0x0200 The printer is waiting for a 681 form change 682 10 PRJ_DESTCRTCHG 0x0400 The printer is waiting for a 683 CIFS Printing Specification 685 cartridge change 686 11 PRJ_DESTENCHG 0x0800 The printer is waiting for a pen 687 change 688 15 PRJ_ PRINTING 0x8000 An alert indicates the job was 689 deleted 691 pszStatus points to an ASCII string that contains a comment about 692 the status of the job. This element contains valid data only when 693 the job is printing and an error occurs. This element may be null 694 or point to a null string. 696 Submitted contains an unsigned long integer specifying when the 697 user submitted the job. This is stored as the number of seconds 698 elapsed since 00:00:00 Jan 1st, 1970. 700 Size contains an unsigned long integer that specifies the size of 701 the print job in terms of number of bytes. 703 pszComment points to a null terminated ASCII string that contains 704 a comment about the print job. 706 pszDocument points to a null terminated ASCII string that contains 707 the name of the document. 709 7.2 DosPrintJobEnum 711 The DosPrintJobEnum service lists print jobs in the specified printer 712 queue. The definition is: 714 unsigned short DosPrintJobEnum( 715 char *pszQueueName; 716 short sLevel; 717 RCVBUF pbBuffer; 718 RCVBUFLEN cbBuffer; 719 unsigned short *pcbTotalAvail; 720 ); 722 where: 724 pszQueuename points to a null-terminated string specifying the 725 name of the print queue for which print jobs should be enumerated. 727 sLevel specifies the level of detail returned. (Legal values are 728 0 and 2) 730 pbBuffer points to the buffer to receive the returned data. 732 cbBuffer specifies the size, in bytes, of the buffer pointed to by 733 the pbBuffer parameter. 735 CIFS Printing Specification 737 pcbTotalAvail points to a 16 bit variable that receives a count of 738 the total number of bytes of information available. This count is 739 valid only if the return value is NERR_Success or ERROR_MORE_DATA . 741 Transaction Request Parameters section 743 The Transaction request parameters section in this instance contains: 745 . The function number for DosPrintJobEnum which is 76. 746 . The parameter descriptor string which is _zWrLeh_ 747 . The data descriptor string for the returned data is _z_ if sLevel 748 (the level of desired information) is 0. This corresponds to the data 749 structure PRJINFO_0 already described. 750 . The data descriptor string for the returned data is _WWzWWDDzz_ if 751 sLevel (the level of desired information) is 2. This corresponds to 752 the PRJINFO_2 data structure.already described. 753 . The actual parameters as described by the parameter descriptor 754 string. These are: 755 . A null terminated ASCII string denoting the name of the print 756 queue which contains the print job of interest. 757 . A 16 bit integer with a value of 0 or 2 . This represents the 758 level of detail the server is expected to return 759 . A 16 bit integer that contains the size of the receive 760 buffer. 762 There is no data or auxiliary data that is sent as part of the 763 Transaction request. 765 Transaction Request Data section 767 There is no data or auxiliary data to send as part of the request. 769 Transaction Response Parameters section 771 The transaction response parameters section consists of: 772 . A 16 bit word indicating the return status. The possible values are: 774 Code Value Description 776 NERR_Success 0 No errors encountered 777 ERROR_ACCESS_DENIED 5 User has insufficient 778 privilege 779 ERROR_MORE_DATA 234 Additional data is 780 available 781 NERR_QNotFound 2150 The specified queue name 782 is invalid 783 NERR_SpoolerNotLoaded 2161 The spooler is not started 784 on the remote server 786 . A 16 bit _converter_ word. 788 CIFS Printing Specification 790 . A 16 bit number representing the total number of available entries. 791 This has meaning only if the return status is NERR_Success, 792 ERROR_MORE_DATA or NERR_BufTooSmall 794 Transaction Response Data Section 796 The Transaction response data section consists of a data structures. 798 At information level 0, a series of PRJINFO_0 data structures are 799 returned. The number of structure is equal to the value in the third 800 parameter in the response parameter section. There is no auxiliary data 801 at this information level. 803 At information level 2, a series of PRJINFO_2 data structures are 804 returned. The number of such data structures returned is equal to the 805 value in the third parameter of the response parameter section. There is 806 no auxiliary data present in this case. 808 As per the RAP specification, all pointers in any of the data 809 structures returned need to be treated specially in the prescribed 810 manner. 812 There is no auxiliary data in the response. 814 7.3 DosPrintJobGetInfo 816 The DosPrintJobGetInfo service retrieves information about a particular 817 print job. The definition is: 819 unsigned short DosPrintJobGetInfo( 820 unsigned short JobId; 821 unsigned short sLevel; 822 RCVBUF pbBuffer; 823 RCVBUFLEN cbBuffer; 824 unsigned short *pcbTotalAvail; 825 ); 827 where: 829 JobId specifies identity of the print job for which information 830 should be retrieved. 832 Level specifies the level of detail returned. (Legal values are 0 833 and 2) 835 pbBuffer points to the buffer to receive the returned data. 837 cbBuffer specifies the size, in bytes, of the buffer pointed to by 838 the pbBuffer parameter. 840 CIFS Printing Specification 842 pcbTotalAvail points to a 16 bit variable that receives a count of 843 the total number of bytes of information available. This count is 844 valid only if DosPrintJobGetInfo returns the 845 NERR_Success or ERROR_MORE_DATA values. 847 Transaction Request Parameters section 849 The Transaction request parameters section in this instance contains: 851 . The function number for DosPrintJobGetInfo which is 77. 852 . The parameter descriptor string which is _WWrLh_ 853 . The data descriptor string for the returned data is _z_ if sLevel 854 (the level of desired information) is 0. This corresponds to the data 855 structure PRJINFO_0 already described. 856 . The data descriptor string for the returned data is _WWzWWDDzz_ if 857 sLevel (the level of desired information) is 2. This corresponds to 858 the PRJINFO_2 data structure.already described. 859 . The actual parameters as described by the parameter descriptor 860 string. These are: 861 . A 16 bit integer specifying the identity of the job for which 862 information should be retrieved. 863 . A 16 bit integer with a value of 0 or 2 . This represents the 864 level of detail the server is expected to return 865 . A 16 bit integer that contains the size of the receive 866 buffer. 868 There is no data or auxiliary data that is sent as part of the 869 Transaction request. 871 Transaction Request Data section 873 There is no data or auxiliary data to send as part of the request. 875 Transaction Response Parameters section 877 The transaction response parameters section consists of: 878 . A 16 bit word indicating the return status. The possible values are: 879 Code Value Description 880 NERR_Success 0 No errors encountered 881 ERROR_ACCESS_DENIED 5 The user does not have required 882 priveleges 883 ERROR_MORE_DATA 234 Additional data is available 884 NERR_SpoolerNotLoaded 2161 The spooler is not started on the 885 remote server 886 NERR_BadTransactConfig 2141 The server is not configured for 887 transactions, IPC$ is not shared 889 . A 16 bit _converter_ word. 890 . A 16 bit number representing the total number of available bytes. 891 This has meaning only if the return status is NERR_Success, 892 ERROR_MORE_DATA or NERR_BufTooSmall 893 CIFS Printing Specification 895 Transaction Response Data Section 897 The return data section consists of a PRJINFO_0 data structure if the 898 desired level of information is 0. The return data section consists of a 899 PRJINFO_2 data structure if the desired level of information is 2. These 900 have already been detailed. 902 Note that the pointers in the data structure in data structure PRJINFO_2 903 need to be treated specially. The high 16 bit word needs to be ignored. 904 The converter word returned in the response parameters section needs to 905 be subtracted from the low 16 bit value to locate the actual offset of 906 the item within the response buffer sent by the server. 908 There is no auxiliary data to receive. 910 DosPrintJobPause 912 DosPrintJobPause pauses a print job in a printer queue. The definition 913 is: 915 unsigned short DosPrintJobPause( 916 unsigned short JobId; 917 ); 919 where: 921 JobId specifies the identity of the print job that should be 922 paused 924 Transaction Request Parameters section 926 The Transaction request parameters section in this instance contains: 928 . The function number for DosPrintJobPause which is 82. 929 . The parameter descriptor string which is _W_ 930 . The data descriptor string is null. 931 . The actual parameters as described by the parameter descriptor 932 string. This consists of just a 16 bit integer representing the 933 JobId, identifying the job to be paused. 935 Transaction Request Data section 937 There is no data or auxiliary data to send as part of the request. 939 Transaction Response Parameters section 941 The transaction response parameters section consists of: 942 . A 16 bit word indicating the return status. The possible values are: 944 Code Value Description 945 NERR_Success 0 No errors encountered 946 ERROR_ACCESS_DENIED 5 User has insufficient 947 CIFS Printing Specification 949 privilege 950 ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied 951 NERR_BadTransactConfig 2141 The server is not configured 952 for transactions, IPC$ is not 953 shared 954 NERR_JobNotFound 2151 The specified print job could 955 not be located 956 NERR_SpoolerNotLoaded 2161 The spooler is not started on 957 the remote server 958 NERR_JobInvalidState 2164 The operation cannot be 959 performed on the job in it's 960 current state(job is already 961 printing) 963 Transaction Response Data Section 965 There is no data or auxiliary data in the response. 967 7.4 DosPrintJobContinue 969 DosPrintJobContinue allows a paused print job to resume printing. The 970 definition is: 972 unsigned short DosPrintJobContinue( 973 unsigned short JobId; 974 ); 976 where: 978 JobId specifies the identity of the print job that should resume 979 printing 981 Transaction Request Parameters section 983 The Transaction request parameters section in this instance contains: 985 . The function number for DosPrintJobContinue which is 83. 986 . The parameter descriptor string which is _W_ 987 . The data descriptor string is null. 988 . The actual parameters as described by the parameter descriptor 989 string. This consists of just a 16 bit integer representing the JobId 990 (identifies job to be paused) 992 Transaction Request Data section 994 There is no data or auxiliary data to send as part of the request. 996 Transaction Response Parameters section 998 The transaction response parameters section consists of: 1000 CIFS Printing Specification 1002 . A 16 bit word indicating the return status. The possible values are: 1004 Code Value Description 1005 NERR_Success 0 No errors encountered 1006 ERROR_ACCESS_DENIED 5 User has insufficient 1007 privilege 1008 ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied 1009 NERR_BadTransactConfig 2141 The server is not configured 1010 for transactions, IPC$ is not 1011 shared 1012 NERR_JobNotFound 2151 The specified print job could 1013 not be located 1014 NERR_SpoolerNotLoaded 2161 The spooler is not started on 1015 the remote server 1016 NERR_JobInvalidStatus 2164 The operation cannot be 1017 performed on the print job in 1018 it's current state 1020 Transaction Response Data Section 1022 There is no data or auxiliary data in the response. 1024 7.5 DosPrintJobDel 1026 DosPrintJobDel deletes a print job from a printer queue. The definition 1027 is: 1029 unsigned short DosPrintJobDel( 1030 unsigned short JobId; 1031 ); 1033 where: 1035 JobId specifies the identity of the print job that should be 1036 deleted 1038 Transaction Request Parameters section 1040 The Transaction request parameters section in this instance contains: 1042 . The function number for DosPrintJobDel which is 81. 1043 . The parameter descriptor string which is _W_ 1044 . The data descriptor string is null. 1045 . The actual parameters as described by the parameter descriptor 1046 string. This consists of just a 16 bit integer representing the JobId 1047 , identifying the job to be paused. 1049 Transaction Request Data section 1051 There is no data or auxiliary data to send as part of the request. 1053 Transaction Response Parameters section 1054 CIFS Printing Specification 1056 The transaction response parameters section consists of: 1057 . A 16 bit word indicating the return status. The possible values are: 1059 Code Value Description 1061 NERR_Success 0 No errors encountered 1062 ERROR_ACCESS_DENIED 5 User has insufficient 1063 privilege 1064 ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied 1065 NERR_BadTransactConfig 2141 The server is not 1066 configured for 1067 transactions, IPC$ 1068 is not shared 1069 NERR_JobNotFound 2151 The specified print job 1070 could not be located 1071 NERR_ProcNotRespond 2160 The print process is not 1072 responding 1073 NERR_SpoolerNotLoaded 2161 The spooler is not 1074 started on the 1075 remote server 1077 Transaction Response Data Section 1079 There is no data or auxiliary data in the response. 1081 8. Author's Addresses 1083 Paul Leach 1084 Dilip Naik 1085 Microsoft 1086 1 Microsoft Way 1087 Redmond, WA 98052 1088 paulle@microsoft.com 1089 v-dilipn@microsoft.com 1091 9. Remote Administration Protocol overview 1092 The Remote Administration Protocol (RAP) is similar to an RPC protocol, 1093 in that: 1094 . it is an at-most-once synchronous request-response protocol 1095 . it is a framework that can be used for remotely requesting many 1096 different kinds of services 1097 . it is designed to allow (but not require) the programming interface 1098 to the protocol to be that of remotely executed procedure calls _ 1099 which means that one thinks if the protocol in terms of marshaling 1100 and unmarshaling procedure call input and output arguments into 1101 messages and reliably transporting the messages to and from the 1102 client and server 1103 Each RAP request is characterized by a set of ASCII descriptor strings 1104 that are sufficient to be used to interpretively drive the marshaling 1105 CIFS Printing Specification 1107 and unmarshaling process, if an implementation wanted to use them for 1108 that purpose. These descriptor strings are included in each request 1109 packet, and make the requests self-describing. 1111 RAP is layered on the CIFS Transact2 SMB, which provides reliable 1112 message delivery, security, and messages larger than the underlying 1113 network maximum packet size. When used for RAP, the name field in the 1114 Transact2 SMB is always set to "\PIPE\LANMAN". The Transact2 SMB is sent 1115 on a session/connection that is established to the remote server using a 1116 SessionSetupAndX SMB, and using a TID obtained by doing a 1117 TreeConnectAndX SMB to a share named "IPC$". 1119 [Refer to the CIFS specification for complete details on SMBs in 1120 general, and the Transact2 SMB in particular. For convenience, relevant 1121 portions from the CIFS specification have been reproduced here in 1122 Appendix A. Note that the CIFS specification should be considered the 1123 authoritative source of information, rather than Appendix A as far as 1124 details on the Transact2 SMB are concerned.] 1126 The model of a RAP service is that there are a few parameters as inputs 1127 and outputs to the service, exactly one of which may be a buffer 1128 descriptor that indicates the presence of a potentially much larger 1129 input or output data buffer. An argument may be a scalar, pointer, fixed 1130 length small array or struct, or a buffer descriptor. The data buffer 1131 consists of entries followed by a heap. An entry consists of a primary 1132 data struct and a sequence of 0 or more auxiliary data structs. An 1133 input buffer must contain exactly one entry; an output buffer may 1134 contain 0 or more. The heap is where data is stored that is referenced 1135 by pointers in the entries. The parameters are described by a parameter 1136 descriptor string; the primary data struct by a data descriptor string; 1137 and the auxiliary data structs by an auxiliary data descriptor string. 1139 10. Appendix A - Remote Administration Protocol 1140 A RAP service request is sent to the server encapsulated in a Transact2 1141 request SMB and the server sends back a Transact2 SMB response. An 1142 attribute of the Transact2 SMB is that it divides the payload of request 1143 and response messages into two sections: a parameters section and a data 1144 section. As might be expected from the nomenclature, RAP service 1145 parameters are sent in the parameters section of a Transact2 SMB, and 1146 the data buffer in the data section. Therefore, to define a service 1147 protocol, it is necessary to define the formats of the parameter and 1148 data sections of the Transact2 request and response. 1150 This is done in two stages. First, a C-like declaration notation is used 1151 to define descriptor strings, and then the descriptor strings define the 1152 formats of the parameter and data sections.. Note well: even though the 1153 declarations may look like a programming interface, they are not: they 1154 are a notation for describing the contents of RAP requests and 1155 responses; an implementation on any particular system can use any 1156 programming interface to RAP services that is appropriate to that 1157 system. 1159 CIFS Printing Specification 1161 10.1 Notation 1162 Parameter descriptor strings are defined using a C-like function 1163 declaration; data descriptor and auxiliary data descriptor strings are 1164 defined using a C-like structure declaration. 1166 Parameter descriptor strings are defined with the following C-like 1167 function declaration syntax: 1168 rap-service = "unsigned short" service-name "(" parameters ");" 1169 service-name = 1170 The return type of the function is always "unsigned short", and 1171 represents the status code from the function. The service-name is for 1172 documentation purposes. 1173 parameters = parameter [ ";" parameter ] 1174 The parameter descriptor string for the service is the concatenation of 1175 the descriptor characters for the parameters. 1176 parameter = [ "const" ] param-data-type parameter-name 1177 [ "[" size "]" ] 1178 param-data-type = 1179 parameter-name = 1180 size = 1181 The descriptor character for a parameter is determined by looking up the 1182 data-type in the tables below for request or response parameter 1183 descriptors. The parameter-name is for documentation purposes. If there 1184 is a size following the parameter-name, then it is placed in the 1185 descriptor string following the descriptor character. 1187 Data and auxiliary data descriptor strings are defined with the 1188 following C-like structure declaration syntax: 1189 rap-struct = "struct" struct-name "{" members "}" 1190 The descriptor string for the struct is the concatenation of the 1191 descriptor characters for the members. The struct-name is for 1192 documentation purposes. 1193 members = member [ ";" member ] 1194 member = member-data-type member-name [ "[" size "]" ] 1195 member-data-type = 1196 The descriptor character for a member is determined by looking up the 1197 data-type in the tables below for data descriptors. The member-name is 1198 for documentation purposes. If there is a size following the member- 1199 name, then it is placed in the descriptor string following the 1200 descriptor character. 1202 10.2 Descriptors 1203 The following section contain tables that specify the descriptor 1204 character and the notation for each data type for that data type. 1206 10.2.1 Request Parameter Descriptors 1208 Descriptor Data Type Format 1209 ========== ========= ===== 1210 W unsigned short indicates parameter type of 16 bit integer 1211 (word). 1212 D unsigned long indicates parameter type of 32 bit integer 1213 (dword). 1215 CIFS Printing Specification 1217 b BYTE indicates bytes (octets). May be followed 1218 by an ASCII number indicating number of 1219 bytes.. 1220 O NULL indicates a NULL pointer 1221 z char indicates a NULL terminated ASCII string 1222 present in the parameter area 1223 F PAD indicates Pad bytes (octets). May be 1224 followed by an ASCII number indicating the 1225 number of bytes 1226 r RCVBUF pointer to receive data buffer in response 1227 parameter section 1228 L RCVBUFLEN 16 bit integer containing length of 1229 receive data buffer in (16 bit) words 1230 s SNDBUF pointer to send data buffer in request 1231 parameter section 1232 T SNDBUFLEN 16 bit integer containing length of send 1233 data buffer in words 1235 10.2.2 Response Parameter Descriptors 1237 Descriptor Data Type Format 1238 ========== ========= ===== 1239 g BYTE * indicates a byte is to be received. May 1240 be followed by an ASCII number indicating 1241 number of bytes to receive 1242 h unsigned short * indicates a word is to be received 1243 i unsigned long * indicates a dword is to be received 1244 e ENTCOUNT indicates a word is to be received which 1245 indicates the number of entries returned 1247 10.2.3 Data Descriptors 1249 Descriptor Data Type Format 1250 ========== ========= ===== 1251 W unsigned short indicates data type of 16 bit integer 1252 (word). Descriptor char may be followed by 1253 an ASCII number indicating the number of 1254 16 bit words present 1255 D unsigned long indicates data type of 32 bit integer 1256 (dword). Descriptor char may be followed 1257 by an ASCII number indicating the number 1258 of 32 bit words present 1259 B BYTE indicates item of data type 8 bit byte 1260 (octet). The indicated number of bytes are 1261 present in the data. Descriptor char may 1262 be followed by an ASCII number indicating 1263 the number of 8 bit bytes present 1264 O NULL indicates a NULL pointer 1265 z char * indicates a 32 bit pointer to a NULL 1266 terminated ASCII string is present in the 1267 CIFS Printing Specification 1269 response parameter area. The actual string 1270 is in the response data area and the 1271 pointer in the parameter area points to 1272 the string in the data area. The high word 1273 of the pointer should be ignored. The 1274 converter word present in the response 1275 parameter section should be subtracted 1276 from the low 16 bit value to obtain an 1277 offset into the data area indicating where 1278 the data area resides. 1279 N AUXCOUNT indicates number of auxiliary data 1280 structures. The transaction response data 1281 section contains an unsigned 16 bit number 1282 corresponding to this data item. 1284 10.3 Transaction Request Parameters section 1285 The parameters and data being sent and received are described by ASCII 1286 descriptor strings. These descriptor strings are described in section 1287 4.2. 1289 The parameters section of the Transact2 SMB request contains the 1290 following (in the order described) 1291 . The function number: an unsigned short 16 bit integer identifying the 1292 function being remoted 1293 . The parameter descriptor string: a null terminated ASCII string 1294 . The data descriptor string: a null terminated ASCII string. 1295 . The request parameters, as described by the parameter descriptor 1296 string, in the order that the request parameter descriptor characters 1297 appear in the parameter descriptor string 1298 . An optional auxiliary data descriptor string: a null terminated ASCII 1299 string. It will be present if there is an auxiliary data structure 1300 count in the primary data struct (an "N" descriptor in the data 1301 descriptor string). 1303 RAP requires that the length of the return parameters be less than or 1304 equal to the length of the parameters being sent; this requirement is 1305 made to simply buffer management in implementations. This is reasonable 1306 as the functions were designed to return data in the data section and 1307 use the return parameters for items like data length, handles, etc. If 1308 need be, this restriction can be circumvented by filling in some pad 1309 bytes into the parameters being sent. 1311 10.4 Transaction Request Data section 1312 The Data section for the transaction request is present if the parameter 1313 description string contains an "s" (SENDBUF) descriptor. If present, it 1314 contains: 1315 . A primary data struct, as described by the data descriptor string 1316 . Zero or more instances of the auxiliary data struct, as described by 1317 the auxiliary data descriptor string. The number of instances is 1318 determined by the value of the an auxiliary data structure count 1319 member of the primary data struct, indicated by the "N" (AUXCOUNT) 1320 descriptor. The auxiliary data is present only if the auxiliary data 1321 descriptor string is non null. 1323 CIFS Printing Specification 1325 . Possibly some pad bytes 1326 . The heap: the data referenced by pointers in the primary and 1327 auxiliary data structs. 1329 10.5 Transaction Response Parameters section 1330 The response sent by the server contains a parameter section which 1331 consists of: 1332 . A 16 bit integer indicating the status or return code. The possible 1333 values for different functions are different. 1334 . A 16 bit converter word, used adjust pointers to information in the 1335 response data section. Pointers returned within the response buffer 1336 are 32 bit pointers. The high order 16 bit word should be ignored. 1337 The converter word needs to be subtracted from the low order 16 bit 1338 word to arrive at an offset into the response buffer. 1339 . The response parameters, as described by the parameter descriptor 1340 string, in the order that the response parameter descriptor 1341 characters appear in the parameter descriptor string. 1343 10.6 Transaction Response Data section 1344 The Data section for the transaction response is present if the 1345 parameter description string contains an "r" (RCVBUF) descriptor. If 1346 present, it contains: 1347 . Zero or more entries. The number of entries is determined by the 1348 value of the entry count parameter, indicated by the "e"(ENTCOUNT) 1349 descriptor. Each entry contains: 1350 . A primary data struct, as described by the data descriptor 1351 string 1352 . Zero or more instances of the auxiliary data struct, as 1353 described by the auxiliary data descriptor string. The number 1354 of instances is determined by the value of the AUXCOUNT 1355 member of the primary data struct (whose descriptor is "N"). 1356 The auxiliary data is present only if the auxiliary data 1357 descriptor string is non null. 1358 . Possibly some pad bytes 1359 . The heap: the data referenced by pointers in the primary and 1360 auxiliary data structs. 1362 11. Appendix B 1363 Transaction SMBs 1365 These SMBs are used both to retrieve bulk data from the server (e.g.: 1366 enumerate shares, etc.) and to change the server's state (EG: add a new 1367 share, change file permissions, etc.) Transaction requests are also 1368 unusual because they can have a multiple part request and/or a multiple 1369 part response. For this reason, transactions are handled as a set of 1370 sequenced commands to the server. Each part of a request is sent as a 1371 sequenced command using the same Mid value and an increasing Seq value. 1372 The server responds to each request piece except the last one with a 1373 response indicating that the server is ready for the next piece. The 1374 last piece is responded to with the first piece of the result data. The 1375 client then sends a transaction secondary SMB with ParameterDisplacement 1376 set to the number of parameter bytes received so far and 1377 DataDisplacement set to the number of data bytes received so far and 1378 ParameterCount, ParameterOffset, DataCount, and DataOffset set to zero 1379 CIFS Printing Specification 1381 (0). The server responds with the next piece of the transaction result. 1382 The process is repeated until all of the response information has been 1383 received. When the transaction has been completed, the redirector must 1384 send another sequenced command (an echo SMB will do fine) to the server 1385 to allow the server to know that the final piece was received and that 1386 resources allocated to the transaction command may be released. 1387 The flow is as follows, where (S) is the SequenceNumber, (N) is the 1388 number of request packets to be sent from the client to the server, and 1389 (M) is the number of response packets to be sent by the server to the 1390 client: 1392 Client <-> Server 1393 ======================= === =========================== 1395 SMB(S) Transact -> 1396 <- OK (S) send more data 1397 [ repeat N-1 times: 1398 SMB(S+1) Transact -> 1399 secondary 1400 <- OK (S+1) send more data 1401 SMB(S+N-1) 1402 ] 1403 <- OK (S+N-1) transaction 1404 response (1) 1405 [ repeat M-1 times: 1406 SMB(S+N) Transact -> 1407 secondary 1408 <- OK (S+N) transaction 1409 response (2) 1410 SMB(S+N+M-2) Transact -> 1411 secondary 1412 <- OK (S+N+M-2] transaction 1413 response (M) 1414 ] 1415 SMB(S+N+M-1) Echo -> 1416 <- OK (S+N+M-1) echoed 1418 In order to allow the server to detect clients which have been powered 1419 off, have crashed, etc., the client must send commands to the server 1420 periodically if it has resources open on the server. If nothing has 1421 been received from a client for awhile, the server will assume that the 1422 client is no longer running and disconnect the client. This includes 1423 closing any files that the client had open at the time and releasing any 1424 resources being used on behalf of the client. Clients should at least 1425 send an echo SMB to the server every four (4) minutes if there is 1426 nothing else to send. The server will disconnect clients after a 1427 configurable amount of time which cannot be less than five (5) minutes. 1428 (Note: the NT server has a default timeout value of 15 minutes.) 1429 CIFS Printing Specification 1431 11.1.1 TRANSACTIONS 1433 SMB_COM_TRANSACTION performs a symbolically named transaction. This 1434 transaction is known only by a name (no file handle used). 1435 SMB_COM_TRANSACTION2 likewise performs a transaction, but a word 1436 parameter is used to identify the transaction instead of a name. 1437 SMB_COM_NT_TRANSACTION is used for commands that potentially need to 1438 transfer a large amount of data (greater than 64K bytes). 1440 11.1.1.1 SMB_COM_TRANSACTION AND SMB_COM_TRANSACTION2 FORMATS 1442 Primary Client Request Description 1443 =============================== ==================================== 1445 Command SMB_COM_TRANSACTION or 1446 SMB_COM_TRANSACTION2 1448 UCHAR WordCount; Count of parameter words; value = 1449 (14 + SetupCount) 1450 USHORT TotalParameterCount; Total parameter bytes being sent 1451 USHORT TotalDataCount; Total data bytes being sent 1452 USHORT MaxParameterCount; Max parameter bytes to return 1453 USHORT MaxDataCount; Max data bytes to return 1454 UCHAR MaxSetupCount; Max setup words to return 1455 UCHAR Reserved; 1456 USHORT Flags; Additional information: 1457 bit 0 - also disconnect TID in TID 1458 bit 1 - one-way transaction (no 1459 resp) 1460 ULONG Timeout; 1461 USHORT Reserved2; 1462 USHORT ParameterCount; Parameter bytes sent this buffer 1463 USHORT ParameterOffset; Offset (from header start) to 1464 Parameters 1465 USHORT DataCount; Data bytes sent this buffer 1466 USHORT DataOffset; Offset (from header start) to data 1467 UCHAR SetupCount; Count of setup words 1468 UCHAR Reserved3; Reserved (pad above to word) 1469 USHORT Setup[SetupCount]; Setup words (# = SetupWordCount) 1470 USHORT ByteCount; Count of data bytes 1471 STRING Name[]; Name of transaction (NULL if 1472 SMB_COM_TRANSACTION2) 1473 UCHAR Pad[]; Pad to SHORT or LONG 1474 UCHAR Parameters[ Parameter bytes (# = ParameterCount) 1475 ParameterCount]; 1476 UCHAR Pad1[]; Pad to SHORT or LONG 1477 UCHAR Data[ DataCount ]; Data bytes (# = DataCount) 1478 CIFS Printing Specification 1480 Interim Server Response Description 1481 =============================== ==================================== 1483 UCHAR WordCount; Count of parameter words = 0 1484 USHORT ByteCount; Count of data bytes = 0 1486 Secondary Client Request Description 1487 =============================== ==================================== 1489 Command SMB_COM_TRANSACTION_SECONDARY 1491 UCHAR WordCount; Count of parameter words = 8 1492 USHORT TotalParameterCount; Total parameter bytes being sent 1493 USHORT TotalDataCount; Total data bytes being sent 1494 USHORT ParameterCount; Parameter bytes sent this buffer 1495 USHORT ParameterOffset; Offset (from header start) to 1496 Parameters 1497 USHORT ParameterDisplacement; Displacement of these Parameter 1498 bytes 1499 USHORT DataCount; Data bytes sent this buffer 1500 USHORT DataOffset; Offset (from header start) to data 1501 USHORT DataDisplacement; Displacement of these data bytes 1502 USHORT Fid; FID for handle based requests, else 1503 0xFFFF. This field is present only 1504 if this is an SMB_COM_TRANSACTION2 1505 request. 1506 USHORT ByteCount; Count of data bytes 1507 UCHAR Pad[]; Pad to SHORT or LONG 1508 UCHAR Parameter bytes (# = ParameterCount) 1509 Parameters[ParameterCount]; 1510 UCHAR Pad1[]; Pad to SHORT or LONG 1511 UCHAR Data[DataCount]; Data bytes (# = DataCount) 1512 CIFS Printing Specification 1514 Server Response Description 1515 =============================== ==================================== 1517 UCHAR WordCount; Count of data bytes; value = 10 + 1518 SETUPCOUNT 1519 USHORT TotalParameterCount; Total parameter bytes being sent 1520 USHORT TotalDataCount; Total data bytes being sent 1521 USHORT Reserved; 1522 USHORT ParameterCount; Parameter bytes sent this buffer 1523 USHORT ParameterOffset; Offset (from header start) to 1524 Parameters 1525 USHORT ParameterDisplacement; Displacement of these Parameter 1526 bytes 1527 USHORT DataCount; Data bytes sent this buffer 1528 USHORT DataOffset; Offset (from header start) to data 1529 USHORT DataDisplacement; Displacement of these data bytes 1530 UCHAR SetupCount; Count of setup words 1531 UCHAR Reserved2; Reserved (pad above to word) 1532 USHORT Setup[SetupWordCount]; Setup words (# = SetupWordCount) 1533 USHORT ByteCount; Count of data bytes 1534 UCHAR Pad[]; Pad to SHORT or LONG 1535 UCHAR Parameter bytes (# = ParameterCount) 1536 Parameters[ParameterCount]; 1537 UCHAR Pad1[]; Pad to SHORT or LONG 1538 UCHAR Data[DataCount]; Data bytes (# = DataCount)