Функция CommandLineToArgvW (shellapi.h)

  • Статья

Анализирует строку командной строки Юникода и возвращает массив указателей на аргументы командной строки, а также количество таких аргументов, аналогично стандартным значениям argv и argc времени выполнения C.

Синтаксис

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

Параметры

[in] lpCmdLine

Тип: LPCWSTR

Указатель на строку Юникода, завершающуюся null, которая содержит полную командную строку. Если этот параметр является пустой строкой, функция возвращает путь к текущему исполняемому файлу.

[out] pNumArgs

Тип: int*

Указатель на int , получающий количество возвращаемых элементов массива, аналогично argc.

Возвращаемое значение

Тип: LPWSTR*

Указатель на массив значений LPWSTR , аналогичный argv.

Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Комментарии

Адрес, возвращаемый командой CommandLineToArgvW , — это адрес первого элемента в массиве значений LPWSTR ; количество указателей в этом массиве обозначается pNumArgs. Каждый указатель на строку Юникода, завершаемую null, представляет отдельный аргумент, найденный в командной строке.

CommandLineToArgvW выделяет блок непрерывной памяти для указателей на строки аргументов и для самих строк аргументов; вызывающее приложение должно освободить память, используемую списком аргументов, если она больше не нужна. Чтобы освободить память, используйте один вызов функции LocalFree .

Дополнительные сведения о соглашении аргументов argv и argc см. в разделах Определения аргументов и Синтаксический анализ аргументов C Command-Line.

Функцию GetCommandLineW можно использовать для получения строки командной строки, которая подходит для использования в качестве параметра lpCmdLine .

Эта функция принимает командные строки, содержащие имя программы; Имя программы может быть заключено в кавычки или нет.

CommandLineToArgvW имеет специальную интерпретацию символов обратной косой черты, за которыми следует символ кавычек ("). Эта интерпретация предполагает, что любой предыдущий аргумент является допустимым путем файловой системы, иначе он может вести себя непредсказуемо.

Эта специальная интерпретация управляет режимом "в кавычках", отслеживаемым анализатором. Если этот режим отключен, пробел завершает текущий аргумент. Если включено, пробел добавляется к аргументу, как и все остальные символы.

  • 2n обратных косых черт, за которым следует кавычка, создают n обратных косых черт, за которыми следует начальная/конечная кавычка. Это не становится частью проанализированного аргумента, но переключает режим "в кавычках".
  • (2n) + 1 обратная косая черта, за которой следует кавычка, снова создают n обратных косых черт, за которыми следует литерал кавычки ("). При этом режим "в кавычках" не переключается.
  • N обратных косых черт, за которыми не следует кавычка, просто производят n обратных косых черт.
Важно  

CommandLineToArgvW рассматривает пробелы вне кавычек как разделители аргументов. Однако если lpCmdLine начинается с любого количества пробелов, CommandLineToArgvW будет считать первый аргумент пустой строкой. Лишние пробелы в конце lpCmdLine игнорируются.

 

Примеры

В следующем примере показано, как проанализировать строку командной строки Юникода. Код освобождает память для списка аргументов при выходе.

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

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Professional, Windows XP [только классические приложения]
Минимальная версия сервера Windows 2000 Server, Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header shellapi.h
Библиотека Shell32.lib
DLL Shell32.dll (версия 6.0 или более поздняя)