EastFax電子傳真軟件二次開發(fā)接口使用說明說課講解

1、Good is good, but better carries it.精益求精，善益求善。EastFax電子傳真軟件二次開發(fā)接口使用說明EastFax智能傳真服務器二次開發(fā)接口說明之一目錄TOCo1-3hzuHYPERLINKl_Toc204415109一、概述PAGEREF_Toc204415109h2HYPERLINKl_Toc204415110二、EastFax服務端發(fā)送接口說明PAGEREF_Toc204415110h2HYPERLINKl_Toc2044151112.1單個文件單個號碼的發(fā)送方式PAGEREF_Toc204415111h2HYPERLINKl_Toc20441511

2、22.1.1實現(xiàn)原理：PAGEREF_Toc204415112h2HYPERLINKl_Toc2044151132.1.2單號碼發(fā)送的文件命名規(guī)則PAGEREF_Toc204415113h3HYPERLINKl_Toc2044151142.2多個文件多個號碼的群發(fā)方式PAGEREF_Toc204415114h4HYPERLINKl_Toc2044151152.2.1實現(xiàn)原理PAGEREF_Toc204415115h4HYPERLINKl_Toc2044151162.2.2多號碼發(fā)送的文件命名規(guī)則PAGEREF_Toc204415116h5HYPERLINKl_Toc2044151172.3文件

3、目錄的制定規(guī)則PAGEREF_Toc204415117h6HYPERLINKl_Toc204415118三、EastFax客戶端發(fā)送接口說明PAGEREF_Toc204415118h6HYPERLINKl_Toc2044151193.1實現(xiàn)原理：PAGEREF_Toc204415119h7HYPERLINKl_Toc2044151203.2客戶端配置文件內(nèi)容：PAGEREF_Toc204415120h7HYPERLINKl_Toc2044151213.3配置文件使用說明：PAGEREF_Toc204415121h8HYPERLINKl_Toc204415122四、發(fā)送結(jié)果的處理PAGEREF_

4、Toc204415122h9HYPERLINKl_Toc204415123五、EastFax接收接口說明PAGEREF_Toc204415123h13HYPERLINKl_Toc204415124六、傳真接收結(jié)果的處理PAGEREF_Toc204415124h14一、概述EastFax智能傳真系統(tǒng)提供方便的二次開發(fā)接口，可與企業(yè)的其它業(yè)務系統(tǒng)（如ERP、CRM、OA、HR等）無縫集成，協(xié)同辦公，提高工作效率。EastFax提供豐富的二次開發(fā)接口，本文所列接口方式為其中之一。本文所列二次開發(fā)接口分為兩大類，分別是發(fā)送接口和接收接口。發(fā)送接口又分為服務端接口和客戶端接口兩種，兩種發(fā)送接口實現(xiàn)原理各

5、不相同，所適合的用戶需求也不相同。不論哪種發(fā)送接口方式，在傳真發(fā)送完畢后，EastFax都提供結(jié)果反饋程序，可將與傳真發(fā)送結(jié)果相關(guān)的所有信息反饋到用戶自己的數(shù)據(jù)庫中，方便用戶自行查詢傳真的發(fā)送結(jié)果。如果使用的是客戶端發(fā)送接口，傳真的發(fā)送結(jié)果還可以在客戶端中查詢。下面分別對各接口進行詳細說明。二、EastFax服務端發(fā)送接口說明使用EastFax服務端發(fā)送接口時無需安裝EastFax客戶端程序，EastFax服務端會帶有EastFax外部打印機和結(jié)果回傳器二個外掛程序，并隨EastFax服務端同時運行。發(fā)送接口支持兩種發(fā)送方式，分別是單個文件單個號碼的發(fā)送方式和多個文件需要合并發(fā)送給多個號碼的群

