RasGetEntryDialParams

This function retrieves the connection information saved by the last successful call to the RasDial function for a specified phone book entry.

DWORD RasGetEntryDialParams(
LPWSTR lpszPhoneBook, 
LPRASDIALPARAMS lpRasDialParams, 
LPBOOL lpfPassword );

Parameters

  • lpszPhoneBook
    Windows CE: This parameter is ignored and should be set to NULL.  Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

  • lpRasDialParams
    Pointer to a RASDIALPARAMS structure. On input, the dwSize member must specify the size of the RASDIALPARAMS structure, and the szEntryName member must specify a valid phone-book entry. On output, the structure receives the connection parameters associated with the specified phone-book entry.

    Note that the szPhoneNumber member of the structure does not receive the phone number associated with the phone-book entry. To get the phone number associated with a phone-book entry, call the RasGetEntryProperties function.

  • lpfPassword
    Pointer to a flag that indicates whether the function retrieved the password associated with the user name for the phone-book entry. The function sets this flag to TRUE if the users password was returned in the szPassword member of the RASDIALPARAMS structure pointed to by lpRasDialParams.

Return Values

Zero indicates success. ERROR_BUFFER_INVALID indicates that the lpRasDialParams or lpfPassword pointer is invalid, or the lpRasDialParams buffer is invalid. ERROR_CANNOT_OPEN_PHONEBOOK indicates that the phone book is corrupted or missing components. ERROR_CANNOT_FIND_PHONEBOOK_ENTRY indicates that the phone-book entry does not exist.

Include Raserror.h for definitions of the RAS error codes.

Windows CE Remarks

The szCallBackNumber and szPhoneNumber members of lpRasDialParams are not used and should be set to NULL.

When the dwSize member of the RASDIALPARAMS structure, which is pointed to by the lpRasDialParams parameter, is uninitialized or set to an incorrect value, the RasGetEntryDialParams function fails and returns a misleading error value, ERROR_CANNOT_FIND_PHONEBOOK_ENTRY.

Note that this function requires a plain text password, but it does not return a plain text password. therefore only trusted applications should be allowed to make calls to RasGetEntryDialParams.

For additional security devices should implement, and users encouraged to use, a power-on password. This will deter unauthorized users from searching for stored passwords on the device.

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 1.0 and later Ras.h, Afdfunc.h   Ppp.lib

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

RasDial, RASDIALPARAMS, RasSetEntryDialParams

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.