Função RasGetCredentialsA (ras.h)

Artigo
11/20/2024

A função RasGetCredentials recupera as credenciais de usuário associadas a uma entrada de catálogo telefônico RAS especificada.

Sintaxe

DWORD RasGetCredentialsA(
  [in]      LPCSTR            unnamedParam1,
  [in]      LPCSTR            unnamedParam2,
  [in, out] LPRASCREDENTIALSA unnamedParam3
);

Parâmetros

[in] unnamedParam1

Ponteiro para um cadeia de caracteres nulaterminada que especifica o caminho completo e o nome do arquivo de um arquivo PBK (phone-book). Se esse parâmetro for NULL, a função usará o arquivo de agendamento telefônico padrão atual. O arquivo de lista telefônica padrão é o selecionado pelo usuário na folha de propriedades preferências do usuário da caixa de diálogo rede discada .

[in] unnamedParam2

Ponteiro para um cadeia de caracteresterminada nula que especifica o nome de uma entrada de lista telefônica.

[in, out] unnamedParam3

Ponteiro para a estrutura de RASCREDENTIALS que, na saída, recebe as credenciais do usuário associadas à entrada de catálogo telefônico especificada.

Na entrada, defina o dwSize membro da estrutura como sizeof(RASCREDENTIALS) e defina o membro dwMask para indicar as informações de credencial a serem recuperadas. Quando a função retorna, dwMask indica os membros que foram recuperados com êxito.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será um dos seguintes códigos de erro ou um valor de códigos de erro de roteamento e acesso remoto ou Winerror.h.

Valor	Significado
ERROR_CANNOT_OPEN_PHONEBOOK	A lista telefônica especificada não pode ser encontrada.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	A entrada especificada não existe na lista telefônica.
ERROR_INVALID_PARAMETER	O parâmetro lpCredentials foi NULL.
ERROR_INVALID_SIZE	O dwSize membro da estrutura de RASCREDENTIALS é um valor não reconhecido.

Observações

A função RasGetCredentials recupera as credenciais do último usuário para se conectar usando a entrada de lista telefônica especificada ou as credenciais especificadas posteriormente em uma chamada para a função RasSetCredentials para a entrada do catálogo telefônico.

Essa função é a maneira preferencial de recuperar com segurança as credenciais associadas a uma entrada de lista telefônica RAS. RasGetCredentials substitui a função RasGetEntryDialParams, que pode não ter suporte em versões futuras do Windows.

RasGetCredentials não retorna a senha real. Em vez disso, o szPassword membro da estrutura RASCREDENTIALS contém um identificador para a senha salva. Substitua esse identificador pela senha salva em chamadas subsequentes para rasSetCredentials e rasDial. Quando apresentado com esse identificador, RasDial recupera e usa a senha salva. O valor desse identificador pode mudar em versões futuras do sistema operacional; não desenvolva código que dependa do conteúdo ou formato desse valor.

O dwMask membro do RASCREDENTIALS contém o sinalizador RASCM_Password se o sistema salvou uma senha para a entrada especificada. Se o sistema não tiver nenhuma senha salva para essa entrada, dwMask não conterá RASCM_Password.

Windows 2000/NT: Não há suporte para esse recurso.

Se o dwMask da estrutura RASCREDENTIALS contiver o sinalizador RASCM_DefaultCreds, as credenciais retornadas serão as credenciais padrão para uma conexão de todos os usuários.

Para recuperar uma chave pré-compartilhada, use o sinalizador RASCM_PreSharedKey no campo RASCREDENTIALS.dwMask.

Windows 2000/NT: Não há suporte para esse recurso.

O código de exemplo a seguir cria a entrada da lista telefônica "RasEntryName", define suas credenciais usando rasSetCredentialse recupera essas credenciais usandorasGetCredentials .

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

#define PHONE_NUMBER_LENGTH 7
#define DEVICE_NAME_LENGTH 5
#define DEVICE_TYPE_LENGTH 5
#define DOMAIN_NAME_LENGTH 9
#define USER_NAME_LENGTH 11

