[MSDN] VISTA_RESTART MANAGER 번역본입니다. | 마을

- 목적

The Restart Manager API (이하 리스타트 매니저) 는 인스톨이나 업데이트를 완수하기 위해 필요로 하는 수많은 시스템의 재시작을 배제하거나 줄여줄 수 있다.

무엇보다도 현재 돌아가고 있는 어플리케이션이나 서비스의 몇몇 파일에 대한 인스톨이나 업데이트는 시스템 재시작을 요한다.

리스타트 매니저는 critical system services를 제외한 모든 셧다운과 재 시작이 가능하며, 인스톨 작업의 완전한 수행을 위해, 사용되는 파일들을 자유롭게 해준다.

- 어디에 적용 가능한가?

리스타트 매니저 DLL 은 스탠다드 혹은 커스텀 인스톨러에의해 로딩 될 수 있는 일반 C 인터페이스를 export한다.

인스톨러는 어플리케이션의 인스톨이나 업데이트가 진행되는 동안 대체 되어야 하는 register 파일을 위해 리스타트 매니저를 사용할 수 있다. 그리고 이후의 인스톨이나 업데이트가 진행되는 동안 인스톨러는 가령 현재 사용중이기 때문에 업데이트 할 수 없는 파일들을 결정하기 위해 리스타트 매니저를 사용할 수 있다.

리스타트 매니저는 현재 파일을 사용하고 있는 non-critical 서비스들 혹은 어플리케이션들을 셧다운 하거나 재시작한다.

인스톨러는 파일의 사용이나 process ID(PID) 혹은 Windows 서비스 약어에 기반을 둔 어플리케이션이나 서비스들을 셧다운 혹은 재시작 하기 위해 리스타트 매니저를 조작한다.

- 대상 개발자

이 문서는 윈도우 비스타 혹은 롱혼에 캐퍼블 한 인스톨러의 편의를 원하는 인스톨 어플리케이션 개발자를 위한 것이다.

인스톨과 서비스를 위해 Windows Installer 버전 4.0을 사용하는 어플리케이션은 자동적으로 시스템 리스타트를 줄이기 위해 리스타트 매니저를 사용하게 된다.

커스텀 인스톨러 또한 리스타트 매니저 API를 호출 하는 방법을 통해 어플리케이션과 서비스의 셧다운과 리스타트을 위해 디자인 될 수 있다.

시스템을 리스타트가 불가피한 경우에는 인스톨러가 리스타트 매니저 API를 통해 사용자의 혼란을 최소화 하는 방향으로 사용할 수 있다.

- 실행 환경

리스타트 매니저 API는 윈도우 비스타 Beta 2 Release 이상에서 사용 가능하다. 어플리케이션이 리스타트 매니저 API를 로딩하여 사용할 수 있도록 싱글 DLL로 구성되어 있다.

1. 리스타트 매니저에 대해(About Restart Manager)

주요 쟁점은 소프트웨어의 인스톨이나 업데이트는 현재 실행되고 있는 어플리케이션이나 서비스의 몇몇 파일의 업데이트를 필요로 한다는 것이다.

리스타트 매니저는 critical system services 를 제외한 모든 셧다운과 재시작이 가능하며, 인스톨 작업의 완전한 수행을 위해 현재 사용되는 파일들을 자유롭게 해준다. 또한 인스톨이나 업데이트가 필요로 하는 수많은 시스템의 재 시작을 배제하거나 줄여줄 수 있다.

리스타트 매니저는 아래와 같이 순차적으로 어플리케이션을 멈추고 업데이트 된 후, 역순으로 재시작을 위해 등록된 어플리케이션을 재시작 한다.

1. GUI Applications

2. Console Applications

3. Windows Services

4. Windows explorer

리스타트 매니저는 호출자가 그렇게 하라는 허가(권한)가 있을 때만 어플리케이션이나 서비스들을 셧다운 할 수 있다. 다른 세션의 셧다운은 지원되지 않음을 기억해 두라.

인스톨이나 서비스를 위한 윈도우즈 인스톨러 v4.0을 사용하는 어플리케이션은 자동적으로 리스타트 매니저를 사용하여 시스템 재시작을 줄인다. 커스텀 인스톨러 또한 리스타트 매니저 API를 호출할 수 있도록 디자인하여 어플리케이션 과 서비스의 셧다운 혹은 재시작을 할 수 있다.

시스템의 재시작이 불가피한 경우 인스톨러는 리스타트 매니저 API를 이용해 사용자의 혼란을 최소화 하는 방향으로 리스타트를 스케쥴 할수 있다. 인스톨 및 업데이트 간에 리스타트 매니저 API를 사용하고자 한다면, Using Restart Manager을 참고하라.

단, Critical system services은 시스템의 재시작 없이 리스타트 매니저로 서비스를 멈추거나 재시작 할 수 없다.

Critical system services에 대한 정보는 Critical System Services을 참고하라.

어플리케이션이나 서비스들은 저장(save)된 사용자 데이터(user data)나 상태 정보의 깔끔한 재시작을 위해 리스타트 매니저에 의해 셧다운 되도록 준비되어야 한다.

리스타트 매니저를 통해 어플리케이션과 서비스들을 작업하기 원한다면 Guidelines for Applications and Services 를 준수하라.

리스타트 매니저 API의 열거자, 구조체 그리고 함수에 대한 레퍼런스 정보는 Restart Manager Reference 섹션을 참고하라.

1.1 어플리케이션과 서비스를 위한 가이드라인 (Guidelines for Applications and Services)

윈도우즈 비스타 혹은 롱혼 서버에서 어플리케이션을 인스톨하거나 서비스할 때 여러번의 시스템 재시작을 줄이기 위해, 당신의 어플리케이션이나 서비스가 깔끔하게 셧다운 되거나 재시작 할 수 있도록 아래의 가이드라인을 따르라.

- 시스템에 의해 업데이트를 설치 시 필요하다면 어플리케이션과 서비스들은 반드시 셧다운이나 재시작 되도록 준비되어야 한다. 일반적으로 업데이트가 설치될때 어플리케이션이나 서비스는 현재 영향을 받고 있는 파일 때문에 재시작 되어야 한다. 업데이트 동안 파일을 소유(hold)하는 모든 어플리케이션이나 서비스들은 반드시 깔끔하게 셧다운 되도록 준비되어야 한다.

- 어플리케이션은 리스타트 후 필요한 사용자 데이터와 상태 정보를 저장하여야 한다. Guidelines for Applications를 반드시 준수하기 바란다.

- 서비스는 Guidelines for Serveces를 반드시 준수하여야 한다.

- 리스타트 매니저는 critical system services에 대하여는 셧다운 할 수 없다.

그런 까닭에 이런 services는 의존하고 있는 DLL 의 개수를 제한 해야 한다.

1.1.1 어플리케이션을 위한 가이드라인(Guidelines for Applications)

비스타나 롱혼 서버에서 수행되는 어플리케이션은 리스타트 매니저가 업데이트의 설치를 위한 필요 시 셧다운 혹은 재시작을 할 수 있도록 보장하는 가이드라인을 준수하여야 한다. Guidlines for Services를 참고하라.

- 리스타트 매니저는 lParam의 파라미터가 ENDSESSION_CLOSEAPP(0x1) 을 가진 WM_QUERYENDSESSION 통지 메시지에 의해 셧다운 하기 위해 GUI 어플리케이션에 쿼리한다. 어플리케이션은 WM_QUERYENDSESSION 메시지를 받을 때 셧다운 되지 않아야 한다. 왜냐하면 다른 어플리케이션이 셧다운을 준비하지 않고 있을 수 있기 때문이다.

GUI 어플리케이션은 반드시 WM_QUERYENDSESSION 메시지를 listen하여야 한다. 그리고 만약 어플레케이션 셧다운과 재시작이 준비되었다면 TRUE값을 리턴해야 한다. 아무 어플리케이션도 FALSE를 리턴하지 않으면 리스타트 매니저는 lParam의 파라미터가 ENDSESSION_CLOSEAPP(0x1)을 가지고 wParam 파리미터가 TRUE의 값을 갖는 WM_ENDSESSION 메시지를 보낸다.

또한 리스타트 매니저는 WM_ENDSESSION 메시지를 받을 때 셧다운 되지 않는 GUI 어플리케이션을 위해 WM_CLOSE 메시지를 보낸다.

만약 GUI 어플리케이션 중 어느 하나라도 FALSE 값을 리턴하는 WM_QUERYENDSESSION 메시지에 응답한다면 셧다운은 취소된다. 하지만 강제로 셧다운 하게되면 어플리케이션은 괘념치 않고 종료된다.

- GUI 어플리케이션이 WM_ENDSESSION 메시지를 받을 때 어플리케이션은 명시된 타임아웃 시간 내에 셧다운이 준비되어야 한다. 최소한 어플리케이션은 재시작 후에 필요한 사용자의 데이터나 상태정보를 저장하도록 준비되어야 한다. 어플리케이션이 사용자 데이터와 상태 정보를 주기적으로 저장하는 것을 추천한다.

- 리스타트 매니저는 셧다운이나 재시작이 필요한 콘솔 어플리케이션에 CTRL_C_EVENT 통지 메시지를 보낸다.

콘솔 어플리케이션이 CTRL_C_EVENT 통지 메시지를 받을 때 어플리케이션은 명시된 타임아웃 시간 내에 셧다운 되도록 준비하기 위해 필요한 액션을 취해야 한다.

최소한 콘솔 어플리케이션은 CTRL_C_EVENT 통지 메시지와 재시작 후 필요하게 될 모든 사용자 데이터와 상태 정보를 핸들링 할 HandlerRoutine함수를 정의하여야한다.

어플리케이션이 사용자 데이터와 상태 정보를 주기적으로 저장하는 것을 추천한다.

- 만약 어느 하나의 애플리케이션 이라도 셧다운 메시지에 응답하여 셧다운 되지 않으면 인스톨러는 RmShutdown함수의 RmForceShutdown 옵션을 사용하여 강제로 어플리케이션을 셧다운 할 수 있다. 인스톨러가 강제 종료를 명시하면 리스타트 매니저는 셧다운 메시지를 보내 어플리케이션 셧다운을 시도한다. 실패하더라도 강제로 셧다운 한다.

GUI 어플리케이션과 콘솔 어플리케이션은 critical security update가 가능하도록 강제로 셧다운을 할 수 있다.

데이터 손실의 우려가 있기 떄문에 어플리케이션은 반드시 셧다운 메시지를 핸들링 해야 하고 필요시 깔끔히 셧다운 되어야 한다.

- 어플리케이션은 리스타트를 위해 RegisterApplicationRestart함수를 사용하여 등록 되어야 한다. 리스타트 매니저는 재시작을 위해 반드시 등록된 어플리케이션만을 재시작 할 수 있다. 리스타트 매니저는 어플리케이션이 재시작될 때 사용되는 Command-Line 명령을 결정할 수 있다. 어플리케이션이 몇몇 저장된 상태나 데이터와 함께 다시 열린다면 그 정보는 어플리케이션이 등록한 Command-Line 명령에 포함 되어야 한다.

NOTE : 만약 재시작된 어플리케이션이 셧다운되어지기 전에 실행되던 같은 디렉토리에서 실행되어야만 한다면, 어플리케이션은 반드시 디렉토리 정보에 저장되고 재시작 후 디렉토리가 변경되어야 한다.

