3.1 Example 1: Discovering and Utilizing a Print Queue in a Domain

This example demonstrates the use cases described in section 2.5.3.3 with extensions (a) and (c), and section 2.5.3.7.1 with extension (a).

Prior to the beginning of this example, an administrator has installed a printer on a print server and provisioned a print queue corresponding to the printer. The print server has published the name of the print queue to the directory service by using LDAP [RFC4511]. In this scenario, PSS uses LDAP to discover the available shared print queues, after which it uses the Print System Remote Protocol [MS-RPRN] and the SMB access protocols for subsequent operations.

Prerequisites

The example described in this section and subsections has the following prerequisites:

  • The print client communicates with the print server by using the Print System Remote Protocol, which includes support for the RpcGetPrinterDriverPackagePath method.<14>

  • The print queue has been provisioned and is located on a print server in a domain.

  • The print server has published a list of the shared print queues to the Active Directory system.

  • The print client is configured not to use Windows Update to obtain the printer driver. This precondition is only present to illustrate downloading a printer driver from the print server.

  • The printer driver is available from the printer server, and the print driver is enabled as package aware.<15>

  • Either the print client or the print server supports the Print System Remote Protocol but not the Print System Asynchronous Remote Protocol [MS-PAR].<16> This precondition was chosen to illustrate the fallback use of the Print System Remote Protocol.<17>

Initial System State

The example described in this section and subsections applies in the following initial system state:

  • The user of the print client does not know the name of the print server, and the print client does not yet have a list of the available print servers or print queues.

  • The print client does not have the printer driver for the print queue.

  • The print client does not have the printer driver package for the printer driver in its local driver store. This state is presented to illustrate a printer driver download from the print server.

Final System State

  • The print client obtains the list of available printers and print servers.

  • The print client has downloaded a printer driver for the print queue.

Tasks

This example is divided into four tasks:

  • Locating print queue in a domain

  • Establishing a connection, downloading a driver, and registering for notifications

  • Submitting a print job and receiving notifications

  • Unregistering from notifications

Task 1: Locating a print queue in a domain

The following diagram shows the first part of this example in which the print client locates a print queue in a domain by using LDAP.

Print client locating a print queue in a domain by using LDAP

Figure 16: Print client locating a print queue in a domain by using LDAP

The message group labeled "Locating a print queue in a domain" in the preceding diagram represents the search for a print queue in Active Directory by using the LDAP search option ([RFC4511] section 4.5 and [MS-RPRN] section 2.3.3.3).

The following steps describe task 1 of this example.

  1. The print client uses LDAP to query the LDAP server for print queues, optionally specifying criteria, such as functionality, that the print queues are required to satisfy. The print client obtains criteria from the user interface and makes several queries to obtain criteria, such as the physical location of the print client.

  2. The LDAP server returns a list of print queues by using LDAP. The print client user interface then presents the list to the user who selects a print queue.

    Task 2: Establishing a connection, downloading a driver, and registering for notifications

    The following diagram shows a print client that connects to a print queue, downloads a driver, and registers for notifications. The sequence is described in the steps that follow the diagram.

Print client connecting to a print queue, downloading a driver, and registering for notifications

Figure 17: Print client connecting to a print queue, downloading a driver, and registering for notifications

The following table shows the message groups from the preceding diagram and their purpose.

Message group

Description

References

Connecting to a printer

Obtains the print server handle and information about the specified printer.

[MS-RPRN] section 3.1.4.2

Getting printer driver information

Obtains the driver information and package path of the specified printer driver.

[MS-RPRN] section 3.1.4.4

Downloading a printer driver

Downloads a printer driver by using the SMB Version 1.0 Protocol [MS-SMB].

[MS-SMB] section 2.2 and [MS-FASOD] section 3.5

Retrieving print queue information

Obtains configuration data and form information for a print queue.

[MS-RPRN] section 3.1.4.2 and [MS-RPRN] section 3.1.4.5

Registering for notifications

Creates a remote change notification object that monitors changes to printer objects and sends change notifications to the client.

