Fungsi RasRenameEntryA (ras.h)

Fungsi RasRenameEntry mengubah nama entri dalam buku telepon.

Sintaks

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

Parameter

[in] unnamedParam1

Penunjuk ke string yang dihentikan null yang menentukan jalur lengkap dan nama file file buku telepon (PBK). Jika parameter ini NULL, fungsi menggunakan file buku telepon default saat ini. File buku telepon default adalah file yang dipilih oleh pengguna di lembar properti Preferensi Pengguna dari kotak dialog Jaringan Dial-Up .

Windows Me/98/95: Parameter ini harus selalu NULL. Jaringan dial-up menyimpan entri buku telepon dalam registri, bukan dalam file buku telepon.

[in] unnamedParam2

Penunjuk ke string yang dihentikan null yang menentukan nama entri yang ada.

[in] unnamedParam3

Penunjuk ke string yang dihentikan null yang menentukan nama entri baru. Sebelum memanggil RasRenameEntry, panggil fungsi RasValidateEntryName untuk memvalidasi nama entri baru.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut atau nilai dari Kode Kesalahan Perutean dan Akses Jarak Jauh atau Winerror.h.

Nilai	Makna
ERROR_NOT_ENOUGH_MEMORY	Fungsi tidak dapat mengalokasikan memori yang cukup untuk menyelesaikan operasi.
ERROR_INVALID_NAME	Nama lpszNewEntry tidak valid.
ERROR_ALREADY_EXISTS	Entri dengan nama lpszNewEntry sudah ada.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	Entri buku telepon tidak ada.

Keterangan

Fungsi RasRenameEntry memungkinkan nama entri yang tidak akan diterima oleh antarmuka pengguna jaringan dial-up. Nama entri yang ditentukan dalam RasRenameEntry dapat terdiri dari string apa pun yang mematuhi kondisi berikut:

1. String tidak boleh memiliki panjang yang lebih besar dari RAS_MaxEntryName (seperti yang didefinisikan dalam Ras.h).
2. String tidak boleh terdiri dari seluruh spasi atau karakter tab.
3. Karakter pertama dalam string tidak boleh berupa karakter titik (".").

Sampel kode berikut mengganti nama entri buku telepon dengan nama yang ditentukan oleh pszOldName menjadi nama baru yang ditentukan oleh 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;
}

Catatan

Header ras.h mendefinisikan RasRenameEntry sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	ras.h
Pustaka	Rasapi32.lib
DLL	Rasapi32.dll

Lihat juga

RasValidateEntryName

Gambaran Umum Layanan Akses Jarak Jauh (RAS)

Fungsi Layanan Akses Jarak Jauh