RasGetEntryDialParamsA function (ras.h)
The RasGetEntryDialParams function retrieves the connection information saved by the last successful call to the RasDial or RasSetEntryDialParams function for a specified phone-book entry.
Syntax
DWORD RasGetEntryDialParamsA(
[in] LPCSTR unnamedParam1,
[in, out] LPRASDIALPARAMSA unnamedParam2,
[out] LPBOOL unnamedParam3
);
Parameters
[in] unnamedParam1
Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
Windows Me/98/95: This parameter should always be NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
[in, out] unnamedParam2
Pointer to a RASDIALPARAMS structure.
On input, the dwSize member specifies the size of the RASDIALPARAMS structure, and the szEntryName member specifies 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. If szPhoneNumber is an empty string in the RASDIALPARAMS structure passed to RasDial, RasDial uses the phone number stored in the phone-book entry.
The szPassword member of the RASDIALPARAMS structure does not return the actual password. Instead, szPassword contains a handle to the saved password. Substitute this handle for the saved password in subsequent calls to RasSetEntryDialParams and RasDial. When presented with this handle, RasDial retrieves and uses the saved password. The value of this handle may change in future versions of the operating system; do not develop code that depends on the contents or format of this value.
Windows NT and Windows Me/98/95: Secure password feature not supported.
[out] unnamedParam3
Pointer to a flag that indicates whether the function retrieved the password associated with the user name for the phone-book entry. The lpfPassword parameter is TRUE if the system has saved a password for the specified entry. If the system has no password saved for this entry, lpfPassword is FALSE.
Windows NT and Windows Me/98/95: The function sets this flag to TRUE if the user's password was returned in the szPassword member of the RASDIALPARAMS structure pointed to by lprasdialparams.
Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is one of the following error codes or a value from Routing and Remote Access Error Codes or Winerror.h.
| Value | Description |
|---|---|
|
The lprasdialparams or lpfPassword pointer is invalid, or the lprasdialparams buffer is invalid. |
|
The phone book is corrupted or missing components. |
|
The phone-book entry does not exist. |
Remarks
Note
The ras.h header defines RasGetEntryDialParams as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | ras.h |
| Library | Rasapi32.lib |
| DLL | Rasapi32.dll |