6、發(fā)發(fā)送方式。2.1單個文件單個號碼的發(fā)送方式2.1.1實現(xiàn)原理第一步：其他系統(tǒng)（如ERP系統(tǒng)）將要發(fā)送的傳真內(nèi)容，生成單個文件，以協(xié)議好的命名規(guī)則命名，把文件統(tǒng)一放到指定的目錄。第二步：外部打印機程序（EastFaxExtPrinter.exe）能夠自動、即時地從指定的目錄里得到需要發(fā)送傳真的文件，且從文件名里得到相關(guān)的傳真發(fā)送信息（例如對方單位名稱、傳真號碼、傳真屬性等等），然后將此文件轉(zhuǎn)換為傳真格式并提交給EastFax智能傳真服務器進行發(fā)送。第三步：結(jié)果回傳程序（EastFaxResultExt.exe）可以將傳真的發(fā)送結(jié)果寫入數(shù)據(jù)庫，以便企業(yè)查看和管理傳真的收發(fā)情況。接口運行流程圖如下

7、：外部打印機運行狀態(tài)如下圖：結(jié)果回傳器運行狀態(tài)如下圖：2.1.2單號碼發(fā)送的文件命名規(guī)則默認情況下，對于單個文件單個號碼的文件發(fā)送，客戶業(yè)務系統(tǒng)必須按以下規(guī)則生成待發(fā)送的傳真文件，并存放在配置文件指定的目錄中（目錄的詳細說明見后面的2.3節(jié)）：1、傳真文件的命名規(guī)則：接收單位名稱#接收方傳真號碼#傳真件屬性#傳真流水號.txt例：上海復園電子科技有限公司#65111322#訂貨單#5155212.txt2、文件的格式可以是常見的如txt、doc、xls、pdf、html、mht等；3、如有其他需求，需要反饋回數(shù)據(jù)庫的信息字段，可另行協(xié)商定制開發(fā)。2.2多個文件多個號碼的群發(fā)方式2.2.1實現(xiàn)原

8、理第一步：其他系統(tǒng)（如ERP系統(tǒng)）將要發(fā)送的傳真內(nèi)容，生成多個文件，統(tǒng)一放到指定的目錄下。每個文件的文件名前面部分相同，后面加上文件序號。第二步：第一步完成后，業(yè)務系統(tǒng)再生成一個與文件名同名且后綴為epi格式的配置文件（20080720.epi），與前面的傳真內(nèi)容文件一起存放在指定的目錄下。配置文件中的內(nèi)容說明見下一節(jié)。第三步：外部打印機程序（EastFaxExtPrinter.exe）能夠自動、即時地從指定的目錄里得到需要發(fā)送傳真的文件，且從epi配置文件里得到相關(guān)的傳真發(fā)送信息，然后將同名且?guī)蛱柕乃形募D(zhuǎn)換為傳真格式并提交給EastFax智能傳真服務器進行發(fā)送。第四步：結(jié)果回傳程序（E

9、astFaxResultExt.exe）可以將傳真的發(fā)送結(jié)果寫入數(shù)據(jù)庫，以便企業(yè)查看和管理傳真的收發(fā)情況。接口運行流程圖如下：外部打印機運行狀態(tài)如下圖：結(jié)果回傳器運行狀態(tài)如下圖：2.2.2多號碼發(fā)送的文件命名規(guī)則對于多個文件多個號碼的群發(fā)傳真方式，客戶業(yè)務系統(tǒng)必須按以下規(guī)則生成待發(fā)送的傳真文件，并存放在配置文件指定的目錄中（目錄的詳細說明見后面的2.3節(jié)）：（1）傳真文件的命名規(guī)則每個文件的文件名前面部分相同，后面加上文件序號。例如同時生成3個需要發(fā)送的文件，則可以這樣命名：20080720_1.pdf，20080720_2.pdf，20080720_3.pdf。（2）配置文件的說明配置文件名

10、必須與要發(fā)送的傳真文件名匹配，如20080720.epi，其中各章節(jié)說明如下：GeneralAccount=001;提交打印任務的帳號，會同步到其客戶端，如果不指定就取用缺省的ExtPrinter帳號Subject=TestforExtPrinter;傳真的主題Comments=Comments;傳真的注釋FaxFlowAccounts=;傳真簽審流程，如002003008SerialNO=;傳真序列號，用于同步到結(jié)果數(shù)據(jù)庫Priority=1;傳真優(yōu)先級，0低，1普通，2高，該配置生效的前提需對于賬戶具有“重要傳真優(yōu)先發(fā)送”的權(quán)限；EmailResult=;發(fā)送者的郵箱，發(fā)送結(jié)果會發(fā)送到該郵

