SHELLEXECUTEINFOW 구조체(shellapi.h)

아티클
03/15/2023

ShellExecuteEx에서 사용하는 정보를 포함합니다.

구문

typedef struct _SHELLEXECUTEINFOW {
  DWORD     cbSize;
  ULONG     fMask;
  HWND      hwnd;
  LPCWSTR   lpVerb;
  LPCWSTR   lpFile;
  LPCWSTR   lpParameters;
  LPCWSTR   lpDirectory;
  int       nShow;
  HINSTANCE hInstApp;
  void      *lpIDList;
  LPCWSTR   lpClass;
  HKEY      hkeyClass;
  DWORD     dwHotKey;
  union {
    HANDLE hIcon;
    HANDLE hMonitor;
  } DUMMYUNIONNAME;
  HANDLE    hProcess;
} SHELLEXECUTEINFOW, *LPSHELLEXECUTEINFOW;

멤버

cbSize

형식:DWORD

필수 사항입니다. 이 구조체의 크기(바이트)입니다.

fMask

형식: ULONG

다른 구조체 멤버의 콘텐츠와 유효성을 나타내는 다음 값 중 하나 이상의 조합입니다.

SEE_MASK_DEFAULT(0x00000000)	기본값을 사용합니다.
SEE_MASK_CLASSNAME(0x00000001)	lpClass 멤버가 지정한 클래스 이름을 사용합니다. SEE_MASK_CLASSKEY 및 SEE_MASK_CLASSNAME 모두 설정되면 클래스 키가 사용됩니다.
SEE_MASK_CLASSKEY(0x00000003)	hkeyClass 멤버가 제공한 클래스 키를 사용합니다. SEE_MASK_CLASSKEY 및 SEE_MASK_CLASSNAME 모두 설정되면 클래스 키가 사용됩니다.
SEE_MASK_IDLIST(0x00000004)	lpIDList 멤버가 제공한 항목 식별자 목록을 사용합니다. lpIDList 멤버는 ITEMIDLIST 구조를 가리킵니다.
SEE_MASK_INVOKEIDLIST(0x0000000C)	선택한 항목의 바로 가기 메뉴 처리기의 IContextMenu 인터페이스를 사용합니다. lpFile을 사용하여 파일 시스템 경로로 항목을 식별하거나 lpIDList를 사용하여 해당 PIDL로 항목을 식별합니다. 이 플래그를 사용하면 애플리케이션에서 ShellExecuteEx 를 사용하여 레지스트리에 나열된 정적 동사 대신 바로 가기 메뉴 확장에서 동사를 호출할 수 있습니다. 참고: SEE_MASK_INVOKEIDLIST 재정의되고 SEE_MASK_IDLIST 의미합니다.
SEE_MASK_ICON(0x00000010)	hIcon 멤버가 지정한 아이콘을 사용합니다. 이 플래그는 SEE_MASK_HMONITOR 결합할 수 없습니다. 참고: 이 플래그는 Windows XP 및 이전 버전에서만 사용됩니다. Windows Vista를 기준으로 무시됩니다.
SEE_MASK_HOTKEY(0x00000020)	dwHotKey 멤버가 제공한 바로 가기 키를 사용합니다.
SEE_MASK_NOCLOSEPROCESS(0x00000040)	를 사용하여 hProcess 멤버가 프로세스 핸들을 수신함을 나타냅니다. 이 핸들은 일반적으로 ShellExecuteEx 를 사용하여 만든 프로세스가 종료되는 시기를 애플리케이션에서 확인할 수 있도록 하는 데 사용됩니다. DDE 대화를 통해 실행이 충족되는 경우와 같은 경우에 핸들이 반환되지 않습니다. 호출 애플리케이션은 더 이상 필요하지 않은 경우 핸들을 닫습니다.
SEE_MASK_CONNECTNETDRV(0x00000080)	공유의 유효성을 검사하고 드라이브 문자에 연결합니다. 이렇게 하면 연결이 끊긴 네트워크 드라이브를 다시 연결할 수 있습니다. lpFile 멤버는 네트워크에 있는 파일의 UNC 경로입니다.
SEE_MASK_NOASYNC(0x00000100)	파일을 시작할 때만 적용되며 URI 또는 셸 네임스페이스 항목(예: "이 PC")에는 적용되지 않습니다. 반환하기 전에 실행 작업의 비동기 부분(예: DDE)이 완료되기를 기다립니다. 이 작업이 적용되면 반환하기 전에 시작 작업이 완료됩니다. ShellExecuteEx를 호출한 직후 종료되는 애플리케이션은 이 플래그를 지정해야 합니다. ShellExecuteEx는 호출자의 스레딩 모델이 Apartment가 아닌 경우 해당 작업을 백그라운드 스레드로 이동합니다. 호출을 동기적으로 적용하면 해당 동작이 비활성화되고 발신자 COM 아파트가 사용됩니다. SEE_MASK_FLAG_HINST_IS_SITE 지정하면 항상 동기 동작이 강제됩니다. 실행 작업이 백그라운드 스레드에서 수행되고 호출자가 SEE_MASK_ASYNCOK 플래그를 지정하지 않은 경우 호출 스레드는 반환하기 전에 새 프로세스가 시작될 때까지 기다립니다. 이는 일반적으로 CreateProcess 가 호출되었거나, DDE 통신이 완료되었거나, 사용자 지정 실행 대리자에서 ShellExecuteEx 에 작업이 완료되었음을 통보했음을 의미합니다. SEE_MASK_WAITFORINPUTIDLE 플래그를 지정하면 ShellExecuteEx 는 WaitForInputIdle 을 호출하고 반환하기 전에 새 프로세스가 유휴 상태가 될 때까지 대기하며 최대 시간 제한은 1분입니다. 이 플래그가 필요한 시기에 대한 자세한 내용은 설명 섹션을 참조하세요.
SEE_MASK_FLAG_DDEWAIT(0x00000100)	SEE_MASK_NOASYNC 동일한 옵션을 사용하는 것이 좋습니다.
SEE_MASK_DOENVSUBST(0x00000200)	lpDirectory 또는 lpFile 멤버가 지정한 문자열에 지정된 환경 변수를 확장합니다.
SEE_MASK_FLAG_NO_UI(0x00000400)	이 옵션 없이 일반적으로 표시되는 오류 대화 상자, 보안 경고 또는 기타 사용자 인터페이스를 포함하여 UI(사용자 인터페이스)를 표시하지 마세요.
SEE_MASK_UNICODE(0x00004000)	이 플래그를 사용하여 유니코드 애플리케이션을 나타냅니다.
SEE_MASK_NO_CONSOLE(0x00008000)	를 사용하여 새 콘솔을 만드는 대신 새 프로세스에 대한 부모의 콘솔을 상속합니다. CreateProcess에서 CREATE_NEW_CONSOLE 플래그를 사용하는 것과는 반대입니다.
SEE_MASK_ASYNCOK(0x00100000)	백그라운드 스레드에서 실행을 수행할 수 있으며 백그라운드 스레드가 완료될 때까지 기다리지 않고 호출이 즉시 반환되어야 합니다. 특정 경우에 ShellExecuteEx 는 이 플래그를 무시하고 반환하기 전에 프로세스가 완료되기를 기다립니다.
SEE_MASK_NOQUERYCLASSSTORE(0x01000000)	사용되지 않습니다.
SEE_MASK_HMONITOR(0x00200000)	다중 모니터 시스템에서 모니터를 지정할 때 이 플래그를 사용합니다. 모니터는 hMonitor 멤버에 지정됩니다. 이 플래그는 SEE_MASK_ICON 결합할 수 없습니다.
SEE_MASK_NOZONECHECKS(0x00800000)	영역 검사 수행하지 마세요. 이 플래그를 사용하면 ShellExecuteEx 가 IAttachmentExecute에 의해 배치된 영역 검사를 무시할 수 있습니다.
SEE_MASK_WAITFORINPUTIDLE(0x02000000)	새 프로세스를 만든 후 1분 시간 제한으로 반환하기 전에 프로세스가 유휴 상태가 될 때까지 기다립니다. 자세한 내용은 WaitForInputIdle 을 참조하세요.
SEE_MASK_FLAG_LOG_USAGE(0x04000000)	자주 사용하는 프로그램 및 기타 동작을 추적할 수 있는 사용자가 시작한 시작을 나타냅니다.
SEE_MASK_FLAG_HINST_IS_SITE'(0x08000000)	hInstApp 멤버는 IServiceProvider를 구현하는 개체의 IUnknown을 지정하는 데 사용됩니다. 이 개체는 사이트 포인터로 사용됩니다. 사이트 포인터는 ShellExecuteEx 함수, 처리기 바인딩 프로세스 및 호출된 동사 처리기에 서비스를 제공하는 데 사용됩니다. 호출자가 생성되는 프로세스의 일부 매개 변수를 변경할 수 있도록 ICreatingProcess를 제공할 수 있습니다. 이 플래그는 Windows 8 이상에서 지원됩니다. 이 옵션을 지정하면 호출 스레드에서 호출이 동기적으로 실행됩니다.

