> For the complete documentation index, see [llms.txt](https://docs.medcrypt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.medcrypt.com/ko/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-service.md). # medcrypt::guardian::Service ## 개요 연결 및 채널 구성의 이름이 지정된 그룹입니다. **사용법:** 이 클래스는 Guardian 애플리케이션에서 네트워크 연결과 통신 채널을 관리하는 데 사용됩니다. **포함:** ```cpp #include ``` **구문:** ```cpp struct medcrypt::guardian::utilities::ProvisionOnlineFiles; ``` ### 공개 함수 * [\~Service](#function-~service): 소멸자입니다. * [IsReady](#function-isready): 서비스가 작동 가능한 상태인지 확인합니다. * [IsFailed](#function-isfailed): 서비스가 실패 상태인지 확인합니다. * [Listen](#function-listen): 관리형 서버 서비스가 새 연결을 수신 대기하도록 합니다. * [ConfigureTransport](#function-configuretransport): 로드된 프로필을 기반으로 제공된 전송을 보호합니다. * [Shutdown](#function-shutdown): 포함된 모든 연결을 중지하며, 대기 중인 데이터가 전송되거나 전송에 실패할 때까지 차단됩니다. * [Start](#function-start) (재정의 없음): 연결을 시작합니다. 이 함수는 차단 방식으로 동작합니다. * [Start](#start-with-override) (재정의 사용): 제공된 재정의 문자열을 사용하여 연결을 시작합니다. 이 함수는 차단 방식으로 동작합니다. * [AsyncStart](#function-asyncstart): 연결을 시작합니다. 이 함수는 비차단 방식으로 동작합니다. * [AsyncStart](#asyncstart-with-override): 제공된 재정의 문자열을 사용하여 연결을 시작합니다. 이 함수는 비차단 방식으로 동작합니다. * [ClientWaiting](#function-clientwaiting): 연결을 기다리는 클라이언트가 있는지 확인합니다. 이 함수는 비차단 방식으로 동작합니다. ### 함수 세부 정보 #### \~Service() * **설명:** 소멸자는 내부 [Guardian](/ko/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-guardian.md) 표현에 영향을 주지 않습니다. [Service](/ko/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-service.md).. * **종속성:** 없음 - 소멸자는 자동으로 호출됩니다 * **매개변수:** 없음 - 소멸자는 매개변수를 받지 않습니다 * **반환값:** 소멸자이므로 반환값이 없습니다. * **작업:** Guardian의 내부 표현에 영향을 주지 않고 서비스 리소스를 정리합니다. * **구문:** ```cpp ~Service() ``` #### IsReady() * **설명:** 서비스가 작동 가능한 상태인지 확인합니다. * **종속성:** 서비스를 생성한 후 호출해야 합니다 * **매개변수:** 없음 * **반환값:** 서비스 준비 상태를 나타내는 부울 값 * `true` - 서비스가 구성된 작업을 수행할 준비가 되었습니다 * `false` - 서비스가 준비되지 않았거나 수신 대기 중이 아닌 서버 서비스입니다 * **조치:** * **클라이언트/비관리형 서비스의 경우:** 다음을 사용하여 새 세션을 만들 준비가 되었습니다. [Start](#function-start) 비동기적으로 실행합니다. * **서버 서비스의 경우:** 전송 계층이 수신 대기 중이며 연결을 수락할 준비가 되었습니다. * **구문:** ```cpp bool IsReady() ``` #### IsFailed() * **설명:** 수신 대기 중 기본 전송 계층에 오류가 발생했을 때 서버 서비스에 사용됩니다. 서비스가 실패 상태인지 확인합니다. * **종속성:** 전송 상태를 확인하기 위해 서버 서비스에 사용됩니다. * **매개변수:** 없음 * **반환값:** 실패 상태를 나타내는 부울 값 * `true` - 기본 서버 전송 계층에 오류가 발생했습니다. * `false` - 기본 서버 전송 계층에 오류가 발생하지 않았습니다. * **조치:** 서비스를 종료한 다음 [Listen](#function-listen) 을 다시 호출해야 합니다. * **구문:** ```cpp bool IsFailed() ``` #### Listen() * **설명:** * 관리형 서버 서비스가 새 연결을 수신 대기하도록 합니다. * 서버 소켓에서 'bind'와 'listen'을 호출하는 것과 같습니다. * 이 함수는 비관리형 서비스 또는 클라이언트 서비스에는 적용되지 않습니다. * **종속성:** 관리형 서버 서비스에만 적용됩니다. * **매개변수:** * `in_override`: 널 문자로 끝나는 전송 계층별 재정의 문자열 * **기본값:** nullptr(재정의 없음) * **반환값:** 성공 또는 실패를 나타내는 상태 코드입니다. * **성공 코드:** `OK` - 연결 수신 대기를 성공적으로 시작했습니다. * **오류 코드:** * `FAIL` - 일반 오류입니다. 연결 수신 대기를 시작하지 못했습니다. * `MISCONFIGURED` - 서비스가 비관리형 또는 클라이언트로 구성되어 있습니다. * **조치:** * 구성된 전송 계층에서 들어오는 연결의 수신 대기를 시작합니다. * **예:** zeromq 예: "tcp\://127.0.0.1:12345" * (기본값: 재정의 없음) * **함께 보기:** "Override Strings" 문서 * **구문:** ```cpp Status Listen( const char * in_override =nullptr ) ``` #### ConfigureTransport() * **설명:** * 로드된 프로필에 따라 제공된 전송 계층을 보호합니다. * 프로필 구성을 사용하여 비관리형 서비스 구성에 따라 제공된 전송 계층을 보호하거나 인증을 활성화합니다. * **종속성:** 전송 구성이 포함된 프로필을 로드해야 합니다 * **매개변수:** * `in_transport`: 구성할 전송 * **반환값:** 성공 또는 실패를 나타내는 상태 코드입니다. * **성공 코드:** `OK` - 제공된 전송을 성공적으로 구성했습니다 * **오류 코드:** * `FAIL` - 일반 오류입니다. 전송이 구성되지 않았습니다 * `BADPARAM` - `in_transport` 이 비어 있습니다 * `MISCONFIGURED` - 이 프로필은 이 서비스에서 전송 구성을 지원하지 않습니다 * `HANDSHAKEREQUIRED` - 현재 CertificateManager에 필요한 키 또는 신뢰 정보가 없습니다 * **관련 문서:** "Unmanaged Handshaking" 문서 * **작업:** 프로필의 보안 구성을 제공된 전송에 적용합니다. * **관련 문서:** "Unmanaged Handshaking" 문서. * **구문:** ```cpp Status ConfigureTransport( std::shared_ptr< TransportInterface > in_transport ) ``` #### Shutdown() * **설명:** * 포함된 모든 연결을 중지하고, 대기 중인 데이터를 전송하거나 전송 실패 처리할 때까지 대기합니다. * 다른 스레드에서 실행하도록 배치한 항목을 포함해 모든 세션, 연결 및 채널을 포함합니다. [CreateTask](/ko/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-guardian.md#function-createtask). * **종속성:** 활성 서비스에서 호출할 수 있습니다 * **매개변수:** * `in_force`: 제한 시간이 지난 후(또는 제한 시간이 0이면 즉시) 대기 중인 데이터를 모두 버리고 종료합니다. * **기본값:** `false` * **반환값:** 성공 또는 실패를 나타내는 상태 코드입니다. * **성공 코드:** `OK` - 서비스가 종료되었습니다 * **오류 코드:** * `FAIL` - 일반 오류입니다. 로그를 확인하세요. * `AGAIN` - 하나 이상의 전송에 전송 대기 중인 데이터가 있습니다 * **작업:** 포함된 모든 연결을 중지하고 리소스를 정리합니다. * **구문:** ```cpp Status Shutdown( const bool & in_force =false ) ``` #### Start(): 재정의 없음 * **설명:** * 블로킹 호출을 통해 연결을 시작합니다. * 동작은 서비스 유형에 따라 다릅니다. * **관리형:** * **클라이언트 서비스:** 연결이 성공하거나 실패할 때까지 대기합니다. * **서버 서비스:** 클라이언트가 연결할 때까지 대기합니다. * **비관리형 서비스:** 전송 구성이 필요하지만 전송이 제공되지 않은 경우를 제외하고 항상 성공합니다. * **종속성:** 서비스가 준비되어 있고 올바르게 구성되어 있어야 합니다 * **매개변수:** * `out_session`: 성공 시 결과 세션이 포인터에 저장됩니다 * **반환값:** 성공 또는 실패를 나타내는 상태 코드입니다. * **성공 코드:** `OK` - 연결을 성공적으로 시작했습니다 * **오류 코드:** * `FAIL` - 엔드포인트에 연결할 수 없거나 서버 서비스가 종료되었습니다 * `BADPARAM` - `out_session` 이 null 포인터입니다 * `MISCONFIGURED` - 연결을 생성하기에 프로필 데이터가 부족합니다 * **작업:** 연결을 생성하고 설정한 후 세션 객체를 반환합니다. * **구문:** ```cpp Status Start( std::unique_ptr< Session > * out_session ) ``` #### Start(): 재정의 문자열 사용 * **설명:** * 제공된 재정의 문자열을 사용하여 연결을 생성하는 블로킹 호출입니다. * 서버 서비스에는 적용되지 않습니다. * **종속성:** 서비스가 재정의 문자열을 지원해야 합니다 * **매개변수:** * `in_override`: null로 종료되는 전송 방식별 재정의 문자열 * `out_session`: 성공 시 결과 세션이 포인터에 저장됩니다 * **반환값:** 성공 또는 실패를 나타내는 상태 코드입니다. * **성공 코드:** `OK` - 연결을 성공적으로 시작했습니다 * **오류 코드:** * `FAIL` - 엔드포인트에 연결할 수 없거나 서버 서비스가 종료되었습니다 * `BADPARAM` - out\_session이 null 포인터입니다 * `MISCONFIGURED` - 프로필 데이터가 부족하거나 관리되지 않는 연결에 구성된 전송 방식이 필요합니다 * `DENIED` - 서버 서비스이므로 재정의할 수 없습니다 * **참조:** 전체 참조는 모든 상태 코드를 확인하세요 * **작업:** 사용자 지정 전송 매개변수를 사용하여 연결을 생성합니다. * **구문:** ```cpp Status Start( const char * in_override, std::unique_ptr< Session > * out_session ) ``` 제공된 재정의 문자열을 사용하여 연결을 시작합니다(블로킹). **매개변수**: * **in\_override** null로 종료되는 전송 방식별 재정의 문자열입니다. "Override Strings" 문서를 참조하세요. zeromq 예: "tcp\://127.0.0.1:12345". 기본값은 재정의를 사용하지 않는 것입니다 * **out\_session** 성공 시 이 포인터에 결과 세션이 저장됩니다 **반환값**: * **OK** 연결을 성공적으로 시작했습니다 * **FAIL** 엔드포인트에 연결할 수 없거나 서버 서비스가 종료되었습니다 * **BADPARAM** out\_session이 nullptr입니다 * **MISCONFIGURED** 연결을 생성하기에 프로필 데이터가 부족하거나 관리되지 않는 연결에 구성된 전송 방식이 필요합니다 * **거부됨** 서버 서비스이므로 재정의할 수 없습니다. **반환값**: [medcrypt::guardian::Status](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) 연결을 생성하는 차단 호출입니다. 관리형: 클라이언트: 연결에 성공하거나 실패할 때까지 대기합니다. 서버: 해당 없음. 비관리형: 로드된 프로필에서 구성된 전송을 요구하지만 전송이 제공되지 않은 경우를 제외하면 이 호출은 항상 성공합니다. #### AsyncStart() * **설명:** 연결을 생성하는 비차단 호출입니다. 클라이언트 서비스는 연결 프로세스가 시작되면 반환합니다. 서버 서비스는 대기 중인 클라이언트가 있으면 해당 클라이언트를 반환합니다. 비관리형 서비스에서는 Start()와 동일합니다. * **종속성:** 서비스가 연결을 받을 준비가 되어 있어야 합니다. * **매개변수:** * `out_session`: 성공 시 결과 세션이 포인터에 저장됩니다 * **반환값:** 성공 또는 실패를 나타내는 상태 코드입니다. * **성공 코드:** `OK` - 연결 프로세스가 성공적으로 시작되었습니다. * **오류 코드:** * `FAIL` - 엔드포인트에 연결할 수 없습니다. * `BADPARAM` - out\_session이 null 포인터입니다 * `MISCONFIGURED` - 연결을 생성하기에 프로필 데이터가 부족합니다 * `AGAIN` - 서버에만 해당: 연결을 기다리는 클라이언트가 없습니다. * **참조:** 전체 참조는 모든 상태 코드를 확인하세요 * **작업:** 차단 없이 연결 프로세스를 시작합니다. * **구문:** #### AsyncStart() - 재정의 사용 * **설명:** 재정의 문자열을 사용해 연결을 생성하는 비차단 호출입니다. 이미 수신 대기 중인 서버 서비스에는 해당하지 않습니다. * **종속성:** 서비스가 재정의를 지원해야 하며, 수신 대기 중인 서버가 아니어야 합니다. * **매개변수:** * `in_override`: null로 종료되는 전송 방식별 재정의 문자열 * `out_session`: 성공 시 결과 세션이 포인터에 저장됩니다 * **반환값:** 성공 또는 실패를 나타내는 상태 코드입니다. * **성공 코드:** `OK` - 연결을 성공적으로 시작했습니다 * **오류 코드:** * `FAIL` - 엔드포인트에 연결할 수 없습니다. * `BADPARAM` - out\_session이 null 포인터입니다 * `MISCONFIGURED` - 연결을 생성하기에 프로필 데이터가 부족합니다 * `DENIED` - 서버 서비스가 이미 수신 대기 중이므로 재정의할 수 없습니다. * `AGAIN` - 서버에만 해당: 연결을 기다리는 클라이언트가 없습니다. * **참조:** 전체 참조는 모든 상태 코드를 확인하세요 * **작업:** 차단 없이 사용자 지정 매개변수로 연결을 시작합니다. **구문:** #### ClientWaiting() * **설명:** 클라이언트가 연결을 기다리고 있는지 확인합니다(비차단). 클라이언트 서비스에서는 항상 false를 반환합니다. * **종속성:** 서버 서비스에만 해당합니다. * **매개변수:** 없음 * **반환값:** 클라이언트 사용 가능 여부를 나타내는 불리언 값 * `true` - 대기 중인 클라이언트가 있습니다. * `false` - 대기 중인 클라이언트가 없거나 클라이언트 서비스입니다. * **작업:** true이면 AsyncStart()가 성공하고 Start()가 차단되지 않습니다. * **구문:** | | 이름 | | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | |

\~Service()
소멸자입니다.

| | bool |

IsReady()
서비스가 작업을 수행할 준비가 되었는지 확인합니다.

| | bool |

IsFailed()
서비스가 실패 상태인지 확인합니다.

| | [상태](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

Listen(const char \* in\_override =nullptr)
관리형 서버 서비스가 새 연결을 수신 대기하도록 합니다.

| | [상태](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

ConfigureTransport(std::shared\_ptr< TransportInterface > in\_transport)
로드된 프로필을 기반으로 제공된 전송을 보호합니다.

| | [상태](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

Shutdown(const bool & in\_force =false)
포함된 모든 연결을 중지하고, 대기열에 있는 데이터를 전송하거나 전송에 실패할 때까지 대기합니다.

| | [상태](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

Start(std::unique\_ptr< Session > \* out\_session)
연결을 시작합니다(블로킹 방식).

| | [상태](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

Start(const char in\_override, std::unique\_ptr< Session > out\_session)
제공된 재정의 문자열을 사용하여 연결을 시작합니다(블로킹 방식).

| | [상태](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

AsyncStart(std::unique\_ptr< Session > \* out\_session)
연결을 시작합니다(논블로킹 방식).

| | [상태](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) |

AsyncStart(const char in\_override, std::unique\_ptr< Session > out\_session)
제공된 재정의 문자열을 사용하여 연결을 시작합니다(논블로킹 방식).

| | bool |

ClientWaiting()
연결을 기다리는 클라이언트가 있는지 확인합니다(논블로킹 방식).

| ## 공개 함수 문서 ### 함수 Start ```cpp Status Start( std::unique_ptr< Session > * out_session ) ``` 연결을 시작합니다(블로킹 방식). **매개변수**: * **out\_session** 성공 시 이 포인터에 결과 세션이 저장됩니다 **반환값**: * **OK** 연결을 성공적으로 시작했습니다 * **FAIL** 엔드포인트에 연결할 수 없거나 서버 서비스가 종료되었습니다 * **BADPARAM** out\_session이 nullptr입니다 * **MISCONFIGURED** 프로필의 연결 생성에 필요한 데이터가 부족합니다 **반환값**: [medcrypt::guardian::Status](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) 연결을 생성하는 블로킹 호출입니다. 관리형: 클라이언트: 연결에 성공하거나 실패할 때까지 대기합니다. 서버: 클라이언트가 연결할 때까지 대기합니다. 비관리형: 로드된 프로필에서 구성된 전송을 요구하지만 전송이 제공되지 않은 경우를 제외하면 이 호출은 항상 성공합니다. ### 함수 Start ```cpp Status Start( const char * in_override, std::unique_ptr< Session > * out_session ) ``` 제공된 재정의 문자열을 사용하여 연결을 시작합니다(블로킹). **매개변수**: * **in\_override** null로 종료되는 전송 방식별 재정의 문자열입니다. "Override Strings" 문서를 참조하세요. zeromq 예: "tcp\://127.0.0.1:12345". 기본값은 재정의를 사용하지 않는 것입니다 * **out\_session** 성공 시 이 포인터에 결과 세션이 저장됩니다 **반환값**: * **OK** 연결을 성공적으로 시작했습니다 * **FAIL** 엔드포인트에 연결할 수 없거나 서버 서비스가 종료되었습니다 * **BADPARAM** out\_session이 nullptr입니다 * **MISCONFIGURED** 연결을 생성하기에 프로필 데이터가 부족하거나 관리되지 않는 연결에 구성된 전송 방식이 필요합니다 * **거부됨** 서버 서비스이므로 재정의할 수 없습니다. **반환값**: [medcrypt::guardian::Status](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) 연결을 생성하는 차단 호출입니다. 관리형: 클라이언트: 연결에 성공하거나 실패할 때까지 대기합니다. 서버: 해당 없음. 비관리형: 로드된 프로필에서 구성된 전송을 요구하지만 전송이 제공되지 않은 경우를 제외하면 이 호출은 항상 성공합니다. ### 함수 AsyncStart ```cpp 상태 AsyncStart( std::unique_ptr< Session > * out_session ) ``` 연결을 시작합니다(논블로킹 방식). **매개변수**: * **out\_session** 성공 시 이 포인터에 결과 세션이 저장됩니다 **반환값**: * **OK** 연결 프로세스가 성공적으로 시작되었습니다 * **FAIL** 엔드포인트에 연결할 수 없습니다 * **BADPARAM** out\_session이 nullptr로 설정되었습니다 * **MISCONFIGURED** 프로필의 연결 생성에 필요한 데이터가 부족합니다 * **AGAIN** 서버 전용이며, 연결을 기다리는 클라이언트가 없습니다. 다시 시도하세요. **반환값**: [medcrypt::guardian::Status](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) 연결을 생성하는 논블로킹 호출입니다. 관리형: 클라이언트: 하위 연결 프로세스가 시작되거나 실패하면 반환합니다. 서버: 사용 가능한 대기 중인 클라이언트 연결을 반환합니다. 비관리형: Start를 호출하는 것과 같습니다. ### 함수 AsyncStart ```cpp 상태 AsyncStart( const char * in_override, std::unique_ptr< Session > * out_session ) ``` 제공된 재정의 문자열을 사용하여 연결을 시작합니다(논블로킹 방식). **매개변수**: * **in\_override** null로 종료되는 전송 방식별 재정의 문자열입니다. "Override Strings" 문서를 참조하세요. zeromq 예: "tcp\://127.0.0.1:12345". 기본값은 재정의를 사용하지 않는 것입니다 * **out\_session** 성공 시 이 포인터에 결과 세션이 저장됩니다 **반환값**: * **OK** 연결을 성공적으로 시작했습니다 * **FAIL** 엔드포인트에 연결할 수 없습니다 * **BADPARAM** out\_session이 nullptr로 설정되었습니다 * **MISCONFIGURED** 프로필의 연결 생성에 필요한 데이터가 부족합니다 * **DENIED** 이미 수신 대기 중인 서버 서비스이므로 재정의할 수 없습니다 * **AGAIN** 서버 전용이며, 연결을 기다리는 클라이언트가 없습니다. 다시 시도하세요. **반환값**: [medcrypt::guardian::Status](/ko/guardian/api-overview/api-reference/namespaces/namespacemedcrypt-guardian.md#typedef-status) 연결을 생성하는 논블로킹 호출입니다. 관리형: 클라이언트: 하위 연결 프로세스가 시작되거나 실패하면 반환합니다. 서버: 해당 없음. 비관리형: Start를 호출하는 것과 같습니다. ### 함수 ClientWaiting ```cpp bool ClientWaiting() ``` 연결을 기다리는 클라이언트가 있는지 확인합니다(논블로킹 방식). **매개변수**: * **없음** **반환값**: * **true** 대기 중인 클라이언트가 있습니다 * **false** 대기 중인 클라이언트가 없거나 클라이언트 서비스입니다 **반환값**: bool true이면 비동기 시작이 성공하고 Start가 차단되지 않습니다. 클라이언트 서비스의 경우 항상 false를 반환합니다. ## 디버깅 및 로깅 Guardian은 로그 파일을 생성하지 않습니다. 대신 로깅은 애플리케이션에서 제어합니다. * Guardian은 로그를 다음으로 출력합니다: `stdout` 및 `stderr`이러한 로그는 실행 중인 애플리케이션의 터미널/CLI에 표시됩니다. 출력에서 특정 오류 코드나 연결 실패를 확인하세요. * **사용자 지정 로깅:** 다음을 사용하여 `SetLoggingCallback` 로그 메시지를 콜백 함수로 리디렉션할 수 있습니다. 이렇게 하면 터미널 출력이 중단되고 사용자 지정 로그 처리가 가능해집니다. * **로그 제어:** 애플리케이션에서 로그 수준과 상세도를 제어할 수 있습니다. * **Guardian Cloud UI**: Guardian Cloud 인터페이스에서 추가 오류 세부 정보와 프로비저닝 상태를 확인하세요. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.medcrypt.com/ko/guardian/api-overview/api-reference/classes/classmedcrypt-guardian-service.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.