Starting a RAS Connection

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

The RasDial function indicates a successful connection in two ways. If RasDial make a successful connection:

• It returns a zero. A nonzero value indicates failure.
• The function stores a handle to the RAS connection in the variable pointed to by the function parameter pRasConn.

The RasDial function must specify data so that RAS can establish the connection from a Windows Embedded CE–based device to a remote access server. The client uses the RasDial function parameters to specify a phone-book entry. The lpszPhonebookPath parameter must be NULL. The lpRasDialParams parameter points to a RASDIALPARAMS structure that specifies the phone-book entry to use. To connect, the RasDial function must specify the data necessary to establish a connection. Typically, the RasDial call provides the connection data by specifying a phone-book entry using the RASDIALPARAMS structure to provide data such as a phone number, user name, domain, and password.

Instead of having the user supply credential information before RasDial is called, you can also set the RASEO_PreviewUserPw option bit in the RASENTRY structure. Setting this option bit causes a username and password dialog box to be displayed to the user before dialing occurs.

The connection data includes callback and user authentication data. To make a connection, the RasDial function can specify an empty string for the szEntryName member of the RASDIALPARAMS structure. This will result in the first available modem being used. The szPhoneNumber member must contain the phone number to dial.

To use RasDial to establish a connection

1. Set the dialExtensions parameter to NULL.

2. Set the lpszPhonebook parameter to NULL. Phone-book entries are stored in the registry rather than in a phone-book file.

3. Set the dwNotiferType parameter to 0xFFFFFFFF, specifying the lpvNotifier parameter as a handle to the window receiving progress notification messages. If the application requires messages from RAS, the messages must be sent to a window handle. There is no support for callback functions.

4. If you have not set the RASEO_PreviewUserPw option bit in the RASENTRY structure, which presents the user with a username and password dialog box before dialing, set the szEntryName, szUserName, szPassword, and szDomain members of the RASDIALPARAMstructure. Pass a pointer to this structure into lpRasDialParam.

RAS Connection Example

The following code example shows how to establish a RAS connection.

BOOL MakeRasDial (HWND hDlgWnd)
{
  BOOL bPassword;
  TCHAR szBuffer[100];

  if (bUseCurrent)
  {
    // Get the last configuration parameters used for this connection. 
    // If the password was saved, then the logon dialog box will not be
    // displayed.
    if (RasGetEntryDialParams (NULL, &RasDialParams, &bPassword) != 0)
    {
      MessageBox (hDlgWnd, 
                  TEXT("Could not get parameter details"), 
                  szTitle, 
                  MB_OK);
      return FALSE;
    }
  }
  else
  {
    // Display the Authentication dialog box.
    DialogBox (hInst, MAKEINTRESOURCE(IDD_AUTHDLG), hDlgWnd, 
               AuthDlgProc);

    // Set hRasConn to NULL before attempting to connect.
    hRasConn = NULL;

    // Initialize the structure.
    memset (&RasDialParams, 0, sizeof (RASDIALPARAMS));

    // Configure the RASDIALPARAMS structure. 
    RasDialParams.dwSize = sizeof (RASDIALPARAMS);
    RasDialParams.szPhoneNumber[0] = TEXT('\0');
    RasDialParams.szCallbackNumber[0] = TEXT('\0');
    wcscpy (RasDialParams.szEntryName, szRasEntryName);
    wcscpy (RasDialParams.szUserName, szUserName); //This is optional    wcscpy (RasDialParams.szPassword, szPassword); //This is optional
    wcscpy (RasDialParams.szDomain, szDomain); //This is optional
  }

  // Try to establish RAS connection.
  if (RasDial (NULL,            // Extension not supported
               NULL,            // Phone book is in registry
               &RasDialParams,  // RAS configuration for connection
               0xFFFFFFFF,      // Notifier type is a window handle
               hDlgWnd,         // Window receives notification message
               &hRasConn) != 0) // Connection handle
  {
    MessageBox (hDlgWnd, 
                TEXT("Could not connect using RAS"), 
                szTitle, 
                MB_OK);
    return FALSE;
  }

  wsprintf (szBuffer, TEXT("Dialing %s..."), szRasEntryName);

  // Set the Dialing dialog box window name to szBuffer.
  SetWindowText (hDlgWnd, szBuffer);

  return TRUE;
}

See Also

Concepts

Sample Application