3.1.1.4.3 IRPCAsyncNotify_GetNewChannel (Opnum 3)

  • Article

The IRPCAsyncNotify_GetNewChannel method returns an array of pointers to print notification channels. This method MUST only be used with bidirectional communication mode.

 HRESULT IRPCAsyncNotify_GetNewChannel(
   [in] PRPCREMOTEOBJECT pRemoteObj,
   [out] unsigned long* pNoOfChannels,
   [out, size_is( , *pNoOfChannels)] 
     PNOTIFYOBJECT** ppChannelCtxt
 );

pRemoteObj: MUST be the remote object context handle. This handle is obtained from IRPCRemoteObject_Create (section 3.1.2.4.1). This remote object MUST have been registered for bidirectional communication mode by a prior successful call to IRPCAsyncNotify_RegisterClient (section 3.1.1.4.1).

pNoOfChannels: MUST specify the number of notification channels returned. The array of notification channels is specified by the ppChannelCtxt parameter.

The server SHOULD return all not-yet-acquired bidirectional channels in response to a single IRPCAsyncNotify_GetNewChannel call. The server SHOULD return such channels regardless of whether they were created before or after client registration or the call to IRPCAsyncNotify_GetNewChannel.

ppChannelCtxt: MUST specify a pointer to the array of returned notification channels. This data is represented by a Bidirectional Notification Channel structure in the Abstract Data Model (section 3.1.1.1).

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

0x8004000C

The server has not yet returned from a previous call to this method with the same remote object.

If this error value is returned, the client SHOULD NOT retry this call before the previous call to this method with the specified remote object has completed.

0x8007000E

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

0x8007071A

Incoming notifications have been terminated. Upon completion of this call with this return value, the server MUST fail subsequent calls to this method with the same remote object.

If this error value is returned, the client SHOULD NOT retry this call.

Exceptions Thrown: An exception code of 0x8004000C or 0x8007071A SHOULD be thrown by the server under the circumstances described in the preceding table for the corresponding return values. The client MUST treat these exception codes exactly as it would treat the same return values. No additional 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.

  3. Call IRPCAsyncNotify_GetNewChannel 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. Retries SHOULD terminate when the above sequence succeeds or the client determines that it is no longer interested in notifications for the particular combination of notification type, print queue name, conversation style, and user identity filter that were originally specified in the call to IRPCAsyncNotify_RegisterClient.

If successful, the IRPCAsyncNotify_GetNewChannel method MUST return an array of pointers to print notification channels.

A server MUST NOT do the following:

  • Indicate success to a client call of IRPCAsyncNotify_GetNewChannel unless a prior call to IRPCAsyncNotify_RegisterClient succeeded using the same PRPCREMOTEOBJECT value.

  • Indicate success to a client call of IRPCAsyncNotify_GetNewChannel following a prior successful call to IRPCAsyncNotify_UnregisterClient using the same PRPCREMOTEOBJECT value.

  • Complete a call to IRPCAsyncNotify_GetNewChannel unless an unreturned notification channel is available on the Bidirectional Notification Channel Queue associated with the Client Registration (Abstract Data Model, section 3.1.1.1), or an abnormal event happened, such as an initiated server shutdown sequence.

A client SHOULD do the following:

  • Call IRPCAsyncNotify_GetNewChannel in response to a prior successful return from IRPCAsyncNotify_RegisterClient or IRPCAsyncNotify_GetNewChannel.

  • Call IRPCAsyncNotify_GetNotificationSendResponse in response to a prior successful return from IRPCAsyncNotify_GetNewChannel.

A client MUST NOT do the following:

  • Call IRPCAsyncNotify_GetNewChannel, unless a prior call to IRPCAsyncNotify_RegisterClient succeeded by using the same PRPCREMOTEOBJECT value.<8>

  • Call IRPCAsyncNotify_GetNewChannel following a prior call to IRPCAsyncNotify_UnregisterClient by using the same PRPCREMOTEOBJECT value.<9>