RAS SDK部分翻譯

Remote Access Service(RAS)

   RAS 讓使用者能夠在遠端通路一個或多個RAS伺服器，就像直接連到了計算機網絡.

About Remote Access Service

   Microsoft Windows 能使RAS客戶應用程式執行如下功能:

   1.顯示任何RAS通用對話框.包括主要的Dial-Up Networking對話框，Dial-Up Networking Monitor

    屬性頁，和其他對話框用來建立，編輯，複制，或撥号

   2.通過使用對話框或低級撥号函數來開始和停止RAS連接配接操作。

   3.通過通用對話框或低級phone-book函數來建立，編輯，複制 phone-book條目

   4.與RAS自動撥号資料庫中的内容一起使用，這個資料庫映射了網絡位址到phone-book的條目，這些條   目能和一個網絡位址建立連接配接

   5.取得RAS資訊，包括存在的RAS連接配接資訊，本機上RAS相容裝置的配置資訊和當一個RAS連接配接開始或結   束的通知消息

  Windows NT 版本4.0同時也提供RAS伺服器的管理，第三方的對RAS伺服器的安全性的擴充和連接配接管理。

  windows 95  沒有提供.

RAS Common Dialog Boxes

Windows NT版本4.0提供了一個函數集合，用來顯示系統提供的RAS對話框。這些函數使得應用程式顯示一個熟悉的使用者接口以便讓他們執行RAS任務，如建立和監視連接配接，或處理phone-book條目。Windows95沒有支援。

RasPhonebookDlg函數顯示Dial-Up Networking 對話框。使用這個對話框，使用者可以撥号，編輯，或删除一個選中的phone-book條目,建立一個新的phone-book條目,或指定使用者的選擇。這個函數使用RASPBDLG結果作為指定的附加輸入輸出參數.例如，你能夠設定這結構的成員來改變對話框的螢幕上的顯示位置，你也可以使用這個結構來指定一個RasPBDlgFunc的回調函數，這個函數來接受使用者活動通知消息當對話框打開的時候.例如，RAS調用你的RasPBDlgFunc函數如果你在撥号，編輯，或建立，或删除一個phone-book項目。

你可以使用RasDialDlg函數開始一個RAS連接配接操作而不通過顯示主Dial-Up-Networking 對話框。使用RasDialDlg，你能指定一個電話号碼或phone-book中的項目來進行撥号。這個函數顯示一串對話框，他們包括連接配接的狀态。RasDialDlg使用RASDIALDLG結構指定附加資訊，例如對話框的位置，和phone-book的子項目的調用。

你可以調用RasEntryDlg函數來顯示一個屬性頁，用來建立，編輯，複制一個phone-book 項目.RasEntryDlg使用一個RASENTRYDLG結構作為附加資訊的輸入輸出，例如對話框的位置，和顯示在最上面的屬性頁。

RAS Connection Operations

Windows NT版本4.0使用RasPhonebookDlg 和 RasDialDlg函數來顯示内建的使用者接口來開始RAS連接配接操作。多大多數應用程式來說，這是一個使用RAS的好的開始。Windows 95沒有支援。

下面的部分來描述使用低級函數建立RAS連接配接.這些函數在Windows NT 和Windows 95 上都可以使用。

一個RAS客戶應用程式使用RasDial函數來建立到伺服器的連接配接。RasDial函數開始連接配接操作，這個操作然後又由Remote Access Connection Manager來執行。

Remote Access Connection Manager是一個服務，他來處理建立連接配接的細節。他同時也提供客戶在建立連接配接時的狀态。Remote Access Connection Manager 自動開始當應用程式載入RASAPI32.DLL時。

當開始連接配接時，RasDial指定以下資訊：

1.連接配接資訊，他是Remote Access Connection Manager需要的用來建立連接配接。

2.一個可選的通知消息處理器，他用來接受建立連接配接中的程序通知消息。如果RasDial指定一個通知消息處理器，那麼這個調用是異步的，否則是同步的。

3.一個可選的RASDIALEXTENSIONS結構來激活或禁止對RasDial的擴充.這些擴充讓RAS客戶直接設定modem的配置,來控制RAS是否使用字首和字尾在電話本項目中,以及支援暫停在連接配接操作時.

Synchronous Operations