NOTE : RmRestart 함수는 현재 로그인 된 사용자가 실행시키지 않은 어플리케이션을 재시작 하지 않는다. 예로, RmRestart 함수는 현재 로그인 되어있는 사용자가 실행하지 않은 Run As 커맨드로 시작된 어플리케이션을 재시작 하지 않는다. 이런 어플리케이션들은 수동으로 재시작되어야만 한다.

- 리스타트 매니저가 요구된 업데이트의 설치를 위해 시스템 재시작을 고려할때, 어떠한 애플리케이션과 서비스도 셧다운하지 않는다. 대신 인스톨러가 시스템 리스타트와 업데이트 설치의 스케쥴을 결정하도록 남겨둔다.

인스톨러는 ExitWindowEx 함수의 EWX_RESTARTAPPS 플래그 혹은 InitiateShutdown 함수 SHUTDOWN_RESTARTAPPS 플래그의 사용에 의해 시스템 재시작이 요구되어진 업데이트에 대해 사용자의 혼란을 줄일 수 있다. 해당 플래그들은 사용자에게 미치는 영향을 최소화 하여 시스템 리부트 후의 재시작을 위한 어플리케이션의 등록을 보장한다.

1.1.2 서비스를 위한 가이드라인(Guidelines for Services)

서비스는 리스타트 매니저가 업데이트를 설치하기 위해 서비스에서 필요한 셧다운이나 재시작을 할 수 있도록 보장된 가이드 라인을 준수해야 한다. 어플리케이션은 Guidelines for Applications에 기술된 가이드라인을 따르면 된다.

- 서비스는 시스템 재시작을 요구하지 않는 Service Control Manager를 사용하여 셧다운이나 재시작이 가능해야 한다. 이 가이드라인의 예외는 lsass.exe혹은 services.exe 안에서 실행되어지는 critical system 프로세스이다.

- 리스타트 매니저는 서비스 의존성을 따른다. 서비스가 셧다운이나 재시작 될때는 속해있는 서비스들도 셧다운이나 재시작 된다.

- svchost.exe 내에서 실행된 서비스들은 서비스가 셧다운 될때 반드시 unload DLLs를 등록해야 한다. 서비스의 소유자는 아래 기록된 레지스트리 키의 REG_DWORD 값을 1로 셋팅하여야 한다.

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\

<Your Service>\Parameters\ServiceDllUnloadOnStop

만약 서비스가 ServiceMain 쓰레드의 서비스가 시작되고 서비스가 중지 될 때 svchost.exe의 컨텍스트에 리턴하는 동안 active를 남기도록 구현되어있다면 서비스가 멈출 때 레지스트리 키 unloads the DLLs로 셋팅하라.

만약 서비스가 ServiceMain이 RegisterWaitForSingleObject 함수와 리턴값을 사용하여 콜백 함수를 등록하는 식으로 구현되어 있다면 레지스트리키가 반드시 설정되어 있어야 하고 서비스는 함수를 export하여야 한다: SvcHostPushServiceGlobals

이 함수는 글로벌 데이터 블록 포인터에서 서비스로 svchost.exe 프로세스를 넘기는 것이 가능해야한다. RegisterWaitForSingleObject함수를 호출하는 대신 RegisterStopCallback을 호출한다.

- 서비스들은 서비스 컨트롤 매니저(SCM) 의 리커버리 인터벌과 리셋 시간을 명시해야 한다. 리커버리 인터벌은 리커버리 액션을 취하기 전에 SCM이 기다리는 마지막 실패 후의 분/초를 나타내는 시간이다. 리셋 시간은 실패 카운트를 0으로 리셋하기 전 서비스 컨트롤 매니저가 기다리는 최종 실패 후의 초를 나타내는 시간이다. 서비스들은 셋팅 속성의 변경을 위해 ChangeServiceConfig2 함수를 사용할 수 있다.

Critical services등은 반드시 서비스 재시작의 첫 실패 1분 후에 재시작 되도록 아래의 리커버리 셋팅으로 명시해야 한다

두번째 실패 뒤 2분후에 재시작되고 세번째 실패 후 1분 뒤엔 컴퓨터가 리부트 된다.

실패 카운트는 300초 후 0으로 리셋 된다.

Recovery Actions: Restart/60000/Restart/120000/Reboot/60000 & Reset = 300.

Critical 서비스들은 non-critical 서비스들 전에 시작되어야 한다. critical services가 아닌 서비스들은 아래 명시된 리커버리 셋팅을 사용한다. 첫번째 실패 2분 후 서비스를 재시작하며, 서비스는 두번째 실패 후 재시작 되지 않고 이 경우 관리자는 중재가 필요 할 것이다. 실패 카운트는 900초 후 0으로 리셋된다.

Recovery Actions: Restart/120000/Restart/300000/None/0 & Reset = 900

1.1.3 Critical 시스템 서비스(Critical System Services)

Critical 시스템 서비스는 시스템 재시작 없이 리스타트 매니저를 통해 멈추거나 재시작 될 수 없다. 이들 중 한 개의 서비스가 시스템 리스타트를 요구해도 당 서비스가 사용하는 어떠한 파일이나 리소스는 꼭 업데이트한다.

프로세스가 critical system service 인지 아닌지 고려하기

1. RmRegisterResources 함수를 사용하는 프로세스를 등록한다.

2. RmGetList 함수를 호출하여 RM_PROCESS_INFO 구조체를 얻는다.

3. RM_PROCESS_INFO구조체가 포함하는 RM_APP_TYPE 열거자의 값이 리턴하는 Application Type을 살펴본다. 이 값은 critical 시스템 프로세스를 위해 RmCritical을 설정한다.

Critical 시스템 서비스는 smss.exe, csrss.exe, winit.exe, logonui.exe, lsass.exe, services.exe, winlogon.exe, System, svchost.exe with RPCSS 와 svchost.exe with Dcom/Pnp를 포함한다.

2. 리스타트 매니저 사용하기 (Using Restart Manager)

이어지는 섹션들은 리스타트 매니저 API를 기술한다. 어플리케이션이나 서비스는 아래 Guidelines for Applications and Services를 준수하여야 한다.

Microsoft Windows Installer 사용하기

Microsoft Windows Installer Version 4.0은 Windows 비스타와 롱혼 서버의 어플리케이션 인스톨 서비스이다. 윈도우 인스톨러 버전 4.0을 사용하는 어플리케이션은 설치와 시스템 재시작을 줄이기 위해 자동적으로 리스타트 매니저를 사용한다. 커스텀 인스톨러 또한 리스타트 매니저 API를 호출하도록 디자인하여 시스템 리스타트 요구를 피해 셧다운이나 어플리케이션과 서비스를 재시작 할 수 있다.

시스템 재시작이 불가피한 경우 인스톨러는 InitiateShutdown 혹은 ExitWindowsEx 함수를 사용해 사용자의 혼란을 최소화 하는 방향으로 시스템 재시작을 스케쥴 할 수 있다.

대화형의 윈도우즈 인스톨러 패키지는 MsiRMFilesInUse 다이얼로그 박스가 포함된 UI로 구현되어야 한다. 자세한 정보는 윈도우즈 인스톨러 SDK 문서 내 Using Windows Installer with Restart Manager 섹션을 참고하라.

커스텀 인스톨러 상에서 리스타트 매니저 API 사용하기

시스템 재시작을 필요로 하는 커스텀 인스톨러나 커스텀 액션을 포함하고 있는 윈도우 인스톨러 패키지는 셧다운이나 어플리케이션과 서비스의 재시작을 위해 리스타트 매니저 API를 사용 할 수 있다.

- 리스타트 매니저 API에 의해 수행되는 모든 명령들은 반드시 세션과 연결되어야 한다.

사용자 세션당 64개의 리스타트 매니저 세션을 한 시스템에서 동시에 열 수 있다.

Primary 인스톨러는 리스타트 매니저 세션의 시작과 끝을 담당한다. 단일 인스톨러 기반의 리스타트 매니저의 사용은 Using Restart Manager with a Primary Installer를 참고하라.

- 인스톨 시 필요에 의해 한 개 이상의 secondary 인스톨러가 필요한 경우 primary 인스톨러의 리스타트 매니저 세션과 in-process 혹은 out of process 형태로 join이 가능하다.

join을 위해 secondary 인스톨러는 primary 인스톨러가 제공하는 세션 키를 필요로 한다.

secondary 인스톨러의 사용에 대한 자세한 정보와 예제는 Resart Manager with a Secondary Installer를 참고하라.

- 대화형 인스톨러는 유저에게 어플리케이션이나 서비스를 닫는지의 여부를 물을 수 있도록 MsiRMFilesInUse 다이얼로그 박스가 포함된 UI로 구현되어야 한다.

자세한 정보는 윈도우즈 인스톨러 SDK 문서 내의 Using Windows Installer with Restart Manager섹션을 참고하라.

- 인스톨러는 현재 리스타트 매니저의 명령의 상태를 변경, 취소 혹은 얻기 위해 리스타트 매니저 API를 호출 할 수 있다. 자세한 정보는 아래의 토픽을 참고하라. : Getting the Status of a Restart Manager Operation, Canceling the Current Restart Manager Operation

- 인스톨러는 리스타트 매니저 API를 호출하기 전에 파일 시스템 리다이렉션이 불가능하지 않아야 한다. 이것은 곧 64비트의 윈도우즈에서 실행되는 32비트 인스톨러는 %windir%system32 디렉토리에 쓰기가 불가능 하다는 것을 의미한다.

2-1 Primary 인스톨러에 리스타트 매니저 사용하기 (Using Restart Manager with a Primary Installer)

아래의 절차들은 리스타트 매니저를 사용하여 어플리케이션이나 서비스를 셧다운이나 재시작하는 방법을 기술한다.

리스타트 매니저가 단일 인스톨러와 함께 사용될 때 인스톨러는 UI를 컨트롤하는 Primary 인스톨러라고 할 수 있다.

à primary installer에 리스타트 매니저 사용하는 방법

1. 인스톨러는 RmStartSession 함수를 호출하여 리스타트 매니저 세션을 시작하고 세션의 핸들과 세션키를 얻는다.

2. 인스톨러는 RmRegisterResources 함수를 호출하여 리소스를 등록한다.

리스타트 매니저는 어플리케이션과 서비스에서 반드시 셧다운 혹은 재시작되도록 고려되어 등록한 리소스만을 사용할 수 있다. 설치에 영향을 받는 모든 리소스들은 반드시 세션에 등록되어 있어야 한다. 리소스들은 파일 이름혹은 service short name 혹은 RM_UNIQUE_PROCESS 구조체에 의해 식별할 수 있다.

3. 인스톨러는 RmGetList 함수를 호출하여 셧다운되거나 재시작 되어야 할 모든 어플리케이션과 서비스 의 목록인 RM_PROCESS_INFO 구조체의 배열을 얻는다.

만약 lpdwRebootReason 파라미터의 값(RmGetList 함수의 리턴값)이 0이 아닐 경우 리스타트 매니저는 어플리케이션이나 서비스의 셧다운을 위해 등록된 리소스들을 해제 할 수 없다. 이 경우 시스템 셧다운과 재시작은 설치를 계속할 것을 요구하게 된다. 인스톨러는 유저에게 프로그램이나 서비스를 중지할 것인지, 혹은 시스템 셧다운이나 리스타트의 스케쥴을 결정하는 액션을 질문한다.

