Funzione CommandLineToArgvW (shellapi.h)

Articolo
03/11/2023

Analizza una stringa della riga di comando Unicode e restituisce una matrice di puntatori agli argomenti della riga di comando, insieme a un conteggio di tali argomenti, in modo simile ai valori argv e argc di runtime C standard.

Sintassi

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

Parametri

[in] lpCmdLine

Tipo: LPCWSTR

Puntatore a una stringa Unicode con terminazione Null che contiene la riga di comando completa. Se questo parametro è una stringa vuota, la funzione restituisce il percorso del file eseguibile corrente.

[out] pNumArgs

Tipo: int*

Puntatore a un valore int che riceve il numero di elementi di matrice restituiti, simile a argc.

Valore restituito

Tipo: LPWSTR*

Puntatore a una matrice di valori LPWSTR , simile ad argv.

Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

L'indirizzo restituito da CommandLineToArgvW è l'indirizzo del primo elemento in una matrice di valori LPWSTR ; il numero di puntatori in questa matrice è indicato da pNumArgs. Ogni puntatore a una stringa Unicode con terminazione Null rappresenta un singolo argomento trovato nella riga di comando.

CommandLineToArgvW alloca un blocco di memoria contigua per i puntatori alle stringhe di argomenti e per le stringhe degli argomenti stessi; l'applicazione chiamante deve liberare la memoria usata dall'elenco di argomenti quando non è più necessaria. Per liberare la memoria, usare una singola chiamata alla funzione LocalFree .

Per altre informazioni sulla convenzione degli argomenti argv e argc, vedere Definizioni di argomenti e analisi degli argomenti C Command-Line.

La funzione GetCommandLineW può essere usata per ottenere una stringa della riga di comando adatta per l'uso come parametro lpCmdLine .

Questa funzione accetta righe di comando che contengono un nome di programma; il nome del programma può essere racchiuso tra virgolette o meno.

CommandLineToArgvW ha un'interpretazione speciale dei caratteri barra rovesciata quando sono seguiti da una virgoletta ("). Questa interpretazione presuppone che qualsiasi argomento precedente sia un percorso di file system valido oppure che possa comportarsi in modo imprevedibile.

Questa interpretazione speciale controlla la modalità "tra virgolette" rilevata dal parser. Quando questa modalità è disattivata, lo spazio vuoto termina l'argomento corrente. Quando è attivato, gli spazi vuoti vengono aggiunti all'argomento come tutti gli altri caratteri.

2n barre rovesciata seguite da virgolette producono n barre rovesciata seguite da virgolette iniziali/finali. Questo non diventa parte dell'argomento analizzato, ma attiva o disattiva la modalità "tra virgolette".
(2n) + 1 barre rovesciata seguite da una virgoletta producono di nuovo n barre rovesciata seguite da un valore letterale virgolette ("). In questo modo non viene attivata o disattivata la modalità "tra virgolette".
n barre rovesciata non seguite da virgolette producono semplicemente n barre rovesciata.

Importante

CommandLineToArgvW considera gli spazi vuoti all'esterno delle virgolette come delimitatori di argomenti. Tuttavia, se lpCmdLine inizia con qualsiasi quantità di spazi vuoti, CommandLineToArgvW considererà il primo argomento come stringa vuota. Gli spazi vuoti in eccesso alla fine di lpCmdLine vengono ignorati.

Esempio

Nell'esempio seguente viene illustrato come analizzare una stringa della riga di comando Unicode. Il codice libera la memoria per l'elenco di argomenti all'uscita.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional, Windows XP [solo app desktop]
Server minimo supportato	Windows 2000 Server, Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shellapi.h
Libreria	Shell32.lib
DLL	Shell32.dll (versione 6.0 o successiva)

Condividi tramite