hwnd

형식: HWND

선택 사항입니다. 이 함수를 실행하는 동안 시스템에서 생성할 수 있는 UI를 표시하고 배치하는 데 사용되는 소유자 창에 대한 핸들입니다.

lpVerb

형식: LPCTSTR

수행할 작업을 지정하는 동사라고 하는 문자열입니다. 사용 가능한 동사 집합은 특정 파일 또는 폴더에 따라 달라집니다. 일반적으로 개체의 바로 가기 메뉴에서 사용할 수 있는 작업은 동사를 사용할 수 있습니다. 이 매개 변수는 NULL일 수 있으며, 이 경우 기본 동사가 사용 가능한 경우 사용됩니다. 그렇지 않은 경우 "open" 동사가 사용됩니다. 두 동사를 모두 사용할 수 없는 경우 시스템은 레지스트리에 나열된 첫 번째 동사를 사용합니다. 일반적으로 사용되는 동사는 다음과 같습니다.

편집: 편집기를 시작하고 편집할 문서를 엽니다. lpFile이 문서 파일이 아니면 함수가 실패합니다.
explore: lpFile으로 지정된 폴더를 탐색합니다.
find: 지정된 디렉터리에서 시작하여 검색을 시작합니다.
열기: lpFile 매개 변수로 지정된 파일을 엽니다. 파일은 실행 파일, 문서 파일 또는 폴더일 수 있습니다.
print: lpFile으로 지정된 문서 파일을 인쇄합니다. lpFile이 문서 파일이 아니면 함수가 실패합니다.
properties: 파일 또는 폴더의 속성을 표시합니다.
runas: 관리자 권한으로 애플리케이션을 시작합니다. UAC(사용자 계정 컨트롤)는 사용자에게 관리자 권한 애플리케이션을 실행하는 데 동의하라는 메시지를 표시하거나 애플리케이션을 실행하는 데 사용되는 관리자 계정의 자격 증명을 입력합니다.

