ホーム › Graphics.Printing › CreatePrintAsyncNotifyChannel

CreatePrintAsyncNotifyChannel

関数

印刷の非同期通知チャネルを作成する。

DLLwinspool.drv呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// winspool.drv
#include <windows.h>

HRESULT CreatePrintAsyncNotifyChannel(
    LPCWSTR pszName,   // optional
    GUID* pNotificationType,
    PrintAsyncNotifyUserFilter eUserFilter,
    PrintAsyncNotifyConversationStyle eConversationStyle,
    IPrintAsyncNotifyCallback* pCallback,   // optional
    IPrintAsyncNotifyChannel** ppIAsynchNotification
);

パラメーター

名前	型	方向	説明
pszName	LPCWSTR	inoptional	プリントサーバーまたは印刷キューの名前へのポインター。
pNotificationType	GUID*	in	チャネルで送信される通知の種類に対応するデータスキーマの GUID へのポインター。
eUserFilter	PrintAsyncNotifyUserFilter	in	通知の送信先を指定する値。次のいずれかを指定します。 Print Spooler がホストするプラグイン (送信側) と同じユーザーとして実行されているアプリケーションのみ。より広範囲の、リッスンしているアプリケーション。
eConversationStyle	PrintAsyncNotifyConversationStyle	in	通信が双方向か単方向かを指定する値。
pCallback	IPrintAsyncNotifyCallback*	inoptional	リッスンしているアプリケーションが、Print Spooler がホストするコンポーネントをコールバックするために使用するオブジェクトへのポインター。directionality が kUniDirectional の場合は NULL にする必要があります。
ppIAsynchNotification	IPrintAsyncNotifyChannel**	out	新しいチャネルへのポインター。

戻り値の型: HRESULT

公式ドキュメント

Print Spooler がホストする印刷コンポーネント (プリンタードライバーやポートモニターなど) と、そのコンポーネントから通知を受け取るアプリケーションとの間に通信チャネルを作成します。

戻り値

HRESULT	重大度	意味
S_OK	SUCCESS	関数は正常に完了しました。
CHANNEL_ALREADY_OPENED	ERROR	チャネルは既に開かれています。
MAX_CHANNEL_COUNT_EXCEEDED	ERROR	指定されたキューまたはプリントサーバーに対して、指定された種類の通知を受け取るリッスンしているアプリケーションが既に最大数まで登録されています。既定の最大数は 10,000 です。

戻り値は COM エラーコードです。この関数は処理に成功した場合でも S_OK 以外の HRESULT を返すことがあるため、呼び出しの成否を判断するには SUCCEEDED マクロまたは FAILED マクロを使用してください。関数が返した具体的な HRESULT を取得するには、HRESULT_CODE マクロを使用します。

次のコード例は、これらのマクロを使用して戻り値を評価する方法を示しています。

if (SUCCEEDED(hr)){
  //Call was successful 
}

if (FAILED(hr)) {
  // Call failed 
}

if (FAILED(hr)) {
  // Call failed 
  switch (HRESULT_CODE(hr)){
    case CHANNEL_ALREADY_OPENED:
      // Some action 
      break;
    case MAX_CHANNEL_COUNT_EXCEEDED:
      // Some action 
      break;
    default:
      //Default action 
      break;
  }
} else {
  //call succeeded 
}

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

その他の返される可能性がある値については、PrintAsyncNotifyError を参照してください。

解説(Remarks)

注意これはブロッキング関数 (同期関数) であり、すぐに制御が戻らない場合があります。この関数が返るまでの時間は、ネットワークの状態、プリントサーバーの構成、プリンタードライバーの実装など、アプリケーションの作成時には予測が困難な実行時の要因に左右されます。ユーザーインターフェイスとのやり取りを管理するスレッドからこの関数を呼び出すと、アプリケーションが応答していないように見えることがあります。

