Función CommandLineToArgvW (shellapi.h)

Analiza una cadena de línea de comandos Unicode y devuelve una matriz de punteros a los argumentos de la línea de comandos, junto con un recuento de estos argumentos, de forma similar a los valores argv y argc estándar en tiempo de ejecución de C.

Sintaxis

LPWSTR * CommandLineToArgvW(
  [in]  LPCWSTR lpCmdLine,
  [out] int     *pNumArgs
);

Parámetros

[in] lpCmdLine

Tipo: LPCWSTR

Puntero a una cadena Unicode terminada en null que contiene la línea de comandos completa. Si este parámetro es una cadena vacía, la función devuelve la ruta de acceso al archivo ejecutable actual.

[out] pNumArgs

Tipo: int*

Puntero a un valor int que recibe el número de elementos de matriz devueltos, similar a argc.

Valor devuelto

Tipo: LPWSTR*

Puntero a una matriz de valores LPWSTR , similar a argv.

Si la función no se realiza correctamente, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La dirección devuelta por CommandLineToArgvW es la dirección del primer elemento de una matriz de valores LPWSTR ; el número de punteros de esta matriz se indica mediante pNumArgs. Cada puntero a una cadena Unicode terminada en null representa un argumento individual que se encuentra en la línea de comandos.

CommandLineToArgvW asigna un bloque de memoria contigua para punteros a las cadenas de argumentos y para las propias cadenas de argumentos; la aplicación que realiza la llamada debe liberar la memoria usada por la lista de argumentos cuando ya no es necesaria. Para liberar la memoria, use una sola llamada a la función LocalFree .

Para obtener más información sobre la convención de argumentos argv y argc , vea Definiciones de argumentos y análisis de C Command-Line Argumentos.

La función GetCommandLineW se puede usar para obtener una cadena de línea de comandos adecuada para su uso como parámetro lpCmdLine .

Esta función acepta líneas de comandos que contienen un nombre de programa; el nombre del programa se puede incluir entre comillas o no.

CommandLineToArgvW tiene una interpretación especial de caracteres de barra diagonal inversa cuando van seguidos de un carácter de comillas ("). Esta interpretación supone que cualquier argumento anterior es una ruta de acceso válida del sistema de archivos o, de lo contrario, puede comportarse de forma impredecible.

Esta interpretación especial controla el modo "entre comillas" seguido por el analizador. Cuando este modo está desactivado, el espacio en blanco finaliza el argumento actual. Cuando está activado, se agrega un espacio en blanco al argumento como todos los demás caracteres.

• 2n barras diagonales inversas seguidas de una comilla produce n barras diagonales inversas seguidas de comillas iniciales y finales. Esto no forma parte del argumento analizado, pero alterna el modo "entre comillas".
• (2n) + 1 barras diagonales inversas seguidas de una comilla produce de nuevo n barras diagonales inversas seguidas de un literal de comillas ("). Esto no alterna el modo "entre comillas".
• n barras diagonales inversas no seguidas de comillas simplemente producen n barras diagonales inversas.

Importante  

CommandLineToArgvW trata el espacio en blanco fuera de comillas como delimitadores de argumentos. Sin embargo, si lpCmdLine comienza con cualquier cantidad de espacio en blanco, CommandLineToArgvW considerará que el primer argumento es una cadena vacía. Se omite el exceso de espacios en blanco al final de lpCmdLine .

 

Ejemplos

En el ejemplo siguiente se muestra cómo analizar una cadena de línea de comandos Unicode. El código libera la memoria de la lista de argumentos al salir.

#include <windows.h>
#include <stdio.h>
#include <shellapi.h>

int __cdecl main()
{
   LPWSTR *szArglist;
   int nArgs;
   int i;

   szArglist = CommandLineToArgvW(GetCommandLineW(), &nArgs);
   if( NULL == szArglist )
   {
      wprintf(L"CommandLineToArgvW failed\n");
      return 0;
   }
   else for( i=0; i<nArgs; i++) printf("%d: %ws\n", i, szArglist[i]);

// Free memory allocated for CommandLineToArgvW arguments.

   LocalFree(szArglist);

   return(1);
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server, Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shellapi.h
Library	Shell32.lib
Archivo DLL	Shell32.dll (versión 6.0 o posterior)