lpFile

형식: LPCTSTR

ShellExecuteEx가 lpVerb 매개 변수로 지정된 작업을 수행할 파일 또는 개체의 이름을 지정하는 null로 종료된 문자열의 주소입니다. ShellExecuteEx 함수에서 지원하는 시스템 레지스트리 동사에는 실행 파일 및 문서 파일에 대한 "열기"와 인쇄 처리기가 등록된 문서 파일의 경우 "인쇄"가 포함됩니다. 다른 애플리케이션은 시스템 레지스트리를 통해 셸 동사를 추가했을 수 있습니다(예: .avi 및 .wav 파일에 대한 "재생"). Shell 네임스페이스 개체를 지정하려면 정규화된 구문 분석 이름을 전달하고 fMask 매개 변수에서 SEE_MASK_INVOKEIDLIST 플래그를 설정합니다.

참고:SEE_MASK_INVOKEIDLIST 플래그가 설정된 경우 lpFile 또는 lpIDList 를 사용하여 각각 파일 시스템 경로 또는 해당 PIDL로 항목을 식별할 수 있습니다. lpFile 또는 lpIDList의 두 값 중 하나를 설정해야 합니다.

참고: 경로가 이름에 포함되지 않은 경우 현재 디렉터리가 가정됩니다.

lpParameters

