3.1.1.4.1 IRPCAsyncNotify_RegisterClient (Opnum 0)

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.

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.

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.