FindFirstPrinterChangeNotification 函式

  • 發行項

FindFirstPrinterChangeNotification函式會建立變更通知物件，並傳回物件的控制碼。 接著，您可以在呼叫其中一個等候函式中使用此控制碼來監視印表機或列印伺服器的變更。

FindFirstPrinterChangeNotification呼叫會指定要監視的變更類型。 您可以指定要監視變更的條件集、一組要監視的印表機資訊欄位，或兩者皆可監視。

當其中一個指定的變更發生在指定的印表機或列印伺服器時，變更通知控制碼上的等候作業就會成功。 然後，呼叫 FindNextPrinterChangeNotification 函式來擷取變更的相關資訊，並重設變更通知物件以供下一個等候作業使用。

語法

HANDLE FindFirstPrinterChangeNotification(
  _In_     HANDLE hPrinter,
           DWORD  fdwFilter,
           DWORD  fdwOptions,
  _In_opt_ LPVOID pPrinterNotifyOptions
);

參數

hPrinter [in]

您要監視之印表機或列印伺服器的控制碼。 使用 OpenPrinter 或 AddPrinter 函式來擷取印表機控制碼。

fdwFilter

導致變更通知物件進入訊號狀態的條件。 符合一或多個指定的條件時，就會發生變更通知。 如果pPrinterNotifyOptions非Null，fdwFilter參數可以是零。

此參數可以是下列一或多個值。

值 意義
PRINTER_CHANGE_FORM
 通知表單的任何變更。 您可以設定此一般旗標或下列一或多個特定旗標：
PRINTER_CHANGE_ADD_FORM
PRINTER_CHANGE_SET_FORM
PRINTER_CHANGE_DELETE_FORM
PRINTER_CHANGE_JOB
 通知作業的任何變更。 您可以設定此一般旗標或下列一或多個特定旗標：
PRINTER_CHANGE_ADD_JOB
PRINTER_CHANGE_SET_JOB
PRINTER_CHANGE_DELETE_JOB
PRINTER_CHANGE_WRITE_JOB
PRINTER_CHANGE_PORT
 通知埠的任何變更。 您可以設定此一般旗標或下列一或多個特定旗標：
PRINTER_CHANGE_ADD_PORT
PRINTER_CHANGE_CONFIGURE_PORT
PRINTER_CHANGE_DELETE_PORT
PRINTER_CHANGE_PRINT_PROCESSOR
 通知列印處理器的任何變更。 您可以設定此一般旗標或下列一或多個特定旗標：
PRINTER_CHANGE_ADD_PRINT_PROCESSOR
PRINTER_CHANGE_DELETE_PRINT_PROCESSOR
PRINTER_CHANGE_PRINTER
 通知印表機的任何變更。 您可以設定此一般旗標或下列一或多個特定旗標：
PRINTER_CHANGE_ADD_PRINTER
PRINTER_CHANGE_SET_PRINTER
PRINTER_CHANGE_DELETE_PRINTER
PRINTER_CHANGE_FAILED_CONNECTION_PRINTER
PRINTER_CHANGE_PRINTER_DRIVER
 通知印表機驅動程式的任何變更。 您可以設定此一般旗標或下列一或多個特定旗標：
PRINTER_CHANGE_ADD_PRINTER_DRIVER
PRINTER_CHANGE_SET_PRINTER_DRIVER
PRINTER_CHANGE_DELETE_PRINTER_DRIVER
PRINTER_CHANGE_ALL
 如果發生上述任何變更，請通知。
PRINTER_CHANGE_SERVER
 Windows 7：通知伺服器的任何變更。
設定 PRINTER_CHANGE_ALL 值來監視的變更中不包含此旗標。

如需上表中更具體旗標的描述，請參閱 FindNextPrinterChangeNotification 函式。

fdwOptions

旗標，決定哪些通知可運作的印表機類別。

值 意義
PRINTER_NOTIFY_CATEGORY_ALL
0x001000
 FindNextPrinterChangeNotification 會傳回 2D 和 3D 印表機的通知。
PRINTER_NOTIFY_CATEGORY_3D
0x002000
 FindNextPrinterChangeNotification 只會針對 3D 印表機傳回通知。

當此旗標設定為零 (0) 時， FindFirstPrinterChangeNotification 僅適用于 2D 印表機。 這是預設值。

pPrinterNotifyOptions [in， optional]