[MS-RPRN] (section 3.1.4.10

The following steps describe task 2 of this example:

  1. The print client calls the RpcOpenPrinterEx method on the print server for the designated print queue.

  2. The print server returns a handle to the print queue and a success code.

  3. The print client calls the RpcGetPrinter (*) method on the print server for the print queue handle.

  4. The print server returns the PRINTER_INFO structure with details about the print queue and a success code.

  5. The print client calls the RpcGetPrinterDriver2 (*) method on the print server for the print queue handle.

  6. The print server returns the requested DRIVER_INFO structure, which contains details about the print queue's printer driver, such as driver file name and driver version, and a success code.

  7. The print client calls the RpcGetPrinterDriverPackagePath (*) method on the print server for the print queue handle.

  8. The print server returns the path for the printer driver package CAB file and a success code.

  9. The print client downloads the printer driver by using the SMB protocol family, which uses the following operations.

    • Open File SMB ([MS-FASOD] section 3.5.1).

    • Perform File Operation SMB Query FS Information ([MS-FASOD] section 3.5.2).

    • Perform File Operation SMB Read ([MS-FASOD] section 3.5.3)

    • Perform File Operation SMB Close ([MS-FASOD] section 3.5.4).

  10. The print client extracts the printer driver files that are contained in the downloaded data file and installs the printer driver.

  11. The print client creates a connection to the print queue by creating a local print queue proxy object.

  12. The print client calls the RpcEnumPrinterKey (*) method on the print server for the designated print queue handle.

  13. The print server returns the requested printer data key and a success code.

  14. The print client calls the RpcEnumPrinterDataEx (*) method on the print server for the designated print queue handle.

  15. The print server returns the requested printer data key/value pairs and a success code.

  16. The print client calls the RpcEnumForms (*) method on the print server for the designated print queue handle.

  17. The print server returns the requested form data and a success code.

  18. The print client calls the RpcGetPrinterData (*) method on the print server for the designated print queue handle to obtain values of specific keys.

  19. The print server returns the requested data and a success code.

  20. The print client calls the print server's RpcGetPrinterDriverDirectory method.<18>

  21. The print server responds with the name of its printer driver directory and a success code.

  22. The print client mirrors the returned data on the local print queue proxy object.

  23. The print client calls the RpcRemoteFindFirstPrinterChangeNotificationEx method on the print server with a print queue handle to begin the process for registering to receive print status notifications.

  24. The print server calls the RpcReplyOpenPrinter method on the print client to establish a notification channel.

  25. The print client returns the RpcReplyOpenPrinter method call with a handle to the notification channel.

  26. The print server returns the RpcRemoteFindFirstPrinterChangeNotificationEx method call with a success code.<19>

    Task 3: Submitting a print job and receiving notifications

    The following diagram shows the print client that submits a print job to the print queue and receives notifications.

Print client submitting a print job to the print queue

Figure 18: Print client submitting a print job to the print queue

The message group labeled "Submitting a print job and receiving notifications" in the preceding diagram shows how the client receives asynchronous notification of changes on the print queue and how the client submits a print job ([MS-RPRN] sections 3.1.4.9.1, 3.1.4.9.2, 3.1.4.9.3, 3.1.4.9.4, and 3.1.4.9.7).

The following steps describe task 3 of this example:

Asynchronously on a separate thread, during each of the steps of task 3 and until the print server has finished processing the print job, the print server calls the RpcRouterReplyPrinterEx method to notify the print client of changes on the print queue, such as job processing progress, status changes, or other changes. The print client responds to each notification with a success code.

  1. The print client calls the RpcOpenPrinterEx method on the print server to open a handle to the print queue for submitting a print job, and the print server returns a success code.

  2. The print client calls the RpcStartDocPrinter method on the print server, and the print server returns a job ID and a success code.

  3. The print client calls the RpcStartPagePrinter method on the print server, and the print server responds with a success code.

  4. The print client repeatedly calls the RpcWritePrinter method on the print server, by sending successive portions of the print job. The print server responds to each call with a success code. This step is repeated until all the print data has been sent.

  5. The print client calls the RpcEndPagePrinter method on the print server, and the print server responds with a success code.

  6. When all print data has been sent, the print client calls the RpcEndDocPrinter method on the print server, and the print server responds with a success code.

  7. The print client calls the RpcClosePrinter method on the print server, and the print server returns a success code. This step only occurs if the print client does not proceed to the next portion of this example.

    Task 4: Unregistering from notifications

    The following diagram shows the print client unregistering from notifications.

Print client unregistering from notifications

Figure 19: Print client unregistering from notifications

Message group

Description

References

Unregistering from notifications

The print client unregisters from notifications of changes to the print queue.

[MS-RPRN] section 3.1.4.10.2

Disconnecting from a print queue

The print client closes the handle to the printer object.

[MS-RPRN] section 3.1.4.2.9

The following steps describe task 4 of this example:

  1. When a print client has no further use for notifications, for example, when the user closes the print queue dialog user interface, the print client calls the RpcFindClosePrinterChangeNotification method on the print server.

  2. The print server calls the RpcReplyClosePrinter method on the print client, and the print client returns a success code.

  3. The print server responds to the RpcFindClosePrinterChangeNotification method with a success code.

  4. The print client calls the RpcClosePrinter method on the print server by using the handle to the print queue that was specified during registration, and the print server returns a success code.

It is common for clients to listen for notifications from more than one thread. Therefore, the sequence of steps for registration for notifications, from task 2, and unregistration, from task 3, can be observed on the network multiple times.