만약 lpdwRebootReason 파라미터의 값(RmGetList 함수의 리턴값)이 0일 경우 인스톨러는 RmShutdown 함수를 호출하여 서비스와 리소스가 등록된 애플리케이션을 셧다운 한다.

인스톨러는 설치를 완료를 요구하는 시스템 변경을 수행하여야 한다. 마지막으로 인스톨러는 리스타트 매니저가, 셧다운 되었던 재시작을 위해 등록된 어플리케이션을 재시작 할 수 있도록 하기 위해 RmRestart함수를 호출해야 한다.

4. 인스톨러는 RmAddFilter 함수를 사용하여 특정 어플리케이션과 서비스의 리스타트 매니저 명령에 의한 셧다운이나 재시작을 방지할 수 있다. RmGetFilterList 함수는 셧다운이나 재시작으로부터 필터링 되어야 할 어플리케이션이나 서비스의 리스트를 리턴한다.

5. 인스톨러는 RmEndSession 함수를 호출하여 Restart Manager 세션을 종료한다.

primary 인스톨러를 이용한 리스타트 매니저 세션의 시작과 사용에 대해 간단한 예와 secondary 인스톨러를 사용하여 존재하는 세션을 joinning 하는 방법은 Using Restart Manager with a Secondary Installer를 참고하라.

2.2 Secondary 인스톨러에 리스타트 매니저 사용하기(Using Restart Manager with a Secondary Installer)

아래의 절차들은 primary 와 secondary 인스톨러에 리스타트 매니저를 사용하는 방법들을 기술한다. primary와 secondary 인스톨러가 사용될 때 primary 인스톨러는 UI를 컨트롤 한다.

à primary 와 secondary 인스톨러에 리스타트 매니저 사용하는 방법

1. primary 인스톨러는 RmStartSessiond 함수를 호출하여 리스타트 매니저 세션을 시작하고 세션의 핸들과 세션키를 얻는다.

2. primary 인스톨러는 secondary 인스톨러를 시작하거나, 선택(contact)하고 전단계에서 얻은 세션키를 제공한다.

3. secondary 인스톨러는 리스타트 매니저 세션의 join을 위해 세션키와 RmJoinsession 함수를 호출한다. secondary 인스톨러는 두 인스톨러가 같은 유저 컨택스트에서 수행 될 때 primary 인스톨러에 의해 시작된 세션에 join한다.

4. primary와 secondary 인스톨러는 RmRegisterResources 함수를 호출하여 리소스를 등록한다. 리스타트 매니저는 어플리케이션과 서비스에서 반드시 셧다운 혹은 재시작되도록 고려되어 등록한 리소스만을 사용할 수 있다. 설치에 영향을 받는 모든 리소스들은 반드시 세션에 등록되어 있어야 한다. 리소스들은 파일 이름혹은 service short name 혹은 RM_UNIQUE_PROCESS 구조체에 의해 식별할 수 있다.

5. primary 인스톨러는 RmGetList 함수를 호출하여 셧다운되거나 리스타트 되어야 할 모든 어플리케이션과 서비스 의 목록인 RM_PROCESS_INFO 구조체의 배열을 얻는다.

만약 lpdwRebootReason 파라미터의 값(RmGetList 함수의 리턴값)이 0이 아닐 경우 리스타트 매니저는 어플리케이션이나 서비스의 셧다운을 위해 등록된 리소스들을 해제 할 수 없다. 이 경우 시스템 셧다운과 재시작은 설치를 계속할 것을 요구하게 된다. Primary 인스톨러는 유저에게 프로그램이나 서비스를 중지할 것인지, 혹은 시스템 셧다운이나 리스타트의 스케쥴을 결정하는 액션을 질문한다.

Primary와 secondary 인스톨러는 설치를 완료를 요구하는 시스템 변경을 수행하여야 한다. 마지막으로 인스톨러는 리스타트 매니저가, 셧다운 되었던 재시작을 위해 등록된 어플리케이션을 재시작 할 수 있도록 하기 위해 RmRestart함수를 호출해야 한다.

6. primary와 secondary 인스톨러는 RmEndSession 함수를 호출하여 Restart Manager 세션을 종료한다.

아래의 코드는 primary 인스톨러의 시작과 리스타트 매니저 세션의 사용을 보여주는 예다.

DWORD dVal;

         DWORD dwSessionHandle = -1;

         WCHAR sessKey[CCH_RM_SESSION_KEY+1];

         UINT nProcInfo = 100;

         UINT nProcInfoNeeded;

         RM_PROCESS_INFO *rgProcInfo = NULL;

         DWORD lpdwRebootReason = 0;

         DWORD nServices = 1;

         LPWSTR rgsServices[] = { "iisadmin" };

         DWORD nProcs = 0;

         DWORD nFiles = 1;

         LPWSTR rgsFiles[] = { "c:\\windows\\system32\\oleaut32.dll" };

         rgAffectedApps = new RM_PROCESS_INFO[nProcInfo];

         // Starting Session

         dVal = RmStartSession( &dwSessionHandle, sessKey );

         if (dVal != ERROR_SUCCESS)

                 goto RM_END;

         // Register items

         dVal = RmRegisterResources(

                          dwSessionHandle,

                          nFiles, rgsFiles,                  // Files

                          nProcs, NULL,                      // Processes

                          nServices, rgsServices );          // Services

         if (dVal != ERROR_SUCCESS)

                 goto RM_END;

         // Getting affected apps

         dVal = RmGetList(

                          dwSessionHandle,

                          &nProcInfoNeeded,

                          &nAffectedApps, rgAffectedApps, &lpdwRebootReason );

         if (dVal != ERROR_SUCCESS)

                 goto RM_END;

         // Shut down apps

         dVal = RmShutdown( dwSessionHandle, 0, NULL );

         if (dVal != ERROR_SUCCESS)

                 goto RM_END;

         // Restart apps

         dVal = RmRestart( dwSessionHandle, NULL );

         if (dVal != ERROR_SUCCESS)

                 goto RM_END;

RM_END:

         if (rgAffectedApps)

                 delete [] rgAffectedApps;

                 rgAffectedApps = NULL;

         if (dwSessionHandle != -1)

                 // Clean up session

                 dVal = RmEndSession( dwSessionHandle );

                 dwSessionHandle = -1;

}

아래의 코드는 secondary 인스톨러를 존재하는 리스타트 매니저 세션에 join 하는 것을 보여주는 예이다.

DWORD dVal;

         DWORD dwSessionHandle = -1;

         WCHAR sessKey[CCH_RM_SESSION_KEY+1];

         DWORD nServices = 1;

         LPWSTR rgsServices[] = { "iisadmin" };

         DWORD nProcs = 0;

         DWORD nFiles = 1;

         LPWSTR rgsFiles[] = { "c:\\windows\\system32\\oleaut32.dll" };

 // Secondary installer obtains the session key from the

 // primary installer

         // Joining Session

         dVal = RmJoinSession( &dwSessionHandle, sessKey );

         if (dVal != ERROR_SUCCESS)

                 goto RMSUB_END;

         // Register items

         dVal = RmRegisterResources(

                          dwSessionHandle,

                          nFiles, rgsFiles,                  // Files

                          nProcs, NULL,                      // Processes

                          nServices, rgsServices );          // Services

         if (dVal != ERROR_SUCCESS)

                 goto RMSUB_END;

RMSUB_END:

         if (dwSessionHandle != -1)

                 // Clean up session

                 dVal = RmEndSession( dwSessionHandle );

                 dwSessionHandle = -1;

2.3 Getting the Status of a Restart Manager Operation

다수의 어플리케이션들과 서비스들이 셧다운이나 재시작 될 때, 리스타트 매니저의 명령은 시기(기간)를 확장할 수 있다. 아래의 메쏘드는 현재 명령의 상태를 얻는 데 사용되어질 수 있다.

à 현재 리스타트 매니저 명령의 상태 얻기

1. 인스톨러는 셧다운이나 재시작 되어야 할 어플리케이션의 상태의 결정을 위해RM_WRITE_STATUS_CALLBACK 함수를 구현해야 한다. 함수를 사용하여 UI 나 로그에 정보를 제공할 수 있다.

2. 인스톨러는 RmShutdown 혹은 RmRestart함수가 호출 될 때 RM_WRITE_STATUS_CALLBACK함수에 포인터를 전달하여야 한다.

2.4 현재 리스타트 매니저 명령의 취소(Canceling the Current Restart Manager Operation)

사용자의 액션이 다른 액션의 수행을 위해 인스톨러를 제어할 때 아래의 메쏘드는 현재 리스타트 명령을 취소하는 데 쓰일 수 있다.

à 현재 리스타트 매니저 명령의 취소

- 인스톨러는 다른 쓰레드로부터 현재의 RmGetList, RmShutdown, 혹은 RmRestart 명령을취소할 수 있도록 RMCancelCurrentTask를 호출할 수 있다. 리스타트 매니저는 RMCancelCurrentTask 함수가 호출될 때 수행된 명령의 한도에 따라 취소가 가능하다.

3. 리스타트 매니저 레퍼런스 (Restart Manager Reference)

리스타트 매니저 API는 아래의 파트들을 포함한다.

- Callback Functions

- Enumerations

- Functions

- Structures

3.1 콜백 함수(Callback Functions)

리스타트 매니저 API는 아래 표의 콜백 함수를 사용한다.

Callback Function	Description
RM_WRITE_STATUS_CALLBACK	리스타트 매니저의 세션을 시작한 어플리케이션은 리스타트 매니저 함수가 완성률의 퍼센테이지를 받기 위해 이 함수에 포인터를 전달한다.

3.1.1 RM_WRITE_STATUS_CALLBACK

RM_WRITE_STATUS_CALLBACK 함수는 리스타트 매니저를 컨트롤 하는 UI에 의해 구현 될 수 있다. 리스타트 매니저 세션을 시작한 인스톨러는 리스타트 매니저 함수가 완성율의 퍼센테이지를 받기 위해 포인터를 이 함수로 넘겨줄 수 있다. 완성율의 퍼센테이지는 증가하고 구조체는 현재 수행되고 영향을 끼치는 어플리케이션의 이름을 기술한다.

typedef void ( *RM_WRITE_STATUS_CALLBACK )(

UINT nPercentComplete

);

파라미터

nPercentComplete

[in] 0~100까지의 integer값으로 셧다운되거나 재시작 되어진 어플리케이션의 토털 넘버의 퍼센테이지를 나타낸다.

리턴 값

함수 포인터는 값을 리턴하지 않는다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.

See also

RmRestart

RmShutdown

3.2 열거자(Enumerations)

리스타트 매니저 API는 아래의 열거자를 사용한다.

RM_APP_STATUS

RM_APP_TYPE

RM_FILTER_ACTION

RM_FILTER_TRIGGER

RM_REBOOT_REASON

RM_SHUTDOWN_TYPE

3.2.1 RM_APP_STATUS

리스타트 매니저에 의해 활성화 된 현재 어플리케이션의 현재 상태를 기술한다.

