3.1.4.2.15 RpcAddPrinterEx (Opnum 70)

  • Article

RpcAddPrinterEx installs a printer on the print server.<275>

 DWORD RpcAddPrinterEx(
   [in, string, unique] STRING_HANDLE pName,
   [in] PRINTER_CONTAINER* pPrinterContainer,
   [in] DEVMODE_CONTAINER* pDevModeContainer,
   [in] SECURITY_CONTAINER* pSecurityContainer,
   [in] SPLCLIENT_CONTAINER* pClientInfo,
   [out] PRINTER_HANDLE* pHandle
 );

pName: A parameter specified in Print Server Name Parameters (section 3.1.4.1.4).

pPrinterContainer: A parameter specified in PRINTER_CONTAINER Parameters (section 3.1.4.1.8.6). The Level member of the PRINTER_CONTAINER MUST be 0x00000001 or 0x00000002.

pDevModeContainer: A parameter specified in DEVMODE_CONTAINER Parameters (section 3.1.4.1.8.1).

pSecurityContainer: A parameter specified in SECURITY_CONTAINER Parameters (section 3.1.4.1.8.7).

pClientInfo: A parameter specified in SPLCLIENT_CONTAINER Parameters (section 3.1.4.1.8.8).

pHandle: A pointer to a variable that MUST receive the printer remote procedure call (RPC) context handle to the printer object added. RPC context handles are specified in [C706].

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:

  • Perform the validation steps specified in Print Server Name Parameters.

  • Perform the validation steps specified in PRINTER_CONTAINER Parameters.

  • Perform the validation steps specified in DEVMODE_CONTAINER Parameters.

  • Perform the validation steps specified in SECURITY_CONTAINER Parameters.

  • Perform the validation steps specified in SPLCLIENT_CONTAINER Parameters.

  • If the value of the Level member of the PRINTER_CONTAINER that is pointed to by the pPrinterContainer parameter is 0x00000002:

    • Verify that the printer driver specified in the PRINTER_INFO that is pointed to by the pointer member of the PRINTER_CONTAINER pointed to by the pPrinterContainer parameter already exists in the system; if that verification fails, return ERROR_UNKNOWN_PRINTER_DRIVER [MS-ERREF].

    • Verify that the port specified in the PRINTER_INFO that is pointed to by the pointer member of the PRINTER_CONTAINER pointed to by the pPrinterContainer parameter already exists in the system; if that verification fails, return ERROR_UNKNOWN_PORT [MS-ERREF].

    • Verify that the print processor specified in the PRINTER_INFO that is pointed to by the pointer member of the PRINTER_CONTAINER pointed to by the pPrinterContainer parameter already exists in the system; if that verification fails, return ERROR_UNKNOWN_PRINTPROCESSOR [MS-ERREF].

    • Verify that the printer with the name specified in the PRINTER_INFO that is pointed to by the pointer member of the PRINTER_CONTAINER pointed to by the pPrinterContainer parameter does not already exist in the system; if that verification fails, return ERROR_PRINTER_ALREADY_EXISTS [MS-ERREF].

  • Additional validation MAY<276> be performed.

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:

  • Perform PRINTER_CONTAINER parameter processing steps as specified in PRINTER_CONTAINER Parameters, section 3.1.4.1.8.6.

  • If the value of the Level member of the PRINTER_CONTAINER that is pointed to by the pPrinterContainer parameter is 0x00000001, and if the server does not maintain a "List of Known Printers", the server MUST return ERROR_PRINTER_ALREADY_EXISTS [MS-ERREF]. Otherwise, the server MUST continue to process the message and compose a response to the client as follows:

    • If the PRINTER_ATTRIBUTE_SHARED bit is set in the Flags member of the PRINTER_INFO structure pointed to by the pPrinterInfo1 member of the PRINTER_CONTAINER that is pointed to by the pPrinterContainer parameter, add the printer to the "List of Known Printers" as specified in Abstract Data Model (section 3.1.1).<277>

    • If PRINTER_ATTRIBUTE_SHARED is not set in the Flags member of the PRINTER_INFO structure pointed to by the pPrinterInfo1 member of the PRINTER_CONTAINER that is pointed to by the pPrinterContainer parameter, remove the printer from the "List of Known Printers".

    • Store NULL in the output parameter that is pointed to by pHandle.

    • Return ERROR_PRINTER_ALREADY_EXISTS [MS-ERREF].

    Note: An error return code is required by remote procedure call (RPC) because NULL was stored to the output parameter pointed to by pHandle.

  • If the value of the Level member of the PRINTER_CONTAINER that is pointed to by the pPrinterContainer parameter is 0x00000002:

    • Instead of failing the validation steps for missing printer driver, port, and print processor, the server MAY create the required printer driver, port, and print processor if they do not exist in the system.<278>

    • Create the printer object and assign to it the security descriptor from the SECURITY_CONTAINER that is pointed to by the pSecurityContainer parameter.

    • Add the printer to the "List of Printers" specified in section 3.1.1).

    • Create a session that includes:

      • An RPC handle.

      • A snapshot of the printer data specific to this instance of the printer invocation.

      • The data from DEVMODE that is contained in the DEVMODE_CONTAINER pointed to by the pDevModeContainer parameter if it is not NULL.

      • The data from the SPLCLIENT_CONTAINER that is pointed to by the pClientInfo parameter if it is not NULL.

    • Store the RPC handle for the session in the output parameter pHandle. The handle returned from this method MUST be granted PRINTER_ALL_ACCESS permission.

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

    • If any clients are registered for notifications of the server object change, a notification MUST be broadcast to them.

  • Return the status of the operation.