Função CommandLineToArgvW (shellapi.h)

Analisa uma cadeia de caracteres de linha de comando Unicode e retorna uma matriz de ponteiros para os argumentos de linha de comando, juntamente com uma contagem desses argumentos, de forma semelhante aos valores padrão de argv e argc em tempo de execução C.

Sintaxe

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

Parâmetros

[in] lpCmdLine

Tipo: LPCWSTR

Ponteiro para uma cadeia de caracteres Unicode terminada em nulo que contém a linha de comando completa. Se esse parâmetro for uma cadeia de caracteres vazia, a função retornará o caminho para o arquivo executável atual.

[out] pNumArgs

Tipo: int*

Ponteiro para um int que recebe o número de elementos de matriz retornados, semelhante ao argc.

Retornar valor

Tipo: LPWSTR*

Um ponteiro para uma matriz de valores LPWSTR , semelhante a argv.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

O endereço retornado por CommandLineToArgvW é o endereço do primeiro elemento em uma matriz de valores LPWSTR ; o número de ponteiros nessa matriz é indicado por pNumArgs. Cada ponteiro para uma cadeia de caracteres Unicode terminada em nulo representa um argumento individual encontrado na linha de comando.

CommandLineToArgvW aloca um bloco de memória contígua para ponteiros para as cadeias de caracteres de argumento e para as próprias cadeias de caracteres de argumento; o aplicativo de chamada deve liberar a memória usada pela lista de argumentos quando ela não for mais necessária. Para liberar a memória, use uma única chamada para a função LocalFree .

Para obter mais informações sobre a convenção de argumento argv e argc , consulte Definições de argumento e analisando argumentos de Command-Line C.

A função GetCommandLineW pode ser usada para obter uma cadeia de caracteres de linha de comando adequada para uso como o parâmetro lpCmdLine .

Essa função aceita linhas de comando que contêm um nome de programa; o nome do programa pode ser colocado entre aspas ou não.

CommandLineToArgvW tem uma interpretação especial de caracteres de barra invertida quando eles são seguidos por um caractere de aspas ("). Essa interpretação pressupõe que qualquer argumento anterior seja um caminho válido do sistema de arquivos ou então ele pode se comportar de forma imprevisível.

Essa interpretação especial controla o modo "entre aspas" rastreado pelo analisador. Quando esse modo está desativado, o espaço em branco encerra o argumento atual. Quando ativado, o espaço em branco é adicionado ao argumento como todos os outros caracteres.

• 2n barras invertidas seguidas por uma aspa produzem n barras invertidas seguidas de aspas de início/fim. Isso não se torna parte do argumento analisado, mas alterna o modo "entre aspas".
• (2n) + 1 barras invertidas seguidas por uma aspa novamente produzem n barras invertidas seguidas por um literal de aspas ("). Isso não alterna o modo "entre aspas".
• n barras invertidas não seguidas por uma aspa simplesmente produzem n barras invertidas.

Importante  

CommandLineToArgvW trata o espaço em branco fora das aspas como delimitadores de argumento. No entanto, se lpCmdLine começar com qualquer quantidade de espaço em branco, CommandLineToArgvW considerará o primeiro argumento como uma cadeia de caracteres vazia. O excesso de espaço em branco no final do lpCmdLine é ignorado.

 

Exemplos

O exemplo a seguir demonstra como analisar uma cadeia de caracteres de linha de comando Unicode. O código libera a memória da lista de argumentos na saída.

#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	Valor
Cliente mínimo com suporte	Windows 2000 Professional, Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server, Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shellapi.h
Biblioteca	Shell32.lib
DLL	Shell32.dll (versão 6.0 ou posterior)