3.1.4.2.3 RpcAddPrinter (Opnum 5)

  • Article

RpcAddPrinter adds a printer to the list of supported printers for a specified server.

 DWORD RpcAddPrinter(
   [in, string, unique] STRING_HANDLE pName,
   [in] PRINTER_CONTAINER* pPrinterContainer,
   [in] DEVMODE_CONTAINER* pDevModeContainer,
   [in] SECURITY_CONTAINER* pSecurityContainer,
   [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).

pHandle: A pointer to a variable that receives the printer 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 validation steps as specified in Print Server Name Parameters (section 3.1.4.1.4).

  • Perform validation steps as specified in PRINTER_CONTAINER Parameters (section 3.1.4.1.8.6).

  • Perform validation steps as specified in DEVMODE_CONTAINER Parameters (section 3.1.4.1.8.1).

  • Perform validation steps as specified in SECURITY_CONTAINER Parameters (section 3.1.4.1.8.7).

  • If the Level member of the PRINTER_CONTAINER 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 pPrinterContainer already exists in the system, and 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 pPrinterContainer already exists in the system, and 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 pPrinterContainer already exists in the system, and 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 pPrinterContainer does not already exist in the system, and if that verification fails, return ERROR_PRINTER_ALREADY_EXISTS [MS-ERREF].

  • Additional validation MAY<269> 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 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_1 structure, add the printer<270> to the "List of Known Printers" as specified in section 3.1.1.

    • If PRINTER_ATTRIBUTE_SHARED bit is not set in the Flags member of the PRINTER_INFO_1 structure, remove the printer from the "List of Known Printers".

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

    • Increment the number of network printers added to this server.

    • 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 Level member of the PRINTER_CONTAINER is 0x00000002:

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

    • Add the printer to the "List of Printers" (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 the DEVMODE that is contained in the DEVMODE_CONTAINER pointed to by the pDevModeContainer parameter if it is not NULL.

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

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

    • If there are any clients that are registered for notifications on the server object change, a notification MUST be sent to those clients.

  • Return the status of the operation.