Share via

3.1.4.10.5 RpcRouterRefreshPrinterChangeNotification (Opnum 67)

  • Articolo

RpcRouterRefreshPrinterChangeNotification returns change notification information.<383>

 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 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).

This handle MUST have been previously used successfully by the client in a call to RpcRemoteFindFirstPrinterChangeNotification (section 3.1.4.10.3) or RpcRemoteFindFirstPrinterChangeNotificationEx (section 3.1.4.10.4), and it MUST NOT have been closed by calling RpcFindClosePrinterChangeNotification (section 3.1.4.10.2).

dwColor: An implementation-specific value that MAY be used by print clients to get an indication of the order of notifications.<384>

pOptions: A pointer to an RPC_V2_NOTIFY_OPTIONS (section 2.2.1.13.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 2.2.3.8) and Job Notification Values (section 2.2.3.3).

ppInfo: A pointer to a variable that receives a pointer to an RPC_V2_NOTIFY_INFO (section 2.2.1.13.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 [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.

  • 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.