# 프로세스 제어 관련 서비스

 본 서비스는 시스템에서 실행 중인 특정 프로세스 또는 특정 프로세스의 창을 조작하기 위한 기능을 지원합니다.

## 서비스 리스트

 프로세스 제어 관련 서비스 리스트는 다음과 같습니다.

<table border="1" id="bkmrk-no.-%EC%84%9C%EB%B9%84%EC%8A%A4%EB%AA%85-api%EB%AA%85-%EB%B9%84%EA%B3%A0-1-%EC%97%B0" style="border-collapse: collapse; width: 100%; height: 178.781px;"><colgroup><col style="width: 7.03218%;"></col><col style="width: 31.4631%;"></col><col style="width: 31.469%;"></col><col style="width: 30.0358%;"></col></colgroup><thead><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">**No.**</td><td class="align-center" style="height: 29.7969px;">**서비스명**</td><td class="align-center" style="height: 29.7969px;">**API명**</td><td class="align-center" style="height: 29.7969px;">비고</td></tr></thead><tbody><tr><td class="align-center">1</td><td>타이틀 기반 프로세스 구동 체크</td><td>CheckProcessRunningByTitle</td><td>  
</td></tr><tr><td class="align-center">2</td><td>PID 기반 프로세스 구동 체크</td><td>CheckProcessRunningByPID</td><td>  
</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">3</td><td>타이틀 기반 특정 프로세스 창 이동</td><td>SetWindowPosition</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">4</td><td>타이틀 기반 특정 프로세스 창 최상단 배치</td><td>BringWindowToTop</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">5</td><td>PID 기반 특정 프로세스 창 이동</td><td>SetProcessWindowPosition</td><td style="height: 29.7969px;">  
</td></tr><tr><td class="align-center">6</td><td>프로세스 IME 모드 변경</td><td>WinInfo.SetImeMode</td><td>  
</td></tr></tbody></table>

## 서비스 상태 코드 리스트

 본 서비스에서 공통으로 사용되는 서비스 상태코드 리스트에 대해 정의합니다.

 이 상태 코드는 응답 JSON 메시지 중 *return* 또는 *returnValue*의 값에 해당합니다.

<table border="1" id="bkmrk-%EB%A6%AC%ED%84%B4%EC%BD%94%EB%93%9C-%EB%A6%AC%ED%84%B4-%EC%BD%94%EB%93%9C-%EB%82%B4%EC%9A%A9-%EB%8C%80%EC%83%81-%EC%84%9C%EB%B9%84%EC%8A%A4-3" style="border-collapse: collapse; width: 100%; height: 475.141px;"><colgroup><col style="width: 8.70083%;"></col><col style="width: 37.5526%;"></col><col style="width: 30.8621%;"></col><col style="width: 23.0036%;"></col></colgroup><thead><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">**리턴코드**</td><td class="align-center" style="height: 29.7969px;">**리턴 코드 내용**</td><td class="align-center" style="height: 29.7969px;">**대상 서비스**</td><td class="align-center" style="height: 29.7969px;">**비고**</td></tr></thead><tbody><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">-1</td><td style="height: 29.7969px;">정의되지 않은 예외</td><td style="height: 29.7969px;">공통</td><td style="height: 29.7969px;">Log 파일에서 내용 확인 필요</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">0</td><td style="height: 29.7969px;">정상</td><td style="height: 29.7969px;">공통</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 46.5938px;"><td class="align-center" style="height: 46.5938px;">2</td><td style="height: 46.5938px;">PC와 연결된 모니터 리스트 획득 실패</td><td style="height: 46.5938px;">SetWindowPosition,

SetProcessWindowPosition

</td><td style="height: 46.5938px;">-</td></tr><tr style="height: 46.5938px;"><td class="align-center" style="height: 46.5938px;">3</td><td style="height: 46.5938px;">요청 모니터 정보 획득 실패</td><td style="height: 46.5938px;">SetWindowPosition,

SetProcessWindowPosition

</td><td style="height: 46.5938px;">-</td></tr><tr style="height: 46.5938px;"><td class="align-center" style="height: 46.5938px;">4</td><td style="height: 46.5938px; text-align: justify;">모니터 해상도 획득 실패</td><td style="height: 46.5938px;">SetWindowPosition,

SetProcessWindowPosition

</td><td style="height: 46.5938px;">-</td></tr><tr style="height: 46.5938px;"><td class="align-center" style="height: 46.5938px;">5</td><td style="height: 46.5938px;">지원하지 않는 창 크기 설정 옵션</td><td style="height: 46.5938px;">SetWindowPosition,

SetProcessWindowPosition

</td><td style="height: 46.5938px;">-</td></tr><tr style="height: 80.1875px;"><td class="align-center" style="height: 80.1875px;">6</td><td style="height: 80.1875px;">대상 타이틀을 가진 프로세스가 없음</td><td style="height: 80.1875px;">SetWindowPosition,

BringWindowToTop,

SetProcessWindowPosition,

SetImeMode

</td><td style="height: 80.1875px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">16</td><td style="height: 29.7969px;">지원되지 않는 프로세스</td><td style="height: 29.7969px;">SetImeMode, GetImeMode

