Funzione RasEntryDlgA (rasdlg.h)

Articolo
11/20/2024

La funzione RasEntryDlg visualizza le finestre delle proprietà modali che consentono a un utente di modificare le voci della rubrica telefonica. Se si modifica o si copia una voce della rubrica telefonica esistente, la funzione visualizza una finestra delle proprietà della voce della rubrica telefonica. La funzione RasEntryDlg restituisce quando l'utente chiude la finestra delle proprietà.

Sintassi

BOOL RasEntryDlgA(
  [in] LPSTR          lpszPhonebook,
  [in] LPSTR          lpszEntry,
  [in] LPRASENTRYDLGA lpInfo
);

Parametri

[in] lpszPhonebook

Puntatore a un nullstringa con terminazione che specifica il percorso completo e il nome file di un file con rubrica telefonica (PBK). Se questo parametro è NULL, la funzione usa il file predefinito corrente della rubrica telefonica. Il file predefinito della rubrica telefonica è quello selezionato dall'utente nella finestra di dialogo Preferenze utente della finestra di dialogo Rete remota.

[in] lpszEntry

Puntatore a un nullstringa con terminazione che specifica il nome della voce della rubrica telefonica da modificare, copiare o creare.

Se si sta modificando o copiando una voce, questo parametro è il nome di una voce di rubrica telefonica esistente. Se si copia una voce, impostare il flag di RASEDFLAG_CloneEntry nella dwFlags membro della struttura RASENTRYDLG.

Nota Il flag RASEDFLAG_CloneEntry è stato deprecato, a partire da Windows Vista e Windows Server 2008. Potrebbe essere modificato o non disponibile nelle versioni successive. Copiare invece una voce chiamando RasGetEntryProperties per ottenere la voce e quindi chiamando RasSetEntryProperties per salvare la voce con un nuovo nome.

Se si crea una voce, questo parametro è un nuovo nome di voce predefinito che l'utente può modificare. Se questo parametro è NULL, la funzione fornisce un nome predefinito. Se si sta creando una voce, impostare il flag di RASEDFLAG_NewEntry nella dwFlags membro della struttura RASENTRYDLG.

[in] lpInfo

Puntatore a una struttura RASENTRYDLG che specifica parametri di input e output aggiuntivi. Il membro dwSize di questa struttura deve specificare sizeof(RASENTRYDLG). Utilizzare il dwFlags membro per indicare se si sta creando, modificando o copiando una voce. Se si verifica un errore, il membro dwError restituisce un codice di errore; in caso contrario, restituisce zero.

Valore restituito

Se l'utente crea, copia o modifica una voce della rubrica telefonica, il valore restituito è TRUE. In caso contrario, la funzione restituisce FALSE.

Se si verifica un errore, rasEntryDlg imposta il membro dwError della struttura RASENTRYDLG su un valore routing e codici di errore di accesso remoto o Winerror.h.

Osservazioni

Le funzioni RasCreatePhonebookEntry e RasEditPhonebookEntry chiamano la funzione RasEntryDlg.

Nel codice di esempio seguente viene visualizzata una finestra delle proprietà per creare una nuova voce. La variabile lpszEntry specifica il nome predefinito per la nuova voce.

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "rasdlg.h"
#include <tchar.h>

DWORD __cdecl wmain(){

    DWORD dwRet = ERROR_SUCCESS;
    BOOL nRet = TRUE;
    LPTSTR lpszEntry = L"EntryName";

    // Allocate heap memory and initialize RASENTRYDLG structure
    LPRASENTRYDLG lpEntry = (LPRASENTRYDLG)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRYDLG));
    if (lpEntry == NULL){
        wprintf(L"HeapAlloc failed.\n");
        return 0;
    }
    
    // The RASENTRYDLG->dwSize member has to be initialized or the RRAS APIs will fail below.
    lpEntry->dwSize = sizeof(RASENTRYDLG);
    lpEntry->dwFlags |= RASEDFLAG_NewEntry;

    // Create the new entry using a user dialog
    nRet = RasEntryDlg(NULL, lpszEntry, lpEntry);

    // Any error codes are returned in lpEntry
    dwRet = lpEntry->dwError;
    
    if (nRet == TRUE) {
        wprintf(L"New entry created: %s\n", lpEntry->szEntry);

        // Clean up: delete the new entry
        dwRet = RasDeleteEntry(NULL, lpszEntry);
        if (dwRet != ERROR_SUCCESS) {
            wprintf(L"RasDeleteEntry failed: Error = %d\n", dwRet);
        }

    } 
    else {
        if (dwRet != ERROR_SUCCESS) {
            wprintf(L"RasEntryDlg failed: Error = %d\n", dwRet);
        }
        else {
            wprintf(L"User pressed Cancel\n");
        }
    }

    HeapFree(GetProcessHeap(), 0, lpEntry);
    return 0;
}

Nota

L'intestazione rasdlg.h definisce RASENTRYDLG come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	rasdlg.h
libreria	Rasdlg.lib
dll	Rasdlg.dll