コンポーネントがチャネルを開けるのは、Print Spooler のプロセス内で実行されている場合だけです。たとえば、アプリケーションがプリンタードライバーを読み込んだ場合、そのドライバーはチャネルを開くことができませんが、Print Spooler 内に読み込まれたプリンタードライバーはチャネルを開くことができます。リッスンするアプリケーションは、Print Spooler のプロセスの内部と外部のどちらにあってもかまいません。

チャネルを閉じるには IPrintAsyncNotifyChannel::CloseChannel を呼び出します。ただし、IPrintAsyncNotifyChannel::CloseChannel は CreatePrintAsyncNotifyChannel の呼び出し直後には呼び出せません。

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

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

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// winspool.drv
#include <windows.h>

HRESULT CreatePrintAsyncNotifyChannel(
    LPCWSTR pszName,   // optional
    GUID* pNotificationType,
    PrintAsyncNotifyUserFilter eUserFilter,
    PrintAsyncNotifyConversationStyle eConversationStyle,
    IPrintAsyncNotifyCallback* pCallback,   // optional
    IPrintAsyncNotifyChannel** ppIAsynchNotification
);

[DllImport("winspool.drv", ExactSpelling = true)]
static extern int CreatePrintAsyncNotifyChannel(
    [MarshalAs(UnmanagedType.LPWStr)] string pszName,   // LPCWSTR optional
    ref Guid pNotificationType,   // GUID*
    int eUserFilter,   // PrintAsyncNotifyUserFilter
    int eConversationStyle,   // PrintAsyncNotifyConversationStyle
    IntPtr pCallback,   // IPrintAsyncNotifyCallback* optional
    IntPtr ppIAsynchNotification   // IPrintAsyncNotifyChannel** out
);

<DllImport("winspool.drv", ExactSpelling:=True)>
Public Shared Function CreatePrintAsyncNotifyChannel(
    <MarshalAs(UnmanagedType.LPWStr)> pszName As String,   ' LPCWSTR optional
    ByRef pNotificationType As Guid,   ' GUID*
    eUserFilter As Integer,   ' PrintAsyncNotifyUserFilter
    eConversationStyle As Integer,   ' PrintAsyncNotifyConversationStyle
    pCallback As IntPtr,   ' IPrintAsyncNotifyCallback* optional
    ppIAsynchNotification As IntPtr   ' IPrintAsyncNotifyChannel** out
) As Integer
End Function