형식: LPCTSTR

선택 사항입니다. 애플리케이션 매개 변수를 포함하는 null로 종료된 문자열의 주소입니다. 매개 변수는 공백으로 구분해야 합니다. lpFile 멤버가 문서 파일을 지정하는 경우 lpParameters는NULL이어야 합니다.

lpDirectory

형식: LPCTSTR

선택 사항입니다. 작업 디렉터리의 이름을 지정하는 null로 끝나는 문자열의 주소입니다. 이 멤버가 NULL이면 현재 디렉터리가 작업 디렉터리로 사용됩니다.

nShow

형식: int

필수 사항입니다. 애플리케이션을 열 때 표시할 방법을 지정하는 플래그입니다. ShellExecute 함수에 대해 나열된 SW_ 값 중 하나입니다. lpFile에서 문서 파일을 지정하는 경우 플래그는 연결된 애플리케이션에 전달됩니다. 처리 방법을 결정하는 것은 애플리케이션에 달려 있습니다.

hInstApp

형식: HINSTANCE

[out] SEE_MASK_NOCLOSEPROCESS 설정되고 ShellExecuteEx 호출이 성공하면 이 멤버를 32보다 큰 값으로 설정합니다. 함수가 실패하면 실패의 원인을 나타내는 SE_ERR_XXX 오류 값으로 설정됩니다. hInstApp은 16비트 Windows 애플리케이션과의 호환성을 위해 HINSTANCE로 선언되지만 진정한 HINSTANCE는 아닙니다. int로만 캐스팅할 수 있으며 32 또는 다음 SE_ERR_XXX 오류 코드와 비교할 수 있습니다.

오류 코드	이유
SE_ERR_FNF (2)	파일을 찾을 수 없습니다.
SE_ERR_PNF (3)	경로를 찾을 수 없습니다.
SE_ERR_ACCESSDENIED (5)	액세스가 거부되었습니다.
SE_ERR_OOM (8)	메모리가 부족합니다.
SE_ERR_DLLNOTFOUND(32)	동적 링크 라이브러리를 찾을 수 없습니다.
SE_ERR_SHARE (26)	열려 있는 파일을 공유할 수 없습니다.
SE_ERR_ASSOCINCOMPLETE (27)	파일 연결 정보가 완료되지 않았습니다.
SE_ERR_DDETIMEOUT (28)	DDE 작업 시간이 초과되었습니다.
SE_ERR_DDEFAIL (29)	DDE 작업이 실패했습니다.
SE_ERR_DDEBUSY(30)	DDE 작업이 사용 중입니다.
SE_ERR_NOASSOC (31)	파일 연결을 사용할 수 없습니다.

lpIDList

형식: LPVOID

실행할 파일을 고유하게 식별하는 항목 식별자 목록을 포함하는 절대 ITEMIDLIST 구조체(PCIDLIST_ABSOLUTE)의 주소입니다. fMask 멤버에 SEE_MASK_IDLIST 또는SEE_MASK_INVOKEIDLIST 포함되지 않은 경우 이 멤버는 무시됩니다.

lpClass

형식: LPCTSTR

다음 중 하나를 지정하는 null로 끝나는 문자열의 주소입니다.

ProgId입니다. 예를 들어 "Paint.Picture"입니다.
URI 프로토콜 체계입니다. 예를 들어 "http"입니다.
파일 확장명. 예를 들어 ".txt"입니다.
하나 이상의 셸 동사가 포함된 하위 키의 이름을 지정하는 HKEY_CLASSES_ROOT 아래의 레지스트리 경로입니다. 이 키에는 셸\동사 이름과 같은 셸 동사 레지스트리 스키마를 준수하는 하위 키가 있습니다.

fMask에 SEE_MASK_CLASSNAME 포함되지 않은 경우 이 멤버는 무시됩니다.

