Partager via

3.1.4.10.3 RpcRemoteFindFirstPrinterChangeNotification (Opnum 62)

  • Article

RpcRemoteFindFirstPrinterChangeNotification 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 RpcRemoteFindFirstPrinterChangeNotification(
   [in] PRINTER_HANDLE hPrinter,
   [in] DWORD fdwFlags,
   [in] DWORD fdwOptions,
   [in, string, unique] wchar_t* pszLocalMachine,
   [in] DWORD dwPrinterLocal,
   [in, range(0,512)] DWORD cbBuffer,
   [in, out, unique, size_is(cbBuffer), disable_consistency_check] 
     BYTE* pBuffer
 );

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

cbBuffer: A value that SHOULD be set to zero when sent and MUST be ignored on receipt.

pBuffer: A pointer that MUST be set to NULL when sent and MUST be ignored on receipt.

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

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