typedef enum {

RmStatusUnknown = 0x0,

RmStatusRunning = 0x1,

RmStatusStopped = 0x2,

RmStatusStoppedOther = 0x4,

RmStatusRestarted = 0x8,

RmStatusErrorOnStop = 0x10,

RmStatusErrorOnRestart = 0x20,

RmStatusShutdownMasked = 0x40,

RmStatusRestartMasked = 0x80

}RM_APP_STATUS;

Constants

RmStatusUnknown : 아래 나열된 어떤 열거자의 상태에도 기술되지 않은 어플리케이션

RmStatusRunning : 현재 수행중인 어플리케이션

RmStatusStopped : 리스타트 매니저가 중지한 어플리케이션

RmStatusStoppedOther : 리스타트 매니저가 중지한 어플리케이션의 외부의 액션

RmStatusRestarted : 리스타트 매니저가 재시작한 어플리케이션

RmStatusErrorOnStop : 리스타트 매니저가 어플리케이션을 중지할 때 발견한 에러

RmStatusErrorOnRestart : 리스타트 매니저가 어플리케이션을 재시작 할 때 발견한 에러

RmStatusShutdownMasked : 필터에 의해 셧다운이 마스킹 됨

RmStatusRestartMasked : 필터에 의해 재시작이 마스킹 됨

Remarks

RM_APP_STAUS는 OR 연산으로 조합이 가능하다.

조합은 어플리케이션의 리스타트 매니저에 의해 영향을 받은 액션의 기록들을 기술한다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.

see also

RM_PROCESS_INFO

3.2.2 RM_APP_TYPE

RM_PROCESS_INFO 구조체에 의해 기술된 어플리케이션의 타입을 명세한다.

