Creating Dialup Connections with RAS APIs

1.      Basic knowedge:

a)      RAS

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

RAS applications 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

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

Phone books 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-Up Networking dialog box to create personal phone-book files.

 

2.      RASENTRY structure

a)      The RASENTRY structure describes a phone-book entry. The RasSetEntryProperties and RasGetEntryProperties functions use this structure to set and retrieve the properties of a phone-book entry.

b)      Some important parameters

                    i.              dwSize: filled with sizeof (RASENTRY )

                ii.              dwfOptions:  

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

RASEO_RemoteDefaultGateway , If this flag is set, the default route for IP packets is through the dial-up adapter when the connection is active. If this flag is clear, the default route is not modified

            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:

int CreateLink()

{

    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 to create a phone book first.

Demo code:

bool Dial ()

{

    LPTSTR lpszEntry = "my con" ;

    LPTSTR strUserName = "user" ;

    LPTSTR strPassword = "password" ;

    RASDIALPARAMS rdParams ;

    DWORD dwRet = 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' ;

 

    HRASCONN hRasConn = NULL ;

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

    if ( dwRet == 0 )

        return true ;

    char   szBuf [256];

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

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

    RasHangUp ( hRasConn );

    return false ;

}

 

5.      RAS Dialogs

a)      RASDIALDLG

The RasDialDlg function establishes a RAS connection using a specified phone-book entry and the credentials of the logged-on user.

Features for the 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 initialize RASDIALDLG structure

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

    if (lpInfo == NULL ){

        printf ("HeapAlloc failed" );

        HeapFree (GetProcessHeap (), 0, lpInfo );

        return 0;

    }

 

    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 function displays modal property sheets that allow a user to manipulate phone-book entries.

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 function displays the main Dial-Up Networking dialog box. can dial, edit, or delete a selected phone-book entry, create a new phone-book entry, or specify user 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 the API 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 );

}