11、箱，如果提供的話ReceiverList=65654240(復園科技小張);55666857(復園科技小王);接收者傳真號碼，采用客戶端輸入傳真號碼文本框中的樣式，多個號碼以分號分隔開來ReceiverNumber_1=88889797;第二種接收者傳真號碼表示方式，多個接收者用_1,_2表示，如果填寫的是內(nèi)部賬戶名，則發(fā)送給內(nèi)部該用戶,也支持填寫EastFax地址ReceiverName_1=姓名1ReceiverCompany_1=公司1ReceiverNumber_2=99998787ReceiverName_2=姓名2ReceiverCompany_2=公司2SendLine=-1；指

12、定線路發(fā)送(默認-1為自動選擇)，0表示0通道，暨表示第一個線路功能不為“無”的線路，該配置生效的前提需對應帳號具有“指定線路發(fā)送”的權(quán)限；SendTime=20090101120000；指定時間發(fā)送，格式為YYYYMMDDhhmmss，如果不填或者填寫的時間早于服務器當前時間表示即時發(fā)送EastFax=Yes;該字段非常重要，只有這樣填寫了，才被認為是一個合法的打印提交文件。且該字段應該最后填寫，因為程序一旦檢測到該值為Yes即開始轉(zhuǎn)換文件。2.3文件目錄的制定規(guī)則在使用EastFax傳真服務器的服務端發(fā)送接口后，在服務器的安裝目錄下將會有一個名為EastFaxEP.ini的配置文件；打開該

13、配置文件，找到其中的“DirectorynameofsourcefileSrcDir=”部分，在“=”號后面填寫一個文件夾的絕對路徑。當然也可以是網(wǎng)絡(luò)路徑，但需要確保安裝EastFax服務端的電腦有權(quán)限訪問網(wǎng)絡(luò)上的該文件夾。例如在已有的業(yè)務系統(tǒng)中生成要發(fā)送傳真的文件時，如果你想把所有要發(fā)送傳真的文件直接存放在傳真服務器主機的D盤根目錄下的sendfax文件夾中，則應填寫的內(nèi)容為“D：sendfax”；如果你想把生成的需要傳真的文件放在局域網(wǎng)內(nèi)IP地址為192.168.1.1的主機D盤下的sendfax目錄中，該D盤為默認名稱，則應填寫的內(nèi)容為“192.168.1.186本地磁盤(d)sendf

14、ax”，或者更簡單的，將該主機的D盤通過共享映射為本機的其他盤如S盤，然后填寫路徑“S:sendfax”。SrcDir配置項可支持指定多個文件目錄，不同的文件目錄使用“|”符分隔，如需要對C盤根目錄下的sendfax文件夾和D盤根目錄下的sendfax下的文件進行發(fā)送，可設(shè)定“SrcDir=C:sendfax|D:sendfax”。其他部分可使用默認的內(nèi)容無需更改，配置完成后保存即可。外部打印機程序?qū)⒆x取該配置文件信息，獲取存放傳真文件的路徑和目錄并從該目錄中獲取要發(fā)送傳真的文件，轉(zhuǎn)換格式后提交給服務端發(fā)送。三、EastFax客戶端發(fā)送接口說明使用EastFax客戶端發(fā)送接口時需要安裝East

15、Fax客戶端程序，可以實現(xiàn)每個用戶在自己電腦的業(yè)務系統(tǒng)（如ERP、CRM）中直接發(fā)送傳真，無須打開新建傳真窗口和輸入傳真號碼，傳真內(nèi)容直接提交給服務器發(fā)送，極大提高工作效率。EastFax客戶端發(fā)送接口的流程圖如下圖：3.1實現(xiàn)原理第一步：在業(yè)務系統(tǒng)（如ERP、CRM）中增加“發(fā)送傳真”的按鈕，用戶點擊“發(fā)送傳真”時，業(yè)務系統(tǒng)將當前發(fā)送時間、收件人傳真號碼、傳真流水號、傳真優(yōu)先級等信息寫入EastFax客戶端的配置文件EastFaxC.ini中。第二步：業(yè)務系統(tǒng)調(diào)用“EastFax”虛擬打印機將當時要發(fā)送的內(nèi)容，EastFax虛擬打印機自動轉(zhuǎn)換當前要發(fā)送的內(nèi)容為傳真所需的TIFF格式文件并提交

