RasRenameEntryA-Funktion (ras.h)

Artikel
11/20/2024

Die RasRenameEntry Funktion ändert den Namen eines Eintrags in einem Telefonbuch.

Syntax

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

Parameter

[in] unnamedParam1

Zeigen Sie auf eine mit Null beendete Zeichenfolge, die den vollständigen Pfad und Dateinamen einer PbK-Datei (Phone-Book) angibt. Wenn dieser Parameter NULL-ist, verwendet die Funktion die aktuelle Standarddatei des Telefonbuchs. Die Standardmäßige Telefonbuchdatei ist die vom Benutzer im Eigenschaftenblatt Benutzereinstellungen Eigenschaftenblatt des Dialogfelds DFÜ-Netzwerk ausgewählt.

Windows Me/98/95: Dieser Parameter sollte immer NULL-sein. DFÜ-Netzwerke speichern Telefonbucheinträge in der Registrierung und nicht in einer Telefonbuchdatei.

[in] unnamedParam2

Zeigen Sie auf eine mit Null beendete Zeichenfolge, die einen vorhandenen Eintragsnamen angibt.

[in] unnamedParam3

Zeiger auf eine mit Null beendete Zeichenfolge, die den neuen Eintragsnamen angibt. Rufen Sie vor dem Aufrufen RasRenameEntry-den RasValidateEntryName-Funktion auf, um den neuen Eintragsnamen zu überprüfen.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes oder ein Wert aus Routing- und Remotezugriffsfehlercodes oder Winerror.h.

Wert	Bedeutung
ERROR_NOT_ENOUGH_MEMORY	Die Funktion konnte nicht genügend Arbeitsspeicher zuordnen, um den Vorgang abzuschließen.
ERROR_INVALID_NAME	Der lpszNewEntry Name ist ungültig.
ERROR_ALREADY_EXISTS	Ein Eintrag mit dem lpszNewEntry Namen ist bereits vorhanden.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	Der Telefonbucheintrag ist nicht vorhanden.

Bemerkungen

Die RasRenameEntry-Funktion ermöglicht Eintragsnamen, die von der DFÜ-Netzwerkbenutzeroberfläche nicht akzeptiert würden. Die in RasRenameEntry angegebenen Eintragsnamen können aus einer beliebigen Zeichenfolge bestehen, die den folgenden Bedingungen entspricht:

Die Zeichenfolge darf keine Länge größer als RAS_MaxEntryName haben (wie in Ras.h definiert).
Die Zeichenfolge darf nicht vollständig aus Leerzeichen oder Tabstoppzeichen bestehen.
Das erste Zeichen in der Zeichenfolge darf kein Punktzeichen (".") sein.

Im folgenden Codebeispiel wird der Phone-Book-Eintrag mit dem durch pszOldName angegebenen Namen in den neuen Namen umbenannt, der durch pszNewNameangegeben wird.

#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;
}

Anmerkung

Der ras.h-Header definiert RasRenameEntry als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	ras.h
Library	Rasapi32.lib
DLL-	Rasapi32.dll

Siehe auch

RasValidateEntryName

übersicht über Ras(Remote Access Service)

Remotezugriffsdienstfunktionen

Freigeben über