Establishing a Connection

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

• It returns a zero, a non-zero value indicates failure.
• In addition, the function stores a handle to the RAS connection into the variable point to by the function parameter pRasConn.

The RasDial function must specify data so that RAS can establish the connection from a Windows CE–based device to a remote access server. The client uses the RasDial function parameters to specify a phone-book file and a phone-book entry. The lpszPhonebookPath parameter can specify the name of a phone-book file, or it can be NULL to indicate that the default phone-book file should be used. 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 phone number, user name, domain, and password.

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. 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. Set the szEntryName, szUserName, szPassword, and szDomain members of the RASDIALPARAM structure. Pass a pointer to this structure into lpRasDialParam.

Note RasDial does not automatically display the logon dialog box. This is currently done through the Remote Networking application. Your application is responsible for getting the data from a user.

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);
    wcscpy (RasDialParams.szPassword, szPassword);
    wcscpy (RasDialParams.szDomain, szDomain); 
  }

  // Try to establish RAS connection.
  if (RasDial (NULL,            // Extension not supported
               NULL,            // Phone book is in registry
               &RasDialParams,  // RAS configuration for connection
               0xFFFFFFFF,      // Use this value
               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;
}