3.1.4.10.1 RpcWaitForPrinterChange (Opnum 28)

  • Article

RpcWaitForPrinterChange retrieves information about the most recent change notification that is associated with a printer or print server.

 DWORD RpcWaitForPrinterChange(
   [in] PRINTER_HANDLE hPrinter,
   [in] DWORD Flags,
   [out] DWORD* pFlags
 );

hPrinter: A handle to a printer object or server object that was opened by RpcAddPrinter (section 3.1.4.2.3), RpcAddPrinterEx (section 3.1.4.2.15), RpcOpenPrinter (section 3.1.4.2.2), or RpcOpenPrinterEx (section 3.1.4.2.14).

Flags: The change notifications to wait for. The value of this parameter is a bitwise OR of one or more printer change values, defined in sections 2.2.3.6.1 and 2.2.3.6.2. For rules governing printer change values, see section 2.2.4.13.

pFlags: A pointer to a variable that receives the bitwise OR combination of one or more printer change values.

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_HANDLE Parameters, section 3.1.4.1.11. This method SHOULD assume that the handle to the printer or server object can be used without further access checks.

If parameter validation fails, the server MUST fail the operation immediately, returning 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 client and the requested change notifications to the list of notification clients for the printer or server object.

  • Wait for an implementation-specific period of time,<379> or until one of the changes specified by the value of the Flags parameter occurs.

  • Remove the client from the list of notification clients for the printer or server object.

  • If the hPrinter handle is closed with RpcClosePrinter (section 3.1.4.2.9) during this wait period, return ERROR_INVALID_HANDLE.

  • If one or more of the specified changes occurred within the time-out period, write a bitwise OR combination of the changes to the variable that is pointed to by pFlags and return zero.

  • If the time-out period has expired without any of the specified changes, return PRINTER_CHANGE_TIMEOUT [MS-ERREF].

Note: Because this method waits for an implementation-specific, potentially long, period of time, it can cause the client system to stop responding. Therefore, this method is deprecated and SHOULD NOT be used. The implementer of a protocol client SHOULD consider using RpcRemoteFindFirstPrinterChangeNotificationEx instead.