16、給客戶端。第三步：EastFax客戶端程序會自動從EastFaxC.ini配置文件中讀取發(fā)送信息并將文件提交給服務器進行發(fā)送。傳真發(fā)送后，發(fā)送結(jié)果可以反饋到客戶端，也可以在服務端直接把結(jié)果回傳到業(yè)務系統(tǒng)的數(shù)據(jù)庫中。3.2客戶端配置文件內(nèi)容在EastFax客戶端安裝目錄下，客戶端的配置文件為EastFaxC.ini。打開配置文件，可以看到如下章節(jié)和字段：ExternalPrintPrintTime=Receiver=Subject=Priority=1SerialNo=SuccessReceiverSmsInd=NoErrorSenderSmsInd=NoNewFaxDialog=Yes提示：由

17、于各臺主機的EastFax客戶端可能安裝在不同路徑，因此要獲得該配置文件的路徑，可通過注冊表路徑:HKEY_LOCAL_MACHINESOFTWAREForwaveEastFaxPrinterApps下的字符串值，獲得當前主機EastFax客戶端的安裝路徑即可。3.3配置文件使用說明當用戶在業(yè)務系統(tǒng)點擊“發(fā)達傳真”時，業(yè)務系統(tǒng)首先修改EastFaxC.ini配置文件中的上述對應字段，然后調(diào)用“EastFax”虛擬打印機虛擬打印當前頁面即可。對于上述字段的描述如下：PrintTime=當前的打印時間，格式為：年月日時分秒，如：20070128111308，表示打印時間為2007年1月28號11時

18、13分8秒；Receiver=收件人的傳真號碼，也即是所要發(fā)送的傳真號碼?？商顚懚鄠€號碼群發(fā)，每個號碼之間用分號分割即可。也可以實現(xiàn)不同號碼顯示不同的接收者信息，填寫格式為：Receiver=02155666857(Company1/Name1);65654240(Company2/Name2);55666860*801（Company3/Name3）;01087654321,801（Company4/Name4）；Subject=傳真主題，可顯示在對方收到文件的頁眉或頁腳上；Priority=傳真優(yōu)先級，分三個級別0、1、2，0最低，2最高，默認級別為1；SerialNo=傳真流水號，可在業(yè)

19、務系統(tǒng)中生成該傳真流水號并與傳真對應；SuccessReceiverSmsInd=服務端發(fā)送成功之后是否需要給收件人發(fā)送短信通知對方接收傳真，Yes表示需要，No表示不需要，默認為No；ErrorSenderSmsInd=服務端發(fā)送失敗之后是否需要給發(fā)件人發(fā)送短信通知，Yes表示需要，No表示不需要，默認為No；NewFaxDialog=是否需要顯示新建傳真窗口，Yes表示需要，No表示不需要，默認為Yes；當上述字段被修改后，再通過“EastFax”虛擬打印機虛擬打印文件時，客戶端程序?qū)凑丈鲜鲎侄蔚膬?nèi)容自動發(fā)送傳真，不再彈出新建傳真的對話框。如果打印過程中發(fā)生失敗，或者由于其它一些原因想取

20、消這次的信息自動填入功能，那只需要將PrintTime字段設(shè)置為空就可以了。PrintTime用于標識一次打印活動，不同的值表示不同的打印活動，在本次打印請求處理完成之后，程序會在相同的ExternalPrint章節(jié)添加一個TreatTime字段，其值就為PrintTime的值，如上例中：TreatTime=20070128111308，就表示這次的請求已經(jīng)處理完成了，下次就不再次處理了。因此并不影響一般的其他普通文檔（如Word,Excel等）通過打印的方式發(fā)送。對于下一次的打印，只需要設(shè)置新的PrintTime就可以了。四、發(fā)送結(jié)果的處理當通過接口方式將傳真發(fā)送完成后，對于發(fā)送結(jié)果的查看有

