Partager via

3.1.1.4.1 IRPCAsyncNotify_RegisterClient (Opnum 0)

  • Article

The IRPCAsyncNotify_RegisterClient method is called by clients to register to receive notifications and to associate the parameters describing the set of notifications they are registering to receive with a remote object.

 HRESULT IRPCAsyncNotify_RegisterClient(
   [in] PRPCREMOTEOBJECT pRegistrationObj,
   [in, string, unique] const wchar_t* pName,
   [in] PrintAsyncNotificationType* pInNotificationType,
   [in] PrintAsyncNotifyUserFilter NotifyFilter,
   [in] PrintAsyncNotifyConversationStyle conversationStyle,
   [out, string] wchar_t** ppRmtServerReferral
 );

pRegistrationObj: MUST be the remote object context handle that was returned by the server in the ppRemoteObject output parameter of a prior call to IRPCRemoteObject_Create (section 3.1.2.4.1). This value MUST NOT be NULL.

pName: MUST be NULL or a pointer to a NULL-terminated string, encoded in Unicode UTF-16LE ([RFC2781] section 4.2), which specifies the full UNC name of the print queue from which the print client is registering to receive notifications.

This UNC name MUST be in the following format:

 "\\" SERVER_NAME "\" LOCAL_PRINTER_NAME

SERVER_NAME is a DNS, NetBIOS, IPv4, or IPv6 host name.

LOCAL_PRINTER_NAME is a string that MUST NOT contain the characters "\" or ",".

DNS names are specified in [RFC819] section 2, and NetBIOS names are specified in [RFC1001] section 14. Basic notational conventions are specified in [RFC2616] section 2, and "host" is defined in [RFC3986] section 3.2.2.

If pName is NULL, the registration MUST be made for the remote print server itself.

pInNotificationType: MUST be a pointer to a PrintAsyncNotificationType structure that specifies the notification type identifier for the notifications that the client is registering to receive.

NotifyFilter: MUST be a value of type PrintAsyncNotifyUserFilter that specifies whether the client is registering to receive notifications that are issued to all registered clients, irrespective of their authenticated user identity, or to receive notifications that are issued only to the specific authenticated user identity of the registering RPC client.

conversationStyle: MUST be a value of type PrintAsyncNotifyConversationStyle that specifies whether the client is registering for bidirectional communication mode or unidirectional communication mode.

ppRmtServerReferral: Servers SHOULD return NULL for this parameter, and clients MUST ignore it on receipt.

Return Values: This method MUST return zero to indicate success, or an HRESULT error value ([MS-ERREF] section 2.1.1) to indicate failure. Protocol-specific error values are defined in the following table. The client SHOULD treat all error return values the same, except where noted.

Return value

Description

0x80070005

The client does not have authorization to register for notifications with the set of parameters specified in this call.

If this error value is returned, the client SHOULD NOT retry this call; the client SHOULD consider the error to be fatal and report it to the higher level caller.

0x8007000E

The server does not have enough memory for the new registration.

0x80070015

The server has reached its maximum registration limit.

0x8007007B

The pName parameter does not conform to the format specified above.

If this error value is returned, the client SHOULD NOT retry this call; the client SHOULD consider the error to be fatal and report it to the higher level caller.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

Unless specified otherwise, if a failure is indicated by an error return or an exception, the client SHOULD retry this method call by performing the following steps:

  1. Call IRPCRemoteObject_Create to generate a new PRPCREMOTEOBJECT (section 2.2.4).

  2. Call IRPCAsyncNotify_RegisterClient with the new PRPCREMOTEOBJECT.

Retries SHOULD be separated by time intervals decaying from 1 second to 1 minute to reduce a potential burden on the server.

The IRPCAsyncNotify_RegisterClient method MUST be called by clients to register for receiving notifications. Servers MUST associate the given remote object with the registration parameters specified.

A client MUST NOT call IRPCAsyncNotify_RegisterClient if a prior call to IRPCAsyncNotify_RegisterClient succeeded using the same PRPCREMOTEOBJECT value, unless a later call to IRPCAsyncNotify_UnregisterClient also succeeded.

If registering for unidirectional communication mode, a client SHOULD call IRPCAsyncNotify_GetNotification after a successful call to IRPCAsyncNotify_RegisterClient using the same PRPCREMOTEOBJECT value.

If registering for bidirectional communication mode, a client SHOULD call IRPCAsyncNotify_GetNewChannel after a successful call to IRPCAsyncNotify_RegisterClient using the same PRPCREMOTEOBJECT value.

Servers MUST support the concurrent registration of multiple remote objects with different registration parameters, including notification type, filter, and communication mode.

Servers SHOULD consider the security and privacy context prior to letting clients monitor and receive notifications for all user identities. Relevant access rights are defined in the following table.

Name/Value

Description

SERVER_ALL_ACCESS

0x000F0003

Combines the WO (Write Owner), WD (Write DACL), RC (Read Control), and DE (Delete) bits of the ACCESS_MASK data type ([MS-DTYP] section 2.4.3) with the following protocol-specific bits:

  • 0x00000001 (bit 31): Access rights to administer print servers.

  • 0x00000002 (bit 30): Access rights to enumerate print servers.

These printing-specific access rights allow a client to administer the server and to enumerate server components such as print queues.

PRINTER_ALL_ACCESS

0x000F000C

Combines the WO (Write Owner), WD (Write DACL), RC (Read Control), and DE (Delete) bits of the ACCESS_MASK data type with the following protocol-specific bits:

  • 0x00000004 (bit 29): Access rights for printers to perform administrative tasks.

  • 0x00000008 (bit 28): Access rights for printers to perform basic printing operations.

These printing-specific access rights allow a client basic and administrative use of print queues.

For calls to IRPCAsyncNotify_RegisterClient with NotifyFilter set to kAllUsers, if pName is set to NULL, the server SHOULD fail the call if the calling principal lacks any of the server access rights specified by SERVER_ALL_ACCESS. If pName points to the name of a print queue, the server SHOULD fail the call if the calling principal lacks any of the print queue access rights specified by PRINTER_ALL_ACCESS. For additional information concerning access rights, see [MS-AZOD] section 1.1.1.5.