Função RasSetEntryPropertiesA (ras.h)

Artigo
11/20/2024

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

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 PBK (lista telefônica). 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 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 lista telefônica. Para novas entradas, chame a função RasValidateEntryName para validar o nome da entrada antes de chamar RasSetEntryProperties.

[in] unnamedParam3

Ponteiro para a estrutura de RASENTRY que especifica os novos dados de conexão a serem associados à entrada de lista telefônica indicada pelo parâmetro lpszEntry.

O chamador deve fornecer valores para os seguintes membros na estrutura de 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 dwAlternateOffset membro 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. Estas são informações opacas de configuração do 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 Aplicativos de Telefonia) no SDK da Plataforma.

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

[in] unnamedParam6

Especifica o tamanho, em bytes, do buffer lpbDeviceInfo.

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

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_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.

Observações

Ao definir propriedades para uma conexão de todos os usuários, se o aplicativo de chamada especificar um valor NULL não para o parâmetro de lista telefônica, lpszPhonebook, o arquivo de lista telefônica deverá estar localizado no diretório de catálogo telefônico abaixo do caminho de dados do aplicativo para todos os usuários. Para obter o local correto para o arquivo de lista telefônica, primeira chamada SHGetFolderPath com um valor CSIDL de CSIDL_COMMON_APPDATA. SHGetFolderPath retorna o caminho de dados do aplicativo para 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 lista telefônica.

Observação Especificar um valor de NULL nãopara o parâmetro lpszPhonebook pode não ter suporte em versões do Windows posteriores ao Windows XP.

Nota

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