CSDN - 文檔中心 - Visual C 傳真服務 kathywp [原作] http://dev.csdn.net/develop/article/15/15554.shtm 這個又是先貼到記事本然後貼過來的,格式沒有了,呵呵 這個也是很久以前的東西,如果有地方不準確的話,還請大家見諒! 裏面的插圖大家可以看msdn(這裏不能直接拷貝進來圖形,好麻煩,sorry) 傳真服務篇 第1章 微軟傳真服務簡介 微軟®傳真服務是使網路用戶可以從應用程式中收發傳真的一種相容TAPI（電話應用程式介面）的系統服務，此服務可在微軟®Windows® 2000及以後版本獲得並具有以下特點： ⑴傳送傳真 ⑵靈活的接收傳真 ⑶存檔已發送的傳真檔 ⑷伺服器和設備配置管理 下表詳細列出了可用來開發傳真客戶程式和擴展傳真服務的應用程式介面（API）。 傳真服務客戶API 軟體發展者能在客戶應用程式裏合併基本的傳真函數，包括輸出傳真服務、查詢和管理傳真作業及傳真設備。 傳真路由擴展API 第三方的軟體供應商通過定義輸入傳真路由擴展來擴展傳真服務。此擴展提供了一種靈活的方法以連接接收傳真的應用程式，如：列印、保存傳真，變換傳真圖形圖像到文字檔案等。 傳真服務供應商API 傳真設備製造商提供符合國際電信聯盟（ITU）T.30 規範的非數據機電話設備支援的傳真服務供應商。（微軟數據機傳真服務供應商提供 的T.30傳真協定支援帶有傳真服務數據機設備。） 下圖顯示了傳真服務的基本結構 傳真服務供應商和傳真路由擴展動態連結程式庫（DLLs）由微軟®或設備製造商（OEM）提供。 第2章 傳真服務客戶應用程式介面( API ) 傳真服務客戶API允許客戶在其應用程式中合併基本傳真功能。此項技術適用於運行windows 2000及更高版本的電腦。API包括win32函數和COM雙重介面實現。 本章第一部分構畫使用傳真服務客戶 API可以實現的任務及支援該功能所需的元件，同時也描述了傳真服務的安全性，最後對傳真埠、傳送傳真、傳真封面和傳真路由方法進行了簡潔討論。第二部分討論win32和COM實現環境下傳真程式的差別。還討論了傳真客戶函數、COM雙重介面以及下列有關的編程任務。 ⑴連接到傳真伺服器 ⑵傳真伺服器配置管理 ⑶傳真設備管理 ⑷管理傳真路由資料 ⑸發送傳真 ⑹管理傳真作業 ⑺釋放傳真資源 ⑻斷開與傳真伺服器的連接 注：在閱讀本篇之前，應該對電話應用編程介面( TAPI )和微軟®電話服務供應商( TSPI ) 有所熟悉，如果計畫使用傳真客戶的COM實現,也應該熟悉COM (部件物件模型)和自動化編程概念。 2.1、傳真服務客戶 API 簡介 微軟®的傳真服務為在本地網（LAN）上的客戶提供傳真服務。傳真服務客戶 API 允許開發者在其應用程式裏合併服務並啟動基本傳真功能。傳真服務客戶API 包括Win32 函數介面和 COM 介面。 ⑴Win32 環境 Win32 函數作為動態連結程式庫 WinFax.dll檔被實現。這是一種客戶機/伺服器實現模式，允許遠端電腦上的傳真客戶與使用 RPC 的傳真伺服器進行通訊。客戶機可以使用共用網路傳真印表機訪問輸出傳真服務，或者應用程式可以調用傳真服務客戶 API中的函數連接一台遠端傳真伺服器進行傳真傳送。 ⑵ COM 實現環境 COM 介面作為雙重介面被VB和C/C 程式師接納與實現。本文為兩種編程語言均提供參考資料。 下圖顯示了傳真客戶應用程式的概貌： 要實現傳真服務，必須在原代碼檔中包含WinFax.h 頭檔，而要使用微軟支援的傳真客戶COM實現則必須包含 FaxCom.h頭文件。 2.1.1、傳真服務客戶API功能 傳真服務客戶 API使傳真客戶應用程式可以執行下列任務： ⑴傳送一個存儲於電腦中的文檔。應用程式能把文檔作為一份傳真傳送到一個或廣播到多個程式定義的接受者。 ⑵傳送一張封面頁。用戶可以用傳真傳送一張封面頁，該封面可為伺服器上的公用封面頁，也可以是一張個人的封面頁。 ⑶通過將列印文檔為設備上下文來傳送活動文檔。基於文檔的應用程式可以阻止傳真發送嚮導的顯示。程式能夠直接為傳真客戶圖形設備介面（GDI）提供傳送資訊，並且將它列印到一個傳真設備上下文來傳送一份活動文檔。 ⑷傳送一份傳真文檔到活動調用。使用已經存在的輸入鏈結線路來傳送文檔可以節約發送傳真的費用，這就是所謂的“Faxback服務”。 ⑸使用傳真發送嚮導發送活動文檔。用戶可以通過把文檔列印到傳真印表機來傳送該文檔。傳真發送嚮導會收集用戶的傳送資訊，而開發者則只需使用列印功能即可。 ⑹改變傳真設備和傳真伺服器的配置。應用程式可提供配置管理或可使用微軟管理控制臺( MMC ) 插件元件中的傳真配置服務管理應用程式來進行配置。 2.1.2、傳真服務客戶 API 軟體要求 下列元件被要求支援傳真服務客戶API的功能 ： ⑴ 傳真服務( FaxSvc.exe )。支援傳真服務的應用程式可以管理傳真設備、配置資料、提供列印服務並收發傳真檔。通過傳真路由擴展傳真服務也可以初始化和重發輸出傳真路由方法。 ⑵winFax.lab。包含傳真服務客戶 API功能的靜態程式庫。 ⑶winFax.dll。包含傳真服務客戶 API 功能的動態連結程式庫。 此外,必須在源代碼檔中包括 WinFax.h 頭文件；而使用微軟支援的傳真客戶 COM 實現,則須包括 FaxCOM.h頭文件。 傳真服務可以與使用 RPC 的網路用戶端機進行通訊。儘管不需要在每台客戶電腦上安裝傳真服務，但服務一定要可以由 RPC訪問到客戶電腦。 2.1.3、傳真服務可執行檔和相關檔 下列表格描述了與傳真服務相關的可執行檔、 DLL和頭檔。 檔案名 描述 FaxSvr.exe 管理傳真設備、配置資料、提供列印服務和收發傳真檔的傳真服務支援應用程式， FaxAdmin.dll 微軟管理控制臺( MMC )插件元件之一的傳真服務管理應用程式，提供配置管理功能。 FaxMon.dll 包含傳真列印監視器的動態連結程式庫 WinFax.dll 包含傳真服務客戶API功能的動態連結程式庫 WinFax.lib 包含傳真服務客戶API功能的靜態程式庫 FaxCom.dll 傳真服務客戶API的COM介面 FaxCover.exe 傳真封面頁編輯應用程式 FaxExt32.dll 包含 MAPI用戶介面擴展的動態連結程式庫 FaxXp32.dll 包含傳真郵件傳送功能的動態連結程式庫。 FaxRoute.dll 包含微軟®傳真路由擴展的動態連結程式庫。 FaxDev.h 包含傳真服務供應商 API 原型的頭檔。 FaxRoute.h 包含傳真路由擴展API 原型的頭檔 WinFax.h 包含傳真客戶服務 API Win32環境原型的頭檔 FaxT30.dll 包含微軟®數據機傳真服務提供商的動態連結程式庫 FaxDrv.dll 傳真印表機驅動程式動態連結程式庫 FaxUi.dll 傳真印表機驅動程式動態連結程式庫 2.1.4、設備和配置管理 傳真服務提供的傳真服務管理應用程式是微軟管理控制臺( MMC )插件元件之一，傳真客戶程式可以進行配置管理或使用管理程式進行下列配置管理任務： ⑴指定收發傳真的器件 ⑵指定可在埠上執行的路由方法 ⑶配置全局服務資料 2.1.5、傳真埠 本章中，傳真埠始終被看作是一台傳真設備以及與設備相聯繫的配置和與輸入資訊路由，傳真服務為用戶提供一個或多個傳真埠作為傳真傳送的終點。 傳真虛擬設備也存在傳真埠，這就意味著傳真可以輸出到連接至傳真伺服器的非嚴格物理設備終端。支援互聯網傳送傳真的傳真服務供應商即是使用虛擬傳真設備的供應商的例子。 2.1.6、傳真埠的訪問級別 傳真服務客戶 API 允許應用程式查詢和修改傳真埠的配置資料。 ⑴Win32環境 為了使用戶能訪問個埠的配置資料, 傳真客戶應用程式在調用 FaxOpenPort函數時，必須指定正確的傳真埠訪問級別。FaxOpenPort 返回傳真埠控制碼並根據指定的訪問級別打開埠。應用程式根據用戶的需求和許可，可查詢下列值： 值 意義 PORT_OPEN_QUERY 調用FaxGetPort、 FaxEnumPort和FaxGetDeviceStatus 函數查詢傳真埠資訊的埠訪問級別 PORT_OPEN_MODIFY 調用FaxSetPort 函數修改傳真埠配置的埠訪問級別，默認為是與PORT_OPEN_QUERY訪問級別聯繫的訪問許可權。 除了要求埠用恰當的訪問級別打開之外，傳真服務也要求用戶查詢並且修改埠資料時，要有恰當的訪問許可權。要獲得傳真埠控制碼和查詢埠資料，用戶必須獲得FAX_PORT_QUERY許可；要修改埠資料，用戶必須獲得 FAX_PORT_SET 許可。 傳真客戶應用程式可以調用 FaxAccessCheck函數查詢用戶的訪問許可權。也可使用微軟管理控制臺( MMC )插件元件之一的傳真服務管理應用程式來修改用戶埠訪問許可權。 ⑵COM實現環境 在應用程式調用修改FaxPort屬性的方法之前，須調用 IFaxPort::get CanModiFy方法（檢索 V B 中FaxPort物件的CanModify 屬性）以確保客戶有權修改埠的配置。 2.1.7、傳真客戶程式的用戶訪問許可權 傳真服務是一種安全的服務。在 Win32 環境下，用戶必須擁有訪問許可權以成功調用某一傳真客戶程式函數，每次客戶程式調用傳真客戶程式函數前服務均進行訪問許可權檢查。應用程式可以由調用 FaxAccessCheck 函數來檢查用戶的訪問許可權,。 如果使用微軟®的 COM 實現，則此時傳真客戶應用程式無法獲得該項功能。若客戶沒有執行特定任務的訪問許可權，則方法或函數失敗且返回HRESULT_FROM_WIN32 ( ERROR_ACCESS_DENIED )。 微軟管理控制臺( MMC )插件元件之一傳真服務管理應用程式,為用戶提供查詢和修改作業訪問許可權、埠訪問許可權和全局配置資料訪問許可權。 下麵就詳細敍述傳真訪問許可權的內容。 2.1.7.1、特定傳真訪問許可權 如果使用微軟 COM 實現，則此時傳真客戶應用程式無法利用此項功能。 傳真服務客戶API 定義下列特定訪問許可權,為用戶查詢和管理傳真作業、傳真設備和傳真文檔提供安全保障。 值 意義 FAX_CONFIG_QUERY 允許在傳真伺服器級查詢配置和路由方法資料 FAX_CONFIG_SET 允許在傳真伺服器級修改配置和路由方法資料 FAX_JOB_MANAGE 允許在程式中終止傳真作業或改變傳真作業佇列的狀態 FAX_JOB_QUERY 允許查詢佇列中和活動傳真作業 FAX_JOB_SUBMIT 允許發送傳真到一個或多個接收者 FAX_PORT_QUERY 允許在埠級查詢配置、狀態和路由演算法資料；此訪問許可權有獲取和關閉傳真埠控制碼的能力 FAX_PORT_SET 允許在埠級修改配置和路由方法資料；此許可權有啟用或遮罩傳真路由演算法的能力 2.1.7.2、通用傳真訪問許可權 如果使用微軟 COM 實現，則此時傳真客戶應用程式無法利用此項功能。 傳真服務客戶API 定義下列通用傳真訪問許可權，公共許可權默認用戶有特定傳真訪問許可權： 值 意義 FAX_READ 包含由由特定訪問許可權FAX_JOB_QUERY、FAX_CONFIG_QUERY 和 FAX_PORT_QUERY認可的唯讀許可權 FAX_WRITE 此訪問等同於FAX_JOB_SUBMIT特定訪問許可權認可的許可。注意此許可權不包括在埠或伺服器級修改資料許可。 FAX_ALL_ACCESS 包括由下列特定訪問許可權認可的所有的讀寫許可： FAX_CONFIG_QUERY、 FAX_CONFIG_SET、FAX_JOB_MANAGE、FAX_JOB_QUERY、FAX_JOB_SUBMIT、FAX_PORT_QUERY和FAX_PORT_SET 2.1.7.3、函數要求的傳真訪問權 下列表格列出了win32環境下，用戶成功地調用某個傳真客戶函數後可獲得的訪問許可權。 訪問許可權 函數 FAX_CONFIG_QUERY（傳真配置查詢） FaxEnumGlobalRoutingInFo FaxGetConFiguration FaxGetLoggingCategories FAX_CONFIG_SET（傳真配置設置） FaxSetConFiguration FaxSetGlobalRoutingInFo FaxSetLoggingCategories FAX_JOB_QUERY（傳真作業查詢） FaxEnumJobs FaxGetJob FaxGetPageData FAX_JOB_SET（傳真作業設置） FaxAbort FaxSetJob FAX_JOB_SUBMIT（傳真作業提交） FaxSendDocument FaxSendDocumentForBroadcast FAX_PORT_QUERY（傳真埠查詢） FaxClose FaxEnumPorts* FaxEnumRoutingMethods FaxEnumRoutingMethods FaxGetDeviceStatus* FaxGetPort* FaxGetRoutingInFo FaxOpenPort FAX_PORT_SET（傳真埠設置） FaxEnableRoutingMethod FaxSetPort* FaxSetRoutingInFo *此函數要求特定傳真埠訪問級。 注意：FAX_JOB_MANAGE 訪問級別允許用戶調用FaxAbort 函數和FaxSetJob 函數。 2.1.8、傳送傳真 傳送輸出傳真有以下要點： ⑴文檔文件。傳真服務轉換資料為傳真的標籤圖像檔格式F類格式(TIFF 6.0 F類)。 ⑵發送資訊。該資訊包括傳真序號、發送者和接收者資料、可選的帳單編碼方式以及作業安排資訊。在 Win32 環境下，如果將應用程式列印到設備上下文，則FAX_PRINT_INFO結構會包含此資訊否則由FAX_JOB_PARAM 結構包含資訊。如果使用微軟®COM 實現方式，可以設置 FaxJob物件的多重屬性來指定發傳資訊。 ⑶可選封面頁文件。在 Win32 環境下，FAX_COVERPAGE_INFO 結構包含此資料，該結構提供封面頁範本檔案名 (.cov)及用戶自定義的範本資訊。如果使用微軟®COM 實現，可設置FaxDoc物件的多重屬性來指定封面頁息。 2.1.9、封面頁 封面頁是一個封面頁範本檔( .cov )和傳真傳送時提供給範本的用戶自定義資訊。 傳真服務客戶 API 支援封面頁列印。封面頁可為存儲在本地電腦上的個人封面頁檔，或為存儲在傳真伺服器上存儲的公共封面頁。要獲取封面頁，用戶必須提供應封面頁檔的完整合法路徑或公共封面頁檔的相對路徑。 典型情況下，管理器將公共封面頁檔存儲在如下的位置： \\SERVERNAME\FAX$\Coverpg 在個人電腦系統上，公共封面頁檔存儲於： CSIDL_APPDATA\MicrosoFt\Windows NT\MSFax\coverpg 用戶能夠通過使用傳真控制面板應用程式來添加個人封面頁檔，但此檔必須存儲於用戶“我的文檔”標準檔夾的如下位置： CSIDL_PERSONAL\Fax\Personal Coverpages 此外,在 Win32 環境下，如果用戶要指定一個公共封面頁檔，就必須設置 FAX_COVERPAGE_INFO結構的UseServerCoverPage 成員為真。而在COM 實現環境下，則須設置FaxDoc物件的ServerCoverpage屬性為真。 一個傳真客戶應用程式可以調用 FaxPrintCoverPage 函數將封面頁列印到傳真印表機設備上下文。 2.1.10、傳真路由方法 傳真路由方法是由傳真路由擴展動態連結程式庫（DLL）定義的一種程式。當傳真埠收到輸入傳真時，按照優先順序順序執行傳真路由方法。 由於以下原因，我們需要使用GUID來確定傳真路由方法： ⑴一個傳真路由擴展DLL可以支援多個路由方法。 ⑵一個傳真路由擴展DLL 可以為每個路由方法和傳真設備提供唯一的配置資料。 ⑶多重傳真路由擴展 DLLs可用相同的名字輸出路由方法。 2.1.11、傳真客戶API編程任務 下面我們就具體描述在傳真客戶應用程式中，要求合併傳真服務客戶 API功能的典型任務。 2.1.11.1、win32傳真客戶編程任務 以下步驟總結了在win32編程環境下，編寫一份傳真客戶應用程式需要合併傳真服務客戶API功能的典型編程任務。 ⑴調用FaxconnectFaxsever函數連接到傳真伺服器。注意除非伺服器是本地電腦,否則應用程式必須提供伺服器名。 ⑵必要時，可調用一個或多個傳真服務枚舉函數。這些函數允許用戶查看與傳真伺服器相連的傳真埠和與埠相連的路由資訊，也允許用戶查看活動傳真作業列表。這些枚舉函數包括FaxEnumGlobalRoutingInFo、 FaxEnumJobs、 FaxEnumPorts和FaxEnumRoutingMethods函數。 ⑶調用FaxOpenPort函數獲取傳真埠控制碼。 ⑷必要時，可調用FaxGetRoutingInFo、FaxSetRoutingInFo和FaxEnableRoutingMethod函數之一或多個來查詢和修改傳真埠的路由資訊。 ⑸可以調用FaxSendDocument或 FaxSendDocumentForBroadcast 函數來傳送傳真檔。注意應用程式必須提供諸如傳真序號和接收者資料之類的傳送資訊。 ⑹調用FaxFreebuFFer函數來釋放應用程式調用FaxCOMpletejobparams函數以及Faxenum或Faxget開始的函數時所分配的資源。 ⑺分兩次調用FaxClose 函數。第一次調用斷開應用程式與傳真埠的連接，第二次調用則斷開應用程式與傳真伺服器的連接。 此外,應用程式需要調用其他函數來查詢設備或伺服器配置資料、管理傳真作業以及列印傳真。 2.1.11.2、在C/C 程式中使用 COM 實現 以下步驟總結了COM實現環境下，用C/C 編寫一份傳真客戶應用程式需要合併傳真服務客戶API功能的典型編程任務。 ⑴調用CoCreateInstance函數創建一個FaxServer物件實例，然後調用IFaxServer::Connect 介面方法連接到活動傳真伺服器。 ⑵調用下列iFaxsever介面方法中的一個或多個來創建所需物件： a.調用IFaxServer::GetJobs 方法創建一個 FaxJobs物件，然後使用此物件創造 FaxJob 物件並枚舉與所連結傳真伺服器的相關傳真作業。 b.調用IFaxServer::Getports方法創建一個 Faxports物件，然後使用此物件創造 Faxport 物件並枚舉與所連結傳真伺服器的相關傳真埠配置資訊。 c.調用IFaxServer::CreateDocument方法創建一個Faxdoc物件，然後使用此物件來發送傳真以及檢索和設置Faxdoc物件屬性。 ⑶在為特定埠創建FaxPort物件實例之後，即可調用 IFaxPort::GetRoutingMethods 介面方法創建FaxRoutingMethod物件，當然也可調用IFaxRoutingMethods::get_Item 介面方法創建FaxRoutingMethod物件。FaxRoutingMethod物件允許程式師查詢和修改傳真埠的傳真路由資訊。 ⑷調用IFaxPort::GetStatus介面方法即可創建Faxstatus物件，該物件允許程式師提供關於埠的即時狀態資訊。 ⑸在創建好Faxdoc物件實例之後，就可以調用IFaxDoc::Send 介面方法來發送一份傳真檔。注意，應用程式必須提供諸如傳真序號和將發送檔的名稱之類的資訊。用戶也能通過設置Faxdoc物件的多種屬性來提供其他需要顯示在封面頁上的資料。 ⑹調用sysFreestring函數即可釋放以get_PropertyName結束的所有介面方法分配的資源。 ⑺調用IFaxServer::Disconnect 介面方法終止與傳真伺服器的連接，然後調用IUnknown::Release 方法釋放FaxServer 物件自身。 此外, 要查詢設備或伺服器配置資料、管理傳真作業和銷毀附加介面指標應用程式需要調用其他介面方法，而用戶若要檢索傳真服務已發送或接收的檔資訊則需創建一個FaxTiFF 物件實例及調用IFaxTiFF介面方法。 注意客戶應用程式必須調用CoCreateInstance函數來創建FaxServer 或 FaxTiFF物件的實例。但是,不能調用CoCreateInstance函數來創建 FaxDoc 、 FaxJobs 、 FaxJob 、 FaxPorts 、 FaxPort 、 FaxStatus 、FaxRoutingMethods或FaxRoutingMethod對象。 2.1.11.3、在VB程式中使用 COM 實現 以下步驟總結了COM實現環境下，用VB編寫一份傳真客戶應用程式需要合併傳真服務客戶API功能的典型編程任務。 ⑴調用VB的CreateObject函數創建一個FaxServer物件實例，然後調用物件的Connect方法連接到活動傳真伺服器。 ⑵可調用下面FaxServer物件方法的一個或多個來創建所需的其他物件： a.調用GetJobs方法創造一個 FaxJobs物件後，即可使用該物件創建FaxJob物件和枚舉與所連接傳真伺服器相關的傳真作業。 b.調用GetPorts方法創建一個 FaxPorts物件後，即可使用該物件創建 FaxPort物件和枚舉所連接傳真伺服器的傳真埠配置資訊。 c.調用CreateDocument後方法創建一個 FaxDoc物件，即可使用該物件來傳送傳真以及檢索和設置 FaxDoc物件屬性。 ⑶為特定埠創建一個FaxPort物件實例後，調用該物件的GetRoutingMethods方法即可創建FaxRoutingMethods物件。 ⑷調用 FaxRoutingMethods 物件的Item方法即可創建FaxRoutingMethod物件，該物件允許用戶查詢和修改傳真埠的傳真路由資訊。 ⑸調用FaxPort物件的 GetStatus方法可以創建FaxStatus物件，該物件允許用戶提供即時的傳真埠狀態資訊。 ⑹創建好FaxDoc物件的實例後，即可調用物件的Send方法傳送一份傳真檔。注意應用程式必須提供諸如傳真序號和傳送檔案名之類的資訊。客戶也可以通過設置 FaxDoc 物件的不同屬性，提供在封面頁上出現的其他資料。 ⑺調用FaxServer物件的Disconnect方法可終止與伺服器的連接。 此外，要查詢伺服器和設備配置參數以及管理傳真作業應用程式就需要設置其他的屬性和調用其他方法，而用戶若要檢索有關傳真服務已經收發檔的資訊則需創建一個FaxtiFF物件實例來完成該任務。 2.1.12、連接到傳真伺服器 大多數情況下，傳真客戶應用程式在使用傳真特性前必須連接到傳真伺服器。 ⑴ win32環境 要連接到傳真伺服器,傳真客戶應用程式在調用其他任何傳真客戶函數前，必須首先成功調用 FaxConnectFaxServer 函數。該函數返回調用其他傳真客戶函數所要求的傳真伺服器控制碼。 注意，到傳真伺服器的連接並不要求把傳真文檔列印到傳真印表機設備上下文。程式能直接給傳真客戶圖形設備介面( GDI )函數提供傳送資訊，並通過列印到印表機設備上下文來傳送活動文檔。傳真客戶GDI函數包括FaxStartPrintJob和FaxPrintCoverpage函數。 調用FaxClose函數斷開到傳真伺服器的連接並釋放FaxConnectFaxServer函數返回的控制碼。 ⑵COM實現環境 在C/C 應用程式中，開發者須調用CoCreateInstance函數來檢索指向IFaxServer介面的指標並創建一個FaxServer物件實例。隨後調用IFaxServer::Connect方法初始化與活動傳真伺服器的連接。在應用程式可以訪問以iFax開始的大多數介面之前，要求其必須連接到伺服器。（若訪問iFaxtiFF介面則不必連接到傳真伺服器。） 在vb應用程式中，開發者則須調用vbCreateObject函數創建一個 FaxServer 物件實例，然後調用FaxServer物件的Connect方法初始化與活動傳真伺服器的連接。在應用程式可以訪問以Fax開始的大多數物件之前，要求其必須連接到伺服器。（若訪問FaxtiFF介面則不必連接到傳真伺服器。） 2.1.12、傳真伺服器配置管理 傳真服務客戶 API支援對傳真伺服器配置資料進行改變，並提供伺服器級別的配置選項。 2.1.12.1、管理全局配置資料 必須與活動傳真伺服器連接才能檢索和改變其配置資訊，這些資訊包括對傳送、標記、存檔和封面頁的設置以及貼現率週期和傳真伺服器狀態佇列。 ⑴. Win32環境下 FaxGetConFiguration 函數允許傳真客戶應用程式查詢傳真伺服器的全局配置設置。函數在FAX_CONFIGURATION 結構中返回查詢資訊。 FaxGetConFiguration函數分配FAX_CONFIGURATION 結構所要求的記憶體，因此應用程式必須調用FaxFreeBuFFer函數來釋放已分配的資源。應用程式可調用 FaxSetConFiguration 函數,來修改傳真伺服器的全局配置設置。 注意；應用程式在調用 FaxGetConFiguration函數和FaxSetConFiguration函數前，須先調用 FaxConnectFaxServer函數以獲取傳真伺服器的控制碼。 ⑵.COM實現環境 在檢索和設置有關FaxServer 物件的資訊前，須先連接到活動的傳真伺服器。 C/C 應用程式中，可使用 IFaxServer 介面的屬性方法檢索和設置 FaxServer物件的全局資訊；vb應用程式中，可直接檢索和設置 FaxServer物件的屬性。 2.1.12.2、管理日誌分類 當前此功能僅在Win32 環境下可用；對 COM 實現環境則不可用。 日誌分類決定錯誤類型或傳真伺服器記載在應用程式事件記錄檔中的其他事件類型。日誌等級描述傳真伺服器記載的事件嚴重性的輕重。FaxGetLoggingCategories函數允許傳真客戶程式查詢傳真伺服器的當前日誌分類。函數會在一個或多個的FAX_LOG_CATEGORY結構中返回查詢資訊，每個結構描述一個當前日誌分類。資料包括記日誌分類的描述名、分類序號和當前日誌級別。由FaxGetLoggingCategories 函數分配 FAX_LOG_CATEGORY結構所要求的記憶體，因此應用程式必須調用FaxFreeBuFFer函數來釋放這些資源。應用程式可通過調用 FaxSetLoggingCategories函數，來修改傳真伺服器的全局配置設置。 注意：在調用 FaxGetConFiguration函數和 FaxSetConFiguration函數前，應用程式必須先調用 FaxConnectFaxServer函數以獲得傳真伺服器控制碼。 2.1.13、傳真設備管理 傳真服務客戶 API 支援對傳真路由和設備配置資料進行改變，並提供埠級別的配置選項資訊。 2.1.13.1、查詢傳真埠資料(Win32 環境) 傳真客戶應用程式調用FaxEnumPorts函數即可顯示目前所有與傳真伺服器相連接的傳真設備，而若要查詢單獨的傳真設備，則須調用FaxGetPort 函數。兩函數通過FAX_PORT_INFO 結構返回詳細的設備資訊，一台設備對應一個結構。資料包括永久線路識別字、當前埠的狀態和相容性。注意：應用程式在調用 FaxGetPort函數之前須先調用 FaxOpenPort函數並指定PORT_OPEN_QUERY埠的訪問級，。 可以調用 FaxGetDeviceStatus 函數，來顯示與當前傳真伺服器連接的某台傳真設備的狀態，函數在 FAX_DEVICE_STATUS 結構中返回資料。結構包括當前設備狀態標誌位元、設備及其位置識別字、發送和接收者名以及傳真路由資訊。 注意應用程式在調用 FaxEnumPorts 函數前，必須先調用 FaxConnectFaxServer 函數以獲得傳真伺服器控制碼；而應用程式在調用FaxGetDeviceStatus函數和FaxGetPort 函數前，須先調用 FaxOpenPort 函數指定 PORT_OPEN_QUERY埠的訪問級別並獲得傳真埠控制碼。 因為以FaxGet 和 FaxEnum 開始的函數會分配資料緩衝區所要求的記憶體，故應用程式必須調用 FaxFreeBuFFer 函數以釋放這些資源。 應用程式可以調用 FaxSetPort 函數來修改一台傳真設備的配置設置。 2.1.13.2、查詢傳真埠資料（COM實現） FaxPort物件為傳真客戶應用程式提供查詢埠和埠當前狀態的永久線路識別字，也可以檢索分配到埠的優先傳送權。在埠回應調用前，輸入傳真調用的響鈴處於等待狀態，而不論當前埠是否啟用傳送和接受傳真。 創建FaxPort物件實例後，即可調用 IFaxPort::GetStatus方法(VB 中用 FaxPort 物件的Status方法)創建FaxStatus 物件。使用 FaxStatus 物件檢索父FaxPort物件的即時狀態資訊。 調用FaxPort::GetRoutingMethods方法創建FaxRoutingMethods 物件。（VB中用FaxPort物件的GetRoutingMethods方法）然後能使用此物件創建一個 FaxRoutingMethod物件實例。使用FaxRoutingMethod物件可為連結到傳真伺服器上的傳真埠檢索傳真路由配置資訊。 在C/C 應用程式中，在為指定的傳真創建FaxPort物件以後，可以調用IFaxPort介面方法來檢索埠的屬性；而VB應用程式中，為指定的傳真埠創建FaxPort物件以後，即可檢索埠的多個屬性。 2.1.13.3、修改傳真埠資料 傳真客戶應用程式能修改傳真埠的某個配置資料，這些資料包括分配到埠的傳送優先權和埠回應調用前輸入傳真調用須等待的振鈴次數，還包括埠的當前狀態和功能以及傳送和調用位置的識別字。 ⑴WIN32環境下 傳真客戶應用程式可以調用 FaxSetPort 函數來改變與傳真伺服器相連接的傳真埠的配置。 注意；應用程式在調用 FaxSetPort函數之前，須先調用 FaxOpenPort以指定 PORT_OPEN_MODIFY埠訪問級別來獲得傳真埠控制碼。 ⑵.COM實現環境 創建FaxPort物件的實例後，可調用IFaxPort::GetRoutingMethods方法（VB 中可調用 FaxPort物件的GetRoutingMethods方法）來創建FaxRoutingMethod物件。此物件隨後被用來創建FaxRoutingMethod 物件的實例。使用 FaxRoutingMethod 物件可在特定傳真埠上啟用或遮罩傳真路由方法。 注意，在應用程式調用修改FaxPort屬性的方法前，可先調用IFaxPort::get_CanModiFy方法(在VB中是檢索FaxPort物件的CanModify屬性)確認客戶程式有權修改埠配置。 C/C 的應用程式中，在為指定傳真埠創建FaxPort物件後，即可調用IFaxPort介面方法來改變埠的屬性。 VB的應用程式中，在為指定傳真埠創建FaxPort物件後，就能馬上檢索物件的多種屬性。 2.1.14、管理傳真路由資料 一些路由方法屬性,如方法優先權，可在傳真伺服器級設置並適用於所有連接到傳真伺服器的埠，而其他的傳真路由方法屬性在埠級設置。 下面就詳細討論管理傳真路由資料的有關內容。 2.1.14.1、管理全局傳真路由資料 當前，此功能僅在Win32 環境可用，在 COM 實現環境不可用。 一個傳真客戶應用程式可以調用 FaxEnumGlobalRoutingInFo 函數來查詢全局路由方法資料，函數在FAX_GLOBAL_ROUTING_INFO結構中返回資料，返回資訊包括傳真路由方法的優先權和輸出此路由方法的 DLL名，還包括 GUID 和確定傳真路由方法的函數名以及方法的友好用戶名。 應用程式調用FaxEnumGlobalRoutingInFo函數為FAX_GLOBAL_ROUTING_INFO結構來分配所要求的記憶體,因此程式須調用FaxFreeBuFFer函數來釋放已分配的資源。 程式調用FaxSetGlobalRoutingInFo 函數修改全局路由方法資料。（當前路由方法優先權是應用程式能修改的唯一全局值。） 注意：應用程式在調用FaxEnumGlobalRoutingInFo函數和FaxSetGlobalRoutingInFo函數前，必須首先調用 FaxConnectFaxServer 函數以獲得傳真伺服器控制碼。 2.1.14.2、管理單獨埠的傳真路由資料（WIN32環境） 傳真管理應用程式可以調用 FaxEnumRoutingMethods 函數來顯示與特定設備相關聯的所有傳真路由方法；調用 FaxGetRoutingInFo函數來查詢與設備相關聯的單個方法。兩個函數都由FAX_ROUTING_METHOD 結構返回調用的詳細資訊，每個結構對應一種方法。返回資料包括傳真路由方法是否被啟用的指示和輸出路由方法的 DLL名，還包括GUID 和唯一確定路由方法的函數名及方法的友好用戶名。 程式調用FaxSetRoutingInFo函數即可改變特定傳真路由方法的路由資料。 注意：應用程式在調用FaxEnumGlobalRoutingInFo函數、FaxSetGlobalRoutingInFo函數和FAXGETROUTINGINFO前，須先調用 FaxOPENPORT函數以獲得傳真伺服器控制碼。由於以FAXGET和FAXENUM開始的函數為資料緩存分配記憶體，故應用程式須調用 FaxFreeBuFFer 函數來釋放這些資源。 2.1.14.3、管理單獨埠的傳真路由資料（COM實現） 除了在特定傳真埠上啟用或遮罩傳真路由方法,傳真客戶應用程式還可以檢索有關方法的資料，這些資料包括輸出方法的DLL名、GUID 和唯一指定路由方法的函數名以及方法的友好用戶名。 C/C 程式中，在指定埠為傳真路由方法創建FaxRoutingMethod 物件後，即可調用 IFaxRoutingMethod介面方法。這些方法能檢索路由方法的屬性並在埠上啟用或遮罩一個路由方法； VB應用程式中，在指定埠為傳真路由方法創建FaxRoutingMethod 物件後，即可檢索物件的多種的性質。當然也可以在埠上啟用或遮罩一個路由方法。 2.1.14.4、啟用或遮罩傳真路由方法 傳真路由方法是每次在埠上收到傳真後執行的行為。傳真服務僅執行發送輸入傳真時埠啟用的路由方法。 ⑴Win32 環境 傳真客戶應用程式可以調用 FaxEnableRoutingMethod 函數為特定傳真設備啟用一個傳真路由方法，也能調用函數來遮罩因調用FaxEnableRoutingMethod或傳真服務管理應用程式而啟用的路由方法。應用程式調用FaxEnumRoutingMethods函數來查詢當前傳真路由方法是否啟用。 注意,在調用FaxEnableRoutingMethod 或FaxEnumRoutingMethods前,應用程式須先調用FaxOpenPort 函數以獲得傳真埠控制碼。 ⑵COM的實現環境 C/C 應用程式中，可調用IFaxRoutingMethod::put_Enable屬性方法在特定埠上啟用或遮罩傳真路由方法。若要啟用傳真路由方法,傳真客戶程式須傳遞“真”值到IFaxRoutingMethod::put_Enable方法。IFaxRoutingMethod::get_Enable方法為FaxRoutingMethod物件檢索Enable屬性。在創建FaxRoutingMethod 物件前，須為FaxPort 物件檢索指向IDispatch 介面的指標； vb程式中，可以設定 FaxRoutingMethod 物件的Enable屬性，從而在特定埠啟用或遮罩傳真路由方法。如果此屬性為“真”,則埠啟用路由方法。不過在創建FaxRoutingMethod物件以前，須先創建一個FaxPort物件實例。 2.1.15、傳送傳真 傳真客戶應用程式可以傳送任何一個檔，但檔必須是正確的註冊檔類型,同時傳真伺服器必須能夠訪問該檔。 2.1.15.1、發送一個封面頁 傳真服務客戶API支援列印可選封面頁,用戶端能在傳真文檔中傳送一個公共封面頁或者是私人封面頁. 如果要求發送一個封面頁,則用戶必須提供完整的封面頁檔路徑，或公共封面頁檔的相對路徑。 ⑴發送封面頁(win32環境下) 可以在發送傳真時傳送伺服器上的個人或公共封面頁。要傳送封面頁就須調用FaxSendDocument函數或FaxSendDocumentForBroadcast函數。 當調用FaxSendDocument函數傳送傳真,必須提供指向FAX_COVERPAGE_INFO 結構的指標。該結構提供了封面頁範本檔案名和檔位於本地或傳真伺服器的指示，結構同時也提供用戶支援的封面頁資訊。 a、發送公共封面頁 ①調用FaxSendDocument 函數時,提供指向FAX_COVERPAGE_INFO結構的指標。 ②設定FAX_COVERPAGE_INFO結構的UseServerCoverPage成員為真。 ③在FAX_COVERPAGE_INFO結構的UseServerCoverPage成員指定有效的公共封面頁檔. b、發送一個個人封面頁 ①調用FaxSendDocument函數時, 提供指向FAX_COVERPAGE_INFO結構的指標。 ②設定FAX_COVERPAGE_INFO結構的UseServerCoverPage成員為假。 ③指定一份傳真伺服器在FAX_COVERPAGE_INFO結構的CoverpageName成員中訪問的有效個人封面頁檔。 可以調用FaxGetConFiguration 函數確定傳真伺服器是否允許設置個人封面頁。如果應用程式調用FaxSendDocumentForBroadcast函數傳送一份傳真到多個的接收者，此函數就須調用 FAX_RECIPIENT_CALLBACK函數。而在調用FAX_RECIPIENT_CALLBACK及設置上文提及的成員時,程式必須提供一個指向 FAX_COVERPAGE_INFO 結構的指標。回調函數能為每個特定傳真接收者檢索指定用戶的封面頁資訊。 ⑵發送封面頁(COM實現環境) 通過設定以下的FAXDOC物件屬性,即可在傳真中發送公共封面頁或個人封面頁. a、發送公共封面頁 ①設定SENDCOVERPAGE屬性為真。 ②設定SERVERCOVERPAGE屬性為真。 ③設定封面頁名屬性為有效公共封面頁檔。 b、發送個人封面頁 ①設定SENDCOVERPAGE屬性為真。 ②設定SERVERCOVERPAGE屬性為假。 ③設定封面頁名屬性為有效公共封面頁檔。 可調用IFaxServer::get_ServerCoverpage方法來確定傳真服務是否允許設置個人封面頁。 要在傳真中傳送封面頁,可以調用 IFaxDoc::Send 方法(VB中是FaxDoc物件的Send方法)。 2.1.15.2、發送傳真到一個接收者(WIN32環境) 傳真客戶應用程式調用 FaxSendDocument函數來指定存儲於磁片上的檔，從而排列將要發送到一個接受者的傳真作業。 程式必須指定傳送檔並提供指向 FAX_JOB_PARAM 結構的指標。傳真伺服器將根據FAX_JOB_PARAM指定的細節來排列傳真作業。該結構包括接受者的傳真號碼、發送和接受的資料、可選帳號和作業排列資訊。 要發送一份封面頁，應用程式必須提供一個指向 FAX_COVERPAGE_INFO 結構的指標，此結構包含將顯示在傳真封面頁上的資料。 程式在調用FaxSendDocument 函數前須先調用 FaxCOMpleteJobParams 函數。FaxCOMpleteJobParams函數為 FAX_COVERPAGE_INFO和FAX_JOB_PARAM 結構的成員提供資料。調用FaxFreeBuFFer 函數來釋放與這些結構關聯的記憶體。 要有效地將一份傳真檔發送到若干接收者，應用程式應該調用 FaxSendDocumentForBroadcast 函數，而非多次調用FaxSendDocument 函數。注意：應用程式在調用 FaxSendDocument 函數和 FaxSendDocumentForBroadcast 函數前須先調用 FaxConnectFaxServer 函數以獲得傳真伺服器控制碼。 2.1.15.3、發送一份傳真到一個接收者(COM實現環境) 如果程式使用傳真客戶COM 實現，除非用現存的連接線路來設置屬性以啟用傳真發送，傳送一份傳真需要有FileName屬性和FaxNumber 屬性，。傳送傳真時，用戶也可以指定其他的可選屬性，如封面頁設置、傳真接收和發送者資訊以及一些僅在封面頁顯示的資料。 C/C 應用程式中，在與活動傳真伺服器連接好以後，即可調用 IFaxServer::CreateDocument方法創建一個 FaxDoc物件。隨後調用多種IFxDoc介面方法來設置物件的可選或必須屬性。最後調用 IFaxDoc::Send 方法來傳送檔。 在VB應用程式中,調用VB中的CreateObject 函數創建一個FaxServer物件。然後調用該物件的 CreateDocument 方法創建一個 FaxDoc 物件，並設置FaxDoc物件的必須和可選屬性。最後調用FaxDoc物件的Send方法發送傳真檔。 2.1.15.4、廣播傳真到多個接收者 當前此功能只在WIN32環境下可用，而COM環境下不可用。 FaxSendDocumentForBroadcast 函數排列傳真作業，這些作業把存儲在磁片上的檔傳遞到多個接受者。程式必須指定要傳送的檔。一旦指定了傳真接收者，FaxSendDocumentForBroadcast 函數就會多次調用 FAX_RECIPIENT_CALLBACK 函數來檢索排列的資訊,每次對應一個接收者，若有要求則資訊也包含封面資訊。 程式在調用 FAX_RECIPIENT_CALLBACK 函數前，須先調用FaxCompleteJobParams 函數。FaxCompleteJobParams 函數為 FAX_COVERPAGE_INFO 和 FAX_JOB_PARAM 結構的成員提供資料。可以調用FaxFreeBuffer 函數來釋放與這些結構相關聯的記憶體。 注意程式在調用 FaxSendDocument和FaxSendDocumentForBroadcast函數之前，必須先調用 FaxConnectFaxServer 函數來獲得傳真伺服器的控制碼。 2.1.15.5、傳遞傳真到活動的輸入調用 使用現存的輸入線路連接來傳遞傳真檔可以節約傳真的費用，即所謂的"faxback 服務"。若要使用現存的輸入線路連接成功傳遞檔, 調用須處於LINECALLSTATE_CONNECTED 狀態。 ⑴、WIN32 環境 若要使用現存的線路連接來傳遞傳真,在調用FaxSendDocument 或 FaxSendDocumentForBroadcast函數時，需指定 FAX_JOB_PARAM 結構的CallHandle成員。調用控制碼必須是TAPI LINE_CALLSTATE檢索到的消息之一。如果指定CallHandle成員, 程式會使用現存的連接進行傳真傳遞而不是初始化一個新調用。 ⑵、COM 實現環境 C/C 程式中, 可設置 CallHandle或ConnectionObject 屬性啟用現存連接線路來傳遞傳真。如果要傳遞傳真到活動輸入TAPI 2.x 調用,可以調用 IFaxDoc::put_CallHandle介面方法。若要在FaxDoc物件中存儲TAPI調用物件的引用, 則須調用IFaxDoc::putref_ConnectionObject方法。使用現存線路連接傳遞傳真時，ConnectionObject屬性提供基於COM的全部的功能。在VB程式中,可設置FaxDoc物件的ConnectionObject屬性，在使用現存連接線路傳遞傳真時，該屬性提供基於COM的全部功能。 2.1.15.6、列印傳真到設備上下文 當前此功能只在WIN32環境下可用，而COM環境不可用。 傳真客戶程式不要求到傳真伺服器的連接將傳真列印至列印設備上下文(DC)。不必調用FaxSendDocument或FaxSendDocumentForBroadcast 函數, 程式可直接向傳真客戶服務API提供的圖形設備介面函數（GDI）提供傳遞資訊。這就使程式可以由直接列印到印表機DC來傳遞活動文本。傳真客戶的GDI 函數包括FaxStartPrintJob 和FaxPrintCoverpage 函數。 由於傳真GDI函數使用傳真印表機設備, 故調用FaxStartPrintJob 函數時，必須指定所連接的傳真印表機名。印表機可為本地印表機如“printername”或遠端印表機如“\\machinename\printername”。若將NULL PrinterName 參數傳遞到FaxStartPrintJob,則指本地印表機，FaxStartPrintJob函數返回印表機DC的控制碼。 注意：傳真客戶程式不應調用 CreateDC Win32 GDI函數來創建傳真印表機DC，也不應調用 StartDoc列印函數來啟動文本列印。相反，程式應調用FaxStartPrintJob函數。 列印傳真到設備上下文的步驟： (1)調用FaxStartPrintJob 函數檢索傳真印表機DC的控制碼。函數在FAX_CONTEXT_INFO 結構中返回控制碼。 (2)若傳真要求有封面，可調用FaxPrintCoverpage函數來傳遞指向FaxStartPrintJob函數返回的FAX_CONTEXT_INFO結構的指標。 (3)以常規方式列印傳真文檔到印表機DC時，要給DC傳遞FaxStartPrintJob函數返回的控制碼，此過程包括調用StartPage 和 EndPage Win32 GDI 函數。 (4)調用EndDoc或AbortDoc 函數，向FaxStartPrintJob函數返回的DC傳遞控制碼，這將關閉文檔和結束傳真列印作業。 (5)調用DeleteDC函數釋放分配到DC的控制碼。 2.1.16、管理傳真作業 傳真服務客戶API支援靈活的佇列管理和活動傳真作業管理。下面就詳細描述輸出傳送的管理。 2.1.16.1、查詢傳真作業 傳真客戶程式可以查詢與傳真作業相關的傳真序號、傳真接收者和發送者資訊，也可檢索作業的類型、狀態和唯一標示符；時序、作業順序和傳遞頁的數目。 ⑴Win32 環境 FaxEnumJobs函數允許傳真客戶應用程式檢索指定傳真伺服器上的傳真作業佇列列表。調用FaxGetJob函數可查詢單獨的傳真作業。兩個函數均可返回FAX_JOB_ENTRY結構中作業的詳細資訊，一個結構對應一個作業。 因為FaxEnumJobs和FaxGetJob函數為FAX_JOB_ENTRY結構分配其所要求的記憶體，故應用程式須調用 FaxFreeBuffer 函數來釋放這些資源。 注意:應用程式在調用 FaxEnumJobs和FaxGetJob函數前,須先調用 FaxConnectFaxServer函數獲得傳真伺服器控制碼。 ⑵COM實現環境 C/C 應用程式中，在為指定傳真作業創建FaxJob物件後,可調用IFaxJob介面方法t