3.1.4.10.4 RpcRemoteFindFirstPrinterChangeNotificationEx (Opnum 65)

  • Article

RpcRemoteFindFirstPrinterChangeNotificationEx creates a remote change notification object that monitors changes to printer objects and sends change notifications to a print client using either RpcRouterReplyPrinter (section 3.2.4.1.2) or RpcRouterReplyPrinterEx (section 3.2.4.1.4).

 DWORD RpcRemoteFindFirstPrinterChangeNotificationEx(
   [in] PRINTER_HANDLE hPrinter,
   [in] DWORD fdwFlags,
   [in] DWORD fdwOptions,
   [in, string, unique] wchar_t* pszLocalMachine,
   [in] DWORD dwPrinterLocal,
   [in, unique] RPC_V2_NOTIFY_OPTIONS* pOptions
 );

hPrinter: A handle to a printer 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).

fdwFlags: Flags that specify the conditions that are required for a change notification object to enter a signaled state. A change notification MUST occur when one or more of the specified conditions are met.

This parameter specifies a bitwise OR of zero or more Printer Change Values (section 2.2.4.13). The rules governing printer change values are specified in section 2.2.4.13.

fdwOptions: The category of printers for which change notifications are returned. This parameter MUST be one of the supported values specified in Printer Notification Values (section 2.2.3.8).

pszLocalMachine: A pointer to a string that represents the name of the client computer. The rules governing server names are specified in section 2.2.4.16.

dwPrinterLocal: An implementation-specific unique value that MUST be sufficient for the client to determine whether a call to RpcReplyOpenPrinter (section 3.2.4.1.1) by the server is associated with the hPrinter parameter in this call.<382>

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

The value of this parameter can be NULL if the value of fdwFlags is nonzero.

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 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 a notification object is not already associated with the current handle.

  • Verify that either pOptions is not NULL or that the value fdwFlags is valid and not zero.

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:

  • Create and initialize a notification object that captures the notification settings requested by the user.

  • Create and initialize a notification channel back to the client over which the server MUST communicate the change notifications. This MUST be done by calling RpcReplyOpenPrinter on the client specified by the name pointed to by pszLocalMachine.

  • Associate the notification object with the context for hPrinter.

  • After the preceding steps have been performed, the server SHOULD add the client to the list of notification clients for the printer object or server object, and it SHOULD notify the client by using RpcRouterReplyPrinter or RpcRouterReplyPrinterEx when the object changes.

    The choice of notification methods does not depend on whether notifications have been requested using RpcRemoteFindFirstPrinterChangeNotification or RpcRemoteFindFirstPrinterChangeNotificationEx. It is based on whether notifications can be expressed in the fdwFlags parameter of RpcRouterReplyPrinter alone, or if additional information is required to be provided using the additional parameters of RpcRouterReplyPrinterEx.

  • Return the status of the operation.