' pszName : LPCWSTR optional
' pNotificationType : GUID*
' eUserFilter : PrintAsyncNotifyUserFilter
' eConversationStyle : PrintAsyncNotifyConversationStyle
' pCallback : IPrintAsyncNotifyCallback* optional
' ppIAsynchNotification : IPrintAsyncNotifyChannel** out
Declare PtrSafe Function CreatePrintAsyncNotifyChannel Lib "winspool.drv" ( _
    ByVal pszName As LongPtr, _
    ByVal pNotificationType As LongPtr, _
    ByVal eUserFilter As Long, _
    ByVal eConversationStyle As Long, _
    ByVal pCallback As LongPtr, _
    ByVal ppIAsynchNotification As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CreatePrintAsyncNotifyChannel = ctypes.windll.LoadLibrary("winspool.drv").CreatePrintAsyncNotifyChannel
CreatePrintAsyncNotifyChannel.restype = ctypes.c_int
CreatePrintAsyncNotifyChannel.argtypes = [
    wintypes.LPCWSTR,  # pszName : LPCWSTR optional
    ctypes.c_void_p,  # pNotificationType : GUID*
    ctypes.c_int,  # eUserFilter : PrintAsyncNotifyUserFilter
    ctypes.c_int,  # eConversationStyle : PrintAsyncNotifyConversationStyle
    ctypes.c_void_p,  # pCallback : IPrintAsyncNotifyCallback* optional
    ctypes.c_void_p,  # ppIAsynchNotification : IPrintAsyncNotifyChannel** out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('winspool.drv')
CreatePrintAsyncNotifyChannel = Fiddle::Function.new(
  lib['CreatePrintAsyncNotifyChannel'],
  [
    Fiddle::TYPE_VOIDP,  # pszName : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # pNotificationType : GUID*
    Fiddle::TYPE_INT,  # eUserFilter : PrintAsyncNotifyUserFilter
    Fiddle::TYPE_INT,  # eConversationStyle : PrintAsyncNotifyConversationStyle
    Fiddle::TYPE_VOIDP,  # pCallback : IPrintAsyncNotifyCallback* optional
    Fiddle::TYPE_VOIDP,  # ppIAsynchNotification : IPrintAsyncNotifyChannel** out
  ],
  Fiddle::TYPE_INT)

#[link(name = "winspool.drv")]
extern "system" {
    fn CreatePrintAsyncNotifyChannel(
        pszName: *const u16,  // LPCWSTR optional
        pNotificationType: *mut GUID,  // GUID*
        eUserFilter: i32,  // PrintAsyncNotifyUserFilter
        eConversationStyle: i32,  // PrintAsyncNotifyConversationStyle
        pCallback: *mut core::ffi::c_void,  // IPrintAsyncNotifyCallback* optional
        ppIAsynchNotification: *mut *mut core::ffi::c_void  // IPrintAsyncNotifyChannel** out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("winspool.drv")]
public static extern int CreatePrintAsyncNotifyChannel([MarshalAs(UnmanagedType.LPWStr)] string pszName, ref Guid pNotificationType, int eUserFilter, int eConversationStyle, IntPtr pCallback, IntPtr ppIAsynchNotification);
"@
$api = Add-Type -MemberDefinition $sig -Name 'winspool.drv_CreatePrintAsyncNotifyChannel' -Namespace Win32 -PassThru
# $api::CreatePrintAsyncNotifyChannel(pszName, pNotificationType, eUserFilter, eConversationStyle, pCallback, ppIAsynchNotification)

#uselib "winspool.drv"
#func global CreatePrintAsyncNotifyChannel "CreatePrintAsyncNotifyChannel" sptr, sptr, sptr, sptr, sptr, sptr
; CreatePrintAsyncNotifyChannel pszName, varptr(pNotificationType), eUserFilter, eConversationStyle, pCallback, ppIAsynchNotification   ; 戻り値は stat
; pszName : LPCWSTR optional -> "sptr"
; pNotificationType : GUID* -> "sptr"
; eUserFilter : PrintAsyncNotifyUserFilter -> "sptr"
; eConversationStyle : PrintAsyncNotifyConversationStyle -> "sptr"
; pCallback : IPrintAsyncNotifyCallback* optional -> "sptr"
; ppIAsynchNotification : IPrintAsyncNotifyChannel** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "winspool.drv"
#cfunc global CreatePrintAsyncNotifyChannel "CreatePrintAsyncNotifyChannel" wstr, var, int, int, sptr, sptr
; res = CreatePrintAsyncNotifyChannel(pszName, pNotificationType, eUserFilter, eConversationStyle, pCallback, ppIAsynchNotification)
; pszName : LPCWSTR optional -> "wstr"
; pNotificationType : GUID* -> "var"
; eUserFilter : PrintAsyncNotifyUserFilter -> "int"
; eConversationStyle : PrintAsyncNotifyConversationStyle -> "int"
; pCallback : IPrintAsyncNotifyCallback* optional -> "sptr"
; ppIAsynchNotification : IPrintAsyncNotifyChannel** out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "winspool.drv"
#cfunc global CreatePrintAsyncNotifyChannel "CreatePrintAsyncNotifyChannel" wstr, sptr, int, int, sptr, sptr
; res = CreatePrintAsyncNotifyChannel(pszName, varptr(pNotificationType), eUserFilter, eConversationStyle, pCallback, ppIAsynchNotification)
; pszName : LPCWSTR optional -> "wstr"
; pNotificationType : GUID* -> "sptr"
; eUserFilter : PrintAsyncNotifyUserFilter -> "int"
; eConversationStyle : PrintAsyncNotifyConversationStyle -> "int"
; pCallback : IPrintAsyncNotifyCallback* optional -> "sptr"
; ppIAsynchNotification : IPrintAsyncNotifyChannel** out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。