21、兩種方式：（一）如果使用的是客戶端發(fā)送接口，則可以在客戶端軟件界面中查看發(fā)送結(jié)果。打開客戶端界面，在“已發(fā)送的傳真”中查看發(fā)送結(jié)果。如果采用的是服務端接口的群發(fā)方式并且為每個傳真都添加了帳號，則該傳真在發(fā)送完成后會自動同步到EastFax客戶端軟件中，也可以在客戶端軟件中查看傳真。（二）在業(yè)務系統(tǒng)的數(shù)據(jù)庫中查看。在服務端將傳真發(fā)送完畢后會生成一個格式為efr的結(jié)果文件，記錄有傳真流水號、發(fā)送時間，發(fā)送結(jié)果、對方號碼等等信息，并保存在服務端安裝目錄下的“FaxResult”文件夾中。EastFax提供相應的EastFaxResultExt結(jié)果回傳程序用于讀取該結(jié)果文件中的信息并將結(jié)果寫入業(yè)務系統(tǒng)

22、的數(shù)據(jù)庫中。該結(jié)果回傳程序運行的規(guī)則如下：1、要實現(xiàn)上述的傳真結(jié)果自動反饋到指定的數(shù)據(jù)庫里，對應的數(shù)據(jù)庫必須有按以下規(guī)則建立的表：（1）表名：FAXSTAT（2）字段名與配置文件的設(shè)置SEND_ACCOUNTVARCHAR發(fā)送者帳號SEND_BEGINVARCHAR發(fā)送時間RETRY_TIMENUMBER發(fā)送次數(shù)TOTAL_PAGENUMBER傳真頁數(shù)STATUSNUMBER傳真結(jié)果ORD_NOVARCHAR傳真流水號RECV_INDEXNUMBER接收者序號，每個流水號從1開始RECV_NUMBERVARCHAR對方傳真號碼RECV_NAMEVARCHAR對方姓名RECV_COMPANYVA

23、RCHAR對方公司名稱SEND_CNTNUMBER同RETRY_TIMESENDED_PAGENUMBER已發(fā)送的頁數(shù)各字段長度的大小可靈活設(shè)置，只要保證足夠容納回傳的信息即可，可盡量設(shè)置長一些。在服務器的安裝目錄下面，有一個結(jié)果回傳器的配置文件，名為“EastFaxRE.ini”。雙擊打開該配置文件，可以看到里面包含與數(shù)據(jù)庫連接的相關(guān)信息如下：DatabaseUserName=PassWord=；一旦定義SNoMaxLength字段，則結(jié)果回傳時對流水號超出該字段值的結(jié)果提醒用戶流水號過長，回傳失敗。默認為50SNoMaxLength=;Validvaluecanbe3,0,2,1,plea

24、setryRecordsetType=3在UserName和PassWord后面分別填寫連接數(shù)據(jù)庫所需的用戶名和密碼，RecordsetType默認值為3，使用動態(tài)指針，由于各數(shù)據(jù)庫所支持的指針類型不一樣，所以可能需要嘗試更改該值進行類型的匹配，可能的值分別為0、1、2、3四種。EastFax采用ODBC中數(shù)據(jù)源連接的方式連接數(shù)據(jù)庫，除了在上述配置文件中保存相應的信息外，還需要在系統(tǒng)的ODBC中建立一個系統(tǒng)數(shù)據(jù)庫連接。打開控制面板中的“數(shù)據(jù)源（ODBC）”項目，切換到“系統(tǒng)DSN”標簽，在此添加一個自己所用數(shù)據(jù)庫的數(shù)據(jù)源，名稱為EastFaxResultExt。只有在此測試通過EastFax方

25、能正確連接數(shù)據(jù)庫。以SQLServer數(shù)據(jù)庫為例，首先點擊“系統(tǒng)DSN”中的“添加”按鈕，彈出如下窗口：輸入數(shù)據(jù)源名稱EastFaxResultExt和數(shù)據(jù)庫的服務器名稱，下一步，選擇數(shù)據(jù)庫的認證方式，輸入對應的用戶名和密碼，認證方式、用戶名和密碼都正確才可進入下一步。更改默認數(shù)據(jù)庫為FAXSTAT表所在的數(shù)據(jù)庫。一般語言等其他選項無需更改，點擊完成進入下一步，在此可點擊“測試數(shù)據(jù)源”按鈕測試之前配置是否通過連接，測試成功時連接如下圖：點擊“確定”按鈕回到系統(tǒng)DSN界面，可看到名為EastFaxResultExt的數(shù)據(jù)源已被建立。（3）用戶可以按照自己的需求在FAXSTAT表中添加其他列，當用