typedef enum {{

RmUnknownApp = 0,

RmMainWindow = 1,

RmOtherWindow = 2,

RmService = 3,

RmExplorer = 4,

RmConsole = 5,

RmCritical = 1000

}RM_APP_TYPE;

Constants

RmUnknownApp : 어떤 타입으로도 식별이 불가능한 어플리케이션. 강제로 셧다운 해야만 셧다운이 가능한 어플리케이션

RmMainWindow : 상위 레벨 윈도우에서 보이는 단독 프로세스(stand-alone)로 실행된 윈도우즈 어플리케이션

RmOtherWindow : 단독 프로세스(stand-alnoe)으로 실행되어지지 않고 상위 레벨 윈도우에서 보이지 않는 윈도우즈 어플리케이션

RmService : 윈도우즈 서비스 어플리케이션

RmExplorer : 윈도우즈 Explorer 어플리케이션

RmConsole : 단독 콘솔 어플리케이션

RmCritical : 프로세스가 셧다운 될 수 없기 때문에 설치 완료를 위해 시스템 재시작이 필요. 프로세스는 아래의 이유로 셧다운 할 수 없다.

__프로세스가 Critical 프로세스일 것이다.

__현재 사용자가 프로세스를 셧다운 하기위한 자격을 갖추지 못했다.

__프로세스가 리스타트 매니저가 시작한 primary 인스톨러에 속해있다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.

See Also

RM_PROCESS_INFO

3.2.3 RM_FILTER_ACTION

재시작이나 셧다운 액션이 적용된 변경의 타입을 명세한다.

typedef enum {

RmInvalidFilterAction= 0,

RmNoRestart = 1,

RmNoShutdown = 2

}RM_FILTER_ACTION;

Constants

RmInvalidFilterAction : 유효하지 않은 필터 액션

RmNoRestart : 명시된 어플리케이션이나 서비스의 재시작을 방지

RmNoShutdown : 명시된 어플리케이션이나 서비스의 셧다운과 재시작을 방지

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.

See Also

RM_FILTER_INFO

RmAddFilter

3.2.4 RM_FILTER_TRIGGER

어플리케이션이나 서비스의 재시작 혹은 셧다운 액션을 기술

typedef enum {

RmFilterTriggerInvalid = 0,

RmFilterTriggerFile = 1,

RmFilterTriggerProcess = 2,

RmFilterTriggerService = 3

}RM_FILTER_TRIGGER;

Constants

RmFilterTriggerInvalid : 유효하지 않은 필터 트리거

RmFilterTriggerFile : 실행 파일명으로 식별 되는 어플리케이션의 셧다운이나 재시작을 변경

RmFilterTriggerProcess : RM_UNIQUE_PROCESS 구조체에 의해 식별되는 어플리케이션의 셧다운이나 재시작을 변경

RmFilterTriggerService : 서비스 약어(short name)로 식별되는 어플리케이션의 셧다운이나 재시작을 변경

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.

See Also

RM_FILTER_INFO

3.2.5 RM_REBOOT_REASON

시스템이 시스템 리부트가 필요한 이유를 기술

typedef enum {

RmRebootReasonNone = 0x0,

RmRebootReasonPermissionDenied = 0x1,

RmRebootReasonSessionMismatch = 0x2,

RmRebootReasonCriticalProcess = 0x4,

RmRebootReasonCriticalService = 0x8,

RmRebootReasonDetectedSelf = 0x10

}RM_REBOOT_REASON;

Constants

RmRebootReasonNone : 시스템 리부트가 필요치 않음

RmRebootReasonPermissionDenied : 현재 사용자가 한 개 이상의 프로세스를 셧다운 하기위한 권한이 불충분함.

RmRebootReasonSessionMismatch : 한 개 이상의 프로세스가 다른 터미널 서비스 세션에 의해 수행되고 있음.

RmRebootReasonCriticalProcess : 한 개 이상의 프로세스가 critical 프로세스로 셧다운 되어야 하기 때문에 시스템 리부트가 필요함

RmRebootReasonCriticalService : 한 개 이상의 서비스가 critical 서비스로 셧다운 되어야 하기 때문에 시스템 리부트가 필요함

RmRebootReasonDetectedSelf : 현재 프로세스가 반드시 셧다운 되어야 하기 때문에 시스템 리부트가 필요함.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.

See Also

RmGetList

3.2.6 RM_SHUTDOWN_TYPE

어플리케이션의 셧다운을 구성함

typedef enum {

RmForceShutdown = 0x1,

RmShutdownOnlyRegistered = 0x10

}RM_SHUTDOWN_TYPE;

Constants

RmForceShutdown : 응답이 없는 어플리케이션이나 서비스들을 타임 아웃 시간 후에 강제로 셧다운 함. 리스타트 매니저에 의해 요청된 셧다운에 대해 응답이 없는 어플리케이션은 30초 후에 강제로 셧다운 된다. (서비스는 20초)

디폴트 타임은 Remarks 섹션에 기술된 레지스트리 키를 수정함으로 변경이 가능하다.

RmShutdownOnlyRegistered : RegisterApplicationRestart 함수를 사용하여 재시작을 위해 등록된 모든 어플리케이션을 셧다운 한다. 프로세스나 서비스를 재시작 할 수 없을 때 어떤 프로세스나 서비스도 셧다운 되지 않는다.

Remarks

아래 명시된 레지스트리 키는 어플리케이션의 강제 셧다운 횟수를 초기화 한다.

HKCU\Control Panel\Desktop\HungAppTimeout

아래 명시된 레지스트리 키는 서비스의 강제 셧다운 횟수를 초기화 한다.

HKLM\System\CurrentControlSet\Control\WaitToKillServiceTimeout

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.

See Also

RmShutdown

3.3 함수(Functions)

리스타트 매니저 API는 아래 테이블에 식별된 함수를 사용한다.

Enumeration	Description
RmAddFilter	셧다운이나 재시작의 액션을 변경.
RmStartSession	새로운 리스타트 매니저 세션을 시작
RmJoinSession	어플리케이션의 프로세스를 존재하는 리스타트 매니저 세션으로 연결(Join)
RmEndSession	리스타트 매니저 세션을 종료
RmRegisterResources	리스타트 매니저 세션에 파일명이나 서비스 약어(short name) 혹은 RM_UNIQUE_PROCESS 구조체 형식의 리소스를 등록
RmGetList	인스톨러에 의해 등록되어 모든 어플리케이션에 영향을 미치는 리소스와 현재 상태 리스트를 얻어온 다.
RmGetFilterList	이미 적용된 변경의 셧다운이나 리스타트 상태를 쿼리한다.
RmShutdown	어플리케이션이나 서비스의 셧다운을 시작한다.
RmRemoveFilter	이미 적용된 변경의 셧다운이나 재시작을 제거한다.
RmRestart	RmShutdown함수에 의해 셧다운 되고, RegisterApplicationRestart로 재시작을 위해 등록 된 어플리 케이션이나 서비스를 재시작한다..
RmCancelCurrentTask	RmGetList, RmShutdown, 혹은 RmRestart 함수를 취소한다.

3.3.1 RmAddFilter

어플리케이션이나 서비스에 적용되는 액션을 셧다운 하거나 재시작 하도록 변경함.

primary 인스톨러는 여러 번 RmAddFilter 함수를 호출 할 수 있다. 가장 최근의 호출이 이전의 같은 파일, 프로세스 혹은 서비스에 대한 변경을 덮어쓴다.

DWORD WINAPI RmAddFilter(

DWORD dwSessionHandle,

LPCWSTR strFilename,

RM_UNIQUE_PROCESS* Application,

LPCWSTR strShortServiceName,

RM_FILTER_ACTION ActionType

);

파라미터

dwSessionHandle : [in] 존재하는 리스타트 매니저 세션의 핸들

strFilename : [in, optional] 널 종료 스트링의 포인터로 어플리케이션 실행 파일의 풀 경로를 담는다. 셧다운이나 재시작 액션은 풀 경로를 참조하여 변경한다.

Application : [in, optional] 어플리케션의 RM_UNIQUE_PROCESS 구조체 포인터. 셧다운이나 재시작 액션은 RM_UNIQUE_PROCESS 구조체를 참조하여 변경한다. 이 파라미터는 strFilename 이나 strShortName 파라미터가 NULL이 아닐때 반드시 NULL이어야 한다.

strShortServiceName : [in, optional] 서비스 약어를 얻기 위한 널 종료 스트링의 포인터. 셧다운이나 재시작 액션은 short service filename을 참조하여 변경한다. 이 파라미터는 strFilename이나 Application 파라미터가 NULL이 아닐 때 반드시 NULL이어야 한다.

ActionType: [in] 적용될 수정 타입을 명시하는 RM_FILTER_ACTION 열거자의 값

리턴 값

최근 에러 값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_SUCCESS 0	함수의 성공적인 완료.
ERROR_BAD_ARGUMENTS 160	한 개 이상의 인자가 틀림. 이 에러값은 리스타트 매니저 함수에 의해 리턴되며 non-null 과 non-zero 값일 때 널 포인터 혹은 0이 인자로 넘어온다
ERROR_SESSION_CREDENTIAL_CONFLICT 1219	secondary 인스톨러가 이 기능을 호출 할 때 리턴 되는 에러. 이 기능은 primary 인스톨러에서만 가용하다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.
Library	Use Rstrtmgr.lib.
DLL	Requires Rstrtmgr.dll.

See Also

RmGetFilterList

3.3.2. RmCancelCurrentTask

현재의 RmGetList, RmShutdown 및 RmRestart 명령을 취소한다. 이 함수는 반드시 RmStartSession함수가 호출하여 시작된 세션의 어플리케이션에서 호출할 수 있다.

DWORD WINAPI RmCancelCurrentTask(

DWORD dwSessionHandle

);

파라미터

dwSessionHandle : [in] 존재하는 세션 핸들

리턴값

최근 에러값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_SUCCESS 0	요청된 현재 명령의 취소.
ERROR_BAD_ARGUMENTS 160	한 개 이상의 인자가 틀림. 이 에러 값은 리스타트 매니저 함수에 의해 리턴 되며 non-null 과 non-zero 값일 때 널 포인터 혹은 0이 인자로 넘어온다.
ERROR_OUTOFMEMORY 14	메모리가 부족하여 리스타트 매니저가 명령을 수행할 수 없다
ERROR_INVALID_HANDLE 6	핸들을 제공하기 위한 리스타트 매니저의 세션이 존재하지 않는다

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.
Library	Use Rstrtmgr.lib.
DLL	Requires Rstrtmgr.dll.

See Also

RmGetList

RmRestart

RmShutdown

3.3.3. RmEndSession

리스타트 매니저 세션을 종료한다. 이 함수는 반드시 RmStartSession함수의 호출에 의해 시작된 지난 세션의 primary 인스톨러에 의해 호출 해야 한다. 또한 RmEndSession함수는 세션에 연결된(joined) 더 이상 secondary 인스톨러로 리소스를 등록할 필요가 없는 secondary 인스톨러에 의해 호출될 수 있다.

파라미터

dwSessionHandle : 존재하는 리스타트 매니저 세션의 핸들

DWORD WINAPI RmEndSession(

DWORD dwSessionHandle

);

리턴값

최근 에러값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_SUCCESS 0	함수의 성공적인 완료
ERROR_SEM_TIMEOUT 121	리스타트 매니저 함수가 할당된 횟수의 레지스트리 쓰기 mutex를 얻어올 수 없음. 리스타트 매니저의 실패로 시스템 리부트가 권고됨
ERROR_WRITE_FAULT 29	명령을 레지스트리에 읽거나 쓸수 없다
ERROR_OUTOFMEMORY 14	메모리가 부족하여 리스타트 매니저 명령을 수행할 수 없다
ERROR_INVALID_HANDLE 6	유효하지 않은 핸들이 함수로 전달되었다. 핸들이 제공하는 어떠한 리스타트 매니저 세션도 존재하지 않는다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.
Library	Use Rstrtmgr.lib.
DLL	Requires Rstrtmgr.dll.

See Also

RmJoinSession

RmStartSession

3.3.4 RmGetFilterList

RmAddFilter함수에 의해 이미 적용된 셧다운이나 재시작 액션의 변경 리스트. 적용된 변경에 대한 정보를 담은 버퍼의 포인터를 리턴한다.

DWORD WINAPI RmGetFilterList(

DWORD dwSessionHandle,

PBYTE pbFilterBuf,

DWORD cbFilterBuf,

LPDWORD cbFilterBufNeeded

);

파라미터

dwSessionHandle : [in] 존재하는 리스타트 매니저 세션의 핸들

pbFilterBuf : [out] 변경 정보를 담고 있는 버퍼의 포인터

cbFilterBuf : [in, optional] 변경 정보를 담고 있는 버퍼 포인터의 사이즈(bytes)

cbFilterBufNeeded : [out] 버퍼가 필요로 하는 바이트의 수

리턴값

최근 에러값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_SUCCESS 0	함수의 성공적인 완료
ERROR_BAD_ARGUMENTS 160	한 개 이상의 인자가 틀림. 이 에러값은 리스타트 매니저 함수에 의해 리턴되며 non-null 과 non-zero 값일 때 널 포인터 혹은 0이 인자로 넘어온다.
ERROR_MORE_DATA 234	RmGetFilterList함수의 pbFilterBuf 버퍼가 어플리케이션 정보의 크기보다 작을 때 의해 리턴되는 에러 값. cbFilterBufNeeded는 명시되지 않는다.
ERROR_SESSION_CREDENTIAL_CONFLICT 1219	secondary 인스톨러가 이 기능을 호출 할때 리턴되는 에러. 이 기능은 primary 인스톨러에서만 가용하다.

Remarks

리턴 된 pbFilterBuf 버퍼는 필터 리스트에 접근하기 위해 RM_FILTER_INFO로 형 변환 되어야 한다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.
Library	Use Rstrtmgr.lib.
DLL	Requires Rstrtmgr.dll.

See Also

RmAddFilter

3.3.5 RmGetList

리스타트 매니저 세션과 함께 등록된 어플리케이션이과 서비스에서 현재 사용되어지는 리소스의 리스트를 얻어온다.

DWORD WINAPI RmGetList(

DWORD dwSessionHandle,

UINT* pnProcInfoNeeded,

UINT* pnProcInfo,

RM_PROCESS_INFO rgAffectedApps[ ],

LPDWORD lpdwRebootReasons

);

파라미터

dwSessionHandle : [in] 존재하는 리스타트 매니저 세션의 핸들

pnProcInfoNeeded : [out] 필요로 하는 배열 크기의 포인터로 모든 영향을 미치는 어플리케이션과 서비스들의 리턴 정보를 받는 RM_PROCESS_INFO구조체(?)

pnProcInfo : [in, out] 배열과 채워질 구조체의 수 내에서 RM_PROCESS_INFO 구조체의 총 개수의 포인터

rgAffectedApps : [in, out] 세션에 등록된 리소스를 사용하는 어플리케이션과 서비스의 리스트 RM_PROCESS_INFO 구조체의 배열

lpdwRebootReasons : [in, out] 시스템 리부트가 필요한 이유를 기술하는 RM_REBOOT_REASON 열거자의 값을 위치로 받는 포인터

리턴값

최근 에러값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_SUCCESS 0	함수의 성공적인 완료
ERROR_MORE_DATA 234	RmGetFilterList함수의 pbFilterBuf 버퍼가 어플리케이션 정보의 크기보다 작을 때 의해 리턴되는 에러 값.
ERROR_CANCELLED 1223	현재 명령이 사용자에 의해 취소됨.
ERROR_SEM_TIMEOUT 121	리스타트 매니저 함수가 할당된 횟수의 레지스트리 쓰기 mutex를 얻어올 수 없음. 리스타트 매니저의 실패로 시스템 리부트가 권고됨
ERROR_BAD_ARGUMENTS 160	한 개 이상의 인자가 틀림. 이 에러값은 리스타트 매니저 함수에 의해 리턴 되며 non-null 과 non-zero 값일 때 널 포 인터 혹은 0이 인자로 넘어온다.
ERROR_WRITE_FAULT 29	명령을 레지스트리에 읽거나 쓸수 없다.
ERROR_OUTOFMEMORY 14	메모리가 부족하여 리스타트 매니저 명령을 수행할 수 없다.
ERROR_INVALID_HANDLE 6	유효하지 않은 핸들이 함수로 전달되었다. 핸들이 제공하는 어떠한 리스타트 매니저 세션도 존재하지 않는다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.
Library	Use Rstrtmgr.lib.
DLL	Requires Rstrtmgr.dll.

See Also

RmCancelCurrentTask

3.3.6 RmJoinSession

secondary 인스톨러를 현재 존재하고 있는 리스타트 매니저 세션에 연결(join)한다. 이 함수는 시작된 세션의 primary 인스톨러에 의해 얻어지는 세션키와 함께 호출 되어야 한다. 리스타트 매니저 함수의 몇몇 부분에 적합한 세션 키가 요구되어 진다. secondary 인스톨러가 세션에 연결(join)된 후 RmRegisterResources함수를 호출하여 리소스를 등록할 수 있다.

DWORD WINAPI RmJoinSession(

DWORD* pSessionHandle,

const WCHAR strSessionKey[CCH_RM_SESSION_KEY+1]

);

파라미터

pSessionHandle : [out] 존재하는 리스타트 매니저 세션의 핸들의 포인터

strSessionKey : [in] 존재하는 세션의 세션키를 포함하는 널 종료 스트링

리턴값

최근 에러값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_SUCCESS 0	함수의 성공적인 완료.
ERROR_SESSION_CREDENTIAL_CONFLICT 1219	인스톨러가 이 기능을 호출 할때 리턴되는 에러. 이 기능은 primary 인스톨러에서만 가용하다.
ERROR_SEM_TIMEOUT 121	리스타트 매니저 함수가 할당된 횟수의 레지스트리 쓰기 mutex를 얻어올 수 없음. 리스타트 매니저의 실패로 시스 템 리부트가 권고됨
ERROR_BAD_ARGUMENTS 22	한 개 이상의 인자가 틀림. 이 에러값은 리스타트 매니저 함수에 의해 리턴되며 non-null 과 non-zero 값일 때 널 포인터 혹은 0이 인자로 넘어온다.
ERROR_WRITE_FAULT 29	명령을 레지스트리에 읽거나 쓸수 없다.
ERROR_MAX_SESSIONS_REACHED 353	가용한 세션의 맥스값에 도달했다.
ERROR_OUTOFMEMORY 14	메모리가 부족하여 리스타트 매니저 명령을 수행할 수 없다.

Remarks

RmJoinSession함수는 secondary 인스톨러를 현재 존재하는 리스타트 매니저 세션에 연결(join) 한다. Secondary 인스톨러는 일반적으로 UI를 컨트롤하지 않고 primary 인스톨러의 in-process 혹은 out-of-process 에서 실행하는 인스톨러이다. Primary 인스톨러는 RmStartSession 함수와 UI혹은 업데이트에서 sequence of multiple 설치를 컨트롤 하는 어플리케이션만을 호출할 수 있다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.
Library	Use Rstrtmgr.lib.
DLL	Requires Rstrtmgr.dll.

See Also

RmEndSession
RmStartSession

3.3.7 RmRegisterResources

리스타트 매니저 세션에 리소스를 등록한다. 리스타트 매니저는 셧다운이나 재시작 되어야 할 어플리케이션이과 서비스를 고려하여 세션과 함께 등록한 리소스들의 리스트를 사용한다. 리소스들은 파일명이나, 서비스 약어, 또는 수행중인 어플리케이션을 기술한 RM_UNIQUE_PROCESS 구조체에 의해 식별 할 수 있다. RmRegisterResources 함수는 primary 혹은 secondary 인스톨러에 의해 사용된다.

DWORD WINAPI RmRegisterResources(

DWORD dwSessionHandle,

UINT nFiles,

LPCWSTR rgsFilenames[nFiles],

UINT nApplications,

RM_UNIQUE_PROCESS rgApplications[nApplications],

UINT nServices,

LPCWSTR rgsServiceNames[nServices]

);

파라미터

dwSessionHandle : [in] 존재하는 리스타트 매니저 세션의 핸들

nFiles : [in] 등록될 파일들의 수

rgsFilenames : [in] 널 종료 스트링의 배열로 풀 파일네임 경로이다. 이 파라미터는 nFiles가 0일 경우 NULL이 된다.

nApplications : [in] 등록될 프로세스의 개수

rgApplications : [in] RM_UNIQUE_PROCESS 구조체의 배열. 이 파라미터는 nApplications가 0일경우 NULL이 된다

nServices : [in] 등록될 서비스의 갯수

rgsServiceNames : [in] 널 종료 스트링의 배열로 서비스 약어이다. 이 파라미터는 nService가 0일 경우 NULL이 된다.

리턴값

최근 에러값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_SUCCESS 0	함수의 성공적인 완료
ERROR_SEM_TIMEOUT 121	리스타트 매니저 함수가 할당된 횟수의 레지스트리 쓰기 mutex를 얻어올 수 없음. 리스타트 매니저의 실패로 시스 템 리스타트가 권고됨
ERROR_BAD_ARGUMENTS 160	한 개 이상의 인자가 틀림. 이 에러값은 리스타트 매니저 함수에 의해 리턴되며 non-null 과 non-zero 값일 때 널 포 인터 혹은 0이 인자로 넘어온다.
ERROR_WRITE_FAULT 29	명령을 레지스트리에 읽거나 쓸 수 없다
ERROR_OUTOFMEMORY 14	메모리가 부족하여 리스타트 매니저 명령을 수행할 수 없다.
ERROR_INVALID_HANDLE 6	유효하지 않은 핸들이 함수로 전달되었다. 핸들이 제공하는 어떠한 리스타트 매니저 세션도 존재하지 않는다.

Remarks

RmRegisterResources함수의 수행에 대한 각각의 호출은 쓰기 명령에 expensive 하다.

파일당 한번 함수를 호출하지 말고 컴포넌트와 레지스터안에서 연관된 파일을 그룹으로 호출하라.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.
Library	Use Rstrtmgr.lib.
DLL	Requires Rstrtmgr.dll.

3.3.8 RmRemoveFilter

RmAddFilter함수를 사용하여 적용된 셧다운이나 재시작 액션의 변경을 제거한다.

primary 인스톨러는 RmRemoveFilter함수를 여러 번 호출할 수 있다.

DWORD WINAPI RmRemoveFilter(

DWORD dwSessionHandle,

LPCWSTR strFilename,

RM_UNIQUE_PROCESS* Application,

LPCWSTR strShortServiceName

);

파라미터

dwSessionHandle : [in] 존재하는 리스타트 매니저 세션의 핸들

strFilename : [in, optional] 널 종료 스트링 값의 포인터로 어플리케이션 실행 파일의 풀 경로이다. RmRemoveFilter함수는 어플리케이션에서 참조하는 모든 이전의 RmAddFilter함수에서 적용된 셧다운이나 재시작 액션의 수정을 제거한다. Applicaion 혹은 strServiceShortName 파라미터가 NULL이 아닌 경우 반드시 NULL이어야 한다.

Application : [in, optional] 어플리케이션의 RM_UNIQUE_PROCESS 구조체. RmRemoveFilter함수는 어플리케이션에서 참조하는 모든 이전의 RmAddFilter함수에서 적용된 셧다운이나 재시작 액션의 수정을 제거한다. strFilename 혹은 strShortServiceName파라미터가 NULL 이 아닐 경우 반드시 NULL이어야 한다.

strShortServiceName : [in, optional] 널 종료 스트링 값의 포인터로 서비스 약어를 담는다.

RmRemoveFilter함수는 어플리케이션에서 참조하는 이전의 모든 RmAddFilter함수에서 적용된 셧다운이나 재시작 액션의 수정을 제거한다. strFilename 혹은 Application 파라미터가 NULL 이 아닌 경우 반드시 NULL 이어야 한다.

리턴값

최근 에러값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_SUCCESS 0	함수의 성공적인 완료
ERROR_FILE_NOT_FOUND 1	찾을 수 없는 필터의 명세
ERROR_SESSION_CREDENTIAL_CONFLICT 1219	secondary 인스톨러가 이 기능을 호출 할때 리턴 되는 에러. 이 기능은 primary 인스톨러에서만 가용하다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.
Library	Use Rstrtmgr.lib.
DLL	Requires Rstrtmgr.dll.

3.3.9 RmRestart

RmShutdown함수에 의해 셧다운되고, RegisterApplicationRestart로 재시작를 위해 등록 된 어플리케이션이나 서비스를 재시작한다. 이 함수는 RmStartSession함수의 호출로 리스타트 매니저 세션을 시작한 primary인스톨러에서만 호출 할 수 있다.

DWORD WINAPI RmRestart(

DWORD dwSessionHandle,

DWORD dwRestartFlags,

RM_WRITE_STATUS_CALLBACK fnStatus

);

파라미터

dwSessionHandle : [in] 존재하는 리스타트 매니저 세션의 해들

dwRestartFlags : 예약됨. 반드시 0이어야 한다.

fnStatus : [in] RmRestart함수가 수행되는 동안 상태를 공유(communite)하기 위해 사용되는 메시지 콜백 함수. 만약 NULL이면 아무 상태도 제공되지 않는다.

리턴값

최근 에러값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_REQUEST_OUT_OF_SEQUENCE	RmRestart함수가 RmShutdown함수의 호출 전에 적합한 세션핸들을 호출했을 때 리턴된다.
ERROR_FAILRESTART 352	한 개 이상의 어플리케이션을 리스타트 할 수 없다. RmGetList함수에서 리턴된 업데이트된 상태 정보인 RM_PROCESS_INFO구조체
ERROR_SEM_TIMEOUT 121	리스타트 매니저 함수가 할당된 횟수의 레지스트리 쓰기 mutex를 얻어올 수 없음. 리스타트 매니저의 실패로 시스 템 리부트가 권고됨
ERROR_CANCELLED 1223	현재 명령이 사용자에 의해 취소됨
ERROR_BAD_ARGUMENTS 160	한 개 이상의 인자가 틀림. 이 에러값은 리스타트 매니저 함수에 의해 리턴되며 non-null 과 non-zero 값일 때 널 포 인터 혹은 0이 인자로 넘어온다.
ERROR_WRITE_FAULT 29	명령을 레지스트리에 읽거나 쓸수 없다
ERROR_OUTOFMEMORY 14	메모리가 부족하여 리스타트 매니저 명령을 수행할 수 없다.
ERROR_INVALID_HANDLE 6	유효하지 않은 핸들이 함수로 전달되었다. 핸들이 제공하는 어떠한 리스타트 매니저 세션도 존재하지 않는다.

Remarks

RmRestart함수가 호출된 후, RmGetList함수에 의해 리턴 된 RM_PROCESS_INFO 구조체는 업데이트 된 상태 정보를 포함한다.

리스타트 매니저는 다른 사용자나 터미널 세션으로 분리된 권한을 고려한다. LocalSystem 권한으로 서비스가 수행되는 인스톨러는 어떠한 다른 유저나 터미널 세션의 어플리케이션도 셧다운하거나 재시작 할 수 업다. 인스톨러는 다른 세션에서 수행중인 셧다운과 재시작 어플리케이션에는 반드시 커스텀 메쏘드를 구현하여야 한다. 한 메소드는 셧다운과 재시작 명령을 수행하는 다른 세션에서 새 인스톨러의 프로세스를 시작한다.

콘솔 어플리케이션이 리스타트 매니저에 의해 셧다운되거나 재시작 되어야 할 때, 어플리케이션은 새로운 콘솔에서 재시작 된다.

인스톨러는 RmShutdown함수가 에러 값을 리턴하고, 어플리케이션이나 서비스가 셧다운 될 수 없음을 가리킬 때에도 항상 RmRestart함수가 사용하는 어플리케이션과 서비스를 재시작 하여야 한다. RmRestart 함수는 현재 로그인 되어있지 않은 어떤 사용자의 어플리케이션도 재시작 하지 않는다. 비단 리스타트 매니저에 의해 셧다운 된다 해도 그렇다.

예로 RmRestart 함수는 현재 로그인 되지 않은 사용자 Run As 명령으로 어플리케이션을 시작하면 재시작 되지 않는다. 이런 어플리케이션은 반드시 수동으로 재시작 되어야 한다.

See Also

RegisterApplicationRestart

RmCancelCurrentTask

RmShutdown

3.3.10 RmShutdown

어플리케이션의 셧다운을 시작한다. 이 함수는 RmStartSession의 사용으로 리스타트 매니저 세션과 함께 시작된 인스톨러에 의해서만 호출할 수 있다..

DWORD WINAPI RmShutdown(

DWORD dwSessionHandle,

ULONG lActionFlags,

RM_WRITE_STATUS_CALLBACK fnStatus

);

파라미터

dwSessionHandle : [in] 존재하는 리스타트 매니저 세션의 핸들

IActionFlags : [in] 컴포넌트의 셧다운을 구성하는 한 개 이상의 RM_SHUTDOWN_TYPE 옵션. 아래의 값은 OR 연산으로 조합하여, 재시작 하도록 등록된 모든 응답하지 않는 어플리케이션과 서비스들이 강제로 셧다운 될 수 있도록 한다.

Value	Meaning
RmForceShutdown 0x1	응답이 없는 어플리케이션이나 서비스들을 타임 아웃 시간 후에 강제로 셧다운 함. 리스타트 매니저에 의해 요청된 셧다운에 대해 응답이 없는 어플리케이션은 30초 후에 강제로 셧다운 된다. (서비스는 20초)
RmShutdownOnlyRegistered 0x10	RegisterApplicationRestart 함수를 사용하여 리스타트를 위해 등록된 모든 어플리케이션을 셧다운 한다. 프로세스 혹은 서비스를 재시작 할 수 없을 때 어떤 프로세스나 서비스도 셧다운 되지 않는다.

fnStatus : [in, optional] 함수가 실행되는 동안 세부 정보를 공유(communite) 하는 데 사용 하는 RM_WRITE_STATUS_CALLBACK함수의 포인터. 만약 NULL이면 아무런 status도 제공하지 않는다.

리턴값

최근 에러값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_SUCCESS 0	모든 셧다운, 재시작, 콜백 명령이 성공적으로 완료
ERROR_FAIL_NOACTION_REBOOT 350	아무런 셧다운 액션도 수행되지 않았다. 한개 이상의 프로세스 혹은 서비스가 시스템 셧다운을 위해 리스타트를 요구함. 이 에러 코드는 리스타트 매니저가 모든 어플리케이션을 종료하기 전에 요구되어지는 시스템의 리스타트를 찾아 리턴한다.
ERROR_FAIL_SHUTDOWN 351	몇몇 어플리케이션이 셧다운 될 수 없다. RmGetList함수가 포함하는 업데이트 된 상태 정보의 리턴값으로 RM_PROCESS_INFO 구조체의 AppStatus 이다.
ERROR_CANCELLED 1223	명령의 성공의 취소 요청시 RmShutdown함수에 의해 리턴되는 에러값이다.
ERROR_SEM_TIMEOUT 121	리스타트 매니저 함수가 할당된 횟수의 레지스트리 쓰기 mutex를 얻어올 수 없음. 리스타트 매니저의 실패로 시스 템 리부트가 권고됨
ERROR_BAD_ARGUMENTS 160	한개 이상의 인자가 틀림. 이 에러값은 리스타트 매니저 함수에 의해 리턴되며 non-null 과 non-zero 값일 때 널 포 인터 혹은 0이 인자로 넘어온다.
ERROR_WRITE_FAULT 29	명령을 레지스트리에 읽거나 쓸수 없다
ERROR_OUTOFMEMORY 14	메모리가 부족하여 리스타트 매니저 명령을 수행할 수 없다.
ERROR_INVALID_HANDLE 6	유효하지 않은 핸들이 함수로 전달되었다. 핸들이 제공하는 어떠한 리스타트 매니저 세션도 존재하지 않는다.

Remarks

RmShutdown함수는 RmGetList 호출하고 현재 사용되고 있는, 재시작이 시도된 적이 있던 등록된 리소스들의 프로세스 리스트를 업데이트 한다. 그리고나서 RmShutdown함수는 가장 최근에 등록했던 리소스들을 사용해 프로세스의 셧다운을 시도한다.

RmShutdown함수는 RmGetList함수의 상세정보에 의해 리턴 된 RM_PROCESS_INFO의 AppStatus 멤버를 업데이트 한다. 리스타트 매니저는 분리된 다른 사용자 혹은 터미널 세션의 권한을 따른다. LocalSystem 권한의 서비스로 수행되는 인스톨러는 다른 사용자 혹은 터미널 세션의 어떤 어플리케이션도 셧다운이나 재시작 할 수 없다. 인스톨러는 반드시 다른 세션에서 수행되는 어플리케이션을 셧다운이나 재시작하는 커스텀 메쏘드를 구현해야 한다.

한 메쏘드가 다른 세션에서 셧다운과 재시작 명령을 수행하려면 새 인스톨러 프로세스를 시작해야 한다.

인스톨러는 RmShutdown함수가 에러를 리턴 하고, 가리키는 모든 어플리케이션과 서비스를 셧다운 할 수 없을 때에라도 RmRestart함수를 사용해 항상 어플리케이션과 서비스를 재시작 할 수 있다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.
Library	Use Rstrtmgr.lib.
DLL	Requires Rstrtmgr.dll.

See Also

RegisterApplicationRestart

RmCancelCurrentTask

RmRestart

3.3.11 RmStartSession

새로운 리스타트 매니저 세션을 시작한다. 동시간에 시스템에서 열 수 있는 사용자 세션 당 64개의 리스타트 매니저 세션이 Maximum이다. 이 함수가 세션을 시작할 때 리스타트 매니저 API가 이후로 호출하기 위한 세션 핸들과 세션 키를 리턴 한다.

DWORD WINAPI RmStartSession(

DWORD* pSessionHandle,

DWORD dwSessionFlags,

WCHAR strSessionKey[CCH_RM_SESSION_KEY+1]

);

파라미터

pSeesionHandle : [out] 리스타트 매니저 세션 핸들의 포인터. 세션 핸들은 이후 호출되는 리스타트 매니저 API의 호출에 전달된다.

dwSessionFlags : 예약됨. 파라미터는 0이어야 한다.

strSessionKey : [in, out] 널 종료 문자로 새로운 세션을 위한 세션 키를 담는다. 스트링은 RmStartSession함수를 호출하기 전에 할당 되어야 한다.

리턴값

최근 에러값을 받는다. 함수는 Winerror.h에 정의 된 system error codes 중 하나를 리턴한다.

Value	Meaning
ERROR_SUCCESS 0	함수의 성공적인 완료
ERROR_SEM_TIMEOUT 121	리스타트 매니저 함수가 할당된 횟수의 레지스트리 쓰기 mutex를 얻어올 수 없음. 리스타트 매니저의 실패로 시스 템 리부트가 권고됨
ERROR_BAD_ARGUMENTS 160	한개 이상의 인자가 틀림. 이 에러값은 리스타트 매니저 함수에 의해 리턴되며 non-null 과 non-zero 값일 때 널 포 인터 혹은 0이 인자로 넘어온다.
ERROR_MAX_SESSIONS_REACHED 353	가용한 세션의 맥스값에 도달했다.
ERROR_WRITE_FAULT 29	명령을 레지스트리에 읽거나 쓸수 없다.
ERROR_OUTOFMEMORY 14	메모리가 부족하여 리스타트 매니저 명령을 수행할 수 없다.

Remarks

RmStartSession함수는 세션에 이미 같은 세션 키가 존재하면 에러를 리턴 한다.

RmStartSession함수는 UI를 컨트롤 하거나 업데이트의 sequence of multiple patches 설치를 컨트롤 시 primary 인스톨러에 의해 호출 되어야 한다.

secondary 인스톨러는 RmJoinSession함수로부터 리턴 된, 존재하는 리스타트 매니저 세션 그리고 primary 인스톨러의 RmStartSession 함수 콜로 부터 리턴 된 세션 핸들과 세션 키를 연결(join)할 수 있다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.
Library	Use Rstrtmgr.lib.
DLL	Requires Rstrtmgr.dll.

See Also

RmEndSession

RmJoinSession

3.4 구조체(Structures)

리스타트 매니저 API는 아래의 구조체를 포함한다.

RM_FILTER_INFO

RM_PROCESS_INFO

RM_UNIQUE_PROCESS

3.4.1 RM_FILTER_INFO

변경할 재시작 혹은 셧다운 액션의 정보를 포함하고 있다. RmAddFilter, RmRemoveFilter, 그리고 RmGetFilterList 함수에 의해, 리스타트 매니저 세션과 함께 등록된 어플리케이션이나 서비스들을 추가, 제거 그리고 나열한다.

typedef struct _RM_FILTER_INFO {
RM_FILTER_ACTION FilterAction;
RM_FILTER_TRIGGER FilterTrigger;
DWORD cbNextOffset;
LPWSTR strFilename;
RM_UNIQUE_PROCESS Process;
LPWSTR strServiceShortName;

} RM_FILTER_INFO,
*PRM_FILTER_INFO;

멤버

FilterAction

이 멤버는 RM_FILTER_ACTION 열거자의 값을 포함하고 있다. RmNoRestart 값을 사용하여 어플리케이션이나 서비스의 재시작을 방지하며, RmNoShutdown 값을 사용하여 어플리케이션이나 서비스의 셧다운과 재시작을 방지한다.

FilterTrigger

이 멤버는 RM_FILTER_TRIGGER 열거자의 값을 포함하고 있다. RmFilterTriggerFile 값을 사용하여 실행 파일의 풀 경로를 통해 어플리케이션의 재시작이나 셧다운 액션을 변경하고, RmFilterTriggerProcess의 값을 사용해 RM_UNIQUE_PROCESS구조체를 참조하여 어플리케이션의 재시작이나 셧다운 액션을 변경하며, RmFilterTriggerService의 값을 사용해 서비스 약어를 참조하여 서비스의 재시작이나 셧다운 액션을 변경한다.

cbNextOffset

다음 구조체의 바이트 오프셋

strFilename

만약 FilterTrigger의 값이 RmFilterTriggerFile이면 이 멤버는 어플리케이션 파일네임을 포함한 스트링 값을 담는다.

Process

만약 FilterTrigger의 값이 RmFilterTriggerProcess이면 이 멤버는 어플리케이션를 위한 RM_PROCESS_INFO 구조체이다.

strServiceShortName

만약 FilterTrigger의 값이 RmFilterTriggerService 이면 이 멤버는 서비스 약어를 담는 스트링 값의 포인터이다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.

See Also

RmGetFilterList

RM_FILTER_TRIGGER

3.4.2 RM_PROCESS_INFO

리스타트 매니저와 함께 등록되어야 할 어플리케이션을 기술한다.

typedef struct {
RM_UNIQUE_PROCESS Process;
WCHAR strAppName[CCH_RM_MAX_APP_NAME+1];
WCHAR strServiceShortName[CCH_RM_MAX_SVC_NAME+1];
RM_APP_TYPE ApplicationType;
ULONG AppStatus;
DWORD TSSessionId;
BOOL bRestartable;

} RM_PROCESS_INFO;

멤버

Process

어플리케이션의 PID와 프로세스 시작 시간으로 유일하게 구분할 수 있는 RM_UNIQUE_PROCESS 구조체를 담는다.

strAppName

만약 프로세스가 서비스이면 이 파라미터는 서비스를 위한 long name을 리턴 하고, 프로세스가 서비스가 아니면 이 파라미터는 어플리케이션을 위한 유저 프랜들리 네임을 리턴한다. 만약 프로세스가 critical process이고, 인스톨러가 상승된 권한에서 실행되면 이 파라미터는 critical process의 실행 파일명을 리턴 하고 프로세스가 critical process이고 인스톨러가 서비스로 실행되면 이 파라미터는 critical process의 long name을 리턴한다.

strServiceShortName

만약 프로세스가 서비스일 경우 서비스 약어이고, 서비스가 아닐 경우 사용되지 않는다.

ApplicationType

RmUnknownApp, RmMainWindow, RmOtherWindow, RmService, RmExplorer 혹은 RmCritical 등의 어플리케이션 타입의 RM_APP_TYPE 열거자 값을 포함한다.

AppStatus

어플리케이션의 현재 상태를 기술하는 비트 마스크를 포함한다. RM_APP_STATUS 열거자를 보라

TSSessionId

프로세스의 터미널 서비스 세션 ID를 포함한다. RM_INVALID_SESSION(-1)로 이 멤버의 값이 설정되면 프로세스의 터미널 세션은 고려될 수 없다. 프로세스가 서비스 이거나 system critical process이면 사용되지 않는다.

bRestartable

어플리케이션이 리스타트 매니저에 의해 리스타트될 수 있을 때 TRUE를 리턴하고, 역일때 FALSE를 리턴한다.

프로세스가 서비스일 때 항상 TRUE를 리턴한다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.

See Also

RM_APP_TYPE

RM_FILTER_INFO

RM_UNIQUE_PROCESS

RmGetList

RmRestart

RmShutdown

3.4.3 RM_UNIQUE_PROCESS

프로세스의 시작 시간과 PID로 유일하게 식별 가능한 프로세스.

RM_UNIQUE_PROCESS 구조체의 배열은 RmRegisterResources함수에 전달될 수 있다.

typedef struct {
DWORD dwProcessId;
FILETIME ProcessStartTime;

} RM_UNIQUE_PROCESS,
*PRM_UNIQUE_PROCESS;

멤버

dwProcessId

프로덕트 식별자(PID)

ProcessStartTime

프로세스의 생성 시간. GetProcessTimes함수의 lpCreationTime 파라미터에 의해 리턴 되는 FILETIME 구조체에 제공되는 시간

Remarks

RM_UNIQUE_PROCESS 구조체는 RM_PROCESS_INFO 구조체나 RmRegisterResources함수에 의해 리스타트 매니저 세션과 함께 등록된, 유일한 어플리케이션의 식별자로 사용될 수 있다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in RestartManager.h.

#첨부 1

WM_QUERYENDSESSION

WM_QUERYENDSESSION는 사용자가 세션을 종료하거나 시스템 재시작 함수를 어플리케이션이 호출 했을 때 보내지는 메시지이다. 만약 어플리케이션이 0을 리턴하면 세션은 종료되지 않는다. 어플리케이션이 0을 리턴하는 즉시 시스템은 WM_QUERYENDSESSION메시지 보내기를 멈춘다. 메시지의 처리 후 시스템은 WM_ENDSESSION메시지를 WM_QUERYENDSESSION메시지의 결과 값으로 설정된 wParam 파라미터와 함께 보낸다.

윈도우는 자신의 WindowProc함수를 통해 이 메시지를 받는다.

LRESULT CALLBACK WindowProc(

HWND hwnd, // handle to window

UINT uMsg, // message identifier

WPARAM wParam, // not used

LPARAM lParam // logoff option

);

파라미터

hwnd

윈도우의 핸들

uMsg

WM_QUERYENDSESSION의 식별자

wParam

예약되어 있는 파라미터

lParam

아래의 값들중 한개 이상이 사용될 수 있다. 만약 파라미터가 0일경우 시스템은 셧다운 되거나 재시작된다. (어떤 이벤트가 발생했는지 고려하는 것이 불가능하다)

Value	Meaning
ENDSESSION_CLOSEAPP 0x1	어플리케이션이 대체되어야할 파일을 사용하고 있거나 시스템이 서비스되고 있든지 혹은 시스템 리소스가 고갈 되었다. 자세한 정보는 Guidelines for Application을 참고 하라.
ENDSESSION_LOGOFF 0x80000000	유저가 로그오프 했다. 자세한 정보는 Logging Off를 참고 하라.

이 파라미터는 bit mask임을 기억하라. 테스트시 bit연산을 사용하며, equality 테스트 하지 말라.

lParam

파라미터가 0일 경우, 시스템은 셧다운 되거나 재시작된다. (어떤 이벤트가 발생했는지 고려하는 것이 불가능하다.)

리턴값

어플리케이션은 유저의 의향과 리턴값 TRUE를 따른다.

기본적으로 DefWindowProc함수는 이 메시지를 위해 TRUE를 리턴한다.

만약 셧 다운이 현재 씌어지고 있는 시스템이나 미디어에의해 방해 받으면 어플리케이션은 FALSE를 리턴할 수 있다. 하지만 사용자의 액션을 따르는 것이 좋다.

Remarks

어플리케이션인 TRUE를 리턴할 때 WM_ENDSESSION 메시지를 받는다. 다른 어플리케이션의 WM_QUERYENDSESSION 메시지에 대한 응답을 어떻게 할것인지 상관하지 않는다.

각각의 어플리케이션은 이 메시지를 받은 즉시 TRUE나 FALSE를 리턴한다. 그리고 WM_ENDSESSION메시지를 받을 때 까지 모든 명령의 클린업을 연기한다.

콘솔 어플리케이션은 SetConsoleCtrlHandler함수를 사용하여 셧다운 통지를 받을 수 있다.

서비스 어플리케이션은 RegisterServiceCtrlHandlerEx함수를 사용하여 핸들 루틴의 셧다운 통지를 받을 수 있다.

예제코드

Logging Off를 참고하라.

Requirements

Client	Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation, Windows Me, Windows 98, or Windows 95.
Server	Requires Windows Server "Longhorn", Windows Server 2003, Windows 2000 Server, or Windows NT Server.
Header	Declared in Winuser.h; include Windows.h.

See Also

Logging Off
Shutting Down
DefWindowProc
ExitWindows
SetProcessShutdownParameters
WM_ENDSESSION

#첨부 2

Logging Off

ExitWindows함수는 현재 사용자를 로그 오프한다. EWX_LOGOFF플래그를 명시하여ExitWindowsEx함수를 사용하는 방법도 있다.

기본적으로 어플리케이션이 ExitWindow나 ExitWindowsEx를 사용하여 로그오프 할 때, 시스템은 WM_QUERYENDSESSION메시지를 해당 윈도우로 보낸다.

어플리케이션은 이 메시지를 받을 때 TRUE의 리턴에 의해 종료를 승낙한다. 만약 한 어플리케이션이 메시지 처리 중 FALSE를 리턴 한다면, 로그 오프 명령은 취소된다.

만약 당신의 어플리케이션이 WM_QUERYENDSESSION메시지를 핸들링 한다면 비록 다른 어플리케이션이나 시스템이 세션 종료 요청을 시작한다고 해도 로그오프 명령을 취소하도록 할 수 있다. 자세한 정보는 How to log Off the Current User를 참고하라.

어플리케이션은 WM_QUERYENDSESSION을 위해 TRUE를 리턴할 때, WM_ENDSESSION메시지를 받는다. 그리고 다른 어플리케이션이 WM_QUERYENDSESSION메시지에 어떻게 응답하는가와 상관없이 그 자신은 종료된다..

Windows Me/98/95 : 모든 어플리케이션이 WM_QUERYENDSESSION에 TRUE를 리턴 한 후 WM_ENDSESSION을 받고 종료된다.

강제로 모든 어플리케이션을 종료하려면 EXW_FORCE플래그를 명시하여 ExitWindowsEx를 사용한다. 이것은 시스템이 WM_QUERYENDSESSION메시지를 방지하도록 한다.

또한 시스템은 로그오프 모든 명령간의 처리를 위해 CTRL_LOGOFF_EVENT 컨트롤 신호를 보낼 수 있다. 콘솔 어플리케이션은 메시지 처리를 위해 HandlerRoutine을 등록할 수 있다.

만약 ExitWindowsEx를 호출한 프로세스가 사용자 로그인 세션 대화창에서 수행되고 있다면

로그온 세션의 모든 프로세스는 종료된다.

먄악 ExitWindowsEx를 호출한 프로세스가 다른 로그온 세션에서 수행되고 있다면 단지 통지가 만들어지기만 한다. 고로 어떤 프로세스도 종료되지 않는다.

#첨부 3

현재 사용자를 로그오프하기(How to Log Off the Current User)

아래 코드는 ExitWindows함수를 사용하여 현재 사용자를 로그오프 하는 예이다.

// Log off the current user.

ExitWindows(0, 0);

어플리케이션이 WM_QUERYENDSESSION메시지를 받고, 다이얼로그 박스가 세션을 종료 할 것인 지의 여부를 묻는다. 사용자가 YES를 클릭하면 시스템은 사용자를 로그 오프하며, No를 클릭하면 로그오프를 취소하게 된다.

// Process the message in the window procedure.

case WM_QUERYENDSESSION:

{

int r;

r = MessageBox(NULL, "End the session?", "WM_QUERYENDSESSION", MB_YESNO);

// Return TRUE to continue, FALSE to stop.

return r == IDYES;

break;

}

See Also

Logging Off

#첨부 3

RegisterApplicationRestart

재시작을 위해 어플리케이션의 활성 인스턴스를 등록한다.

HRESULT WINAPI RegisterApplicationRestart(

PCWSTR pwzCommandline,

DWORD dwFlags

);

파라미터

pwzCommandline

[in, optional] 어플리케이션을 위한 command line을 명세한 유니코드 스트링의 포인터.

Command line에 실행명(확장자?)을 포함하지 말라(함수가 붙여준다). Command line의 맥시멈 크기는 RESTART_MAX_CMD_LINE에 명세할 수 있다. 이 파라미터는 NULL이나 빈 문자열 일수 있다.

dwFlags

[in] 이 파라미터는 0이나 1이상의 아래와 같은 값을 갖는다.

Value	Meaning
RESTART_NO_CRASH 1	어플리케이션 crash로 인해 종료된다면 프로세스를 재시작 하지 않는다.
RESTART_NO_HANG 2	어플리케이션 hang으로 인해 종료된다면 프로세스를 재시작 하지 않는다.
RESTART_NO_PATCH 4	업데이트의 설치로 인해 종료된다면 프로세스를 재시작 하지 않는다.
RESTART_NO_REBOOT 8	시스템이 재부팅 되었다면 프로세스를 재시작 하지 않는다.

리턴값

This function returns S_OK on success or one of the following error codes.

성공시 S_OK를 리턴한다. 에러 코드는 아래를 참조

E_FAIL
E_INVALIDARG

Remarks

이 함수를 호출한 어플리케이션이 crashes나 hangs이면 재 시작된다.

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in Winrecovery.h; include Windows.h.
Library	Use Kernel32.lib.
DLL	Requires Kernel32.dll.

See Also

UnregisterApplicationRestart

#첨부 4

UnregisterApplicationRestart

재시작 리스트에서 어플리케이션의 활성 인스턴스를 삭제한다.

HRESULT WINAPI UnregisterApplicationRestart(void);

Parameters

파라미터가 없다.

Return Value

성공시 S_OK를 리턴한다. 에러 코드는 아래를 참조

E_FAIL

Requirements

Client	Requires Windows Vista.
Server	Requires Windows Server "Longhorn".
Header	Declared in Winrecovery.h; include Windows.h.
Library	Use Kernel32.lib.
DLL	Requires Kernel32.dll.

See Also

RegisterApplicationRestart

#첨부 5

Shutting Down

로컬 혹은 리모트 컴퓨터의 어플리케이션을 셧다운 하는 방법은 아래의 3가지가 있다.

시스템 셧다운 (shut down the system)
시스템 재시작 (shut down the system and restart it)
어플리케이션 셧다운, 셧다운과 시스템 재시작, 그리고 리스타트를 위해 등록된 모든 어플리케이션의 재시작 (shut down the application, shut down and restart the system, and restart any applications that have been registered for restart)

시스템을 셧다운 하기 위해 EWX_SHUTDOWN 플래그가 명시된 ExitWindowsEx함수를 사용한다. 자세한 예제는 How to Shut Down the System을 참고하라.

시스템의 재시작을 위해 EWX_REBOOT플래그를 사용하고, RegisterApplicationRestart함수를 사용해 리스타트 되어지도록 등록된 모든 어플리케이션을 재시작하기 위해서는 EXW_RESTARTAPPS 플래그를 사용한다.

InitiateShutdown, InitiateSystemShutdown과 InitiateSystemShutdownEx함수는 사용자 로그오프 프롬프트를 보여주기 위한 다이얼로그와 타이머를 시작한다.

다이얼로그가 떠있는 동안 AbortSystemShutdown함수는 타이머를 멈추고 컴퓨터가 셧다운 되는 것을 방지 할 수 있다. 하지만 타이머가 expire되면 컴퓨터는 셧다운 된다. 이 함수들은 셧다운 명령에 따라서도 컴퓨터를 재시작 할 수 있다. 자세한 정보는 Displaying the Shutdown Dialog Box를 참고하라.

셧다운 통지

윈도우와 메시지큐 어플리케이션은 WM_QUERYENDSESSION과 WM_ENDSESSION메시지를 통해 셧다운 통지를 받는다. 이들 어플리케이션은 TRUE를 리턴함으로 종료할 수 있음을 가리킨다. 어플리케이션은 절대적으로 필요하지 않은 이상 시스템 셧다운을 막을 수 없다.

어플리케이션은 WM_ENDSESSION 처리 중에 요구되어진 클린업을 수행해야 한다. 저장되지 않은 데이터를 가진 어플리케이션은 temporary 위치에 데이터를 저장할 수 있고 어플리케이션이 다음 번에 시작될 때 복구 되어진다. 빈번하게 어플리케이션이 데이터나 상태정보를 저장할 것을 추천한다. 예로 셧다운시에 저장되어야 할 데이터의 양을 줄이기 위해 사용자에 의해 시작된 자동 저장과 저장 명령을 들 수 있다.(?)
콘솔 어플리케이션은 각각의 handler routines에서 셧다운 통지를 받는다. 콘솔 핸들러를 등록하기 위해 SetConsoleCtrlHandler함수를 사용한다.

서비스 어플리케이션은 각각의 handler routines에서 셧다운 통지를 받는다. 서비스 컨트롤 핸들러를 등록하기 위해 RegisterServiceCtrlHandlerEx함수를 사용한다.

셧다운 막기(Blocking Shutdown)

어플리케이션이 중요한 시스템 셧다운을 막아야 한다면 ShutdownBlockReasonCreate함수를 호출할 수 있다. 호출자는 사용자에게 디스플레이 해야 할 이유를 문자열로 제공해야 한다.

문자열은 셧다운의 결과와 계속해서 시스템을 셧다운 하기위해 필요한 정보를 가리켜야 한다.