> For the complete documentation index, see [llms.txt](https://docs.proudnet.com/proudnet.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.proudnet.com/proudnet.cn/proudnet/using_pn/pidl/using_pidl.md).

# 如何使用PIDL

## 使用Custom Build Rules

> <mark style="color:orange;">Display Name</mark> : 這是將在自訂建置規則中顯示的名稱。 例如) PIDL 規則\ <mark style="color:orange;">File Name</mark> : 建立規則檔名。 例如）PIDL\_Custom\_Build\_Rule\ <mark style="color:orange;">Directory</mark> : 指定規則檔案的儲存位置。 例如) C:\XXX\YYY

<figure><img src="/files/7l8imOJlfAtIIWKEQ0kp" alt=""><figcaption><p>Custom Build Rule 設置</p></figcaption></figure>

各項設定的詳細資訊如下。

```
Additional Dependencies : ..\..\..\util\PIDL.exe
Batching Separator :
Command Line : ..\..\..\util\PIDL.exe "$(InputPath)" -outdir .\
Display Name : PIDL
Execution Description : Compiling $(InputName).pidl ...
File Extensions : *.pidl
Name : PIDL Custom Build Rule
Outputs : $(InputDir)\$(InputName)_common.cpp;$(InputDir)\$(InputName)_common.h;$(InputDir)\$(InputName)_proxy.cpp;$(InputDir)\$(InputName)_proxy.h;$(InputDir)\$(InputName)_stub.cpp;$(InputDir)\$(InputName)_stub.h
```

完成設定後，在自訂建置規則中新增一條PIDL建置規則，如下所示。

<figure><img src="/files/CKjFYMzqr81Rn0kiailm" alt=""><figcaption><p>Custom Build Rules</p></figcaption></figure>

如果您檢查新建立的規則文件並在專案中建立文件，您將看到 PIDL 被自動選擇為建置工具。

## 使用命令提示字元(Command Prompt, cmd.exe)&#x20;

如果 PIDL AddOn 或自訂建置規則不可用，您可以透過 Windows 作業系統上的命令提示字元進行編譯。

<figure><img src="/files/n3yrP4lhzREeEAhib0ok" alt=""><figcaption></figcaption></figure>

對於cs，可以透過新增PIDL -cs命令來編譯。

<figure><img src="/files/0HHaYjVozdEmT0EYskG4" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}

* <mark style="color:orange;">PIDL.exe</mark>位於ProudNet安裝路徑的<mark style="color:orange;">util</mark>資料夾中。
* Debug, Release必須設定相同。
* 不要依照範例寫<mark style="color:orange;">PIDL.exe</mark>的路徑，而是設定為ProudNet安裝路徑的PIDL。
  {% endhint %}

{% hint style="warning" %}

* 在此範例中，建立了 Common - PIDL 資料夾並將其指定為 PIDL 編譯路徑 (outdir)。
* 請不要遵循包含路徑，而是指定您正在使用的項目所需的路徑。
  {% endhint %}

<figure><img src="/files/OpS6J3Umep0N5iLdXi2j" alt=""><figcaption><p>Common - 使用 PIDL 設定 outdir 後，將其設定為附加包含目錄。</p></figcaption></figure>

您可以透過檢查產生的來源檔案（將它們包含在 Visual Studio 專案屬性視窗中，然後建置）來使用它。

## 使用Customizations

{% hint style="info" %}
**Visual Stuido 2005, 2008 版本**

