220.127.116.11.5 RpcRouterRefreshPrinterChangeNotification (Opnum 67)
RpcRouterRefreshPrinterChangeNotification returns change notification information.<439>
DWORD RpcRouterRefreshPrinterChangeNotification( [in] PRINTER_HANDLE hPrinter, [in] DWORD dwColor, [in, unique] RPC_V2_NOTIFY_OPTIONS* pOptions, [out] RPC_V2_NOTIFY_INFO** ppInfo );
hPrinter: A handle to a printer object or server object that was opened by RpcAddPrinter (section 18.104.22.168.3), RpcAddPrinterEx (section 22.214.171.124.15), RpcOpenPrinter (section 126.96.36.199.2), or RpcOpenPrinterEx (section 188.8.131.52.14).
This handle MUST have been previously used successfully by the client in a call to RpcRemoteFindFirstPrinterChangeNotification (section 184.108.40.206.3) or RpcRemoteFindFirstPrinterChangeNotificationEx (section 220.127.116.11.4), and it MUST NOT have been closed by calling RpcFindClosePrinterChangeNotification (section 18.104.22.168.2).
pOptions: A pointer to an RPC_V2_NOTIFY_OPTIONS (section 22.214.171.124.1) structure that specifies printer or job members that the client listens to for notifications. For lists of members that can be monitored, see Printer Notification Values (section 126.96.36.199) and Job Notification Values (section 188.8.131.52).
ppInfo: A pointer to a variable that receives a pointer to an RPC_V2_NOTIFY_INFO (section 184.108.40.206.3) structure that contains notification information.
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 the validation steps that are specified in PRINTER_HANDLE Parameters (section 220.127.116.11.11). This method SHOULD assume that the handle to the printer or server object can be used without further access checks.
Verify that the client is in the list of notification clients for the printer object or server object.
Verify that a notification back channel to the client has been established and is still open.
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:
Collect all the notification data requested for the printer objects.
Allocate a buffer and write the collected notification data in the buffer.
Associate the buffer with ppInfo output parameter.
Return the status of the operation.
This method MUST be called when the client receives an RPC_V2_NOTIFY_INFO structure with the PRINTER_NOTIFY_INFO_DISCARDED bit set in its Flags member. This indicates that an overflow or other error has occurred and that notifications might have been lost, which sets the notification object to the discarded state. The server MUST NOT send any additional notifications until the client makes this method call. If the operation is successful, the server MUST modify the notification object to clear the discarded state.