3.1.4.2.14 RpcOpenPrinterEx (Opnum 69)

  • Article

RpcOpenPrinterEx retrieves a handle for a printer, port, port monitor, print job, or print server.<287>

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

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). For rules governing access values, see section 2.2.4.1.

If no specific access level is requested, the server MUST assume a generic read access level.

pClientInfo: A pointer to a SPLCLIENT_CONTAINER (section 2.2.1.2.14) structure. This parameter MUST adhere to the specification in SPLCLIENT_CONTAINER Parameters (section 3.1.4.1.8.8).

The value of the Level member of the container that is pointed to by pClientInfo MUST be 0x00000001.

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.

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

  • Perform the validation steps that are specified in SPLCLIENT_CONTAINER Parameters (section 3.1.4.1.8.8).

  • Verify that the client issuing the call has authorization equivalent to the value of the AccessRequired parameter. If verification fails, return ERROR_ACCESS_DENIED.

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 correspond 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"; or

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

    • 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:

    • An 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 are not NULL.

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

    • The data from pClientInfo, if it is not NULL.

  • Increment the object's reference count to prevent deletion.

  • Store the RPC handle for the session in the output parameter pHandle.

  • Return the status of the operation.