ShellExecuteA 함수(shellapi.h)

아티클
08/26/2023

지정된 파일에 대한 작업을 수행합니다.

구문

HINSTANCE ShellExecuteA(
  [in, optional] HWND   hwnd,
  [in, optional] LPCSTR lpOperation,
  [in]           LPCSTR lpFile,
  [in, optional] LPCSTR lpParameters,
  [in, optional] LPCSTR lpDirectory,
  [in]           INT    nShowCmd
);

매개 변수

[in, optional] hwnd

형식: HWND

UI 또는 오류 메시지를 표시하는 데 사용되는 부모 창에 대한 핸들입니다. 작업이 창과 연결되지 않은 경우 이 값은 NULL 일 수 있습니다.

[in, optional] lpOperation

형식: LPCTSTR

이 경우 수행할 작업을 지정하는 동사라고 하는 null로 끝나는 문자열에 대한 포인터입니다. 사용 가능한 동사 집합은 특정 파일 또는 폴더에 따라 달라집니다. 일반적으로 개체의 바로 가기 메뉴에서 사용할 수 있는 작업은 동사를 사용할 수 있습니다. 일반적으로 사용되는 동사는 다음과 같습니다.

편집

편집기를 시작하고 편집할 문서를 엽니다. lpFile이 문서 파일이 아니면 함수가 실패합니다.

탐험

lpFile으로 지정된 폴더를 탐색합니다.

찾기

lpDirectory로 지정된 디렉터리에서 시작하는 검색을 시작합니다.

열기

lpFile 매개 변수로 지정된 항목을 엽니다. 항목은 파일 또는 폴더일 수 있습니다.

print

lpFile으로 지정된 파일을 인쇄합니다. lpFile이 문서 파일이 아니면 함수가 실패합니다.

실행 계정

관리자 권한으로 애플리케이션을 시작합니다. UAC(사용자 계정 컨트롤)는 관리자 권한으로 애플리케이션을 실행하는 데 동의하라는 메시지를 표시하거나 애플리케이션을 실행하는 데 사용되는 관리자 계정의 자격 증명을 입력합니다.

NULL

사용 가능한 경우 기본 동사가 사용됩니다. 그렇지 않은 경우 "열린" 동사가 사용됩니다. 동사를 사용할 수 없는 경우 시스템은 레지스트리에 나열된 첫 번째 동사를 사용합니다.

[in] lpFile

형식: LPCTSTR

지정된 동사를 실행할 파일 또는 개체를 지정하는 null로 끝나는 문자열에 대한 포인터입니다. Shell 네임스페이스 개체를 지정하려면 정규화된 구문 분석 이름을 전달합니다. 모든 동사가 모든 개체에서 지원되는 것은 아닙니다. 예를 들어 모든 문서 형식이 "인쇄" 동사를 지원하는 것은 아닙니다. lpDirectory 매개 변수에 상대 경로가 사용되는 경우 lpFile에 대한 상대 경로를 사용하지 않습니다.

[in, optional] lpParameters

형식: LPCTSTR

lpFile이 실행 파일을 지정하는 경우 이 매개 변수는 애플리케이션에 전달할 매개 변수를 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 이 문자열의 형식은 호출할 동사에 의해 결정됩니다. lpFile에서 문서 파일을 지정하는 경우 lpParameters는NULL이어야 합니다.

[in, optional] lpDirectory

형식: LPCTSTR

작업의 기본(작업) 디렉터리를 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 이 값이 NULL이면 현재 작업 디렉터리가 사용됩니다. lpFile에서 상대 경로가 제공되는 경우 lpDirectory에 대한 상대 경로를 사용하지 마세요.

[in] nShowCmd

형식: INT

애플리케이션을 열 때 표시할 방법을 지정하는 플래그입니다. lpFile에서 문서 파일을 지정하면 플래그가 연결된 애플리케이션에 전달됩니다. 처리 방법을 결정하는 것은 애플리케이션에 달려 있습니다. ShowWindow 함수에 대한 nCmdShow 매개 변수에 지정할 수 있는 값이라면 무엇이든 가능합니다.

반환 값

형식: HINSTANCE

