CommandLineToArgvW-Funktion (shellapi.h)

Artikel
03/01/2024

Analysiert eine Unicode-Befehlszeilenzeichenfolge und gibt ein Array von Zeigern auf die Befehlszeilenargumente zusammen mit einer Anzahl solcher Argumente auf eine Weise zurück, die den Standardmäßigen C-Laufzeit argv - und argc-Werten ähnelt.

Syntax

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

Parameter

[in] lpCmdLine

Typ: LPCWSTR

Zeiger auf eine Unicode-Zeichenfolge mit Null-Endung, die die vollständige Befehlszeile enthält. Wenn es sich bei diesem Parameter um eine leere Zeichenfolge handelt, gibt die Funktion den Pfad zur aktuellen ausführbaren Datei zurück.

[out] pNumArgs

Typ: int*

Zeiger auf einen int , der die Anzahl der zurückgegebenen Arrayelemente empfängt, ähnlich wie argc.

Rückgabewert

Typ: LPWSTR*

Ein Zeiger auf ein Array von LPWSTR-Werten , ähnlich wie argv.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die von CommandLineToArgvW zurückgegebene Adresse ist die Adresse des ersten Elements in einem Array von LPWSTR-Werten . die Anzahl der Zeiger in diesem Array wird durch pNumArgs angegeben. Jeder Zeiger auf eine Unicode-Zeichenfolge mit NULL-Beendigung stellt ein einzelnes Argument dar, das in der Befehlszeile gefunden wird.

CommandLineToArgvW weist einen Block zusammenhängenden Arbeitsspeichers für Zeiger auf die Argumentzeichenfolgen und für die Argumentzeichenfolgen selbst zu; Die aufrufende Anwendung muss den von der Argumentliste verwendeten Arbeitsspeicher freigeben, wenn er nicht mehr benötigt wird. Verwenden Sie einen einzelnen Aufruf der LocalFree-Funktion , um den Arbeitsspeicher freizugeben.

Weitere Informationen zur Argumentkonvention argv und argc finden Sie unter Argumentdefinitionen und Analysieren von C-Command-Line-Argumenten.

Die GetCommandLineW-Funktion kann verwendet werden, um eine Befehlszeilenzeichenfolge abzurufen, die für die Verwendung als lpCmdLine-Parameter geeignet ist.

Diese Funktion akzeptiert Befehlszeilen, die einen Programmnamen enthalten. der Programmname kann in Anführungszeichen eingeschlossen werden oder nicht.

CommandLineToArgvW verfügt über eine spezielle Interpretation von umgekehrten Schrägstrichen, wenn ihnen ein Anführungszeichen (") folgt. Bei dieser Interpretation wird davon ausgegangen, dass jedes vorherige Argument ein gültiger Dateisystempfad ist, andernfalls verhält es sich unvorhersehbar.

Diese spezielle Interpretation steuert den vom Parser nachverfolgten Modus "in Anführungszeichen". Wenn dieser Modus deaktiviert ist, beendet leerzeichen das aktuelle Argument. Wenn sie aktiviert ist, wird dem Argument wie bei allen anderen Zeichen Leerzeichen hinzugefügt.

2n umgekehrte Schrägstriche, gefolgt von einem Anführungszeichen, erzeugen n umgekehrte Schrägstriche, gefolgt von Einem Anfangs-/End-Anführungszeichen. Dies wird nicht Teil des analysierten Arguments, sondern schaltet den Modus "in Anführungszeichen" um.
(2n) + 1 umgekehrte Schrägstriche gefolgt von einem Anführungszeichen erzeugen wiederum n umgekehrte Schrägstriche gefolgt von einem Anführungszeichenliteral ("). Dadurch wird der Modus "in Anführungszeichen" nicht umfunktioniert.
n umgekehrte Schrägstriche, die nicht von einem Anführungszeichen gefolgt werden, erzeugen einfach n umgekehrte Schrägstriche.

Wichtig

CommandLineToArgvW behandelt Leerzeichen außerhalb von Anführungszeichen als Argumenttrennzeichen. Wenn lpCmdLine jedoch mit einer beliebigen Menge leerer Leerzeichen beginnt, betrachtet CommandLineToArgvW das erste Argument als leere Zeichenfolge. Überschüssiger Leerraum am Ende von lpCmdLine wird ignoriert.

Beispiele

Im folgenden Beispiel wird veranschaulicht, wie eine Unicode-Befehlszeilenzeichenfolge analysiert wird. Der Code gibt den Arbeitsspeicher für die Argumentliste beim Beenden frei.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional, Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server, Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shellapi.h
Bibliothek	Shell32.lib
DLL	Shell32.dll (Version 6.0 oder höher)

Freigeben über