Phonebook

RAS can set up communication to remote servers by using phonebook entries to store and manage properties for establishing a connection. A phonebook is nothing more than a collection of RASENTRY structures that contain phone numbers, data rates, user authentication information, and other connection information. On Windows 95, Windows 98, and Windows CE, the phonebook is stored in the system Registry. On Windows 2000 and Windows NT, the phonebook is stored in files that typically have the file extension .pbk. A RASENTRY structure is defined as

 typedef struct tagRASENTRY { DWORD dwSize; DWORD dwfOptions; DWORD dwCountryID; DWORD dwCountryCode; TCHAR szAreaCode[RAS_MaxAreaCode + 1]; TCHAR szLocalPhoneNumber[RAS_MaxPhoneNumber + 1]; DWORD dwAlternateOffset; RASIPADDR ipaddr; RASIPADDR ipaddrDns; RASIPADDR ipaddrDnsAlt; RASIPADDR ipaddrWins; RASIPADDR ipaddrWinsAlt; DWORD dwFrameSize; DWORD dwfNetProtocols; DWORD dwFramingProtocol; TCHAR szScript[MAX_PATH]; TCHAR szAutodialDll[MAX_PATH]; TCHAR szAutodialFunc[MAX_PATH]; TCHAR szDeviceType[RAS_MaxDeviceType + 1]; TCHAR szDeviceName[RAS_MaxDeviceName + 1]; TCHAR szX25PadType[RAS_MaxPadType + 1]; TCHAR szX25Address[RAS_MaxX25Address + 1]; TCHAR szX25Facilities[RAS_MaxFacilities + 1]; TCHAR szX25UserData[RAS_MaxUserData + 1]; DWORD dwChannels; DWORD dwReserved1; DWORD dwReserved2; #if (WINVER >= 0x401) DWORD dwSubEntries; DWORD dwDialMode; DWORD dwDialExtraPercent; DWORD dwDialExtraSampleSeconds; DWORD dwHangUpExtraPercent; DWORD dwHangUpExtraSampleSeconds; DWORD dwIdleDisconnectSeconds; #endif #if (WINVER >= 0x500) DWORD dwType; DWORD dwEncryptionType; DWORD dwCustomAuthKey; GUID guidId; TCHAR szCustomDialDll[MAX_PATH]; DWORD dwVpnStrategy; #endif } RASENTRY; 

As you can see, many fields make up this structure. The fields are defined as follows:

• dwSize Identifies the size (in bytes) of a RASENTRY structure.
• dwfOptions Can be set to one or more flags described in Table 16-4.

Table 16-4. RASENTRY structure option flags

Option Flag	Description
RASEO_Custom	On Windows 2000, custom encryption is used.
RASEO_DisableLcpExtensions	RAS disables the PPP LCP extensions defined in RFC 1570.
RASEO_IpHeaderCompression	RAS will negotiate IP header compression over a PPP connection.
RASEO_ModemLights	On Windows 2000, the task bar will display a status monitor.
RASEO_NetworkLogon	On Windows 95 and Windows 98, RAS will attempt to log the user on to a domain only after the RAS connection is authenticated.
RASEO_PreviewDomain	On Windows 2000, RAS will display the user's domain before dialing.
RASEO_PreviewPhoneNumber	On Windows 2000, RAS will display the phone number to be dialed.
RASEO_PromoteAlternates	RAS can make an alternate number the primary number if the alternate number connects successfully.
RASEO_RemoteDefaultGateway	The default route for IP packets is via the dial-up adapter rather than via other network adapters when the RAS connection is active.
RASEO_RequireCHAP	On Windows 2000, the Challenge Handshake Authentication Protocol (CHAP) will be used for authentication.
RASEO_RequireDataEncryption	Data encryption must be negotiated successfully; otherwise, the connection should be dropped. The RASEO_RequireEncryptedPw flag also must be set.
RASEO_RequireEAP	On Windows 2000, EAP will be used for authentication.
RASEO_RequireEncryptedPw	This flag prevents PPP from using the Password Authentication Protocol (PAP) to authenticate the client. The CHAP and Shiva's Password Authentication Protocol (SPAP) are used instead.
RASEO_RequireMsCHAP	On Windows 2000, Microsoft CHAP will be used for authentication.
RASEO_RequireMsCHAP2	On Windows 2000, Microsoft CHAP version 2 will be used for authentication.
RASEO_RequireMsEncryptedPw	This flag overrides RASEO_RequireEncryptedPw and allows RAS to use Microsoft secure password schemes such as Microsoft CHAP.
RASEO_RequirePAP	On Windows 2000, PAP will be used for authentication.
RASEO_RequireSPAP	On Windows 2000, SPAP will be used for authentication.
RASEO_RequireW95MSCHAP	On Windows 2000, an older version of Microsoft CHAP (designed for Windows 95 RAS servers) is used for authentication.
RASEO_ReviewUserPW	On Windows 2000, RAS will display the user's name and password before dialing.
RASEO_SecureLocalFiles	On Windows 2000 and Windows NT, RAS checks for existing remote file system and remote printer bindings before making a connection with this entry.
RASEO_SharedPhoneNumbers	On Windows 2000, phone numbers are shared.
RASEO_ShowDialingProgress	On Windows 2000, RAS will display dialing progress.
RASEO_SpecificIpAddr	This flag tells RAS to use the IP address specified in the ipaddr field.
RASEO_SpecificNameServers	This flag tells RAS to use the IP information specified in the ipaddrDns, ipaddrDnsAlt, ipaddrWins, and ipaddrWinsAlt fields.
RASEO_SwCompression	This flag lets RAS negotiate software compression of data sent over a connection.
RASEO_TerminalAfterDial	RAS displays a terminal window for user input after dialing the connection.
RASEO_TerminalBeforeDial	RAS displays a terminal window for user input before dialing the connection.
RASEO_UseCountryAndAreaCodes	This flag tells RAS to use the dwCountryID, dwCountryCode, and szAreaCode fields to construct a phone number with the szLocalPhoneNumber field.
RASEO_UseLogonCredentials	This flag tells RAS to use the user name, password, and domain of the user who is currently logged on when dialing. This occurs only if the RASEO_RequireMsEncryptedPw flag is set.

• dwCountryID Specifies a TAPI country identifier if the RASEO_UseCountryAndAreaCodes option flag is set. You can retrieve country identifier information by calling the RasGetCountryInfo function (which we'll describe later).
• dwCountryCode Specifies a country code that is associated with the dwCountryID field if the RASEO_UseCountryAndAreaCodes option flag is set. If this field is 0, the country code associated with dwCountryID in Windows is used.
• szAreaCode Specifies an area code if the RASEO_UseCountryAndAreaCodes flag is set.
• szLocalPhoneNumber Specifies a phone number for dialing. If the RASEO_UseCountryAndAreaCodes flag is set, RAS will combine the values of the dwCountryID, dwCountryCode, and szAreaCode fields with your phone number.
• dwAlternateOffset Specifies an offset in bytes, from the beginning of this structure, where alternate phone numbers are stored for a RAS phonebook entry. Alternate numbers are stored as a consecutive set of null-terminated strings. The last string in the set is terminated by two consecutive null characters.
• ipaddr Specifies an IP address to use for this connection if the RASEO_SpecificIpAddr flag is set.
• ipaddrDns Specifies a DNS server IP address for this connection if the RASEO_SpecificNameServers flag is set.
• ipaddrDnsAlt Specifies a secondary DNS server IP address for this connection if the RASEO_SpecificNameServers flag is set.
• ipaddrWins Specifies a WINS server IP address for this connection if the RASEO_SpecificNameServers flag is set.
• ipaddrWinsAlt Specifies a secondary WINS server IP address for this connection if the RASEO_SpecificNameServers flag is set.
• dwFrameSize Changes the size of the framing protocol to 1006 or 1500 bytes if the RASFP_Slip flag is set in the dwFramingProtocol field.
• dwfNetProtocols Specifies the flags identifying which network protocols will be used over the framing protocol. The protocol flags are RASNP_NetBEUI for NetBEUI, RASNP_Ipx for IPX, and RASNP_Ip for IP.
• dwFramingProtocol Specifies the flags identifying which framing protocol will be used over the RAS connection. The possible flags are RASFP_Ppp for PPP, RASFP_Slip for SLIP, and RASFP_Ras for asynchronous NetBEUI.
• szScript Specifies a full path to a dial-up script that gets executed when starting the connection.
• szAutodialDll Specifies a customizable DLL that can be used to set automatic dialing (autodial) features of RAS. This book does not cover the details of managing RAS autodial features.
• szAutodialFunc Specifies the function name exported from the customized DLL in the szAutodialDll field.
• szDeviceType Specifies a device type that is used for a connection. The value should be identified as a string. Table 16-5 lists the possible values.

Table 16-5. RAS device types

Device Name String	Description
"RASDT_Modem"	Modem on a COM port
"RASDT_Isdn"	ISDN adapter
"RASDT_X25"	X.25 card
"RASDT_Vpn"	Virtual private networking (VPN) connection
"RASDT_Pad"	Packet assembler/disassembler
"RASDT_Generic"	Generic type
"RASDT_Serial"	Serial port
"RASDT_FrameRelay"	Frame relay device
"RASDT_Atm"	ATM device
"RASDT_Sonet"	Synchronous Optical Network (Sonet) device
"RASDT_SW56"	Switched 56-Kbps access
"RASDT_Irda"	IrDA device
"RASDT_Parallel"	Parallel port

• szDeviceName Identifies a TAPI device to use for a connection. You can retrieve TAPI devices using the RasEnumDevices function, which we will describe later.
• szX25PadType Specifies an X.25 PAD type.
• szX25Address Specifies an X.25 address.
• szX25Facilities Specifies facilities to request from the X.25 host.
• szX25UserData Specifies extra information for an X.25 connection.
• dwChannels Is not used.
• dwReserved1 Is not used and must be set to 0.
• dwReserved2 Is not used and must be set to 0.
• dwSubEntries Identifies how many multilink subentries are associated with this phonebook entry. You should set this field to 0 and let the RasSetSubEntryProperties function manage multilink subentries for this field. (More on this function later in this chapter.)
• dwDialMode Specifies in Windows 2000 how RAS should dial multilink subentries when a connection is made using the defines RASEDM_DialAll and RASEDM_DialAsNeeded. If this field is set to RASEDM_DialAll, all multilink subentries are dialed. If RASEDM_DialAsNeeded is set, RAS uses the dwDialExtraPercent, dwDialExtraSampleSeconds, dwHangUpExtraPercent, and dwHangUpExtraSampleSeconds fields to determine when to dial and disconnect additional multilink subentries.
• dwDialExtraPercent Specifies in Windows 2000 a percentage of the current total bandwidth of a connection. RAS will dial an additional subentry when the total bandwidth used exceeds this percentage for at least dwDialExtraSampleSeconds.
• dwDialExtraSampleSeconds Specifies in Windows 2000 the number of seconds by which current bandwidth usage must exceed the bandwidth percentage specified in dwDialExtraPercent before RAS dials an additional subentry.
• dwHangUpExtraPercent Specifies in Windows 2000 the percentage of total bandwidth available from the connected subentries. RAS will terminate subentry connections when the total bandwidth usage falls below this percentage for dwHangUpExtraSampleSeconds.
• dwHangUpExtraSampleSeconds Specifies in Windows 2000 the number of seconds by which current bandwidth usage must fall below the bandwidth percentage specified in dwHangUpExtraPercent before RAS disconnects a subentry.
• dwIdleDisconnectSeconds Specifies how many seconds of idle time are allowed before RAS will terminate the connection. You can also set this field to either RASIDS_Disabled to prevent the connection from terminating or RASIDS_UseGlobalValue to use the system's default value.
• dwType Specifies in Windows 2000 the type of phonebook entry. Table 16-6 lists the possible values.

Table 16-6. RASENTRY phonebook types

Type	Description
RASET_Direct	Direct serial or parallel connection
RASET_Internet	Internet connection services (ICS)
RASET_Phone	Phone line
RASET_Vpn	Virtual private network

• dwEncryptionType Specifies in Windows 2000 the type of encryption used on the data passed through the connection. Table 16-7 lists the possible values.

Table 16-7. Data encryption values used on a RAS connection

Value	Description
ET_40Bit	40-bit data encryption
ET_128Bit	128-bit data encryption

• dwCustomAuthKey Specifies on Windows 2000 an authentication key provided to the EAP vendor.
• guidId On Windows 2000, identifies a GUID associated with the phonebook entry.
• szCustomDialDll Specifies on Windows 2000 a path to a DLL containing custom RAS dialer functions. If this field is NULL, RAS will use the default system dialer. This book does not describe the details of developing a custom dialer for RAS.
• dwVpnStrategy Specifies on Windows 2000 the VPN dialing strategy to use on VPN connections. Table 16-8 lists the possible values.

Table 16-8. RAS VPN dialing strategies

Value	Description
VS_Default	RAS dials Point-to-Point Tunneling Protocol (PPTP) first. If PPTP fails, Layer 2 Tunneling Protocol (L2TP) is attempted.
VS_L2tpFirst	RAS dials L2TP first.
VS_L2tpOnly	RAS dials only L2TP.
VS_PptpFirst	RAS dials PPTP first.
VS_PptpOnly	RAS dials only PPTP.

When you call any RAS API that takes a phonebook file as a parameter (lpszPhonebook), you can identify the path to a phonebook file. As we mentioned earlier, this parameter must be NULL on Windows 95, Windows 98, and Windows CE because phonebook entries are stored in the system Registry. On Windows 2000 and Windows NT, this can be a path to a phonebook file. Typically, this phonebook file will have the extension .pbk. Also, the system default phonebook on Windows 2000 and Windows NT is located under %SystemRoot%\System32\Ras\RasPhone.pbk. If you specify NULL as the phonebook, you will use the system default phonebook file.

Three support functions can help you create and manage phonebook entries: RasValidateEntryName, RasEnumDevices, and RasGetCountryInfo. The RasValidateEntryName function, shown below, determines whether a name is properly formatted and whether it already exists in a phonebook.

 DWORD RasValidateEntryName( LPCTSTR lpszPhonebook, LPCTSTR lpszEntry ); 

The lpszPhonebook parameter is a pointer to a name of a phonebook file. The lpszEntry parameter is a string representing the phonebook entry name you are verifying. This function returns ERROR_SUCCESS if the name is not already in the phonebook and is properly formatted. Otherwise, the function fails—with ERROR_INVALID_NAME if the name is not correctly formatted; with ERROR_ALREADY_EXISTS if the name is in the phonebook.

The RasEnumDevices function receives the name and type of all RAS-capable devices available on your computer:

 DWORD RasEnumDevices( LPRASDEVINFO lpRasDevInfo, LPDWORD lpcb, LPDWORD lpcDevices ); 

The lpRasDevInfo parameter is a pointer to an application buffer that you must provide to receive an array of RASDEVINFO structures. The RASDEVINFO structure is defined as

 typedef struct tagRASDEVINFO { DWORD dwSize; TCHAR szDeviceType[RAS_MaxDeviceType + 1]; TCHAR szDeviceName[RAS_MaxDeviceName + 1]; } RASDEVINFOW; 

The fields of this parameter are defined as follows:

• dwSize Must be set to the size (in bytes) of a RASDEVINFO structure before you call RasEnumDevices
• szDeviceType Receives a string describing the device type, such as "RASDT_Modem"
• szDeviceName Receives the formal name of a TAPI device

You must be sure you provide a buffer that is large enough to hold several structures; otherwise, RasEnumDevices will fail with the error ERROR_BUFFER_TOO_SMALL. The next parameter, lpcb, is a pointer to a variable that receives the number of bytes needed to enumerate the devices. You must set this parameter to the size (in bytes) of your lpRasDevInfo buffer. The final parameter, lpcDevices, is a pointer to a variable that receives the number of RASDEVINFO structures written to lpRasDevInfo.

The RasGetCountryInfo function allows you to retrieve country-specific TAPI dialing information from Windows:

 DWORD RasGetCountryInfo( LPRASCTRYINFO lpRasCtryInfo, LPDWORD lpdwSize ); 

The lpRasCtryInfo parameter is a buffer that receives a dialing prefix and other information associated with the country you specify. This buffer must be a RASCTRYINFO structure that is followed by additional bytes that receive a country description string. We recommend allocating at least a 256-byte buffer to hold the RASCTRYINFO structure and the description string. The RASCTRYINFO structure is defined as

 typedef struct RASCTRYINFO { DWORD dwSize; DWORD dwCountryID; DWORD dwNextCountryID; DWORD dwCountryCode; DWORD dwCountryNameOffset; } RASCTRYINFO; 

The fields are described as follows:

• dwSize Must be set to the size (in bytes) of a RASCTRYINFO structure.
• dwCountryID Allows you to specify a TAPI country identifier (which applies to the dwCountryID field of a RASENTRY structure) in the Windows list of countries. If you set this field to 1, you will receive the first entry in the list.
• dwNextCountryID Receives the next TAPI country identifier in the list. If this field is set to 0, you are at the end of the list.
• dwCountryCode Receives the dialing prefix code associated with the country specified in the dwCountryID parameter.
• dwCountryNameOffset Specifies the number of bytes from the start of this structure to the start of the null-terminated string describing the country that follows the RASCTRYINFO structure.

The other parameter of RasGetCountryInfo, lpdwSize, is a pointer to a variable that receives the number of bytes that RasGetCountryInfo placed in the lpRasCtryInfo buffer. You must set this parameter to the size of your application buffer before calling this function.

Adding Phonebook Entries

RAS provides four functions that allow you to programmatically manage phonebook RASENTRY structures: RasSetEntryProperties, RasGetEntryProperties, RasRenameEntry, and RasDeleteEntry. You can use the RasSetEntryProperties function, which is defined below, to create a new entry or modify an existing entry.

 DWORD RasSetEntryProperties( LPCTSTR lpszPhonebook, LPCTSTR lpszEntry, LPRASENTRY lpRasEntry, DWORD dwEntryInfoSize, LPBYTE lpbDeviceInfo, DWORD dwDeviceInfoSize ); 

The lpszPhonebook parameter is a pointer to the name of a phonebook file. The lpszEntry parameter is a pointer to a string used to identify an existing entry or a new one. If a RASENTRY structure exists with this name, the properties are modified; otherwise, a new entry is created in the phonebook. The lpRasEntry parameter is a pointer to a RASENTRY structure. You can place a list of null-terminated strings after the RASENTRY structure defining alternate phone numbers. The last string is terminated by two consecutive null characters. The dwEntryInfoSize parameter is the size (in bytes) of the structure in the lpRasEntry parameter. The lpbDeviceInfo parameter is a pointer to a buffer that contains TAPI device configuration information. On Windows 2000 and Windows NT, this parameter is not used and should be set to NULL. The final parameter, dwDeviceInfoSize, represents the size (in bytes) of the lpbDeviceInfo buffer.

The RasGetEntryProperties function, defined below, can be used to retrieve the properties of an existing phonebook entry or the default values for a new phonebook entry.

 DWORD RasGetEntryProperties( LPCTSTR lpszPhonebook, LPCTSTR lpszEntry, LPRASENTRY lpRasEntry, LPDWORD lpdwEntryInfoSize, LPBYTE lpbDeviceInfo, LPDWORD lpdwDeviceInfoSize ); 

The lpszPhonebook parameter is a pointer to the name of a phonebook file. The lpszEntry parameter is a pointer to a string identifying an existing phonebook entry. If you set this parameter to NULL, the lpRasEntry and lpbDeviceInfo parameters will receive default values of a phonebook entry. Retrieving the default values is quite useful: when you need to create a new RAS phonebook entry, you can populate the lpRasEntry and lpbDeviceInfo fields with correct information about your system before you call the RasSetEntryProperties function.

The lpRasEntry parameter is a pointer to a buffer that your application supplies to receive a RASENTRY structure. As we described in our discussion of the RasSetEntryProperties function, this structure can be followed by an array of null-terminated strings identifying alternate phone numbers for the requested phonebook entry. Therefore, the size of your receiving buffer should be larger than a RASENTRY structure. If you pass a NULL pointer, the lpdwEntryInfoSize parameter will receive the total number of bytes needed to store all the elements of a RASENTRY structure plus any alternate phone numbers. The lpdwEntryInfoSize parameter is a pointer to a DWORD containing the number of bytes that are in the receiving buffer supplied by your application to the lpRasEntry parameter. When this function completes, it will update lpdwEntryInfoSize to the number of bytes actually received in lpRasEntry. We highly recommend calling this function with lpRasEntry set to NULL and lpdwEntryInfoSize set to 0 to obtain buffer sizing information. Once you have the appropriate size, you can call this function again and retrieve all the information without error.

The lpbDeviceInfo parameter is a pointer to an application-supplied buffer that receives TAPI device-specific information for this phonebook entry. If this parameter is set to NULL, the lpdwDeviceInfoSize parameter will receive the number of bytes needed to retrieve this information. If you are using Windows 2000 and Windows NT, lpbDeviceInfo should be set to NULL. The final parameter, lpdwDeviceInfoSize, is a pointer to a DWORD that should be set to the number of bytes contained in the buffer supplied to lpbDeviceInfo. When RasGetEntryProperties returns, lpdwDeviceInfoSize will return the number of bytes that are returned in the lpbDeviceInfo buffer.

Figure 16-3 demonstrates how an application should use RasGetEntryProperties and RasSetEntryProperties to create a new phonebook entry.

Figure 16-3. Creating a new RAS phonebook entry using default properties

 #include <windows.h> #include <ras.h> #include <raserror.h> #include <stdio.h> void main(void) { DWORD EntryInfoSize = 0; DWORD DeviceInfoSize = 0; DWORD Ret; LPRASENTRY lpRasEntry; LPBYTE lpDeviceInfo; // Get buffer sizing information for a default phonebook entry if ((Ret = RasGetEntryProperties(NULL, "", NULL, &EntryInfoSize, NULL, &DeviceInfoSize)) != 0) { if (Ret != ERROR_BUFFER_TOO_SMALL) { printf("RasGetEntryProperties sizing failed " "with error %d\n", Ret); return; } } lpRasEntry = (LPRASENTRY) GlobalAlloc(GPTR, EntryInfoSize); if (DeviceInfoSize == 0) lpDeviceInfo = NULL; else lpDeviceInfo = (LPBYTE) GlobalAlloc(GPTR, DeviceInfoSize); // Get default phonebook entry lpRasEntry->dwSize = sizeof(RASENTRY); if ((Ret = RasGetEntryProperties(NULL, "", lpRasEntry, &EntryInfoSize, lpDeviceInfo, &DeviceInfoSize)) != 0) { printf("RasGetEntryProperties failed with error %d\n", Ret); return; } // Validate new phonebook name "Testentry" if ((Ret = RasValidateEntryName(NULL, "Testentry")) != ERROR_SUCCESS) { printf("RasValidateEntryName failed with error %d\n", Ret); return; } // Install a new phonebook entry, "Testentry", using // default properties if ((Ret = RasSetEntryProperties(NULL, "Testentry", lpRasEntry, EntryInfoSize, lpDeviceInfo, DeviceInfoSize)) != 0) { printf("RasSetEntryProperties failed with error %d\n", Ret); return; } } 

Renaming Phonebook Entries

Now that you have an understanding of what's involved in creating and modifying a phonebook entry, let's look at the RasRenameEntry function. RasRenameEntry, which is defined below, simply allows you to rename a phonebook entry:

 DWORD RasRenameEntry( LPCTSTR lpszPhonebook, LPCTSTR lpszOldEntry, LPCTSTR lpszNewEntry ); 

The lpszPhonebook parameter is a pointer to a name of a phonebook file. The lpszOldEntry parameter is a pointer to a string identifying an existing phonebook entry that you intend to rename. The lpszNewEntry parameter is a pointer to a string containing the new name for the phonebook entry. Your application should call RasValidateEntryName on the new name before calling RasRenameEntry. If RasRenameEntry succeeds, it will return 0. If it fails, it will return the following types of errors:

• ERROR_INVALID_NAME Indicates that the lpszNewEntry name is invalid
• ERROR_ALREADY_EXISTS Indicates that the lpszNewEntry name already exists in the phonebook
• ERROR_CANNOT_FIND_PHONEBOOK_ENTRY Indicates that the lpszOldEntry name cannot be found in the phonebook

Deleting Phonebook Entries

Deleting phonebook entries is easy. To do so, you simply call the RasDeleteEntry function, which is defined as

 DWORD RasDeleteEntry( LPCTSTR lpszPhonebook, LPCTSTR lpszEntry ); 

The lpszPhonebook parameter is a pointer to a name of a phonebook file. The lpszEntry parameter is a string representing an existing phonebook entry. If this function succeeds, it returns ERROR_SUCCESS; otherwise, it returns ERROR_INVALID_NAME.

Enumerating Phonebook Entries

RAS provides a convenient function named RasEnumEntries, which retrieves the phonebook entries available in a phonebook file and is defined as shown below.

 DWORD RasEnumEntries ( LPCTSTR reserved, LPCTSTR lpszPhonebook, LPRASENTRYNAME lprasentryname, LPDWORD lpcb, LPDWORD lpcEntries ); 

The reserved parameter isn't used and must be set to NULL. The lpszPhonebook parameter is a pointer to the name of a phonebook file. The lprasentryname parameter is a pointer to an application buffer that you must provide to receive an array of RASENTRYNAME structures. The RASENTRYNAME structure is defined as

 typedef struct _RASENTRYNAME { DWORD dwSize; TCHAR szEntryName[RAS_MaxEntryName + 1]; #if (WINVER >= 0x500) DWORD dwFlags; CHAR szPhonebookPath[MAX_PATH + 1]; #endif } RASENTRYNAME; 

The fields are defined as follows:

• dwSize Must be set to the size (in bytes) of a RASENTRYNAME structure before you call RasEnumEntries.
• szEntryName Receives the name of a phonebook entry.
• dwFlags On Windows 2000, this flag indicates whether the phonebook entry is in the system default phonebook (described earlier) using flag REN_AllUsers or is in a user's profile phonebook using flag REN_User.
• szPhonebookPath On Windows 2000, specifies the full path to the phonebook file.

You must be sure you provide a buffer large enough to hold several structures; otherwise, RasEnumEntries will fail with the error ERROR_BUFFER_TOO_SMALL. The next parameter, lpcb, is a pointer to a variable that receives the number of bytes needed to enumerate the entries. You must set this parameter to the size (in bytes) of your lprasentryname buffer. The final parameter, lpcEntries, is a pointer to a variable that receives the number of RASENTRYNAME structures written to the lprasentryname buffer.

Managing User Credentials

When a RAS client makes a connection using a phonebook entry through RasDial, it saves the security credentials of the user and associates them with the phonebook entry. The functions RasGetCredentials, RasSetCredentials, RasGetEntryDialParams, and RasSetEntryDialParams allow you to manage user security credentials associated with a phonebook entry. The RasGetCredentials and RasSetCredentials functions were introduced in Windows NT 4. (They are also available on Windows 2000.) These two functions supersede RasGetEntryDialParams and RasSetEntryDialParams. Since RasGetCredentials and RasSetCredentials are not available on Windows 95, Windows 98, and Windows CE, you can use RasGetEntryDialParams and RasSetEntryDialParams for this purpose on all platforms.

The RasGetCredentials function, defined below, retrieves user credentials associated with a phonebook entry:

 DWORD RasGetCredentials( LPCTSTR lpszPhonebook, LPCTSTR lpszEntry, LPRASCREDENTIALS lpCredentials ); 

The lpszPhonebook parameter is a pointer to the name of a phonebook file. The lpszEntry parameter is a string representing an existing phonebook entry. The lpCredentials parameter, defined below, is a pointer to a RASCREDENTIALS structure that can receive the user name, password, and domain associated with the phonebook entry:

 typedef struct { DWORD dwSize; DWORD dwMask; TCHAR szUserName[UNLEN + 1]; TCHAR szPassword[PWLEN + 1]; TCHAR szDomain[DNLEN + 1]; } RASCREDENTIALS, *LPRASCREDENTIALS; 

The fields of this structure are defined as follows:

• dwSize Specifies the size (in bytes) of a RASCREDENTIALS structure. You should always set this field to the structure size.
• dwMask Is a bitmask field that identifies which of the next three fields in the structure are valid by using predefined flags. The flag RASCM_UserName applies to szUserName, RASCM_Password applies to szPassword, and RASCM_Domain applies to szDomain.
• szUserName Is a null-terminated string containing a user's logon name.
• szPassword Is a null-terminated string containing a user's password.
• szDomain Is a null-terminated string containing a user's logon domain.

If RasGetCredentials succeeds, it returns 0. Your application can determine which security credentials are set based on the flags set in the dwMask field of the lpCredentials structure.

The RasSetCredentials function is similar to RasGetCredentials except that it lets you change security credentials associated with a phonebook entry. The parameters are the same except that RasSetCredentials features an additional parameter: fClearCredentials. RasSetCredentials is defined as

 DWORD RasSetCredentials( LPCTSTR lpszPhonebook, LPCTSTR lpszEntry, LPRASCREDENTIALS lpCredentials, BOOL fClearCredentials ); 

The fClearCredentials parameter is a Boolean operator that, if set to TRUE, causes RasSetCredentials to change credentials identified in the dwMask field of the lpCredentials structure to an empty string ("") value. For example, if dwMask contains the RASCM_Password flag, the password stored is replaced with an empty string. If the RasSetCredentials function succeeds, it returns 0.

You can also use RasGetEntryDialParams and RasSetEntryDialParams to manage user security credentials associated with phonebook entries. RasGetEntryDialParams is defined as

 DWORD RasGetEntryDialParams( LPCTSTR lpszPhonebook, LPRASDIALPARAMS lprasdialparams, LPBOOL lpfPassword ); 

The lpszPhonebook parameter is a pointer to the name of a phonebook file. The lprasdialparams parameter is a pointer to a RASDIALPARAMS structure. The lpfPassword parameter is a Boolean flag that returns TRUE if the user's password was retrieved in the lprasdialparams structure.

The RasSetEntryDialParams function changes the connection information that was last set by the RasDial call on a particular phonebook entry. RasSetEntryDialParams is defined as

 DWORD RasSetEntryDialParams( LPCTSTR lpszPhonebook, LPRASDIALPARAMS lprasdialparams, BOOL fRemovePassword ); 

The lpszPhonebook and lprasdialparams parameters are the same as the first two parameters in RasGetEntryDialParams. The fRemovePassword parameter is a Boolean flag that, if set to TRUE, tells RasSetEntryDialParams to remove the password associated with the phonebook entry identified in the lprasdialparams structure.

Multilink Phonebook Subentries

On Windows 2000 and Windows NT, RAS allows you to manage multilink phonebook entries for enhanced communication capability. Multilink entries enable you to have more than one communication device associated with a RAS connection to increase the connection's total bandwidth. RAS allows you to manage multilink phonebook entries by using RasGetSubEntryProperties and RasSetSubEntryProperties. The RasGetSubEntryProperties function is defined as

 DWORD RasGetSubEntryProperties( LPCTSTR lpszPhonebook, LPCTSTR lpszEntry, DWORD dwSubEntry, LPRASSUBENTRY lpRasSubEntry, LPDWORD lpdwcb, LPBYTE lpbDeviceConfig, LPDWORD lpcbDeviceConfig ); 

The lpszPhonebook parameter is a pointer to the name of a phonebook file. The lpszEntry parameter is a phonebook entry. The dwSubEntry parameter specifies the index of a subentry contained within the phonebook entry. The lpRasSubEntry parameter is a pointer to a buffer that will receive a RASSUBENTRY structure followed by an optional list of alternate phone numbers. A RASSUBENTRY structure is defined as

 typedef struct tagRASSUBENTRY { DWORD dwSize; DWORD dwfFlags; TCHAR szDeviceType[RAS_MaxDeviceType + 1]; TCHAR szDeviceName[RAS_MaxDeviceName + 1]; TCHAR szLocalPhoneNumber[RAS_MaxPhoneNumber + 1]; DWORD dwAlternateOffset; } RASSUBENTRY; 

The fields are defined as follows:

• dwSize Must be set to the size (in bytes) of a RASSUBENTRY structure
• dwFlags Is not used
• szDeviceType Receives a string representing the type of device that is used on the connection
• szDeviceName Receives the actual name of the TAPI device
• szLocalPhoneNumber Identifies the phone number to use for this device
• dwAlternateOffset Specifies the number of bytes from the beginning of the structure to the list of consecutive null-terminated strings that follow the RASSUBENTRY structure

The lpRasSubEntry buffer must be large enough to contain a RASSUBENTRY structure along with alternate phone number strings; otherwise, the RasGetSubEntryProperties will fail with the error ERROR_BUFFER_TOO_SMALL. The lpdwcb parameter should be set to the number of bytes in your lpRasSubEntry buffer. On return, lpdwcb will receive the total number of bytes needed to contain a RASSUBENTRY structure along with alternate phone numbers. The lpbDeviceConfig and lpcbDeviceConfig parameters are not used and should be set to NULL.

You can create a new subentry or modify an existing subentry of a specified phonebook entry by calling the RasSetSubEntryProperties function, which is defined as

 DWORD RasSetSubEntryProperties( LPCTSTR lpszPhonebook, LPCTSTR lpszEntry, DWORD dwSubEntry, LPRASSUBENTRY lpRasSubEntry, DWORD dwcbRasSubEntry, LPBYTE lpbDeviceConfig, DWORD dwcbDeviceConfig ); 

The parameters are the same as those described by RasGetSubEntryProperties except that lpRasSubEntry specifies the subentry to add to the phonebook.