</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">17</td><td style="height: 29.7969px;">IME 접근 권한이 없는 프로세스</td><td style="height: 29.7969px;">SetImeMode, GetImeMode

</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">18</td><td style="height: 29.7969px;">IME 핸들 획득 실패</td><td style="height: 29.7969px;">SetImeMode, GetImeMode

</td><td style="height: 29.7969px;">-</td></tr><tr style="height: 29.7969px;"><td class="align-center" style="height: 29.7969px;">19</td><td style="height: 29.7969px;">IME 변경 실패</td><td style="height: 29.7969px;">SetImeMode, GetImeMode

</td><td style="height: 29.7969px;">-</td></tr></tbody></table>

## 1. 타이틀 기반 프로세스 구동 체크

**API명**

- WinInfo.CheckProcessRunningByTitle

**정의**

- 타이틀을 기반으로 특정 프로세스가 현재 구동 중인지 확인합니다.

**호출예시**

```json
{
  "service":"WinInfo.CheckProcessRunningByTitle",
  "requestKey":"Random Request Key",
  "param":{ 
    "processTitle":"TOMATO SYSTEM"
  }
}
```

- processTitle 
    - 검색할 프로세스 타이틀.

**응답예시**

```json
{
  "service":"WinInfo.CheckProcessRunningByTitle",
  "requestKey":"976a-75cf-5b52",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "isRunning":true
  }
}
```

- returnValue 
    - 서비스 상태 코드.
- isRunning: 프로세스 구동 여부 
    - true: 구동 중.
    - false: 구동 중이지 않음.

## 2. PID 기반 프로세스 구동 체크

**API명**

- WinInfo.CheckProcessRunningByPID

**정의**

- 프로세스 ID(PID)를 기반으로 특정 프로세스가 현재 구동 중인지 확인합니다.

**호출예시**

```json
{
  "service": "WinInfo.CheckProcessRunningByPID",
  "requestKey": "Random Request Key",
  "param": { 
    "processId": "28700"
  }
}
```

- processId 
    - 검색할 프로세스 ID(PID).

**응답예시**

```json
{
  "service":"WinInfo.CheckProcessRunningByTitle",
  "requestKey":"976a-75cf-5b52",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "isRunning":true
  }
}
```

- returnValue 
    - 서비스 상태 코드.
- isRunning: 프로세스 구동 여부 
    - true: 구동 중.
    - false: 구동 중이지 않음.

## 3. 타이틀 기반 특정 프로세스 창 이동

**API명**

- WinInfo.SetWindowPosition

**정의**

- 특정 타이틀을 가지는 프로세스의 창(Window)을 특정 모니터의 특정 좌표(left, top)으로 이동합니다.

<p class="callout success">모니터와 관련된 정보는 *"모니터 관련 서비스"* 문서를 참고하시길 바랍니다.</p>

**설명**

- 시스템은 모니터와, 프로세스 창의 좌표 및 해상도를 다음과 같이 식별합니다.

