3.1.4.2.24 RpcAddPerMachineConnection (Opnum 85)

  • Article

RpcAddPerMachineConnection adds a remote printer name to the list of supported printer connections for every user who locally logs onto the computer running the print server.<311>

This method is used for remote administration of client computers running the print system.

 DWORD RpcAddPerMachineConnection(
   [in, string, unique] STRING_HANDLE pServer,
   [in, string] const wchar_t* pPrinterName,
   [in, string] const wchar_t* pPrintServer,
   [in, string] const wchar_t* pProvider
 );

pServer: A value that adheres to the specification in Print Server Name Parameters (section 3.1.4.1.4).

pPrinterName: A value that adheres to the specification in Printer Name Parameters (section 3.1.4.1.5). A printer connection of the form:

 SERVER_NAME LOCAL_PRINTER_NAME  [with a non-empty SERVER_NAME.]

pPrintServer: A pointer to a string that specifies the name of the print server that is hosting the printer to which the connection is established. For rules governing server names, see section 2.2.4.16.

pProvider: A pointer to a string that specifies the name of a print provider. If the string is the empty string "", an implementation-specific default print provider name is used.<312> For rules governing print provider names, see section 2.2.4.12.

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 that are specified in Printer Name Parameters. Perform validations only of the correctness of the syntax of the name; do not perform existence checks for the actual printer object. The existence checks are deferred until the actual creation of the printer object upon user login, and no status feedback is possible. The administration client, therefore, is expected to pass only existing names.

  • Perform the validation steps that are specified in Print Server Name Parameters. Perform validations only of the correctness of the syntax of the name; do not perform existence checks for the actual server object. The existence checks are deferred until the actual creation of the printer object upon user login, and no status feedback is possible. The administration client, therefore, is expected to pass only existing names.

  • Verify that a per-machine printer connection with the same name does not already exist; and if that verification fails, return ERROR_PRINTER_ALREADY_EXISTS [MS-ERREF].

  • Additional validation MAY<313> 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:

  • Add the printer to the list of per-machine connections on the print server.

  • Defer creation of the actual printer object for each user until the user logs on, and then create a printer object for the printer connection to the printer specified in pPrinterName. The created printer object cannot be shared and can be used only when locally logged onto the computer.

  • Return the status of the operation.