함수가 성공하면 32보다 큰 값을 반환합니다. 함수가 실패하면 오류의 원인을 나타내는 오류 값이 반환됩니다. 반환 값은 16비트 Windows 애플리케이션과의 이전 버전과의 호환성을 위해 HINSTANCE로 캐스팅됩니다. 그러나 진정한 HINSTANCE는 아닙니다. INT_PTR만 캐스팅할 수 있으며 아래의 32개 또는 다음 오류 코드와 비교할 수 있습니다.

반환 코드	설명
0	운영 체제가 메모리 또는 리소스가 부족합니다.
ERROR_FILE_NOT_FOUND	지정된 파일을 찾을 수 없습니다.
ERROR_PATH_NOT_FOUND	지정된 경로를 찾을 수 없습니다.
ERROR_BAD_FORMAT	.exe 파일이 잘못되었습니다(비 Win32 .exe 또는 .exe 이미지의 오류).
SE_ERR_ACCESSDENIED	운영 체제에서 지정된 파일에 대한 액세스를 거부했습니다.
SE_ERR_ASSOCINCOMPLETE	파일 이름 연결이 불완전하거나 잘못되었습니다.
SE_ERR_DDEBUSY	다른 DDE 트랜잭션이 처리되고 있으므로 DDE 트랜잭션을 완료할 수 없습니다.
SE_ERR_DDEFAIL	DDE 트랜잭션이 실패했습니다.
SE_ERR_DDETIMEOUT	요청 시간이 초과되어 DDE 트랜잭션을 완료할 수 없습니다.
SE_ERR_DLLNOTFOUND	지정된 DLL을 찾을 수 없습니다.
SE_ERR_FNF	지정된 파일을 찾을 수 없습니다.
SE_ERR_NOASSOC	지정된 파일 이름 확장명과 연결된 애플리케이션이 없습니다. 인쇄할 수 없는 파일을 인쇄하려고 하면 이 오류도 반환됩니다.
SE_ERR_OOM	작업을 완료할 메모리가 부족했습니다.
SE_ERR_PNF	지정된 경로를 찾을 수 없습니다.
SE_ERR_SHARE	공유 위반이 발생했습니다.

확장된 오류 정보는 GetLastError 를 호출합니다.

설명

ShellExecute는 COM(구성 요소 개체 모델)을 사용하여 활성화된 셸 확장(데이터 원본, 상황에 맞는 메뉴 처리기, 동사 구현)에 실행을 위임할 수 있으므로 ShellExecute가 호출되기 전에 COM을 초기화해야 합니다. 일부 셸 확장에는 COM STA(단일 스레드 아파트) 유형이 필요합니다. 이 경우 COM은 다음과 같이 초기화되어야 합니다.

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

ShellExecute가 이러한 유형의 Shell 확장 중 하나를 사용하지 않고 해당 인스턴스에서 COM을 초기화할 필요가 없는 인스턴스가 분명히 있습니다. 그럼에도 불구하고 이 함수를 사용하기 전에 항상 COM을 초기화하는 것이 좋습니다.

이 메서드를 사용하면 폴더의 바로 가기 메뉴에서 또는 레지스트리에 저장된 모든 명령을 실행할 수 있습니다.

폴더를 열려면 다음 호출 중 하나를 사용합니다.

ShellExecute(handle, NULL, <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

또는

ShellExecute(handle, "open", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

폴더를 탐색하려면 다음 호출을 사용합니다.

ShellExecute(handle, "explore", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

디렉터리에 대한 Shell의 찾기 유틸리티를 시작하려면 다음 호출을 사용합니다.

ShellExecute(handle, "find", <fully_qualified_path_to_folder>, NULL, NULL, 0);

lpOperation이 NULL이면 함수는 lpFile으로 지정된 파일을 엽니다. lpOperation이 "열기" 또는 "탐색"인 경우 함수는 폴더를 열거나 탐색하려고 시도합니다.

ShellExecute 호출의 결과로 시작된 애플리케이션에 대한 정보를 가져오려면 ShellExecuteEx를 사용합니다.

참고폴더 옵션의 별도 프로세스 설정에서 폴더 시작 창 은 ShellExecute에 영향을 줍니다. 해당 옵션을 사용하지 않도록 설정한 경우(기본 설정) ShellExecute는 새 창을 시작하는 대신 열린 Explorer 창을 사용합니다. Explorer 창이 열려 있지 않으면 ShellExecute가 새 창을 시작합니다.

참고

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

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	shellapi.h
라이브러리	Shell32.lib
DLL	Shell32.dll(버전 3.51 이상)