Funzione RasRenameEntryA (ras.h)

Articolo
03/15/2023

La funzione RasRenameEntry modifica il nome di una voce in una rubrica telefonica.

Sintassi

DWORD RasRenameEntryA(
  [in] LPCSTR unnamedParam1,
  [in] LPCSTR unnamedParam2,
  [in] LPCSTR unnamedParam3
);

Parametri

[in] unnamedParam1

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

Windows Me/98/95: Questo parametro deve essere sempre NULL. La rete di connessione remota archivia le voci della rubrica nel Registro di sistema anziché in un file di rubrica telefonica.

[in] unnamedParam2

Puntatore a una stringa con terminazione Null che specifica un nome di voce esistente.

[in] unnamedParam3

Puntatore a una stringa con terminazione Null che specifica il nome della nuova voce. Prima di chiamare RasRenameEntry, chiamare la funzione RasValidateEntryName per convalidare il nome della nuova voce.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti o un valore di Routing e Remote Access Error Codes o Winerror.h.

Valore	Significato
ERROR_NOT_ENOUGH_MEMORY	La funzione non è stata in grado di allocare memoria sufficiente per completare l'operazione.
ERROR_INVALID_NAME	Il nome lpszNewEntry non è valido.
ERROR_ALREADY_EXISTS	Esiste già una voce con il nome lpszNewEntry .
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	La voce della rubrica telefonica non esiste.

Commenti

La funzione RasRenameEntry consente nomi di voci che non verrebbero accettati dall'interfaccia utente di rete remota. I nomi di voce specificati in RasRenameEntry possono essere costituiti da qualsiasi stringa conforme alle condizioni seguenti:

La stringa non può avere una lunghezza maggiore di RAS_MaxEntryName (come definito in Ras.h).
La stringa non può essere costituita interamente da spazi o caratteri di tabulazioni.
Il primo carattere nella stringa non può essere un carattere punto (".").

Nell'esempio di codice seguente la voce phone-book viene rinominata con il nome specificato da pszOldName con il nuovo nome specificato da pszNewName.

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

DWORD main (){

    DWORD dwErr = ERROR_SUCCESS;
    LPCTSTR pszOldName = L"RAS Connection 1\0";
    LPCTSTR pszNewName = L"RAS Connection 2\0";

    dwErr = RasValidateEntryName(NULL, pszNewName);
    if (ERROR_SUCCESS != dwErr)
    {
        printf("RasValidateEntryName failed: Error = %d\n", dwErr);
        return dwErr;
    }

    dwErr = RasRenameEntry(NULL, pszOldName, pszNewName);
    if (ERROR_SUCCESS != dwErr)
    {
        printf("RasRenameEntry failed: Error = %d\n", dwErr);
        return dwErr;
    }

    printf("Successfully renamed entry '%s' to '%s'\n", pszOldName, pszNewName);

    return 0;
}

Nota

L'intestazione ras.h definisce RasRenameEntry 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ras.h
Libreria	Rasapi32.lib
DLL	Rasapi32.dll

Vedi anche

RasValidateEntryName

Panoramica del servizio accesso remoto (RAS)

Funzioni del Servizio di accesso remoto

Condividi tramite