CommandLineToArgvW, fonction (shellapi.h)

  • Article

Analyse une chaîne de ligne de commande Unicode et retourne un tableau de pointeurs vers les arguments de ligne de commande, ainsi qu’un nombre de ces arguments, d’une manière similaire aux valeurs argv et argc d’exécution C standard.

Syntaxe

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

Paramètres

[in] lpCmdLine

Type : LPCWSTR

Pointeur vers une chaîne Unicode terminée par null qui contient la ligne de commande complète. Si ce paramètre est une chaîne vide, la fonction retourne le chemin d’accès au fichier exécutable actuel.

[out] pNumArgs

Type : int*

Pointeur vers un int qui reçoit le nombre d’éléments de tableau retournés, comme argc.

Valeur retournée

Type : LPWSTR*

Pointeur vers un tableau de valeurs LPWSTR , similaire à argv.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

L’adresse retournée par CommandLineToArgvW est l’adresse du premier élément d’un tableau de valeurs LPWSTR ; le nombre de pointeurs dans ce tableau est indiqué par pNumArgs. Chaque pointeur vers une chaîne Unicode terminée par null représente un argument individuel trouvé sur la ligne de commande.

CommandLineToArgvW alloue un bloc de mémoire contiguë pour les pointeurs vers les chaînes d’argument et pour les chaînes d’argument elles-mêmes ; l’application appelante doit libérer la mémoire utilisée par la liste d’arguments quand elle n’est plus nécessaire. Pour libérer de la mémoire, utilisez un seul appel à la fonction LocalFree .

Pour plus d’informations sur la convention d’argument argv et argc , consultez Définitions d’arguments et analyse des arguments C Command-Line Arguments.

La fonction GetCommandLineW peut être utilisée pour obtenir une chaîne de ligne de commande qui peut être utilisée comme paramètre lpCmdLine .

Cette fonction accepte les lignes de commande qui contiennent un nom de programme ; le nom du programme peut être placé entre guillemets ou non.

CommandLineToArgvW a une interprétation spéciale des caractères barre oblique inverse lorsqu’ils sont suivis d’un caractère de guillemet (« ). Cette interprétation suppose que tout argument précédent est un chemin de système de fichiers valide, sinon il peut se comporter de manière imprévisible.

Cette interprétation spéciale contrôle le mode « entre guillemets » suivi par l’analyseur. Lorsque ce mode est désactivé, l’espace blanc termine l’argument actuel. Lorsque cette option est activée, un espace blanc est ajouté à l’argument comme tous les autres caractères.

  • 2n barres obliques inverses suivies d’un guillemet produisent n barres obliques inverses suivies d’un guillemet début/fin. Cela ne fait pas partie de l’argument analysé, mais bascule le mode « entre guillemets ».
  • (2n) + 1 barres obliques inverses suivies d’un guillemet produisent à nouveau n barres obliques inverses suivies d’un littéral de guillemets (« ). Cela ne permet pas de désactiver le mode « entre guillemets ».
  • n barres obliques inverses non suivies d’un guillemet produisent simplement n barres obliques inverses.
Important  

CommandLineToArgvW traite les espaces blancs en dehors des guillemets comme des délimiteurs d’arguments. Toutefois, si lpCmdLine commence par une quantité quelconque d’espaces blancs, CommandLineToArgvW considère que le premier argument est une chaîne vide. L’espace blanc excédentaire à la fin de lpCmdLine est ignoré.

 

Exemples

L’exemple suivant montre comment analyser une chaîne de ligne de commande Unicode. Le code libère la mémoire de la liste d’arguments à la sortie.

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

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel, Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server, Windows Server 2003 [applications de bureau uniquement]
Plateforme cible Windows
En-tête shellapi.h
Bibliothèque Shell32.lib
DLL Shell32.dll (version 6.0 ou ultérieure)