RasGetEntryProperties

This function retrieves the properties of a phone book entry.

DWORD RasGetEntryProperties(
LPWSTR lpszPhoneBook, 
LPWSTR szEntry, 
LPRASENTRY lpbEntry, 
LPDWORD lpdwEntrySize, 
LPBYTE lpb, 
LPDWORD lpdwSize );

Parameters

  • lpszPhoneBook
    This parameter is ignored and should be set to NULL.  Phone-book entries are stored in the registry rather than in a phone-book file.

  • szEntry
    Pointer to a null-terminated string that contains an existing entry name. If you specify an empty string, , the function returns default values in the buffers pointed to by the lpbEntry and lpb parameters.

  • lpbEntry
    Pointer to a RASENTRY structure followed by additional bytes for the alternate phone number list, if there is one. The structure receives the connection data associated with the phone-book entry specified by the szEntry parameter. Before calling the function, set the dwSize member of the structure to sizeof(RASENTRY) to identify the version of the structure. Calling RasGetEntryProperties without specifying a RASENTRY structure returns an error.

  • lpdwEntrySize
    Pointer to a variable that that contains the size, in bytes, of the lpbEntry buffer. On return, the function sets this variable to the number of bytes required.

  • lpb
    Long pointer to a buffer that receives device-specific configuration information. This is opaque TAPI device configuration information that you should not manipulate directly. This parameter can be NULL. For more information about TAPI device configuration, see the lineGetDevConfig function in the Win32 Telephony (TAPI) Programmers Reference.

  • lpdwSize
    Long pointer to a variable that that contains the size, in bytes, of the buffer specified by the lpb parameter. On return, the function sets this variable to the number of bytes required. This parameter can be NULL if the lpb parameter s NULL.

    To determine the required buffer size, call RasGetEntryProperties with lpb set to NULL and lpdwSize set to a buffer size such as the 128 bytes required for unimodem. The function returns the required buffer size in lpdwSize.

Return Values

Zero indicates success. ERROR_INVALID_PARAMETER indicates that the function was called with an invalid parameter. ERROR_INVALID_SIZE indicates that the value of the dwSize member of the structure specified in lpbEntry is too small. ERROR_BUFFER_INVALID indicates that the address or buffer specified by lpbEntry is invalid. ERROR_BUFFER_TOO_SMALL indicates that the buffer size indicated in lpdwEntrySize is too small. ERROR_CANNOT_OPEN_PHONEBOOK indicates that the phone book is corrupted or is 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.

Remarks

Calling RasGetEntryProperties with the lpRasEntry parameter set to NULL returns ERROR_BUFFER_INVALID. Desktop applications typically call this function with a NULL parameter in order to read a device configuration without reading entry-specific information). To do this in Windows CE, applications must call RasGetEntryDevConfig, which is defined in the header file Ras.h. Note that the RasGetEntryDevConfig function is undocumented, because its use is disparaged except as a workaround for the above-described situation.

Similarly, if you call RasGetEntryProperties with the lpbDeviceInfo parameter set to NULL and *lpDeviceInfoSize set to zero, the function returns ERROR_BUFFER_TOO_SMALL. The workaround is to set *lpDeviceInfoSize to some minimal, required buffer size, such as the 128 bytes that unimodem requires.

For Windows CE version 2.0 and later, device configuration information can be retrieved by using the lpb and lpdwSize parameters. For Windows CE version 1.0 and 1.01, the lpb and lpdwSize parameters are ignored and should be set to NULL. To retrieve device specific configuration information use the RasGetEntryDevConfig function.

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

RASENTRY, RasSetEntryProperties

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.