Função RasSetEntryPropertiesA (ras.h)

Artigo
08/25/2023

A função RasSetEntryProperties altera as informações de conexão de uma entrada na lista telefônica ou cria uma nova entrada de catálogo telefônico.

Sintaxe

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

Parâmetros

[in] unnamedParam1

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o caminho completo e o nome do arquivo de um arquivo de catálogo telefônico (PBK). Se esse parâmetro for NULL, a função usará o arquivo de catálogo telefônico padrão atual. O arquivo de agendamento telefônico padrão é aquele selecionado pelo usuário na folha de propriedades Preferências do Usuário da caixa de diálogo Rede Discada .

[in] unnamedParam2

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica um nome de entrada.

Se o nome da entrada corresponder a uma entrada existente, RasSetEntryProperties modificará as propriedades dessa entrada.

Se o nome da entrada não corresponder a uma entrada existente, RasSetEntryProperties criará uma nova entrada de catálogo telefônico. Para novas entradas, chame a função RasValidateEntryName para validar o nome da entrada antes de chamar RasSetEntryProperties.

[in] unnamedParam3

Ponteiro para a estrutura RASENTRY que especifica os novos dados de conexão a serem associados à entrada do catálogo telefônico indicada pelo parâmetro lpszEntry .

O chamador deve fornecer valores para os membros a seguir na estrutura RASENTRY .

dwSize
szLocalPhoneNumber
Szdevicename
szDeviceType
dwFramingProtocol
Dwfoptions
Dwtype

Windows XP ou posterior: há suporte para dwType.

Se os valores não forem fornecidos para esses membros, RasSetEntryProperties falhará com ERROR_INVALID_PARAMETER.

A estrutura pode ser seguida por uma matriz de cadeias de caracteres de número de telefone alternativo terminadas em nulo. A última cadeia de caracteres é encerrada por dois caracteres nulos consecutivos. O membro dwAlternateOffset da estrutura RASENTRY contém o deslocamento para a primeira cadeia de caracteres.

[in] unnamedParam4

Especifica o tamanho, em bytes, do buffer identificado pelo parâmetro lpRasEntry .

[in] unnamedParam5

Ponteiro para um buffer que especifica informações de configuração específicas do dispositivo. Essas são informações opacas de configuração de dispositivo TAPI. Para obter mais informações sobre a configuração do dispositivo TAPI, consulte a função lineGetDevConfig em TAPI (Interfaces de Programação de Aplicativo de Telefonia) no SDK da Plataforma.

Windows XP: Esse parâmetro não é utilizado. A função de chamada deve definir esse parâmetro como NULL.

[in] unnamedParam6

Especifica o tamanho, em bytes, do buffer lpbDeviceInfo .

Windows XP: Esse parâmetro não é utilizado. A função de chamada deve definir esse parâmetro como zero.

Retornar valor

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_ACCESS_DENIED	O usuário não tem os privilégios corretos. Somente um administrador pode concluir essa tarefa.
ERROR_BUFFER_INVALID	O endereço ou buffer especificado por lpRasEntry é inválido.
ERROR_CANNOT_OPEN_PHONEBOOK	A lista telefônica está corrompida ou está faltando componentes.
ERROR_INVALID_PARAMETER	A estrutura RASENTRY apontada pelo parâmetro lpRasEntry não contém informações adequadas ou a entrada especificada não existe na lista telefônica. Consulte a descrição de lpRasEntry para ver quais informações são necessárias.

Comentários

Ao definir propriedades para uma conexão de todos os usuários, se o aplicativo de chamada especificar um valor não NULL para o parâmetro phone-book, lpszPhonebook, o arquivo de catálogo telefônico deverá estar localizado no diretório do catálogo telefônico abaixo do caminho de dados do aplicativo de todos os usuários. Para obter o local correto para o arquivo de catálogo telefônico, primeiro chame SHGetFolderPath com um valor CSIDL de CSIDL_COMMON_APPDATA. SHGetFolderPath retorna o caminho de dados do aplicativo de todos os usuários. Acrescente a seguinte cadeia de caracteres a este caminho:

Microsoft\Network\Connections\Pbk

O caminho combinado é o local correto para o arquivo de agendamento telefônico.

Nota A especificação de um valor não NULL para o parâmetro lpszPhonebook pode não ter suporte em versões do Windows posteriores ao Windows XP.

Observação

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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ras.h
Biblioteca	Rasapi32.lib
DLL	Rasapi32.dll