Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
3.1.4.2.3 RpcAddPrinter (Opnum 5)

3.1.4.2.3 RpcAddPrinter (Opnum 5)

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, as specified in [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, as specified in [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, as specified in [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, as specified in [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, as specified in [MS-ERREF].

  • Additional validation MAY<315> 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, as specified in [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<316> 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, as specified in [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.

Show:
© 2015 Microsoft