Connection Management

RAS has three useful functions that allow you to retrieve the properties of connections established on your system: RasEnumConnections, RasGetSubEntryHandle, and RasGetProjectionInfo. The RasEnumConnections function lists all active RAS connections and is defined as

 DWORD RasEnumConnections( LPRASCONN lprasconn, LPDWORD lpcb, LPDWORD lpcConnections ); 

The lprasconn parameter is an application buffer that will receive an array of RASCONN structures. A RASCONN structure is defined as

 typedef struct _RASCONN { DWORD dwSize; HRASCONN hrasconn; TCHAR szEntryName[RAS_MaxEntryName + 1]; #if (WINVER >= 0x400) CHAR szDeviceType[RAS_MaxDeviceType + 1]; CHAR szDeviceName[RAS_MaxDeviceName + 1]; #endif #if (WINVER >= 0x401) CHAR szPhonebook[MAX_PATH]; DWORD dwSubEntry; #endif #if (WINVER >= 0x500) GUID guidEntry; #endif } RASCONN; 

The fields are defined as follows:

• dwSize Indicates the size (in bytes) of a RASCONN structure.
• hrasconn Receives the connection handle that is created by RasDial.
• szEntryName Receives the phonebook entry that was used to establish the connection. If an empty string was used, the field will return a string with a period (.) followed by the phone number used.
• szDeviceType Receives a string describing the device type used in the connection.
• szDeviceName Receives a string with the name of the device that was used to make the connection.
• szPhonebook Receives the full path to the phonebook for the entry that made the connection.
• dwSubEntry Receives a subentry index of a multilink phonebook entry.
• guidEntry On Windows 2000, receives a GUID for the phonebook entry used to make the connection.

You need to pass to RasEnumConnections a large enough buffer to hold several RASCONN structures; otherwise, this function will fail with the error ERROR_BUFFER_TOO_SMALL. Furthermore, the first RASCONN structure in your buffer must have the dwSize field set to the byte size of a RASCONN structure. The next parameter, lpcb, is a pointer to a variable that you must set to the size (in bytes) of your lprasconn array. When this function returns, lpcb will contain the number of bytes required to enumerate all connections. If you don't supply a large enough buffer, you can always try again with the correct buffer size returned in lpcb. The lpcConnections parameter is a pointer to a variable that receives a count of the number of RASCONN structures written to lprasconn.

The RasGetSubEntryHandle function, defined as follows, allows you to retrieve a connection handle for a specified subentry of a multilink connection.

 DWORD RasGetSubEntryHandle( HRASCONN hrasconn, DWORD dwSubEntry, LPHRASCONN lphrasconn ); 

The hrasconn parameter is a RAS connection handle of a multilink connection. The dwSubEntry parameter is a subentry index of a device in the multilink connection. The lphrasconn parameter receives the connection handle for the subentry device.

With the RAS connection handles you receive from RasEnumConnections and RasGetSubEntryHandle, you can obtain network protocol-specific information that is used over an established RAS connection. This network protocol-specific information is known as projection information. A remote access server uses projection information to represent a remote client on the network. For example, when you make a RAS connection that uses the IP protocol over a framing protocol, IP configuration information (such as an assigned IP address) is established from the RAS service to your client. You can retrieve projection information for the protocols that travel over the PPP framing protocol by calling the RasGetProjectionInfo function, which is defined as

 DWORD RasGetProjectionInfo( HRASCONN hrasconn, RASPROJECTION rasprojection, LPVOID lpprojection, LPDWORD lpcb ); 

The hrasconn parameter is a RAS connection handle. The rasprojection parameter is a RASPROJECTION enumeration type that allows you to specify a protocol to receive connection information for. The lpprojection parameter receives a data structure that is associated with the enumeration type specified in rasprojection. The final parameter, lpcb, is a pointer to a variable that you must set to the size of your lpprojection structure. When this function completes, this variable will contain the size of the buffer needed to obtain the projection information.

The following RASPROJECTION enumeration types allow you to receive connection information:

• RASP_Amb
• RASP_PppNbf
• RASP_PppIpx
• RASP_PppIp

If you specify a RASP_Amb enumeration type, you will receive a RASAMB structure that is defined as

 typedef struct _RASAMB { DWORD dwSize; DWORD dwError; TCHAR szNetBiosError[NETBIOS_NAME_LEN + 1]; BYTE bLana; } RASAMB; 

The fields are defined as follows:

• dwSize Should be set to the size (in bytes) of a RASAMB structure.
• dwError Receives an error code from the PPP negotiation process.
• szNetBiosError Receives a NetBIOS name if a name conflict occurs during the authentication process of PPP. If dwError returns ERROR_NAME_EXISTS_ON_NET, szNetBiosError will receive the name that caused the error.
• bLana Identifies the NetBIOS LAN adapter (LANA) number that was used to establish the remote access connection.

If you specify a RASP_PppNbf enumeration type to RasGetProjectionInfo, you will receive a RASPPPNBF structure that is defined as

 typedef struct _RASPPPNBF { DWORD dwSize; DWORD dwError; DWORD dwNetBiosError; TCHAR szNetBiosError[NETBIOS_NAME_LEN + 1]; TCHAR szWorkstationName[NETBIOS_NAME_LEN + 1]; BYTE bLana; } RASPPPNBF; 

The fields of RASPPPNBF are like the fields of the RASAMB structure except that RASPPPNBF contains two additional fields: szWorkstationName and dwNetBiosError. The szWorkstationName field receives the NetBIOS name that is used to identify your workstation on the network you are connecting to. The dwNetBiosError field receives the NetBIOS error that occurred.

If you specify a RASP_PppIpx enumeration type to RasGetProjectionInfo, you will receive a RASPPPIPX structure that is defined as

 typedef struct _RASPPPIPX { DWORD dwSize; DWORD dwError; TCHAR szIpxAddress[RAS_MaxIpxAddress + 1]; } RASPPPIPX; 

The fields are defined as follows:

• dwSize Should be set to the size (in bytes) of a RASPPPIPX structure
• dwError Receives an error code from the PPP negotiation process
• szIpxAddress Receives a string representing the client's IPX address on the remote network

If you specify a RASP_PppIp enumeration type to RasGetProjectionInfo, you will receive a RASPPPIP structure that is defined as

 typedef struct _RASPPPIP { DWORD dwSize; DWORD dwError; TCHAR szIpAddress[RAS_MaxIpAddress + 1]; TCHAR szServerIpAddress[RAS_MaxIpAddress + 1]; } RASPPPIP; 

The fields are defined as follows:

• dwSize Should be set to the size (in bytes) of a RASPPPIP structure
• dwError Receives an error code from the PPP negotiation process
• szIpAddress Receives a string representing the client's IP address
• szServerIpAddress Receives a string representing the server's IP address

Figure 16-4 demonstrates how to retrieve the IP addresses assigned to an IP connection that is made over RAS.

Figure 16-4. Using RasGetProjectionInfo on an IP connection

 lpProjection = (RASPPPIP *) GlobalAlloc(GPTR, cb); lpProjection->dwSize = sizeof(RASPPPIP); cb = sizeof(RASPPPIP);       Ret = RasGetProjectionInfo(hRasConn, RASP_PppIp, lpProjection, &cb);       if (Ret != ERROR_SUCCESS) { printf("RasGetProjectionInfo failed with error %d", Ret); return; } else { printf("\nRas Client IP address: %s\n", lpProjection->szIpAddress); printf("Ras Server IP address: %s\n", lpProjection->szServerIpAddress); }