當RasDial以同步方式調用時,這個函數直到連接配接建立或錯誤發生時才傳回.同步模式提供了一種簡單的方式讓RAS客戶建立一個連接配接.客戶能簡單的調用RASDIAL,等待函數傳回,然後調用RasGetConnecStatus函數來決定連接配接操作是否成功.一旦操作成功,客戶程式要決定能否終止而不打斷連接配接.如果錯誤發生,程式必須關閉連接配接操作在終止之前.

 同步的缺點是客戶不能接受程序通知消息,當沒有程序通知消息時,同步客戶可以使用一個獨立的線程來調用RasGetConnectStatus檢測和顯示目前狀态.然而,對于想接受程序資訊的客戶來數,最好的技術是異步調用.

Asynchronous Operations

當RasDial被異步調用時,函數立即傳回.在異步模式中,RasDial調用必須要指定通知消息處理器,他是由Remote Access Connection Manager使用來通知客戶什麼時候連接配接操作改變狀态,什麼時候錯誤發生.

通知消息處理器能使一個視窗來接受消息,或是一個RasDialFunc,RasDialFunc1,或RasDialFunc2回調函數,Remote Access Connection Manager在調用RadDial的線程的上下文中産生消息.由于這個原因,調用線程不能終止直到連接配接操作完成,或錯誤産生.當在異步模式下時,應用程式能安全的終止當連接配接一旦建立,但是他必須關閉連接配接操作如果有錯誤時.

Phonebook Files and Connection Information

一個RasDial調用必須指定由Remote Access Connection Manager使用的資訊.一般來說,RasDial通過使用指定的 phone-book項目來提供連接配接資訊.連接配接資訊在phonebook項目中,包含有電話号,bps速率,使用者認證資訊和其他連接配接資訊.

一個RAS客戶使用RasDial函數的參數來指定一個電話本檔案和在檔案中的項目.lpszPhonebookPath參數能指定電話本檔案的名字,或者是NULL用來包含預設的電話本檔案.lpRasDialParams參數指向RASDIALPARAMS結構,他用來指定電話本的項目的名字.

為了顯示電話本項目的清單,并從中選擇一個連接配接,RAS 客戶調用RasEnumEntries函數來枚舉在電話本檔案中的項目.

為了建立一個連接配接而不使用電話本項目,RasDial指定一個空的字元串為RASDIALPARAMS:szEntryName。 RASDIALPARAMS.szPhoneNumber 必須包含撥号的電話。在這種情況下，Remote Access Connection Manager 使用第一個可用的貓端口和預設值為其他設定。

User Authentication Information

Remote Access Connection Manager 服務發送一個使用者名和密碼到RAS伺服器上。在這之前他要建立一個連接配接，遠端伺服器使用這個資訊來認證使用者。預設的，Remote Access Connection Manager發送使用者名和目前登入的使用者密碼。RAS客戶使用RASDIALPARAMS結構來指定RasDial的不同使用者名和密碼.

如果遠端伺服器不能認證,他允許連接配接操作今人暫停狀态來激活RAS 客戶收集不同的認證資訊.

Other Connection Information

RASDIALPARAMS的成員也能指定如下連接配接資訊:

1.能覆寫在電話本中的電話号碼

2.一個回調電話号碼,用來讓遠端伺服器調用建立連接配接

3.遠端網絡的域名

例如回調号碼和域名,RASDIALPARAMS成員或者訓示RAS 使用電話本中的資訊或者使用資料覆寫電話本中的資料.

一個RAS客戶能使用RasDial函數的lpRasDialExtension 參數控制RAS是否使用電話字首或字尾.

Connection States

在處理連接配接到遠端伺服器中,Remote Access Connection Manager 和RAS伺服器執行不同的步驟來建立連接配接.每一步被标志為連接配接狀态.RASCONNSTATE枚舉值是相應連接配接狀态的值得集合.

Running states   The running states are the parts of the connection operation that RAS handles        automatically, such as connecting to the necessary devices, authenticating the user,       and waiting for a callback from the remote server. Unless an error occurs, the RAS       client need take no action other than to pass the notification on to the user.

Paused states   The paused states occur when the remote server pauses the connection operation to get additional     input from the user. During a paused state, the user can type a callback number, a different user     name and password if the user authentication fails, or a new password if the old one has expired.

Terminal states  The terminal states occur when the connection has been successfully established, the connection     operation has failed, or the connection has been broken by a RasHangUp call.

