Função RasGetErrorStringA (ras.h)

Artigo
11/20/2024

A função rasGetErrorString obtém uma cadeia de caracteres de mensagem de erro para um valor de erro RAS especificado.

Sintaxe

DWORD RasGetErrorStringA(
  [in]  UINT  ResourceId,
  [out] LPSTR lpszString,
  [in]  DWORD InBufSize
);

Parâmetros

[in] ResourceId

Especifica o valor de erro de interesse. Estes são valores retornados por uma das funções RAS: aquelas listadas no arquivo de cabeçalho RasError.h.

[out] lpszString

Ponteiro para um buffer que recebe a cadeia de caracteres de erro. Esse parâmetro não deve ser NULL.

[in] InBufSize

Especifica o tamanho, em caracteres, do buffer apontado por lpszErrorString.

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. Não há informações de GetLastError definidas pela função RasGetErrorString.

Valor	Significado
ERROR_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função.

Observações

Não há como determinar com antecedência o tamanho exato em caracteres de uma mensagem de erro e, portanto, o tamanho do buffer necessário. As mensagens de erro geralmente terão 80 caracteres ou menos de tamanho; um tamanho de buffer de 512 caracteres sempre será adequado. Um buffer de tamanho insuficiente faz com que a função RasGetErrorString falhe, retornando ERROR_INSUFFICIENT_BUFFER. Observe que os tamanhos de buffer são especificados em caracteres, não em bytes; assim, a versão Unicode do RasGetErrorString requer pelo menos um buffer de bytes 1024 para garantir que cada mensagem de erro se ajuste.

Exemplos

O código a seguir obtém uma cadeia de caracteres de erro para o erro RAS 633.


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

#define  ERROR_VAL 633
#define  BUFFER_SIZE 256

DWORD __cdecl wmain(){

    DWORD dwRetVal = ERROR_SUCCESS;
    UINT  uErrorValue = ERROR_VAL;
    DWORD cBufSize = BUFFER_SIZE;
    WCHAR lpszErrorString[BUFFER_SIZE];

    dwRetVal = RasGetErrorString(uErrorValue, lpszErrorString, cBufSize);

    if(dwRetVal == ERROR_SUCCESS){
        wprintf(L"Error Code %d: %s\n", uErrorValue, lpszErrorString);
    }else{
           wprintf(L"RasGetErrorString failed, Return Value: %d", dwRetVal);
    }

    return 0;
}

Nota

O cabeçalho ras.h define RasGetErrorString 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

GlobalAlloc

LoadString

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

Funções do Serviço de Acesso Remoto

Compartilhar via