Compartir a través de

Función DoEnvironmentSubstA (shellapi.h)

  • Artículo

[Esta función solo se conserva por motivos de compatibilidad con versiones anteriores. Use expandEnvironmentStrings en su lugar.

Analiza una cadena de entrada que contiene referencias a una o varias variables de entorno y las reemplaza por sus valores totalmente expandidos.

Sintaxis

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

Parámetros

[in, out] pszSrc

Tipo: LPTSTR de

Puntero a una cadena terminada en null que contiene referencias a una o varias variables de entorno, cada una de ellas con el formato siguiente. Se omite el caso.

%VariableName%

Cualquier carácter de la cadena que no esté entre "%" caracteres " se omite y se devuelve sin cambios. Por lo tanto, si la cadena contiene varias variables de entorno, puede usar cualquier carácter distinto de "%" como separador, incluidos los espacios o ningún separador.

Cuando esta función se devuelve correctamente, cada %variableName% se reemplaza por su valor expandido. Las reglas de reemplazo son las mismas que las usadas por el intérprete de comandos. Si no se encuentra el nombre de la variable en el sistema, el %variableName% se deja tal como se envió en la entrada.

Si se produce un error en esta función debido a que la cadena expandida es demasiado grande para el búfer, el contenido de este búfer se deja sin cambios.

cchSrc

Tipo: UINT

Tamaño, en caracteres, del búfer al que apunta pszSrc. Tenga en cuenta que el búfer debe ser lo suficientemente grande como para contener la cadena devuelta.

Valor devuelto

Tipo: DWORD de

Si la cadena expandida se ajusta al búfer, se devuelve TRUE en el HIWORD y la longitud, en caracteres, del nuevo pszSrc se devuelve en loWORD.

Si la cadena expandida es demasiado grande para el búfer, se devuelve FALSE en HIWORD y cchSrc en loWORD.

Observaciones

Los parámetros deben contener valores válidos que noNULL. Debe validar estos valores. Si no lo hace, puede proporcionar resultados inesperados.

Dado que la cadena que se devuelve en pszSrc normalmente será más larga que la cadena de entrada, asegúrese de que el búfer es lo suficientemente grande como para contener la versión expandida de la cadena. El tamaño asignado de la cchSrc búfer para cadenas ANSI debe ser uno mayor que el búfer para una cadena Unicode. Al tratar con cadenas ANSI, use la fórmula tamaño del búfer = longitud de cadena + carácter NULO de terminación + 1 para determinar el tamaño mínimo correcto del búfer.

Dado que el usuario o las aplicaciones pueden agregar variables de entorno, la lista completa depende del sistema. Las siguientes variables de entorno son estándar y están disponibles para aplicaciones interactivas y servicios.

  • ALLUSERSPROFILE
  • APPDATA
  • COMPUTERNAME
  • LOCALAPPDATA
  • NUMBER_OF_PROCESSORS
  • Sistema operativo
  • PROCESSOR_ARCHITECTURE
  • PROCESSOR_IDENTIFIER
  • PROCESSOR_LEVEL
  • PROCESSOR_REVISION
  • ProgramData
  • Archivos de programa
  • PÚBLICO
  • SystemDrive
  • SystemRoot
  • USERPROFILE
  • windir
Los siguientes solo están disponibles para aplicaciones interactivas.
  • HOMEDRIVE
  • HOMEPATH
  • LOGONSERVER
  • USERDOMAIN
  • NOMBRE DE USUARIO
Las variables de entorno que corresponden a carpetas del sistema de archivos se pueden asignar a un CSIDL equivalente o valor de KNOWNFOLDERID a través de SHGetFolderLocation o SHGetKnownFolderPath. Los CSIDLs y KNOWNFOLDERIDs son más confiables que los nombres de variables de entorno y se deben usar siempre que sea posible.

Ejemplos

La siguiente aplicación de consola muestra el 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;
}

Nota

El encabezado shellapi.h define DoEnvironmentSubst como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito Valor
cliente mínimo admitido Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de Windows
encabezado de shellapi.h
biblioteca de Shell32.lib
DLL de Shell32.dll (versión 4.0 o posterior)