有好幾種機制能讓RAS客戶決定目前的狀态.當RAS 客戶異步執行RASDial函數時, 當連接配接狀态變化時,Remote Access Connection Manager 發送程序通知資訊給客戶的通知消息處理器.另外,客戶使用RasGerConnectStatus函數來取得目前連接配接狀态.

注:客戶程序向RAS服務程序提供資訊,然後 RAS服務發送資訊給我.連接配接由RAS完成

Notification Handlers

異步調用RasDial必須使用通知消息處理器.在異步連接配接操作中,Remote Access Connection Manager 使用通知來給RAS客戶提供目前連接配接狀态是否發生了變化或錯務發生.

通知消息處理器的動作被分成以下的種類:

1.處理錯誤

2.提供回報給使用者黨連接配接操作完成時

3.處理暫停狀态(注:認證資訊不對産生)

4.通知RAS 客戶程式連接配接建立完成

這裡有三種通知消息處理器的類型,每種接受同樣的基本資訊:目前狀态,錯誤代碼,他是非0的數

RasDialFunc   A callback function prototype that receives only the current connection state and error code      information.

RasDialFunc1   A callback function prototype that receives the HRASCONN connection handle and extended error      information in addition to the basic information. The connection handle parameter makes RasDialFunc1    useful for client applications that support multiple simultaneous connection operations. This allows    the client to specify the same callback function for all operations, and enables the       callback function to determine which connection is changing states.

Window handle   A window handle to which RAS sends WM_RASDIALEVENT messages containing the current connection state     and error code information. Use this method if your source code must be compale with 16-bit      Windows, because 16-bit Windows does not support either of the callback functions.

Remote Access Connection Manager 挂起連接配接操作直到處理器傳回.是以處理器必須盡快傳回除非有錯誤發生.

RasDial函數不應在處理器中調用,但其他可以(RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp)

Handling RAS Errors

當錯誤發生時,

Remote Access Connection Manager 調用客戶程式的處理器.處理器訓示連接配接狀态當錯誤發生時,一個代碼表示一個錯誤.在這種情況下,處理器調用RasHangUp來結束RAS連接配接.

RAS 客戶程式使用RasGetErrorString 函數來顯示錯誤描述

Informational Notifications

連接配接狀态被認為是運作時狀态，隻有錯誤發生時才要處理器的行動。運作狀态在連接配接操作中發生，就像連接配接到必要的裝置，認證使用者和等待伺服器的回調。通知是一個簡單的處理報告給客戶程式。

客戶程式能有選擇的将一些資訊傳給使用者。在一些運作時狀态，客戶程式可能要顯示附加資訊。例如一個收到RASCS_ConnectDevice通知的處理器通過調用RasGetConncetStatus來取得名字和已連接配接的裝置類型.另一個是當客戶收到RASCS_Projected時，當RAS連接配接工程解析完成時發出這個消息。客戶程式調用RasGetPrjectinInfo函數來取得關于工程的附加資訊。客戶程式使用這些資訊來通知使用者當網絡協定可用時。

你應該避免寫一些依靠于特定消息發生順序的代碼，應為可能在不同的平台上。

Completion Notifications

Remote Access Connection Manager 繼續處理通知直到連接配接被完成。這個發生在以下情況：

1.連接配接建立。處理器收到RASCS_Connected通知.RAS 客戶程式能退出而不中斷連接配接.

2.錯誤發生.處理器收到一個訓示錯誤的消息和連接配接狀态.

3.連接配接操作中斷使用RasHangUp。

Paused States

.......

Callback Connections

.......

Disconnecting

當RAS客戶程式開始連接配接操作 ，RasDial收到HRASCONN句柄來标志連接配接。如果句柄不是NULL，客戶調用RasHangUp來結束連接配接。如果在連接配接操作中因錯誤中斷，客戶程式必須調用RasHangUp盡管連接配接沒有建立。

應用程式調用RasHangUp後不要立即退出，因為Remote Access Connection Manager需要時間終止連接配接。的卻，應用程式等待直到RasGetConnectStatus函數傳回ERROR_INVALID_HANDLE,訓示連接配接已經删除.

RAS客戶程式可能需要結束一個連接配接即使他沒有RasDial傳回的句柄.例如,調用RasDial的應用程式可能退出了當連接配接成功建立.

在這種情況下,将要結束連接配接的程式使用RasEnumConnections 來得到所有的目前連接配接.對每個連接配接,RasEnumConnections傳回一個RASCONN結構