[![K-018.png](https://bookstack.tomatosystem.co.kr/uploads/images/gallery/2025-12/scaled-1680-/k-018.png)](https://bookstack.tomatosystem.co.kr/uploads/images/gallery/2025-12/k-018.png)

**&lt;Windows 모니터 및 프로세스 창 해상도 식별 방식&gt;**

**호출예시**

```json
{
  "service": "WinInfo.SetWindowPosition",
  "requestKey": "Random Request Key",
  "param": { 
    "processTitle": "TOMATOSYSTEM",
    "screenIndex": 1,
    "screenSizeMode": 1,
    "left": 0,
    "top": 0,
    "width": 900,
    "height": 800
  }
}

```

- processTitle 
    - 검색할 프로세스 창의 타이틀.
- screenIndex 
    - 프로세스 창을 이동 시킬 모니터 인덱스
    - 시스템이 인식하는 모니터 명칭에서 숫자 값. (예: DISPLAY4 → 4)
- screenSizeMode: 창의 표시 상태. 
    - 1: 일반 모드 (left, top, width, height 지정 가능)
    - 2: 창 최대화 (left, top, width, height 지정 불가)
    - 3: 창 최소화 (left, top, width, height 지정 불가)
- left 
    - 창을 이동 시킬 좌측 좌표 값.
    - 창을 이동 시킬 모니터의 left ~ (left + 모니터 width) 범위 내의 값을 입력.
    - screenSizeMode가 2 또는 3인 경우 0 입력.
- top 
    - 창을 이동 시킬 상단 좌표 값.
    - 창을 이동 시킬 모니터의 top ~ (top + 모니터 height) 범위 내의 값을 입력.
    - screenSizeMode가 2 또는 3인 경우 0 입력.
- width 
    - 창의 가로 길이.
- height 
    - 창의 세로 길이.

**응답예시**

```json
{
  "service":"WinInfo.SetWindowPosition",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}
```

- return 
    - 서비스 상태 코드.

## 4. 타이틀 기반 특정 프로세스 창 최상단 배치

**API명**

- WinInfo.BringWindowToTop

**정의**

- 특정 타이틀을 가지는 프로세스의 창(Window)을 모든 창 중 가장 최상단으로 위치 시킵니다.

**호출예시**

```json
{
  "service": "WinInfo.BringWindowToTop",
  "requestKey": "Random Request Key",
  "param": { 
    "processTitle": "TOMATOSYSTEM"
  }
}
```

- processTitle 
    - 검색할 프로세스의 타이틀.

**응답예시**

```json
{
  "service":"WinInfo.BringWindowToTop",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}
```

## 5. PID 기반 특정 프로세스 창 이동

**API명**

- WinInfo.SetProcessWindowPosition

**정의**

- 특정 프로세스 ID(PID)를 가지는 프로세스의 창(Window)을 특정 모니터의 특정 좌표(left, top)으로 이동합니다.

<p class="callout success">모니터와 관련된 정보는 *"모니터 관련 서비스"* 문서를 참고하시길 바랍니다.</p>

**설명**

- 시스템은 모니터와, 프로세스 창의 좌표 및 해상도를 다음과 같이 식별합니다.

[![K-018.png](https://bookstack.tomatosystem.co.kr/uploads/images/gallery/2025-12/scaled-1680-/k-018.png)](https://bookstack.tomatosystem.co.kr/uploads/images/gallery/2025-12/k-018.png)

**&lt;Windows 모니터 및 프로세스 창 해상도 식별 방식&gt;**

**호출예시**

```json
{
  "service": "WinInfo.SetProcessWindowPosition",
  "requestKey": "Random Request Key",
  "param": { 
    "processId": "28700",
    "screenIndex": 1,
    "screenSizeMode": 1,
    "left": 0,
    "top": 0,
    "width": 900,
    "height": 800
  }
}

```

- processId 
    - 검색할 프로세스 ID.
- screenIndex 
    - 프로세스 창을 이동 시킬 모니터 인덱스
    - 시스템이 인식하는 모니터 명칭에서 숫자 값. (예: DISPLAY4 → 4)
- screenSizeMode: 창의 표시 상태. 
    - 1: 일반 모드 (left, top, width, height 지정 가능)
    - 2: 창 최대화 (left, top, width, height 지정 불가)
    - 3: 창 최소화 (left, top, width, height 지정 불가)
- left 
    - 창을 이동 시킬 좌측 좌표 값.
    - 창을 이동 시킬 모니터의 left ~ (left + 모니터 width) 범위 내의 값을 입력.
    - screenSizeMode가 2 또는 3인 경우 0 입력.
- top 
    - 창을 이동 시킬 상단 좌표 값.
    - 창을 이동 시킬 모니터의 top ~ (top + 모니터 height) 범위 내의 값을 입력.
    - screenSizeMode가 2 또는 3인 경우 0 입력.
- width 
    - 창의 가로 길이.
- height 
    - 창의 세로 길이.

**응답예시**

```json
{
  "service":"WinInfo.SetProcessWindowPosition",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}
```

- return 
    - 서비스 상태 코드.

## 6. 프로세스 IME 모드 변경

**API명**

- WinInfo.SetImeMode

**정의**

- 대상 프로세스의 IME 모드를 변경한다.
- 현재 테스트를 위해 다음 브라우저만 허용. 
    - "chrome", "msedge", "whale", "firefox", "iexplore", "opera"
- IME Mode는 입력 가능한 입력기(textbox, textarea 등)에 focus가 가 있어야 변경 가능하다.

**호출예시**

```json
{
  "service": "WinInfo.SetImeMode",
  "requestKey": "Random Request Key",
  "param": { 
    "toNative": true
  }
}
```

- toNative: IME 입력기에 설정된 원어로 변경할지 여부. (ex. 한국어 입력기에서 원어: "한글") 
    - true: 원어로 설정한다.
    - false: 영어로 설정한다.

**응답예시**

```json
{
  "service":"WinInfo.SetImeMode",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":0
}
```

- return 
    - 서비스 상태 코드.

## 7. 프로세스 IME 모드 획득

**API명**

- WinInfo.GetImeMode

**정의**

- 대상 프로세스에 현재 설정된 IME 모드를 획득한다.
- 현재 테스트를 위해 다음 브라우저만 허용. 
    - "chrome", "msedge", "whale", "firefox", "iexplore", "opera"
- IME Mode는 입력 가능한 입력기(textbox, textarea 등)에 focus가 가 있어야 획득 가능하다.

**호출예시**

```json
{
  "service": "WinInfo.GetImeMode",
  "requestKey": "Random Request Key",
  "param": {}
}
```

**응답예시**

```json
{
  "service":"WinInfo.GetImeMode",
  "requestKey":"호출시 사용한 Request Key",
  "statusCode":"0000",
  "return":{
    "returnValue":0,
    "isNative":true
  }
}
```

- return 
    - 서비스 상태 코드.
- isNative: IME 입력기에 설정된 언어 정보. (ex. 한국어 입력기에서 원어: "한글") 
    - true: 원어로 설정되어 있음.
    - false: 영어로 설정되어 있음.