3.1.4.2.2 RpcOpenPrinter (Opnum 1)

  • Article

RpcOpenPrinter retrieves a handle for a printer, port, port monitor, print job, or print server.

 DWORD RpcOpenPrinter(
   [in, string, unique] STRING_HANDLE pPrinterName,
   [out] PRINTER_HANDLE* pHandle,
   [in, string, unique] wchar_t* pDatatype,
   [in] DEVMODE_CONTAINER* pDevModeContainer,
   [in] DWORD AccessRequired
 );

pPrinterName: A STRING_HANDLE (section 2.2.1.1.7) for a printer connection, printer object, server object, job object, port object, or port monitor object. For opening a server object, this parameter MUST adhere to the specification in Print Server Name Parameters (section 3.1.4.1.4); for opening all other objects, it MUST adhere to the specification in Printer Name Parameters (section 3.1.4.1.5).

pHandle: A pointer to a PRINTER_HANDLE (section 2.2.1.1.4) that MUST receive the RPC context handle [C706] to the object identified by the pPrinterName parameter.

pDatatype: A pointer to a string that specifies the data type to be associated with the printer handle. This parameter MUST adhere to the specification in Datatype Name Parameters (section 3.1.4.1.1).

pDevModeContainer: A pointer to a DEVMODE_CONTAINER structure. This parameter MUST adhere to the specification in DEVMODE_CONTAINER Parameters (section 3.1.4.1.8.1).

AccessRequired: The access level that the client requires for interacting with the object to which a handle is being opened. The value of this parameter is one of those specified in Access Values (section 2.2.3.1) or 0. For rules governing access values, see section 2.2.4.1.

If AccessRequired is set to 0 (if no specific access level is requested), the server MUST assume a GENERIC_READ (section 2.2.3.1) access level.

Return Values: This method MUST return zero (ERROR_SUCCESS) to indicate successful completion or a nonzero Windows error code to indicate failure [MS-ERREF].

Upon receiving this message, the server MUST validate parameters as follows:

  • For opening a server object, perform the validation steps specified in Print Server Name Parameters; for opening all other objects, perform the validation steps specified in Printer Name Parameters.

  • Perform the validation steps that are specified in Datatype Name Parameters (section 3.1.4.1.1).

  • Perform the validation steps that are specified in DEVMODE_CONTAINER Parameters (section 3.1.4.1.8.1).

  • Verify that the client issuing the call has authorization equivalent to the value of the AccessRequired parameter.

If parameter validation fails, the server MUST fail the operation immediately and return a nonzero error response to the client. Otherwise, the server MUST process the message and compose a response to the client as follows:

  • Locate one of the following objects that corresponds to the request:

    • The printer in the "List of Printers", or a job queued for that printer

    • The server in the "List of Print Server Names"

    • The port monitor in the "List of Port Monitors"

    • The port in the "List of Ports".

      These lists are specified in section 3.1.1.

  • Create an implementation-specific representation of the printer, server, job, port monitor, or port ("the object") that MUST include:

    • A remote procedure call (RPC) handle, which is a snapshot of the printer, server, job, port monitor, or port data that is specific to this instance of the invocation.

    • The data from pDataType and pDevModeContainer, if they were not NULL.

    • All other relevant, implementation-specific data required to process all other protocol methods passing in a PRINTER_HANDLE.

  • Store the RPC handle for the object in the variable pointed to by pHandle.

  • Increment the reference count of the object to prevent deletion.

  • Return the status of the operation.