,其中包含HRASCONN 句柄和電話項目的名字或當連接配接時指定的電話号碼.這些資訊來給使用者提供一個清單讓他們選擇要結束的連接配接.

RAS Phone Books

電話本提供了一種标準的方式來收集和指定Remote Access Connection Manager建立連接配接需要的資訊。電話本将一些資訊和項目名字關聯起來，資訊象電話号碼，COM端口，和modem設定。每個電話本項目包含建立RAS連接配接的必要資訊。WindowsNT：電話本存在電話本檔案中，他們是文本檔案，包含項目名和相關資訊。RAS建立一個電話本叫做RASPHONE.PBK。使用者使用主要的Dial-Up Networking對話框來建立私人的電話本檔案。Win32 擋牆不支援建立電話本的函數。一些RAS函數，想RadDial要有一個參數指定電話本檔案。如果調用者必指定一個電話本檔案，函數使用預設的電話本檔案，那是一個由有使用者在User Preferences屬性頁中設定的值。

Windows NT 4.0使用RasPhonebookDlg和RasEntryDlg函數來顯示内建的RAS使用者接口，他們是使用者能處理電話本和電話本項目

Windows 95: Dial-up networking stores phonebook entries in the registry rather than in a phonebook file. Windows 95 does not support personal phone-book files. Windows 95 does not support the functions that display the built-in RAS dialog boxes.

Phone-book Entries

電話本項目包含建立連接配接的必要資訊。使用者或管理者能使用Dial-Up Networking對話框來建立和編輯電話本項目。

Windows 95: Windows 95 supports a limited set of the Win32 functions for working with phone-book entries. You can use the RasCreatePhonebookEntry and RasEditPhonebookEntry functions to create or edit a phone-book entry. These functions display a dialog box in which the user can specify information about the phone-book entry. You can use the RasGetEntryDialParams and RasSetEntryDialParams functions to set or retrieve the connection parameters for a phone-book entry. The RasEnumEntries function retrieves an array of RASENTRYNAME structures that contain the phone-book entry names.

Windows NT 4.0支援Windows 95這些函數，同時也增加了一些函數。

RasEntryDlg函數顯示一個屬性頁，它使使用者建立，編輯或複制電話本項目。RasCreatePhonebookEntry和RasEditPhonebookEntry 調用RasEntryDlg函數。你使用RasRenameEntry函數來重名命項目或使用RasDeleteEntry來删除項目。RasValidateEntryName決定指定的字元串能否被用作項目名。

你使用RasGetEntryProperties和RasSetEntryProperties來取得和設定關于電話本項目的附加資訊.這些函數使用RASENTRY結構.

RasGetCredentials和RasSetCredential取得和設定使用者認證資訊.使用RASCREDENTIALS結構.

RasGetCountryInfo 取得指定國家的撥号資訊.這些函數使用RASCTRYINFO結構.

Subentries and Multilink Connections

.........

RAS AutoDial

Windows NT版本4支援一個自動撥号的特點.Windows NT 3.51和Windows 95不支援.

當企圖連接配接一個網絡位址失敗時因為主機不能到達,自動撥号的特點是能自動的開始撥接上網.要做到這一點,自動撥号查找查找自己的網絡位址資料庫來找到建立連接配接的位址.

自動撥号映射資料到RAS電話本項目.資料庫包含ip位址,域名,或NetBIOS名.相關的每個位址在自動撥号的資料庫裡是一個或多個RASAUTODIALENTR項目.每個項目指定一個電話本項目,他們能被撥号到的位址從TAPI中開始.

自動撥号建立項目在自動撥号資料庫裡有兩種情況:

1.當連接配接到一個網絡位址失敗

如果沒有位址項目在映射資料庫裡,計算機不能連接配接到網絡,自動撥号提示使用者指定必須的資訊來建立一個連接配接.如果使用者提供資訊,

并撥号成功,自動撥号儲存資訊在映射資料庫裡.

2.當電腦被連到了網絡通過RAS

無論什麼時候,使用者連接配接到網絡位址,自動撥号在資料庫裡建立一個項目.這個項目映射網絡位址到電話本中的項目,他們是被用過的RAS連接配接

你能使用RasSetAutodialAddress函數來增加一個位址到自動撥号資料庫裡,删除一個位址,或改變一個位址.

你能使用RasGetAutodialAddress函數來取得與指定網絡位址相應的自動撥号項目在自動撥号資料庫裡。RasEnumAutodialAddress函數傳回所有自動撥号資料中的位址.