3.1.4 Message Processing Events and Sequencing Rules
An implementation of the Print System Asynchronous Remote Protocol MUST indicate the following to the remote procedure call (RPC) runtime ([MS-RPCE] section 3).
Perform a strict NDR data consistency check at target level 6.0.
Reject a NULL unique or full pointer with nonzero conformant value.
Using the strict_context_handle attribute ([MS-RPCE] section 2.2.4.15), reject the use of context handles that are created by the methods of a different RPC interface.
The methods that are defined by this protocol are grouped into functional categories, and their syntax and behavior are specified in sections, as shown in the following table. Most methods described in these sections have functional equivalents in the Print System Remote Protocol ([MS-RPRN] section 3.1.4).
|
Functional category |
Description |
Section |
|---|---|---|
|
Printer management |
Methods used for discovering and obtaining access to supported printers. |
|
|
Printer driver management |
Methods for discovering and installing printer drivers. |
|
|
Printer port management |
Methods for discovering and communicating with printer ports. |
|
|
Print-processor management |
Methods for discovering and manipulating print-processor objects. |
|
|
Port monitor management |
Methods for discovering and installation of port monitor modules. |
|
|
Form management |
Methods for discovering and configuring printer forms. |
|
|
Job management |
Methods for discovering, defining, and scheduling print jobs. |
|
|
Job printing |
Methods for adding documents, pages, and data to print jobs. |
|
|
Printing-related notifications |
Methods for obtaining notifications of printing events. |
|
|
Job named property management |
Methods for creating, updating, deleting, and enumerating Job Named Properties (section 3.1.1).<9> |
|
|
Methods for processing Branch Office Print Remote Log Entries (section 3.1.1).<10> |
The following table lists all the methods of the Print System Asynchronous Remote Protocol in ascending order of their opnums.
Methods in RPC opnum order:
|
Method |
Description |
|---|---|
|
RpcAsyncOpenPrinter retrieves a handle to a specified printer, port, print job or print server. A client uses this method to obtain a print handle to an existing printer on a remote computer. The counterpart of this method in the Print System Remote Protocol is RpcOpenPrinterEx. All parameters not defined below are specified in [MS-RPRN] section 3.1.4.2.14. Opnum: 0 |
|
|
RpcAsyncAddPrinter installs a printer on the print server. The counterpart of this method in the Print System Remote Protocol is RpcAddPrinterEx. All parameters not defined below are specified in [MS-RPRN] section 3.1.4.2.15. Opnum: 1 |
|
|
RpcAsyncSetJob pauses, resumes, cancels, or restarts a print job on a specified printer. This method also can set print job parameters, including the job priority and document name. Opnum: 2 |
|
|
RpcAsyncGetJob retrieves information about a specified print job on a specified printer. Opnum: 3 |
|
|
RpcAsyncEnumJobs retrieves information about a specified set of print jobs on a specified printer. Opnum: 4 |
|
|
RpcAsyncAddJob returns ERROR_INVALID_PARAMETER. Opnum: 5 |
|
|
RpcAsyncScheduleJob returns ERROR_SPL_NO_ADDJOB. Opnum: 6 |
|
|
RpcAsyncDeletePrinter deletes the specified printer object. The client MUST call RpcAsyncClosePrinter (section 3.1.4.1.10) with the same PRINTER_HANDLE after calling this method. Opnum: 7 |
|
|
RpcAsyncSetPrinter sets the state of a specified printer. Opnum: 8 |
|
|
RpcAsyncGetPrinter retrieves information about a specified printer. Opnum: 9 |
|
|
RpcAsyncStartDocPrinter notifies a specified printer that a document is being spooled for printing. Opnum: 10 |
|
|
RpcAsyncStartPagePrinter notifies a specified printer that a page is about to be printed. Opnum: 11 |
|
|
RpcAsyncWritePrinter adds data to the file representing the spool file for a specified printer, if the spooling option is turned on; or it sends data to the device directly, if the printer is configured for direct printing. Opnum: 12 |
|
|
RpcAsyncEndPagePrinter notifies a specified printer that the application is at the end of a page in a print job. Opnum: 13 |
|
|
RpcAsyncEndDocPrinter signals the completion of the current print job on a specified printer. Opnum: 14 |
|
|
RpcAsyncAbortPrinter aborts the current document on a specified printer. Opnum: 15 |
|
|
RpcAsyncGetPrinterData retrieves configuration data from a specified printer or print server. Opnum: 16 |
|
|
RpcAsyncGetPrinterDataEx retrieves configuration data for the specified printer or print server. This method extends RpcAsyncGetPrinterData (section 3.1.4.1.6) and can retrieve values stored under a specified key by RpcAsyncSetPrinterDataEx (section 3.1.4.1.9). Opnum: 17 |
|
|
RpcAsyncSetPrinterData sets the configuration data for a printer or print server. Opnum: 18 |
|
|
RpcAsyncSetPrinterDataEx |
RpcAsyncSetPrinterDataEx sets the configuration data for a printer or print server. This method is similar to RpcAsyncSetPrinterData (section 3.1.4.1.8) but also allows the caller to specify the registry key under which to store the data. Opnum: 19 |
|
RpcAsyncClosePrinter |
RpcAsyncClosePrinter closes a handle to a printer object, server object, job object, or port object, which is opened by calling RpcAsyncOpenPrinter (section 3.1.4.1.1) or RpcAsyncAddPrinter (section 3.1.4.1.2). Opnum: 20 |
|
RpcAsyncAddForm adds a form name to the list of supported forms. Opnum: 21 |
|
|
RpcAsyncDeleteForm removes a form name from the list of supported forms. Opnum: 22 |
|
|
RpcAsyncGetForm retrieves information about a specified form. Opnum: 23 |
|
|
RpcAsyncSetForm sets the form information for the specified printer. Opnum: 24 |
|
|
RpcAsyncEnumForms enumerates the forms that the specified printer supports. Opnum: 25 |
|
|
RpcAsyncGetPrinterDriver retrieves data about a specified printer driver on a specified printer. Opnum: 26 |
|
|
RpcAsyncEnumPrinterData enumerates configuration data for a specified printer. Opnum: 27 |
|
|
RpcAsyncEnumPrinterDataEx enumerates all value names and data for a specified printer and key. This method extends RpcAsyncEnumPrinterData (section 3.1.4.1.11) by retrieving several values in a single call. Opnum: 28 |
|
|
RpcAsyncEnumPrinterKey enumerates the subkeys of a specified key for a specified printer. Opnum: 29 |
|
|
RpcAsyncDeletePrinterData deletes a specified value from the configuration of a specified printer. Opnum: 30 |
|
|
RpcAsyncDeletePrinterDataEx deletes a specified value from the configuration of a specified printer. This method is similar to RpcAsyncDeletePrinterData (section 3.1.4.1.14) but accesses the configuration data using a set of named and typed values that are stored in a hierarchy of registry keys. Opnum: 31 |
|
|
RpcAsyncDeletePrinterKey deletes a specified key and all its subkeys from the configuration of a specified printer. Opnum: 32 |
|
|
RpcAsyncXcvData provides the means by which a port monitor client component can communicate with its server-side counterpart, the actual port monitor that is hosted by the server. Opnum: 33 |
|
|
RpcAsyncSendRecvBidiData sends and receives bidirectional data. This method is used to communicate with print monitors that support such data. Opnum: 34 |
|
|
RpcAsyncCreatePrinterIC creates an information context on a specified printer. Opnum: 35 |
|
|
RpcAsyncPlayGdiScriptOnPrinterIC queries fonts for printer connections. Opnum: 36 |
|
|
RpcAsyncDeletePrinterIC deletes a printer information context. Opnum: 37 |
|
|
RpcAsyncEnumPrinters enumerates available local printers, printers on a specified print server, printers in a specified domain, or print providers. Opnum: 38 |
|
|
RpcAsyncAddPrinterDriver installs a specified local or a remote printer driver on a specified print server, and it links the configuration, data, and driver files. Opnum: 39 |
|
|
RpcAsyncEnumPrinterDrivers enumerates the printer drivers installed on a specified print server. Opnum: 40 |
|
|
RpcAsyncGetPrinterDriverDirectory retrieves the path of the printer-driver directory on a specified print server. Opnum: 41 |
|
|
RpcAsyncDeletePrinterDriver removes the specified printer driver from the list of supported drivers for a specified print server. Opnum: 42 |
|
|
RpcAsyncDeletePrinterDriverEx removes the specified printer driver from the list of supported drivers on a specified print server, and deletes the files associated with the driver. This method is similar to RpcAsyncDeletePrinterDriver (section 3.1.4.2.5) but can also delete specific versions of the driver. Opnum: 43 |
|
|
RpcAsyncAddPrintProcessor installs a specified print processor on the specified server and adds its name to an internal list of supported print processors. Opnum: 44 |
|
|
RpcAsyncEnumPrintProcessors enumerates the print processors installed on a specified server. Opnum: 45 |
|
|
RpcAsyncGetPrintProcessorDirectory retrieves the path for the print processor on the specified server. Opnum: 46 |
|
|
RpcAsyncEnumPorts enumerates the ports that are available for printing on a specified server. Opnum: 47 |
|
|
RpcAsyncEnumMonitors retrieves information about the port monitors installed on a specified server. Opnum: 48 |
|
|
RpcAsyncAddPort adds a specified port name to the list of supported ports on a specified server. Opnum: 49 |
|
|
RpcAsyncSetPort sets the status associated with a specified port on a specified print server. Opnum: 50 |
|
|
RpcAsyncAddMonitor installs a specified local port monitor, and links the configuration, data, and monitor files on a specified print server. Opnum: 51 |
|
|
RpcAsyncDeleteMonitor removes a specified port monitor from a specified print server. Opnum: 52 |
|
|
RpcAsyncDeletePrintProcessor removes a specified print processor from a specified server. Opnum: 53 |
|
|
RpcAsyncEnumPrintProcessorDatatypes enumerates the data types that a specified print processor supports. Opnum: 54 |
|
|
RpcAsyncAddPerMachineConnection persistently saves the configuration information for a connection, including the print server name and the name of the print providers for a specified connection. Opnum: 55 |
|
|
RpcAsyncDeletePerMachineConnection deletes the stored connection configuration information that corresponds to the pPrinterName parameter value. Opnum: 56 |
|
|
RpcAsyncEnumPerMachineConnections enumerates each of the per-machine connections into a specified buffer. Opnum: 57 |
|
|
RpcSyncRegisterForRemoteNotifications opens a notification handle by using a printer handle or print server handle, to listen for remote printer change notifications. Opnum: 58 |
|
|
RpcSyncUnRegisterForRemoteNotifications closes a notification handle that is opened by calling RpcSyncRegisterForRemoteNotifications (section 3.1.4.9.1). Opnum: 59 |
|
|
RpcSyncRefreshRemoteNotifications gets notification information for all requested members. This is called by a client if the "RemoteNotifyData Flags" property in the RpcPrintPropertiesCollection (section 2.2.4) instance, which was returned as part of the notification from an RpcAsyncGetRemoteNotifications (section 3.1.4.9.4) call, has the PRINTER_NOTIFY_INFO_DISCARDED bit set ([MS-RPRN] section 2.2.3.2). Opnum: 60 |
|
|
RpcAsyncGetRemoteNotifications |
RpcAsyncGetRemoteNotifications is used to poll the print server for specified change notifications. A call to this method is suspended until the server has a new change notification for the client. Subsequently, the client calls this method again to poll for additional notifications from the server. Opnum: 61 |
|
RpcAsyncInstallPrinterDriverFromPackage installs a printer driver from a driver package. Opnum: 62 |
|
|
RpcAsyncUploadPrinterDriverPackage uploads a driver package so it can be installed with the RpcAsyncInstallPrinterDriverFromPackage method (section 3.1.4.2.7). Opnum: 63 |
|
|
RpcAsyncGetCorePrinterDrivers retrieves the globally unique identifier (GUID), the version, the date of the specified core printer drivers, and the path to their packages. Opnum: 64 |
|
|
RpcAsyncCorePrinterDriverInstalled determines if a specific core printer driver is installed. Opnum: 65 |
|
|
RpcAsyncGetPrinterDriverPackagePath gets the path to the specified printer driver package. Opnum: 66 |
|
|
RpcAsyncDeletePrinterDriverPackage deletes a specified printer driver package. Opnum: 67 |
|
|
RpcAsyncReadPrinter retrieves data from the specified job object. Opnum: 68 |
|
|
RpcAsyncResetPrinter resets the data type and device mode values to use for printing documents that are submitted by the RpcAsyncStartDocPrinter method (section 3.1.4.8.1). Opnum: 69 |
|
|
RpcAsyncGetJobNamedPropertyValue retrieves the value of the specified Job Named Property (section 3.1.1) for the specified print job. Opnum: 70 |
|
|
RpcAsyncSetJobNamedProperty creates a new Job Named Property or changes the value of an existent Job Named Property for the specified print job. Opnum: 71 |
|
|
RpcAsyncDeleteJobNamedProperty deletes a Job Named Property for the specified print job. Opnum: 72 |
|
|
RpcAsyncEnumJobNamedProperties enumerates the Job Named Properties for the specified print job. Opnum: 73 |
|
|
RpcAsyncLogJobInfoForBranchOffice processes one or more Branch Office Print Remote Log Entries (section 3.1.1) by writing them to the Microsoft-Windows-PrintService/Admin and Microsoft-Windows-PrintService/Operations event channels. Opnum: 74 |
All methods defined in this protocol are request/response RPC methods. Each method returns either an HRESULT value ([MS-ERREF] section 2.1) or a Win32 code ([MS-ERREF] section 2.2).
A non-negative HRESULT return value indicates successful completion, and a negative value indicates failure. A Win32 return value of zero indicates successful completion, and a nonzero value indicates failure, with the following exceptions.
The ERROR_MORE_DATA and ERROR_INSUFFICIENT_BUFFER Win32 codes defined in the table have specific meanings in this protocol. When a method has an output parameter that returns a required buffer size, the method can return one of these errors.
|
Name/Value |
Meaning |
|---|---|
|
ERROR_INSUFFICIENT_BUFFER 0x0000007A |
The buffer size specified in a method call is too small. |
|
ERROR_MORE_DATA 0x000000EA |
More data is available. |
The caller SHOULD NOT treat these return values as errors. The caller SHOULD use the buffer size returned by the method to resize the buffers, and it SHOULD call the method again using the resized buffers. These cases are noted in the method definitions in this section and in their corresponding definitions in [MS-RPRN] section 3.1.4.