PRINTER_NOTIFY_OPTIONS結構的指標。 這個結構的 pTypes 成員是一或多個 PRINTER_NOTIFY_OPTIONS_TYPE 結構的陣列，每個結構都會指定要監視的印表機資訊欄位。 當一或多個指定的欄位變更時，就會發生變更通知。 發生變更時， FindNextPrinterChangeNotification 函式可以擷取新的印表機資訊。 如果fdwFilter為非零值，這個參數可以是Null。

如需可監視的欄位清單，請參閱 PRINTER_NOTIFY_OPTIONS_TYPE。

傳回值

如果函式成功，傳回值是與指定印表機或列印伺服器相關聯之變更通知物件的控制碼。

如果此函數失敗，傳回值就是 INVALID_HANDLE_VALUE。

備註

注意

這是封鎖或同步函式，可能不會立即傳回。 此函式傳回的速度取決於執行時間因素，例如網路狀態、列印伺服器設定，以及撰寫應用程式時難以預測的印表機驅動程式實作因素。 從管理與使用者介面互動的執行緒呼叫此函式，可能會使應用程式看起來沒有回應。

若要監視印表機或列印伺服器，請呼叫 FindFirstPrinterChangeNotification 函式，然後在呼叫其中一個 等候函式時使用傳回的變更通知物件控制碼。 當變更通知物件進入訊號狀態時，就會滿足變更通知物件的等候作業。 當受監視的印表機或列印伺服器中發生一或多個 fdwFilter 或 pPrinterNotifyOptions 所指定的變更時，系統會發出訊號。

當您呼叫 FindFirstPrinterChangeNotification時， fdwFilter 必須是非零值，或 pPrinterNotifyOptions 必須是非Null。 如果同時指定這兩者，則兩者都會發生通知。

滿足印表機變更通知物件的等候作業時，請呼叫 FindNextPrinterChangeNotification 函式來判斷通知的原因。 針對 fdwFilter所指定的條件， FindNextPrinterChangeNotification 會報告已變更的條件。 針對 pPrinterNotifyOptions所指定的印表機資訊欄位， FindNextPrinterChangeNotification 會報告變更的欄位或欄位，以及這些欄位的新資訊。 FindNextPrinterChangeNotification 也會將變更通知物件重設為非ignaled 狀態，讓您可以在另一個等候作業中使用它來繼續監視印表機或列印伺服器。

有一個例外狀況，如果變更通知物件不是處於訊號狀態，請勿呼叫 FindNextPrinterChangeNotification 函式。 如果 wait 函式傳回值WAIT_TIMEOUT，則變更物件不是處於訊號狀態。 只有在等候函式成功而不逾時時，才呼叫 FindNextPrinterChangeNotification 函式。例外狀況是 呼叫 FindNextPrinterChangeNotification 時，會在 pPrinterNotifyOptions 參數中設定PRINTER_NOTIFY_OPTIONS_REFRESH位。

當您不再需要變更通知物件時，請呼叫 FindClosePrinterChangeNotification 函式加以關閉。

FindFirstPrinterChangeNotification的呼叫端必須確定傳入FindFirstPrinterChangeNotification的印表機控制碼在呼叫FindClosePrinterChangeNotification之前保持有效。 如果在印表機變更通知控制碼之前關閉印表機控制碼，則無法傳遞進一步的通知。

FindFirstPrinterChangeNotification 不會將 3D 印表機的變更通知傳送到伺服器控制碼。

注意

在 Service Pack 2 (SP) 2 (SP2 和更新版本中，網際網路連線防火牆 (ICF) 預設會封鎖印表機埠，但可以啟用檔案和列印共用的例外狀況。 如果使用者與另一部電腦建立印表機連線，但未啟用例外狀況，則使用者將不會從伺服器接收印表機變更通知。 電腦系統管理員必須啟用例外狀況。

規格需求

需求 值
最低支援的用戶端
 Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器
 Windows 2000 Server [僅限傳統型應用程式]
標頭
Winspool.h (包含 Windows.h)
程式庫
Winspool.lib
DLL
Spoolss.dll

另請參閱

列印

列印多工緩衝處理器 API 函式

FindClosePrinterChangeNotification

FindNextPrinterChangeNotification

OpenPrinter

PRINTER_NOTIFY_OPTIONS

PRINTER_NOTIFY_OPTIONS_TYPE