Creating Dialup Connections with RAS APIs

1.      Basic knowedge:

a)      RAS

Remote Access Service (RAS) provides remote access capabilities toclient applications on computers running Windows.

RASapplications can perform the following tasks:

• Display any of the RAS common dialog boxes.
• Start and end a RAS connection operation using the common dialog boxes or the low-level dialing functions.
• Create, edit, or copy phone-book entries
• Work with entries in the RAS AutoDial mapping database.
• Get RAS information, including information about existing RAS connections, information about the RAS-capable devices configured on the local computer, and notifications when a RAS connection begins or ends.

 

b)      Phone books

Phonebooks provide a standard way to collect and specify the information that theRemote Access Connection Manager needs to establish a remote connection. Phonebooks associate entry names with information such as phone numbers, COM ports,and modem settings. Each phone-bookentry contains the information needed to establish a RAS connection.

Phonebooks are stored in phone-book files,which are text files that contain the entry names and associated information.RAS creates a phone-book file called RASPHONE.PBK. The user can use the main Dial-UpNetworking dialog box to create personal phone-book files.

 

2.      RASENTRY structure

a)      The RASENTRYstructure describes a phone-book entry. The RasSetEntryPropertiesand RasGetEntryPropertiesfunctions use this structure to set and retrieve the properties of a phone-bookentry.

b)      Some important parameters

                   i.             dwSize:filled with sizeof(RASENTRY)

               ii.             dwfOptions:  

RASEO_PreviewUserPw, If this flag is set, the remote access dialer displaysthe user's name and password prior to dialing.

RASEO_RemoteDefaultGateway, If this flagis set, the default route for IP packets is through the dial-up adapter whenthe connection is active. If this flag is clear, the default route is notmodified

           iii.             dwType: RASET_Broadband,Broadband connections, e.g. Digital Subscriber Line (DSL).

                                                             i.             RASET_Phone, Phone line, for example, modem, ISDN,X.25.

               iv.             szDeviceType:RASDT_Modem, RASDT_Isdn, RASDT_PPPoE

                   v.             szDeviceName:the name of a TAPI device

               vi.             dwfNetProtocols:RASNP_NetBEUI, RASNP_Ipx, RASNP_Ip

           vii.             dwFramingProtocol:RASFP_Ppp, RASFP_Slip

 

3.      Create a phone book

We can use the function RasSetEntryProperties()to create a phone book, and set the features in the structure RASENTRY. Here is an example to create a pppoe link.

Sample code:

intCreateLink()

{

    LPRASENTRY lpRasEntry = NULL; 

    DWORD cb = sizeof(RASENTRY); 

    DWORD dwBufferSize = 0; 

    DWORD dwRet = 0; 

 

    // 取得entry的大小

    RasGetEntryProperties(NULL, "",NULL, &dwBufferSize, NULL, NULL);  

    if (dwBufferSize == 0) 

        return -1; 

 

    lpRasEntry =(LPRASENTRY)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwBufferSize); 

    if (lpRasEntry == NULL)  

        return -2; 

 

    ZeroMemory(lpRasEntry,sizeof(RASENTRY)); 

    lpRasEntry->dwSize = dwBufferSize; 

    lpRasEntry->dwfOptions =RASEO_PreviewUserPw|RASEO_RemoteDefaultGateway; // RASEO_PreviewUserPw需要显示ui 

    lpRasEntry->dwType = RASET_Broadband; 

 

    lstrcpy(lpRasEntry->szDeviceType,RASDT_PPPoE); 

    lstrcpy(lpRasEntry->szDeviceName,"zzc"); 

    lpRasEntry->dwfNetProtocols =RASNP_Ip; 

    lpRasEntry->dwFramingProtocol =RASFP_Ppp; 

 

    dwRet = RasSetEntryProperties(NULL,"my con", lpRasEntry, dwBufferSize, NULL, 0); // 创建连接

    HeapFree(GetProcessHeap(), 0,(LPVOID)lpRasEntry); 

 

    if (dwRet != 0) 

        return 3; 

 

    return 0;

}

 

4.      Dial with API RasDial()

Before dial, we need tocreate a phone book first.

Demo code:

bool Dial()

