Export (0) Print
Expand All

IPrintAsyncNotifyChannel::SendNotification method

Sends a notification from a component that is hosted by the print spooler to one or more listening applications, or sends a response from an application back to a component.

Syntax


HRESULT SendNotification(
  [in]  IPrintAsyncNotifyDataObject *pData
);

Parameters

pData [in]

A pointer to the content of the notification and its size and type.

Return value

HRESULTSeverityMeaning
S_OKSUCCESSThe function completed successfully.
ASYNC_CALL_ALREADY_PARKEDERRORA notification cannot be sent because the recipient has not consumed the previous notification.
ASYNC_CALL_IN_PROGRESSERRORThe channel is busy with another notification or response.
ASYNC_NOTIFICATION_FAILUREERROR None of the listeners on this channel are configured to receive this notification type or there was a problem allocating the resources necessary to complete this call.
CHANNEL_ACQUIREDERRORAnother listener has acquired this channel. The notification was not sent. The original listener will no longer receive notifications.
CHANNEL_ALREADY_CLOSEDERRORThe notification could not be sent because the channel was closed prior to this call.
CHANNEL_NOT_OPENEDERRORThe notification could not be sent because the channel was not opened prior to this call.
CHANNEL_WAITING_FOR_CLIENT_NOTIFICATIONERRORA notification cannot be sent because a response to the last notification has not been received.
INVALID_NOTIFICATION_TYPEERRORThe specified notification type is invalid.
MAX_NOTIFICATION_SIZE_EXCEEDEDERRORThe maximum size of the notification data has been exceeded. By default, the maximum data size allowed is 10 megabytes.
NO_LISTENERSSUCCESSIndicates that there are no registered listening applications.
UNIRECTIONAL_NOTIFICATION_LOSTSUCCESSOne or more listeners did not receive this notification, but at least one listener did receive this notification.

 

The return values are COM error codes. Because this function might complete the operation successfully yet return an HRESULT other than S_OK you should use the SUCCEEDED or FAILED macro to determine the success of the call. To get the specific HRESULT that was returned by the function, use the HRESULT_CODE macro. The following code example shows how these macros can be used.

See PrintAsyncNotifyError for other possible return values.

For more information about COM error codes, see Error Handling.


if (SUCCEEDED(hr)) {
  // Call succeeded, check HRESULT value returned
  switch (HRESULT_CODE(hr)){
    case S_OK:
      // Some action 
      break;
    case NO_LISTENERS:
      // Some action 
      break;
    case UNIRECTIONAL_NOTIFICATION_LOST:
      // Some action 
      break;
    default:
      // Default action 
      break;
  }
} else {
  // Call failed, check HRESULT value returned
  switch (HRESULT_CODE(hr)){
    case ASYNC_NOTIFICATION_FAILURE:
      // Some action 
      break;
    case CHANNEL_ALREADY_CLOSED:
      // Some action 
      break;
    case CHANNEL_NOT_OPENED:
      // Some action 
      break;
    //
    // ... Test for other error cases
    //    
    default:
      // Default action 
      break;
  }
}


Remarks

For a unidirectional channel, if a SendNotification call is made while the print spooler is processing an earlier SendNotification call, the print spooler queues the pending notification. Queued notifications are discarded if either the component that is hosted by the print spooler or the application calls IPrintAsyncNotifyChannel::CloseChannel.

For a bidirectional channel, if a SendNotification call is made while the Print-Spooler is processing an earlier SendNotification call, then the pending call will fail. In that case, if the caller is a sender inside print spooler, SendNotification returns CHANNEL_WAITING_FOR_CLIENT_NOTIFICATION. If the caller is a listener sending a reply, then SendNotification returns ASYNC_CALL_IN_PROGRESS.

When multiple listeners exist for the same bidirectional channel, the initial notification sent on the channel will be delivered to all listeners. The first listener to reply will acquire the channel. Listeners calling SendNotification after the channel was acquired will fail with error CHANNEL_ACQUIRED.

A listener receiving an initial notification on a bidirectional channel might not be interested in acquiring the channel. In this case the listener can call IUnknown::Release method can be called. The IUnknown::Release method does not need to be called if SendNotification or IPrintAsyncNotifyChannel::CloseChannel methods are called.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Prnasnot.h

DLL

Prnasnot.dll

See also

IPrintAsyncNotifyChannel
Printing
Asynchronous Printing Notification Interfaces

 

 

Community Additions

ADD
Show:
© 2014 Microsoft