AddPrinter 函式
AddPrinter 函式會將印表機新增至指定伺服器支援的印表機清單。
語法
HANDLE AddPrinter(
_In_ LPTSTR *pName,
_In_ DWORD Level,
_In_ LPBYTE pPrinter
);
參數
-
pName [in]
-
Null 終止字串的指標，指定應該安裝印表機的伺服器名稱。 如果此字串為 Null，則會在本機安裝印表機。
-
層級 [in]
-
pPrinter指向的結構版本。 此值必須是 2。
-
pPrinter [in]
-
包含印表機相關資訊 之PRINTER_INFO_2 結構的指標。 在呼叫AddPrinter之前，您必須為此結構的pPrinterName、pPortName、pDriverName和pPrintProcessor成員指定非Null值。
傳回值
如果函式成功，傳回值就是 (不是安全線程的控制碼，) 到新的印表機物件。 當您完成控制碼時，請將它傳遞給 ClosePrinter 函 式以關閉它。
如果函式失敗，傳回值為 Null。
備註
請勿在 DllMain中呼叫這個方法。
注意
這是封鎖或同步函式，可能不會立即傳回。 此函式傳回的速度取決於執行時間因素，例如網路狀態、列印伺服器設定，以及撰寫應用程式時難以預測的印表機驅動程式實作因素。 從管理與使用者介面互動的執行緒呼叫此函式，可能會使應用程式看起來沒有回應。
呼叫端必須具有 SeLoadDriverPrivilege。
傳回的控制碼不是安全線程。 如果呼叫端需要在多個執行緒上同時使用它，則必須使用 同步處理函式提供印表機控制碼的自訂同步處理存取權。 若要避免撰寫自訂程式碼，應用程式可以視需要在每一個執行緒上開啟印表機控制碼。
以下是在呼叫AddPrinter函式之前可設定PRINTER_INFO_2結構的成員：
- 屬性
- pPrintProcessor
- DefaultPriority
- 優先順序
- pComment
- pSecurityDescriptor
- pDatatype
- pSepFile
- pDevMode
- pShareName
- pLocation
- StartTime
- pParameters
- UntilTime
PRINTER_INFO_2結構的Status、cJobs和AveragePPM成員會保留供GetPrinter 函式使用。 呼叫 AddPrinter之前，不得設定它們。
如果 pSecurityDescriptor 為 Null，系統會將預設的安全性描述項指派給印表機。 預設安全性描述項具有下列許可權。
| 值 | Description |
|---|---|
| 系統管理員與進階使用者 | 列印佇列的完整控制。 這表示這些群組的成員可以列印、管理佇列 (可以刪除佇列、變更佇列的任何設定，包括安全性描述項) ，以及管理所有使用者的列印工作， (刪除、暫停、繼續、重新開機作業) 。請注意，在 Windows XP Professional 之前，Power Users 不存在。 |
| 建立者/擁有者 | 可以管理自己的作業。 這表示提交工作的使用者可以管理 (刪除、暫停、繼續、重新開機) 自己的作業。 |
| 所有人 | 執行和標準讀取控制項。 這表示每個人群組的成員都可以列印和讀取列印佇列的屬性。 |
應用程式使用 AddPrinter 函式建立印表機物件之後，必須使用 PrinterProperties 函式來指定與印表機物件相關聯之印表機驅動程式的正確設定。
如果印表機物件具有相同名稱， 則 AddPrinter 函 式會傳回錯誤，除非該物件標示為擱置刪除。 在此情況下，不會刪除現有的印表機，而且 AddPrinter 建立參數會用來變更現有的印表機設定 (，就像應用程式已使用 SetPrinter 函式) 一樣。
使用 EnumPrintProcessors 函式來列舉伺服器上安裝的列印處理器集合。 使用 EnumPrintProcessorDatatypes 函式來列舉列印處理器支援的資料類型集合。 使用 EnumPorts 函式來列舉可用的埠集合。 使用 EnumPrinterDrivers 函式來列舉已安裝的印表機驅動程式。
AddPrinter函式的呼叫端必須具有要建立印表機之伺服器的SERVER_ACCESS_ADMINISTER存取權。 函式傳回的控制碼會有PRINTER_ALL_ACCESS許可權，而且可用來在印表機上執行系統管理作業。
如果 DrvPrinterEvent 函式傳遞PRINTER_EVENT_FLAG_NO_UI旗標，驅動程式就不應該在 DrvPrinterEvent期間使用 UI 呼叫。 若要執行 UI 相關作業，安裝程式應該使用印表機 .inf 檔案中的VendorSetup專案，或針對隨插即用裝置，安裝程式可以使用裝置特定的共同安裝程式。 如需 VendorSetup的詳細資訊，請參閱 Microsoft Windows 驅動程式開發工具組 (DDK) 。
網際網路連線防火牆 (ICF) 預設會封鎖印表機埠，但當您執行 AddPrinter時，會啟用檔案和列印共用的例外狀況。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 |
Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 |
Windows 2000 Server [僅限桌面應用程式] |
| 標頭 |
|
| 程式庫 |
|
| DLL |
|
| Unicode 與 ANSI 名稱 |
AddPrinterW (Unicode) 和 AddPrinterA (ANSI) |