Função DoEnvironmentSubstA (shellapi.h)

  • Artigo

[Essa função é mantida apenas para compatibilidade com versões anteriores. Use ExpandEnvironmentStrings em vez disso.]

Analisa uma cadeia de caracteres de entrada que contém referências a uma ou mais variáveis de ambiente e as substitui por seus valores totalmente expandidos.

Sintaxe

DWORD DoEnvironmentSubstA(
  [in, out] LPSTR pszSrc,
            UINT  cchSrc
);

Parâmetros

[in, out] pszSrc

Tipo: LPTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo que contém referências a uma ou mais variáveis de ambiente, cada uma no formulário a seguir. A diferenciação entre maiúsculas e minúsculas é ignorada.

%VariableName%

Qualquer caractere na cadeia de caracteres que não está entre caracteres '%' é ignorado e retornado inalterado. Portanto, se a cadeia de caracteres contiver várias variáveis de ambiente, você poderá usar qualquer caractere diferente de '%' como separador, incluindo espaços ou nenhum separador.

Quando essa função retorna com êxito, cada %VariableName% é substituído por seu valor expandido. As regras de substituição são as mesmas usadas pelo interpretador de comando. Se o nome da variável não for encontrado no sistema, %variableName% será deixado como foi enviado na entrada.

Se essa função falhar devido à cadeia de caracteres expandida ser muito grande para o buffer, o conteúdo desse buffer ficará inalterado.

cchSrc

Tipo: UINT

O tamanho, em caracteres, do buffer apontado por pszSrc. Observe que o buffer deve ser grande o suficiente para manter a cadeia de caracteres retornada.

Retornar valor

Tipo: DWORD

Se a cadeia de caracteres expandida se ajustar ao buffer, TRUE será retornado no HIWORD e o comprimento, em caracteres, do novo pszSrc será retornado no LOWORD.

Se a cadeia de caracteres expandida for muito grande para o buffer, FALSE será retornado em HIWORD e cchSrc no LOWORD.

Comentários

Os parâmetros devem conter valores válidos e não NULL . Você deve validar esses valores. A falha ao fazer isso pode fornecer resultados inesperados.

Como a cadeia de caracteres retornada em pszSrc normalmente será maior que a cadeia de caracteres de entrada, verifique se o buffer é grande o suficiente para manter a versão expandida da cadeia de caracteres. O tamanho alocado do buffer cchSrc para cadeias de caracteres ANSI deve ser um maior que o buffer de uma cadeia de caracteres Unicode. Ao lidar com cadeias de caracteres ANSI, use o tamanho do buffer de fórmula = comprimento da cadeia de caracteres + caractere nulo de terminação + 1 para determinar o tamanho mínimo correto do buffer.

Como as variáveis de ambiente podem ser adicionadas pelo usuário ou aplicativos, a lista completa depende do sistema. As variáveis de ambiente a seguir são padrão e estão disponíveis para aplicativos e serviços interativos.

  • ALLUSERSPROFILE
  • APPDATA
  • COMPUTERNAME
  • LOCALAPPDATA
  • NUMBER_OF_PROCESSORS
  • Sistema operacional
  • PROCESSOR_ARCHITECTURE
  • PROCESSOR_IDENTIFIER
  • PROCESSOR_LEVEL
  • PROCESSOR_REVISION
  • ProgramData
  • ProgramFiles
  • PUBLIC
  • SystemDrive
  • SystemRoot
  • USERPROFILE
  • Windir
Os itens a seguir só estão disponíveis para aplicativos interativos.
  • HOMEDRIVE
  • HOMEPATH
  • LOGONSERVER
  • USERDOMAIN
  • USERNAME
As variáveis de ambiente que correspondem às pastas do sistema de arquivos podem ser mapeadas para um valor CSIDL ou KNOWNFOLDERID equivalente podem ser obtidas por meio de SHGetFolderLocation ou SHGetKnownFolderPath. CSIDLs e KNOWNFOLDERIDs são mais confiáveis do que nomes de variáveis de ambiente e devem ser usados sempre que possível.

Exemplos

O aplicativo de console a seguir demonstra o uso de DoEnvironmentSubstW.


#include "stdafx.h"
#include "windows.h"
#include "windef.h"
#include "shellapi.h"

int _tmain(int argc, _TCHAR* argv[])
{
	WCHAR szSrc[MAX_PATH] = L"%OS%;%HOMEPATH%";

	DWORD result = DoEnvironmentSubstW(szSrc, MAX_PATH);

	WORD success = HIWORD(result);
	WORD string_length = LOWORD(result);

	return 0;
}

Observação

O cabeçalho shellapi.h define DoEnvironmentSubst 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 XP [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 shellapi.h
Biblioteca Shell32.lib
DLL Shell32.dll (versão 4.0 ou posterior)