Funzione RasSetEntryPropertiesA (ras.h)

Articolo
11/20/2024

La funzione RasSetEntryProperties modifica le informazioni di connessione per una voce nella rubrica telefonica o crea una nuova voce della rubrica telefonica.

Sintassi

DWORD RasSetEntryPropertiesA(
  [in] LPCSTR      unnamedParam1,
  [in] LPCSTR      unnamedParam2,
  [in] LPRASENTRYA unnamedParam3,
  [in] DWORD       unnamedParam4,
  [in] LPBYTE      unnamedParam5,
  [in] DWORD       unnamedParam6
);

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 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] unnamedParam2

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

Se il nome della voce corrisponde a una voce esistente, RasSetEntryProperties modifica le proprietà di tale voce.

Se il nome della voce non corrisponde a una voce esistente, RasSetEntryProperties crea una nuova voce della rubrica telefonica. Per le nuove voci, chiamare la funzione RasValidateEntryName per convalidare il nome della voce prima di chiamare RasSetEntryProperties.

[in] unnamedParam3

Puntatore alla struttura RASENTRY che specifica i nuovi dati di connessione da associare alla voce della rubrica telefonica indicata dal parametro lpszEntry.

Il chiamante deve fornire valori per i membri seguenti nella struttura RASENTRY.

dwSize
szLocalPhoneNumber
szDeviceName
szDeviceType
dwFramingProtocol
dwfOptions
dwType

Windows XP o versione successiva: dwType è supportato.

Se i valori non vengono forniti per questi membri, RasSetEntryProperties ha esito negativo con ERROR_INVALID_PARAMETER.

La struttura può essere seguita da una matrice di stringhe di numeri di telefono alternativi con terminazione Null. L'ultima stringa viene terminata da due caratteri Null consecutivi. Il dwAlternateOffset membro della struttura RASENTRY contiene l'offset alla prima stringa.

[in] unnamedParam4

Specifica le dimensioni, in byte, del buffer identificato dal parametro lpRasEntry.

[in] unnamedParam5

Puntatore a un buffer che specifica le informazioni di configurazione specifiche del dispositivo. Si tratta di informazioni di configurazione del dispositivo TAPI opache. Per altre informazioni sulla configurazione del dispositivo TAPI, vedere la funzione lineGetDevConfig in TAPI (Telephony Application Programming Interfaces) in Platform SDK.

Windows XP: Questo parametro non è usato. La funzione chiamante deve impostare questo parametro su NULL.

[in] unnamedParam6

Specifica le dimensioni, in byte, del buffer lpbDeviceInfo.

Windows XP: Questo parametro non è usato. La funzione chiamante deve impostare questo parametro su zero.

Valore restituito

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

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti o un valore di Routing e codici di errore di accesso remoto o WinError.h.

Valore	Significato
ERROR_ACCESS_DENIED	L'utente non dispone dei privilegi corretti. Solo un amministratore può completare questa attività.
ERROR_BUFFER_INVALID	L'indirizzo o il buffer specificato da lpRasEntry non è valido.
ERROR_CANNOT_OPEN_PHONEBOOK	La rubrica telefonica è danneggiata o mancano componenti.
ERROR_INVALID_PARAMETER	La struttura di RASENTRY a cui punta il parametro lpRasEntry non contiene informazioni adeguate oppure la voce specificata non esiste nella rubrica telefonica. Vedere la descrizione per lpRasEntry per visualizzare le informazioni necessarie.

Osservazioni

Quando si impostano le proprietà per una connessione a tutti gli utenti, se l'applicazione chiamante specifica un valore NULL nonper il parametro rubrica telefonica, lpszPhonebook, il file della rubrica telefonica deve trovarsi nella directory rubrica telefonica sotto il percorso dei dati dell'applicazione all-users. Per ottenere la posizione corretta per il file della rubrica telefonica, chiamare prima SHGetFolderPath con un valore CSIDL di CSIDL_COMMON_APPDATA. SHGetFolderPath restituisce il percorso dei dati dell'applicazione all-users. Aggiungere la stringa seguente a questo percorso:

Microsoft\Network\Connections\Pbk

Il percorso combinato è la posizione corretta per il file della rubrica telefonica.

Nota La specifica di un valore NULL nonper il parametro lpszPhonebook potrebbe non essere supportato nelle versioni di Windows successive a Windows XP.

Nota

L'intestazione ras.h definisce RasSetEntryProperties 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	ras.h
libreria	Rasapi32.lib
dll	Rasapi32.dll