hkeyClass

형식: HKEY

파일 형식에 대한 레지스트리 키에 대한 핸들입니다. 이 레지스트리 키에 대한 액세스 권한은 KEY_READ 설정해야 합니다. fMask에 SEE_MASK_CLASSKEY 포함되지 않은 경우 이 멤버는 무시됩니다.

dwHotKey

형식:DWORD

애플리케이션과 연결할 바로 가기 키입니다. 하위 단어는 가상 키 코드이며, 상위 단어는 한정자 플래그(HOTKEYF_)입니다. 한정자 플래그 목록은 WM_SETHOTKEY 메시지에 대한 설명을 참조하세요. fMask에 SEE_MASK_HOTKEY 포함되지 않은 경우 이 멤버는 무시됩니다.

DUMMYUNIONNAME

DUMMYUNIONNAME.hIcon

형식: HANDLE

파일 형식의 아이콘에 대한 핸들입니다. fMask에 SEE_MASK_ICON 포함되지 않은 경우 이 멤버는 무시됩니다. 이 값은 Windows XP 및 이전 버전에서만 사용됩니다. Windows Vista를 기준으로 무시됩니다.

DUMMYUNIONNAME.hMonitor

형식: HANDLE

문서를 표시할 모니터에 대한 핸들입니다. fMask에 SEE_MASK_HMONITOR 포함되지 않은 경우 이 멤버는 무시됩니다.

hProcess

형식: HANDLE

새로 시작된 애플리케이션에 대한 핸들입니다. 이 멤버는 반환 시 설정되며 fMask가 SEE_MASK_NOCLOSEPROCESS 설정되지 않는 한 항상 NULL입니다. fMask가 SEE_MASK_NOCLOSEPROCESS 설정되어 있더라도 프로세스가 시작되지 않은 경우 hProcess는 NULL이 됩니다. 예를 들어 시작할 문서가 URL이고 인터넷 Explorer instance 이미 실행 중인 경우 문서가 표시됩니다. 새 프로세스가 시작되지 않고 hProcess 가 NULL이 됩니다.

참고:ShellExecuteEx 는 호출의 결과로 프로세스가 시작되더라도 항상 hProcess를 반환하지는 않습니다. 예를 들어 SEE_MASK_INVOKEIDLIST 사용하여 IContextMenu를 호출할 때 hProcess가 반환되지 않습니다.

설명

ShellExecuteEx를 호출하는 스레드에 메시지 루프가 없거나 ShellExecuteEx가 반환된 직후 스레드 또는 프로세스가 종료되는 경우 SEE_MASK_NOASYNC 플래그를 지정해야 합니다. 이러한 조건에서는 호출 스레드를 사용하여 DDE 대화를 완료할 수 없으므로 ShellExecuteEx 가 호출 애플리케이션에 제어를 반환하기 전에 대화를 완료하는 것이 중요합니다. 대화를 완료하지 못하면 문서 시작에 실패할 수 있습니다.

호출 스레드에 메시지 루프가 있고 ShellExecuteEx 호출이 반환된 후 일정 시간 동안 존재하는 경우 SEE_MASK_NOASYNC 플래그는 선택 사항입니다. 플래그를 생략하면 호출 스레드의 메시지 펌프가 DDE 대화를 완료하는 데 사용됩니다. DDE 대화를 백그라운드에서 완료할 수 있으므로 호출 애플리케이션은 제어를 더 빨리 회복합니다.

사용자 상호 작용으로 인해 발생하는 이 API에 대한 호출의 경우 SEE_MASK_FLAG_LOG_USAGE 지정합니다.

lpParameters에 큰따옴표를 포함하려면 다음 예제와 같이 각 표시를 따옴표 쌍으로 묶습니다.

sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

이 경우 애플리케이션은 세 가지 매개 변수 인 An, example:및 "quoted text"를 받습니다.

참고

shellapi.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 SHELLEXECUTEINFO를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
머리글	shellapi.h

SHELLEXECUTEINFOW 구조체(shellapi.h)

구문

멤버

설명

요구 사항

피드백

피드백

추가 리소스