26、戶生成傳真文件和流水號時，可事先將傳真流水號寫入表的ORD_NO列中，并將接收者序號填入表的RECV_INDEX列中，同時在其他自定義的列中輸入其他信息以便后續(xù)的查詢。（4）對于發(fā)送傳真的結(jié)果信息，當有其他需求時，可另行協(xié)商定制開發(fā)結(jié)果字段。（5）對于一般支持ODBC連接的數(shù)據(jù)庫，通過上述方式均可實現(xiàn)傳真結(jié)果的回傳，對于某些特殊的或不支持ODBC連接的數(shù)據(jù)庫，可另行協(xié)商定制開發(fā)結(jié)果回傳程序。2、對于傳真結(jié)果的處理，在FAXSTAT表的“STATUS”列中對應的傳真結(jié)果如下：0:管理員刪除1:成功3:服務端取消4:客戶端取消11:傳真文件錯誤12:傳真號碼錯誤13:用戶帳號錯誤14:用戶沒有權(quán)限

27、21:Modem不支持傳真操作22:初始化Modem錯誤23:沒有撥號音24:撥號錯誤25:沒有回鈴音26:長時間靜音27:協(xié)商傳真通訊參數(shù)錯誤28:錯誤的傳真標識29:對方占線30:無人接聽或是空號31:用戶取消32:超時錯誤99:未知錯誤100：外部打印機轉(zhuǎn)換失敗3、若在結(jié)果連續(xù)提交三次仍不能成功提交到數(shù)據(jù)庫后，EastFaxResultExt結(jié)果回傳程序?qū)⒃贔axResult文件夾下的ErrorRE文件夾中再建立一級子文件夾，并以當前的日期命名?；貍鞑怀晒Φ膃fr結(jié)果文件將被轉(zhuǎn)移至該文件夾中保存。4、當有回傳不成功的情況出現(xiàn)時，在服務器安裝目錄中的log文件將有記錄信息。Log文件名為E

28、astFaxRE*.log，“*”號代表0、1、2三個數(shù)字，EastFaxRE0.log為最新的log，根據(jù)該log文件大體可判斷回傳不成功的原因。5、用戶可在自己的系統(tǒng)中開發(fā)查詢程序，讀取上述的FAXSTAT表并顯示發(fā)送結(jié)果。五、EastFax接收接口說明EastFax提供外部接口程序EastFaxPostRecv.exe，專門用于處理服務端接收下來的傳真文件，并按照指定的格式將文件存放到指定的路徑下。當購買了此模塊的授權(quán)，使用該接口程序非常簡單，只需將該文件拷貝到服務端安裝目錄下即可，該程序會隨服務端程序運行而自動運行。拷貝好文件后，還需要進行幾點設(shè)置，打開服務端安裝目錄下的EastFax

29、S.ini配置文件，在General章節(jié)中增加以下內(nèi)容：GeneralPostRecvDir=/設(shè)置用于存放轉(zhuǎn)換后的文件的絕對路徑，缺省為【程序目錄】PostRecv，例如可以設(shè)置為D盤根目錄下的Recv文件夾D:Recv，網(wǎng)絡(luò)路徑也可以，如192.168.1.10PostRecv。路徑中支持轉(zhuǎn)義字，轉(zhuǎn)義字見后面的說明。比如根據(jù)來電號碼分類存放文件，可以設(shè)置路徑為D:RecvCallerID,這樣不同來電號碼發(fā)送過來的傳真都可以歸類到以該來電號碼命名的文件夾。PostRecvFile=/最終文件的文件名格式，以轉(zhuǎn)義字表示，轉(zhuǎn)義字見后面的說明，缺省為FaxExt_FileName。RecvExtName=/設(shè)置接收進來的傳真內(nèi)容的格式，可以是bmp,jpg,gif,tiff,PDF，png等。JpgQuality=20/只對生成JPG文件時有用，取值范圍是0100，默認為20，數(shù)值越大轉(zhuǎn)換后的圖片質(zhì)量越好，但文件所占空間也越大。PostRecvDir和PostRecvFile都支持轉(zhuǎn)義字，可通過轉(zhuǎn)義字定義不同的名稱。下面列出的中的內(nèi)容就表示轉(zhuǎn)義字（下面舉例時，以20080407_213216