{

    LPTSTRlpszEntry = "mycon";

    LPTSTRstrUserName = "user";

    LPTSTRstrPassword = "password";

    RASDIALPARAMSrdParams;

    DWORDdwRet = 0;

 

    rdParams.dwSize = sizeof(RASDIALPARAMS);

    rdParams.szPhoneNumber[0] = '/0';

    lstrcpy(rdParams.szEntryName,lpszEntry );

    rdParams.szCallbackNumber[0] = '/0';

    lstrcpy(rdParams.szUserName,strUserName );

    lstrcpy(rdParams.szPassword,strPassword );

    rdParams.szDomain[0] = '/0';

 

    HRASCONNhRasConn = NULL;

    dwRet= RasDial( NULL,NULL, &rdParams,0L, NULL,&hRasConn );

    if( dwRet == 0 )

        returntrue;

    char  szBuf[256];

    if( RasGetErrorString( (UINT)dwRet, (LPSTR)szBuf, 256 ) != 0 )

        wsprintf((LPSTR)szBuf,"Undefined RAS Dial Error (%ld).", dwRet );

    RasHangUp(hRasConn );

    returnfalse;

}

 

5.      RAS Dialogs

a)      RASDIALDLG

The RasDialDlgfunction establishes a RAS connection using a specified phone-book entry andthe credentials of the logged-on user.

Features forthe RASDIALDLG, just fill the size with sizeof(RASDIALDLG)then can be use.

Sample code:

int CallRasDialDlg()

{

   DWORD dwError= ERROR_SUCCESS;

   BOOL nRet= TRUE;

   LPTSTR lpszEntry= "my con";

 

   // Allocate heap memory and initializeRASDIALDLG structure

   LPRASDIALDLG lpInfo= (LPRASDIALDLG) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY,sizeof(RASDIALDLG));

   if (lpInfo== NULL){

        printf("HeapAlloc failed");

        HeapFree(GetProcessHeap(), 0, lpInfo);

        return0;

   }

 

   lpInfo->dwSize= sizeof(RASDIALDLG);

 

   // Connect using the new entry

   nRet = RasDialDlg(NULL, lpszEntry, NULL, lpInfo);

   if (nRet!= TRUE){

        printf("RasDialDlg failed: Error = %d/n", lpInfo->dwError);

   }

 

   HeapFree(GetProcessHeap(),0, lpInfo);

   return 0;

}

 

b)      RASENTRYDLG

The RasEntryDlg functiondisplays modal property sheets that allow a user to manipulate phone-bookentries.

Sample code:

int RasEntryDlg()

{

   LPTSTR lpszEntry= "my con";

 

   DWORD dwErr= NO_ERROR;

   BOOL nRet= FALSE;

   HANDLE hHeap= NULL;

   LPRASENTRYDLG lpInfo= NULL;

 

   hHeap = GetProcessHeap();

   if( NULL== hHeap )

   {

        dwErr= GetLastError();

        printf("GetProcessHeap() failed: Error = %d/n", dwErr);

        return dwErr;

   }

 

   lpInfo = (LPRASENTRYDLG)HeapAlloc( hHeap,HEAP_ZERO_MEMORY, sizeof(RASENTRYDLG));

   if ( NULL== lpInfo )

   {

        dwErr= ERROR_OUTOFMEMORY;

        printf("HeapAlloc() failed/n");

        return dwErr;

   }

 

   lpInfo->dwSize= sizeof(RASENTRYDLG);

   lpInfo->dwFlags|= RASEDFLAG_NewEntry;

   nRet = RasEntryDlg(NULL, lpszEntry, lpInfo);

   if (nRet)

   {

        printf("New entry created: %s/n", lpInfo->szEntry);

   }

   else

   {

        dwErr= lpInfo->dwError;

        if ( 0!= dwErr )

        {

            printf("RasEntryDlg failed: Error = %d/n", dwErr );

        }

        else

        {

            printf("User pressed Cancel/n");

        }

   }

 

   if( NULL!= lpInfo )

   {

        HeapFree(hHeap, 0, lpInfo);

   }

   return dwErr;

}

 

c)      RasPhonebookDlg

The RasPhonebookDlg functiondisplays the main Dial-Up Networking dialog box. can dial, edit, ordelete a selected phone-book entry, create a new phone-book entry, or specifyuser preferences.

Sample code:

void RasPhonebookDlg()

{

   LPRASPBDLG lpInfo= NULL;

   BOOL nRet= FALSE;

 

   lpInfo = (LPRASPBDLG)GlobalAlloc(GPTR, sizeof(RASPBDLG));

   if (NULL== lpInfo)

        return;

   // Essential, since garbage values cause theAPI to fail

   ZeroMemory(lpInfo,sizeof(RASPBDLG));

   lpInfo->dwSize=sizeof(RASPBDLG);

 

   nRet = RasPhonebookDlg(NULL,NULL,lpInfo);

 

   if (nRet)

        printf("User pressed Dial/n");

   else

   {

        if (lpInfo->dwError!= 0)

        {

            printf("RasPhonebookDlg failed: Error = %d/n", lpInfo->dwError);

        }

        else

            printf("User pressed Close/n");

}

GlobalFree(lpInfo);

}