DWORD __cdecl wmain(){

    DWORD dwRet = ERROR_SUCCESS;    
    LPTSTR lpszEntry = L"RasEntryName";
    LPTSTR lpszPhoneNumber = L"5555555";
    LPTSTR lpszDeviceName = L"Modem";
    LPTSTR lpszDeviceType = RASDT_Modem;
    LPTSTR lpszDomainName = L"RASDomain";
    LPTSTR lpszUserName = L"RASUserName";
    /***********************************************************************************************/
    // Create a new phone book entry
    /***********************************************************************************************/
  
    // Allocate heap memory for the RASENTRY structure
    LPRASENTRY lpentry = (LPRASENTRY)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRY));
    if (lpentry == NULL){
        wprintf(L"HeapAlloc failed!\n");
        return 0;
    }
    // The RASENTRY->dwSize member has to be initialized or the RRAS RasValidateEntryName() and 
    // RasSetEntryProperties APIs will fail below.
    lpentry->dwSize = sizeof(RASENTRY);
    lpentry->dwFramingProtocol = RASFP_Ppp;
    lpentry->dwfOptions = 0;
    lpentry->dwType = RASFP_Ppp;
    dwRet |= StringCchCopyN(lpentry->szLocalPhoneNumber, RAS_MaxPhoneNumber, lpszPhoneNumber, PHONE_NUMBER_LENGTH);
    dwRet |= StringCchCopyN(lpentry->szDeviceName, RAS_MaxDeviceName, lpszDeviceName, DEVICE_NAME_LENGTH);
    dwRet |= StringCchCopyN(lpentry->szDeviceType, RAS_MaxDeviceType, lpszDeviceType, DEVICE_TYPE_LENGTH);
    if (dwRet != ERROR_SUCCESS){
        wprintf(L"RASENTRY structure initialization failed!\n");
        HeapFree(GetProcessHeap(), 0, lpentry);
        return 0;
    }

    // Validate the new entry's name
    dwRet = RasValidateEntryName(NULL, lpszEntry);
    if (dwRet != ERROR_SUCCESS){
        wprintf(L"RasValidateEntryName failed: Error = %d\n", dwRet);
        HeapFree(GetProcessHeap(), 0, lpentry);
        return 0;
        }

    // Create and set the new entry's properties
    dwRet = RasSetEntryProperties(NULL, lpszEntry, lpentry, lpentry->dwSize, NULL, 0);
    if (dwRet != ERROR_SUCCESS){
        wprintf(L"RasSetEntryProperties failed: Error = %d\n", dwRet);
        HeapFree(GetProcessHeap(), 0, lpentry);
        return 0;
    }

    /******************************************************************************************/
    // Set and get the new entry's credentials
    /******************************************************************************************/

    // Allocate heap memory for the RASCREDENTIALS structure
    LPRASCREDENTIALS lpCred = (LPRASCREDENTIALS) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASCREDENTIALS));
    if (lpCred == NULL){
        wprintf(L"HeapAlloc failed!\n");
        return 0;
    }
    // The RASCREDENTIALS->dwsize member must be initialized or the RRAS RasSetCredentials() and 
    // RasGetCredentials() APIs will fail below
    lpCred->dwSize = sizeof(RASCREDENTIALS);

    // The entry's credentials must first be set with RasSetCredentials() before they can be 
    // retrieved with RasGetCredentials(). The values below are used to set the new entry's credentials.
    dwRet |= StringCchCopyN(lpCred->szDomain, DNLEN, lpszDomainName, DOMAIN_NAME_LENGTH);
    dwRet |= StringCchCopyN(lpCred->szUserName, UNLEN, lpszUserName, USER_NAME_LENGTH);
    if (dwRet != ERROR_SUCCESS){
        wprintf(L"RASCREDENTIALS structure initialization failed!\n");
        HeapFree(GetProcessHeap(), 0, lpCred);
        return 0;
    }
    // The username, password, and Domain credentials are valid
    lpCred->dwMask = RASCM_UserName | RASCM_Password | RASCM_Domain;
    
    // Set the newly created entry's credentials
    dwRet = RasSetCredentials(NULL, lpszEntry, lpCred, FALSE);
    
    // The same RASCREDENTIALS structure is used to 'set' and 'get' the credentials. Therefore, zero out 
    // its values. (this proves RasGetCredentials works below!) 
    dwRet |= StringCchCopyN(lpCred->szDomain, DNLEN, L"", 0);
    dwRet |= StringCchCopyN(lpCred->szUserName, UNLEN, L"", 0);
    dwRet |= StringCchCopyN(lpCred->szPassword, UNLEN, L"", 0);
    if (dwRet != ERROR_SUCCESS){
        wprintf(L"RASCREDENTIALS structure reset failed!\n");
        HeapFree(GetProcessHeap(), 0, lpCred);
        HeapFree(GetProcessHeap(), 0, lpentry);
        return 0;
    }

    // Grab the newly created entry's credentials
    dwRet = RasGetCredentials(NULL, lpszEntry, lpCred);
    if(dwRet == ERROR_SUCCESS){
        wprintf(L"The following credentials were retrieved for the entry: %s\n\tUser name: %s\n\tPassword: %s\n\tDomain: %s\n", lpszEntry, lpCred->szUserName, lpCred->szPassword, lpCred->szDomain);
    }else{
        wprintf(L"RasValidateEntryName failed: Error = %d\n", dwRet);
    }

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

    HeapFree(GetProcessHeap(), 0, lpentry);
    HeapFree(GetProcessHeap(), 0, lpCred);
    return 0;
}

Nota

O cabeçalho ras.h define RasGetCredentials como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	ras.h
biblioteca	Rasapi32.lib
de DLL	Rasapi32.dll

Consulte também

RASCREDENTIALS

RasGetEntryDialParams

rasSetCredentials

Visão geral do RAS (Serviço de Acesso Remoto)

Funções do Serviço de Acesso Remoto

Compartilhar via