* 可以使用[**Custom Build Rules**](#custom-build-rules)建立規則檔案。
* 1 個副檔名為 <mark style="color:orange;">.rules</mark> 的規則文件
  {% endhint %}

{% hint style="info" %}
**Visual Studio 2010 或更高版本**

* 可以使用/不能使用[**Custom Build Rules**](#custom-build-rules)創建
* 需要三個檔案：<mark style="color:orange;">.props</mark>, <mark style="color:orange;">.targets</mark>, <mark style="color:orange;">.xml</mark>。 先前版本中建立的<mark style="color:orange;">.rules</mark> 檔案不能按原樣使用。
  {% endhint %}

> **2種使用customizations的方法**
>
> 1\. 在 Visual Studio 2005 或 2008 中建立專案後，建立 <mark style="color:orange;">.rules</mark> 檔案並將其設定為使用，然後將專案轉換為 2010 或更高版本的方法\
> : 轉換專案時，<mark style="color:orange;">.rules</mark> 檔案會自動轉換為 <mark style="color:orange;">.props</mark>, <mark style="color:orange;">.targets</mark>, <mark style="color:orange;">.xml</mark>。<br>
>
> 2\. 生成<mark style="color:orange;">.props</mark>, <mark style="color:orange;">.targets</mark>, <mark style="color:orange;">.xml</mark>文件後直接編寫xml代碼使用的方法

Visual Studio 2005、2008和Visual Studio 2010之後的版本具有不同的定義宏觀。\
如果該規則未以Visual Studio 2010後版本中使用的宏觀編寫，則轉換前應將其轉換爲Visual Studio 2010後版本中使用的宏觀，或轉換後分別修改<mark style="color:orange;">.props</mark>, <mark style="color:orange;">.targets</mark>, <mark style="color:orange;">.xml</mark>。

## 在 PIDL 內容中使用include或import

開發程序時，有時想要在<mark style="color:orange;">.pidl</mark>文件中加入include或import語句。

```
#include "a/b/c.h"
 
class MyStub // PIDL 編譯輸出
{
    ...
}
```

為此，請在 PIDL 內容中使用以下內容：

{% tabs %}
{% tab title="C++" %}

```cpp
#include "a/b/c.h" 
// for C++ language. semicolon is mandatory!
```

{% endtab %}

{% tab title="Java" %}

```java
import com.mycompany.mygame; // for Java
```

{% endtab %}
{% endtabs %}

## 編組

{% tabs %}
{% tab title="C++" %}

#### 在 RMI 中使用自訂類別類型

```cpp
// MyType.h
 
namespace Proud
{
    // 被呼叫的RMI函數的內容被轉換為字串並輸出。
    // 建立日誌時很有用。
    void AppendTextOut(String &a,const MyType &b);
 
    // 從訊息緩衝區讀取自訂類型的內容。
    CMessage& operator>>(CMessage &a, MyType &b);
 
    // 將自訂類型內容插入訊息緩衝區。
    CMessage& operator<<(CMessage &a, const MyType &b);
}
```

在 ProudNet 的 RMI 功能中，我們使用 <mark style="color:orange;">Proud.CMessage</mark>。 RMI 參數是透過重載上述函數來編組的。 這裡使用的是<mark style="color:orange;">Proud.CMessage</mark>。 <mark style="color:orange;">Proud.CMessage</mark>包含ProudNet中用於將RMI轉換為訊息或從訊息中讀取參數的訊息數據，並用作流物件。\ <br>

在封送處理函數中實現流的範例如下：

```cpp
namespace Proud
{
    CMessage& operator>>(CMessage &a, MyType &b)
    {
        a>>b.x,b.y>>b.z>>b.w;
        return a;
    }
    CMessage& operator<<(CMessage &a, const MyType &b)
    {
        // 不要使用a.UseInternalBuffer()！
        a<<b.x,b.y<<b.z<<b.w;
        return a;
    }
    void AppendTextOut(String &a,const MyType &b)
    {
        String f;
        f.Format(L"{x=%f,y=%f,z=%f,w=%f}",b.x,b.y,b.z,b.w);
        a+=f;
    }
}
```

最後，在包含在 PIDL 編譯器中建立的代理程式和存根檔案之前，必須先包含宣告上述重載方法的頭檔。

```cpp
// 例1
#include "MyType.h"
#include "MyPIDL_proxy.h"
 
// 例2
#include "MyType.h"
#include "MyPIDL_stub.h"
```

實際實現的範例請參考<mark style="color:orange;"><安裝資料夾>/sample/CustomTypeMarshal</mark> 或<mark style="color:orange;">\<Sample/CasualGame/GCServer/FarmCommon.h></mark>。 若要檢查您自己的編組函數是否有效，請使用 <mark style="color:orange;">Proud.TestMarshal()</mark>。
{% endtab %}

{% tab title="C#" %}
如果您從 C++ 端序列化並傳送 <mark style="color:orange;">CFastArray</mark>，C# 端會接收它、反序列化它，並在步驟 5 中使用它。\
在此範例中，當從 C# 用戶端呼叫名為 Ping 的 RMI 時，接收它的 C++ 伺服器呼叫 StudentList RMI 並將 C++ 的 <mark style="color:orange;">CFastArray</mark> 傳送到 C#，而 C# 將其作為 List 接收。

1. [編寫](#1-c-student) [C# Student 類](#1-c-student)
2. [編寫](#2-c++-cstudent) [C++ CStudent 類](#2-c++-cstudent)
3. [編寫](#3-pidl) [PIDL ](#3-pidl)
4. [編寫](#4-c++) [C++ 編組程式碼](#4-c++)
5. [編寫](#5-c) [C# 編組程式碼 ](#5-c)

#### (1) 編寫 C# Student 類

```csharp
namespace CsClient
{
    class Student
    {
        public string Name;
        public int ID;
        public int Kor;
        public int Eng;
        public int Mat;
        public override string ToString()
        {
            return string.Format("Name: {0}({1}) K: {2}, E: {3}, M: {4}", Name, ID, Kor, Eng, Mat);
        }
    }
} 
```

#### (2) 編寫 C++ CStudent 類

```cpp
class CStudent
{
    public:
    Proud::String Name;
    int ID;
    int Kor;
    int Eng;
    int Mat;
}; 
```

#### (3) 編寫 PIDL

#### S2C.PIDL

<pre data-line-numbers><code><strong>rename cs(Proud::CFastArray&#x3C;CStudent>, System.Collections.Generic.List&#x3C;CsClient.Student>);
</strong><strong>[marshaler(cs)=CsClient.MyMarshaler]
</strong>global S2C 3000
{
<strong>    StudentList([in] Proud::CFastArray&#x3C;CStudent> students);
</strong>} 
</code></pre>

{% hint style="success" %} <mark style="color:orange;">Line1</mark>: rename關鍵字用於不同語言之間的PIDL通訊。 這個名稱必須包含命名空間。

<mark style="color:orange;">Line2</mark>: marshaler(cs) 關鍵字指定在 C:: 端使用的封送拆收器。 這個名稱必須包含命名空間。

<mark style="color:orange;">Line5</mark>: 建立一個 StudentList PIDL。 基本上，您可以像在 C++ 中使用它一樣編寫它。
{% endhint %}

**C2S.PIDL**

```
[marshaler(cs)=CsClient.MyMarshaler]
global C2S 4000
{
    Ping([in] int value);
} 
```

此範例 PIDL 程式碼是當客戶端發送 ping 時發送 StudentList 的 PIDL 程式碼。建立檔案以建立 <mark style="color:orange;">.h</mark>, <mark style="color:orange;">.cpp</mark>, <mark style="color:orange;">.cs</mark> 檔案。

&#x20;

#### (4) 編寫 C++ 編組程式碼

此程式碼封送作為範例建立的 CStudent 類別。

```cpp
namespace Proud
{
    CMessage& operator >> (CMessage& msg, CStudent student)
    {
        msg >> student.Name >> student.ID >> student.Kor >> student.Eng >> student.Mat;
        return msg;
    }
    CMessage& operator << (CMessage& msg, const CStudent& student)
    {
        msg << student.Name << student.ID << student.Kor << student.Eng << student.Mat;
        return msg;
    }
} 
```

當 C# 客戶端發送 ping 時，此程式碼會傳送 StudentList。

```
class C2SStub : public C2S::Stub
{
    public:
    DECRMI_C2S_Ping;
};
 
DEFRMI_C2S_Ping(C2SStub)
{
    {
        CriticalSectionLock(g_lock, true);
        g_S2CProxy.StudentList(remote, RmiContext::ReliableSend, g_Students);
    }
    return true;
}
C2SStub g_C2SStub; 
```

&#x20;

#### (5) 編寫 C# 編組程式碼

C#中的Marshaling是透過繼承並實作<mark style="color:orange;">Nettention.Proud.Marshaler</mark>然後替換它來開發的，它透過PIDL中聲明的<mark style="color:orange;">marshaler(cs)=CsClient.MyMarshaler</mark>關鍵字進行操作，無需您自己進行操作。

```csharp
namespace CsClient
{
    class MyMarshaler : Nettention.Proud.Marshaler
    {
        public static bool Read(Message msg, out List<Student> students)
        {
            students = null;
            if (!msg.ReadScalar(out var size))
            {
                return false;
            }
            students = new List<Student>();
            for (int i = 0; i < size; ++i)
            {
                Student s = new Student();
                if (!msg.Read(out s.Name)) { return false;
                }
                if (!msg.Read(out s.ID))
                {
                    return false;
                }
                if (!msg.Read(out s.Kor))
                {
                    return false;
                }
                if (!msg.Read(out s.Eng))
                {
                    return false;
                }
                if (!msg.Read(out s.Mat))
                {
                    return false;
                }
                students.Add(s);
            }
            return true;
        }
 
        public static void Write(Message msg, List<Student> students)
        {
            msg.WriteScalar(students.Count);
            for (int i = 0; i < students.Count; ++i)
            {
                msg.Write(students[i].Name);
                msg.Write(students[i].ID);
                msg.Write(students[i].Kor);
                msg.Write(students[i].Eng);
                msg.Write(students[i].Mat);
            }
        }
    }
} 
```

```csharp
g_S2CStub.StudentList = (remote, rmiContext, students) =>
{
    lock(g_lock)
    {
        // 您可以使用傳遞給 List<Student> 的學生。
        foreach (var s in students)
        {
            Console.WriteLine(s.ToString());
        }
    }
    return true;
};
```

{% endtab %}
{% endtabs %}

### - 基於條件的編組方法

有一種方法可以在 RMI 參數中編組字元訊息，每個欄位在不同的字元類型之間有效或無效。 您可以使用 switch/case 語句或物件多態性來實現各種封送處理。

<details>

<summary> <span data-gb-custom-inline data-tag="emoji" data-code="27a1">➡️</span> 使用 switch/case 的範例 </summary>

```cpp
namespace Proud
{
    enum UnitType
    {
        Zergling,     // 星際爭霸的雜技（地面型通商攻擊單元）
        Queen,        // 星際爭霸之王（飛行型特殊技術使用單元）
        Broodling    // 女王使用育雛技能創造的生存時間短的攻擊單位。
    };
 
    struct Unit
    {
        UnitType m_type;          // 單位類型
        Vector2D m_position;    // 單位所在地
        int m_energy;            // 單位的能量（或法力）->僅對皇后有效
        float m_lifeTime;        // 單位存活時間限制->僅對育雛有效
        int m_attackPower;        // 單位攻擊力 -> 只對雜技有效
    };
 
    CMessage& operator<<(CMessage& msg,const Unit& unit)
    {
        msg<<unit.m_type<<unit.m_position;
        switch(unit.m_type)
        {
        case Zergling:
            msg<<unit.m_attackPower;
            break;
        case Queen:
            msg<<unit.m_energy;
            break;
        case Broodling:
            msg<<unit.m_lifeTime;
            break;
        }
        return msg;
    }
 
    CMessage& operator>>(CMessage& msg,Unit& unit)
    {
        msg>>unit.m_type>>unit.m_position;
        switch(unit.m_type)
        {
        case Zergling:
            msg>>unit.m_attackPower;
            break;
        case Queen:
            msg>>unit.m_energy;
            break;
        case Broodling:
            msg>>unit.m_lifeTime;
            break;
        }
        return msg;
    }
}
```

</details>

### - 以位元為單位編組數據

若要減少訊息中儲存的資料量，您可以逐位封送資料。\ <mark style="color:orange;">Proud.CMessage</mark> 有以下方法以位元為單位儲存資料。

<table><thead><tr><th width="351">方法</th><th>註釋</th></tr></thead><tbody><tr><td>Proud.CMessage.ReadBits</td><td>以位元爲單位讀取</td></tr><tr><td>Proud.CMessage.WriteBits</td><td>以位元為單位寫入</td></tr></tbody></table>

<details>

<summary><span data-gb-custom-inline data-tag="emoji" data-code="27a1">➡️</span> 例子</summary>

```cpp
namespace Proud
{
    struct MyType
    {
        int x,y,z;
    };
    CMessage& operator>>(CMessage &a, MyType &b)
    {
        // 6位元用於讀取x值
        a.ReadBits(b.x,6);
        // 3位元用於讀取y值
        a.ReadBits(b.y,3);
        // 15 位元用於讀取 z 值。 換句話說，總共使用了6+3+15=24bit（3位元組）。
        a.ReadBits(b.z,15);
        return a;
    }
    CMessage& operator<<(CMessage &a, const MyType &b)
    {
        a.WriteBits(b.x,6); // 以位元為單位儲存 x、y 和 z 值。
        a.WriteBits(b.y,3);
        a.WriteBits(b.z,15);
        return a;
    }
}
```

</details>

{% hint style="warning" %}
**位元級資料編組的注意事項**&#x20;

您要記錄的位數不得超出您要記錄的實際值的範圍。\
例如，如果您嘗試記錄一個 int，但 int 內部的值實際上是負數，則第一位是 1。 在這種情況下，如果嘗試記錄少於31位元以減少位數，則第一位的值將被省略，因此在逐位讀取/寫入時要小心。
{% endhint %}

### - 編組enum類型

若要封送enum類型，請實作下列函數。

```cpp
enum type { ... } ;
 
namespace Proud
{
    inline CMessage& operator<<(CMessage& a,type b)
    {
        a<<(int)b;
        return a;
    }
    inline CMessage& operator>>(CMessage& a,type& b)
    {
        int x;
        a>>x;
        b=(type)x;
        return a;
    }
    inline void AppendTextOut(String &a,type b)
    {
        String txt;
        txt.Format(L"%d",(int)b);
        a+=txt;
    }
}
```

透過使用ProudNet中已定義的巨集<mark style="color:orange;">PROUDNET\_SERIALIZE\_ENUM</mark>，可以如下輕鬆完成上述實作。

```
PROUDNET_SERIALIZE_ENUM(type)
```

### - 編組集合（陣列等）

ProudNet 已準備好編組幾種基本集合（陣列等）類型。 支援 <mark style="color:orange;">Proud.CFastArray</mark>, <mark style="color:orange;">Proud.CFastMap</mark>, <mark style="color:orange;">std.vector</mark> , <mark style="color:orange;">CAtlArray</mark>。

{% hint style="info" %}
參考<mark style="color:orange;">marshaler.h</mark>中的operator>>, operator<<超載
{% endhint %}

```
// 下面是在 PIDL 中聲明數組類型的範例。
Foo([in] Proud::CFastArray<MyType> a, [in] std::vector<MyType> b);
```

如果需要 <mark style="color:orange;">marshaler.h</mark> 中預設定義的集合類型以外的集合類型，則需要實現與所需集合相對應的重載。為此，請參閱[**使用**](#rmi) [**RMI 的自訂類別類型**](#rmi)或 <mark style="color:orange;">marshaler.h</mark> 以了解已實現的範例。

\
當您想要封送 ProudNet 尚未支援的集合類型時，請參閱下列例程。

<details>

<summary><span data-gb-custom-inline data-tag="emoji" data-code="27a1">➡️</span> <mark style="color:orange;">std.vector</mark> marshalling 示例</summary>

```cpp
namespace Proud
{
    // 向量中可用的序列化函數
    // for output to stream
    template<typename elem>
    inline CMessage& operator>>(CMessage &a, std::vector<elem> &b)
    {
        // 獲得大小。
        int size;
        a >> size;
 
        // 如果大小不能接受，則會產生例外。
        // 可能有人懷疑它被駭客入侵了。
        if (size<0 ||size >= CNetConfig::MessageMaxLength)
            ThrowExceptionOnReadArray(size);
 
        // 減少記憶體碎片
        b.reserve(size);
        b.resize(0);
 
        // 一項一項地讀取每個數組項。
        elem e;
        for (int i = 0;i < size;i++)
        {
            a >> e;
            b.push_back(e);
        }
        return a;
    }
 
    // 可在vector、 list等unary item elem等 
    // 使用的 serialization functions
    // for input from stream
    template<typename elem>
    inline CMessage& operator<<(CMessage &a, const std::vector<elem> &b)
    {
        // 記錄數組大小。
        int size = (int)b.size();
        a << size;
        
        // 記錄每個數組參數。
        for (std::vector<elem>::const_iterator i = b.begin();i != b.end();i++)
        {
            a << (*i);
        }
        return a;
    }
 
    template<typename elem>
    inline void AppendTextOut(String &a, std::vector<elem> &b)
    {
        a += L"<vector>";
    }
}
```

</details>

## 關鍵字列表

<table data-full-width="false"><thead><tr><th width="128.33333333333331">關鍵字名稱</th><th width="304">註釋</th><th>用法範例</th></tr></thead><tbody><tr><td>access</td><td><mark style="color:orange;">[<strong>C#</strong>]</mark> 設定命名空間中代理程式和存根類別的存取權限</td><td>[access=權限名稱]</td></tr><tr><td>byval</td><td>將參數作為值傳遞</td><td>P2PChat([in] Proud::String a, [in, byval] int b);</td></tr><tr><td>global</td><td>命名空間存取權限（目前僅支援全域）</td><td>global Simple 2000 { ... }</td></tr><tr><td>in</td><td>輸入參數</td><td>Chat([in] string txt);</td></tr><tr><td>include</td><td><mark style="color:orange;">[<strong>C#</strong>]</mark> 將包含插入到輸出中</td><td>#include "a/b/c.cpp"</td></tr><tr><td>marshaler</td><td><mark style="color:orange;">[<strong>C#</strong>]</mark> 用於使用者定義類型的封送拆收器</td><td>[marshaler(cs) = SimpleCSharp.CMyMarshaler]</td></tr><tr><td>mutable</td><td>將參數作為可變參數傳遞（:=引用）</td><td>Chat([in, mutable] string txt);</td></tr><tr><td>private</td><td><mark style="color:orange;">[<strong>C#</strong>]</mark> 設定命名空間中代理程式和存根類別的存取權限</td><td>[access=private]</td></tr><tr><td>protected</td><td><mark style="color:orange;">[<strong>C#</strong>]</mark> 設定命名空間中代理程式和存根類別的存取權限</td><td>[access=protected]</td></tr><tr><td>public</td><td><mark style="color:orange;">[<strong>C#</strong>]</mark> 設定命名空間中代理程式和存根類別的存取權限</td><td>[access=public]</td></tr><tr><td>rename</td><td>在特定環境下透過替換編譯</td><td>rename cs(Proud::String, System.String);</td></tr><tr><td>using</td><td><mark style="color:orange;">[<strong>C#</strong>]</mark> 將 using 關鍵字插入輸出中</td><td>using(cs) System.XXX;</td></tr></tbody></table>

## \[C#] 想要傳遞多種參數時

```
global 名稱空間名稱 2000 
{
    函數名稱([in] int 變數名);
}
```

當PIDL如上所寫時，PIDL編譯器編譯基本類型如下。

<pre><code>namespace 名稱空間名稱
{
    class Proxy : public ::Proud::IRmiProxy
    {
    public:
<strong>        virtual bool 函數名稱( ::Proud::HostID remote, ::Proud::RmiContext&#x26; rmiContext , const int&#x26; 變數名) PN_SEALED; 
</strong>        ...
    }
}
</code></pre>

想要更改傳遞方式時，請使用以下關鍵詞。

<table><thead><tr><th width="184.33333333333331">關鍵字名稱</th><th width="259">例子(PIDL)</th><th>例子(輸出結果)</th></tr></thead><tbody><tr><td>無</td><td>Chat([in] int val);</td><td>...Chat(..., const int&#x26; val)...</td></tr><tr><td>byval</td><td>Chat([in, byval] int val);</td><td>...Chat(..., const int val)...</td></tr><tr><td>mutable</td><td>Chat([in, mutable] int val);</td><td>...Chat(..., int&#x26; val)...</td></tr></tbody></table>

***

## :arrow\_left: [返回](/proudnet.cn/proudnet/using_pn/pidl.md)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.proudnet.com/proudnet.cn/proudnet/using_pn/pidl/using_pidl.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.