IPrintAsyncNotifyChannel

印刷スプーラーによってホストされるコンポーネントが、アプリケーションへ通知を送信するために使用する通信チャネルを表します。チャネルが双方向の場合、アプリケーションは同じチャネルを使用して、コンポーネントへ応答を返すことができます。

このインターフェイスを実装するオブジェクトは、印刷スプーラーがホストするコンポーネントによる CreatePrintAsyncNotifyChannel の呼び出しに応じて、印刷スプーラーが作成します。

IPrintAsyncNotifyChannel::Release は、次の場合にのみ呼び出してください。

1. 先行する IPrintAsyncNotifyChannel::AddRef の呼び出しと明示的に対応する場合。
2. チャネルが単方向 (UniDirectional) チャネルであり、CreatePrintAsyncNotifyChannel の呼び出しが成功して受け取ったポインターを破棄する場合。
3. 双方向 (BiDirectional) チャネルを作成した後、または IPrintAsyncNotifyCallback::OnEventNotify の実装内で、次のいずれかに該当する場合。
   1. IPrintAsyncNotifyChannel::SendNotification または IPrintAsyncNotifyChannel::CloseChannel を呼び出さなかった場合。または
   2. 失敗した IPrintAsyncNotifyChannel::SendNotification または IPrintAsyncNotifyChannel::CloseChannel の呼び出しを再試行しなかった場合。または
   3. サーバー側で、戻り値 NO_LISTENER で成功した IPrintAsyncNotifyChannel::SendNotification の呼び出しを再試行しなかった場合。または
   4. クライアント側で、戻り値 CHANNEL_ACQUIRED で成功した IPrintAsyncNotifyChannel::SendNotification の呼び出しを再試行しなかった場合。

印刷スプーラーによってホストされるコンポーネントから、リッスンしている 1 つ以上のアプリケーションへ通知を送信します。または、アプリケーションからコンポーネントへ応答を返します。

戻り値は COM エラー コードです。この関数は操作を正常に完了しても S_OK 以外の HRESULT を返す場合があるため、呼び出しの成否を判定するには SUCCEEDED マクロまたは FAILED マクロを使用してください。関数が返した具体的な HRESULT を取得するには、HRESULT_CODE マクロを使用します。次のコード例は、これらのマクロの使用方法を示しています。

その他の戻り値については、PrintAsyncNotifyError を参照してください。

COM エラー コードの詳細については、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;
  }
}

単方向チャネルの場合、印刷スプーラーが先行する SendNotification の呼び出しを処理している最中に SendNotification が呼び出されると、印刷スプーラーは保留中の通知をキューに入れます。印刷スプーラーがホストするコンポーネントまたはアプリケーションが IPrintAsyncNotifyChannel::CloseChannel を呼び出すと、キューに入れられた通知は破棄されます。

双方向チャネルの場合、印刷スプーラーが先行する SendNotification の呼び出しを処理している最中に SendNotification が呼び出されると、その保留中の呼び出しは失敗します。この場合、呼び出し元が印刷スプーラー内部の送信側であれば、SendNotification は CHANNEL_WAITING_FOR_CLIENT_NOTIFICATION を返します。呼び出し元が応答を送信するリスナーであれば、SendNotification は ASYNC_CALL_IN_PROGRESS を返します。

同一の双方向チャネルに複数のリスナーが存在する場合、そのチャネルで最初に送信された通知はすべてのリスナーに配信されます。最初に応答したリスナーがそのチャネルを取得します。チャネルが取得された後に SendNotification を呼び出したリスナーは、エラー CHANNEL_ACQUIRED で失敗します。

双方向チャネルで最初の通知を受け取ったリスナーが、そのチャネルの取得を望まない場合もあります。その場合、リスナーは IUnknown::Release メソッドを呼び出すことができます。SendNotification メソッドまたは IPrintAsyncNotifyChannel::CloseChannel メソッドを呼び出す場合は、IUnknown::Release メソッドを呼び出す必要はありません。

チャネルを閉じます。(IPrintAsyncNotifyChannel.CloseChannel)

戻り値は COM エラー コードです。この関数は操作を正常に完了しても S_OK 以外の HRESULT を返す場合があるため、呼び出しの成否を判定するには SUCCEEDED マクロまたは FAILED マクロを使用してください。関数が返した具体的な HRESULT を取得するには、HRESULT_CODE マクロを使用します。次のコード例は、これらのマクロの使用方法を示しています。

その他の戻り値については、PrintAsyncNotifyError を参照してください。

COM エラー コードの詳細については、Error Handling を参照してください。

if (SUCCEEDED(hr)) {
  // Call succeeded, check HRESULT value returned
  switch (HRESULT_CODE(hr)){
    case CHANNEL_ACQUIRED:
      // Some action 
      break;
    case CHANNEL_ALREADY_CLOSED:
      // Some action 
      break;
    default:
      // Default action 
      break;
  }
} else {
  // Call failed, check HRESULT value returned
  switch (HRESULT_CODE(hr)){
    case CHANNEL_CLOSED_BY_ANOTHER_LISTENER:
      // Some action 
      break;
    case CHANNEL_CLOSED_BY_SAME_LISTENER:
      // Some action 
      break;
    case INVALID_NOTIFICATION_TYPE:
      // Some action 
      break;
    case CHANNEL_ACQUIRED:
      // This can be an error and a successful return
      //  some action 
      break;
    case CHANNEL_ALREADY_CLOSED:
      // This can be an error and a successful return
      //  some action 
      break;
    default:
      // Default action 
      break;
  }
}

CloseChannel は、通信チャネルのいずれの側からでも呼び出すことができます。つまり、印刷スプーラーによってホストされるコンポーネントからでも、リッスン中のアプリケーションからでも呼び出せます。

印刷スプーラーが先行する SendNotification の呼び出しを処理している最中に IPrintAsyncNotifyChannel::SendNotification が呼び出されると、印刷スプーラーは通知をキューに入れます。印刷スプーラーがホストするコンポーネントまたはアプリケーションが CloseChannel を呼び出すと、キューに入れられた通知は破棄されます。

CloseChannel は、CreatePrintAsyncNotifyChannel の呼び出し直後に呼び出すことはできません。