Compartilhar via

Função DoEnvironmentSubstW (shellapi.h)

  • Artigo

[Essa função é retida apenas para compatibilidade com versões anteriores. Use ExpandEnvironmentStrings.]

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 DoEnvironmentSubstW(
  [in, out] LPWSTR 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. O caso é ignorado.

%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, o %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.

Valor de retorno

Tipo: DWORD

Se a cadeia de caracteres expandida se ajustar ao buffer, VERDADEIRO 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 no HIWORD e cchSrc no LOWORD.

Observações

Os parâmetros devem conter valores de NULL válidos e não. Você deve validar esses valores. 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 de cchSrc para cadeias de caracteres ANSI deve ser maior que o buffer de uma cadeia de caracteres Unicode. Ao lidar com cadeias de caracteres ANSI, use a fórmula tamanho do buffer = comprimento da cadeia de caracteres + terminando caractere nulo + 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
  • NOME DO COMPUTADOR
  • LOCALAPPDATA
  • NUMBER_OF_PROCESSORS
  • SO
  • PROCESSOR_ARCHITECTURE
  • PROCESSOR_IDENTIFIER
  • PROCESSOR_LEVEL
  • PROCESSOR_REVISION
  • ProgramData
  • ProgramFiles
  • PÚBLICO
  • SystemDrive
  • SystemRoot
  • USERPROFILE
  • windir
As opções a seguir só estão disponíveis para aplicativos interativos.
  • HOMEDRIVE
  • HOMEPATH
  • LOGONSERVER
  • USERDOMAIN
  • NOME DE USUÁRIO
As variáveis de ambiente que correspondem a pastas do sistema de arquivos podem ser mapeadas para um valor de CSIDL equivalente ou KNOWNFOLDERID 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 deDoEnvironmentSubstW .


#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;
}

Nota

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 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 XP [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 shellapi.h
biblioteca Shell32.lib
de DLL Shell32.dll (versão 4.0 ou posterior)