本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # coreHTTP 基本多執行緒示範 **重要** 此示範託管在已棄用的 Amazon-FreeRTOS 儲存庫上。我們建議您在建立新專案時從[這裡開始](freertos-getting-started-modular.md)。如果您已經有以現在已棄用的 Amazon-FreeRTOS 儲存庫為基礎的現有 FreeRTOS 專案，請參閱 [Amazon-FreeRTOS Github 儲存庫遷移指南](github-repo-migration.md)。 FreeRTOS ## 簡介 此示範使用 [FreeRTOS 的執行緒安全佇列](https://freertos.org/a00018.html)來保留等待處理的請求和回應。在此示範中，有三個任務需要注意。 + 主要任務會等待請求出現在請求佇列中。它會透過網路傳送這些請求，然後將回應放入回應佇列。 + 請求任務會建立 HTTP 程式庫請求物件以傳送至伺服器，並將其放入請求佇列。每個請求物件都會指定應用程式已設定下載之 S3 檔案的位元組範圍。 + 回應任務會等待回應出現在回應佇列中。它會記錄收到的每個回應。 此基本多執行緒示範設定為僅使用 TLS 連線進行伺服器身分驗證，這是 Amazon S3 HTTP 伺服器的必要項目。應用程式層身分驗證會使用[預先簽章 URL 查詢](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html)中的 [Signature 第 4 版](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)參數來完成。 ## 原始碼組織 示範專案名為 `http_demo_s3_download_multithreaded.c`，可在 `freertos/demos/coreHTTP/`目錄和 [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_download_multithreaded.c) 網站中找到。 ## 建置示範專案 示範專案使用 [Visual Studio 的免費社群版本](https://visualstudio.microsoft.com/vs/community/)。若要建置示範： 1. 從 `mqtt_multitask_demo.sln` Visual Studio IDE 內開啟 Visual Studio 解決方案檔案。 1. 從 IDE 的**建置功能表中選取建置解決方案**。 **** **注意** 如果您使用的是 Microsoft Visual Studio 2017 或更早版本，則必須選取與您的版本相容的**平台工具組**：**Project -> RTOSDemos Properties -> Platform Toolset**。 ## 設定示範專案 示範使用 [FreeRTOS\$1TCP TCP/IP 堆疊](https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/index.html)，因此請依照 TCP[/IP 入門專案](https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/examples_FreeRTOS_simulator.html)提供的指示： 1. 安裝[必要元件 ](https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/examples_FreeRTOS_simulator.html#prerequisites)（例如 WinPCap)。 1. 選擇性地[設定靜態或動態 IP 地址、閘道地址和網路遮罩](https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/examples_FreeRTOS_simulator.html#static-dynamic)。 1. 選擇性地[設定 MAC 地址](https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/examples_FreeRTOS_simulator.html#mac-addr)。 1. 選取主機機器上的[乙太網路介面](https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/examples_FreeRTOS_simulator.html#network-interface)。 1. **在嘗試執行 HTTP 示範之前，請務必**[測試您的網路連線](https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/examples_FreeRTOS_simulator.html#connectivity-test)。 ## 設定 Amazon S3 HTTP 伺服器連線 遵循 *coreHTTP 基本下載示範*[設定 Amazon S3 HTTP 伺服器連線](core-http-s3-download-demo.md#core-http-s3-download-demo-configure-server)中的指示。 ## 功能 示範總共會建立三個任務： + 透過網路傳送請求和接收回應的 。 + 建立要傳送之請求的 。 + 處理收到的回應。 在此示範中，主要任務為： 1. 建立請求和回應佇列。 1. 建立與伺服器的連線。 1. 建立請求和回應任務。 1. 等待請求佇列透過網路傳送請求。 1. 將透過網路收到的回應放入回應佇列。 請求任務： 1. 建立每個範圍請求。 回應任務： 1. 處理收到的每一個回應。 ## Typedefs 示範會定義下列結構以支援多執行緒。 **請求項目** 下列結構定義要放入請求佇列的請求項目。請求任務建立 HTTP 請求後，請求項目會複製到佇列中。 ``` /** * @brief Data type for the request queue. * * Contains the request header struct and its corresponding buffer, to be * populated and enqueued by the request task, and read by the main task. The * buffer is included to avoid pointer inaccuracy during queue copy operations. */ typedef struct RequestItem { HTTPRequestHeaders_t xRequestHeaders; uint8_t ucHeaderBuffer[ democonfigUSER_BUFFER_LENGTH ]; } RequestItem_t; ``` **回應項目** 下列結構定義要放入回應佇列的回應項目。主要 HTTP 任務透過網路收到回應後，回應項目會複製到佇列。 ``` /** * @brief Data type for the response queue. * * Contains the response data type and its corresponding buffer, to be enqueued * by the main task, and interpreted by the response task. The buffer is * included to avoid pointer inaccuracy during queue copy operations. */ typedef struct ResponseItem { HTTPResponse_t xResponse; uint8_t ucResponseBuffer[ democonfigUSER_BUFFER_LENGTH ]; } ResponseItem_t; ``` ## 主要 HTTP 傳送任務 主要應用程式任務： 1. 剖析主機地址的預先簽章 URL，以與 Amazon S3 HTTP 伺服器建立連線。 1. 剖析 S3 儲存貯體中物件路徑的預先簽章 URL。 1. 使用具有伺服器身分驗證的 TLS 連線至 Amazon S3 HTTP 伺服器。 1. 建立請求和回應佇列。 1. 建立請求和回應任務。 函數會`prvHTTPDemoTask()`執行此設定，並提供示範狀態。您可以在 [ Github](https://github.com/FreeRTOS/FreeRTOS/blob/main/FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/HTTP_S3_Download_Multithreaded/DemoTasks/S3DownloadMultithreadedHTTPExample.c#L451-L650) 上找到此函數的原始碼。 在函數 中`prvDownloadLoop()`，主要任務會封鎖並等待來自請求佇列的請求。當它收到請求時，會使用 API 函數 傳送請求`HTTPClient_Send()`。如果 API 函數成功，則會將回應放入回應佇列。 您可以在 Github 上`prvDownloadLoop()`找到 的原始碼。 [https://github.com/FreeRTOS/FreeRTOS/blob/main/FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/HTTP_S3_Download_Multithreaded/DemoTasks/S3DownloadMultithreadedHTTPExample.c#L1071-L1174](https://github.com/FreeRTOS/FreeRTOS/blob/main/FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/HTTP_S3_Download_Multithreaded/DemoTasks/S3DownloadMultithreadedHTTPExample.c#L1071-L1174) ## HTTP 請求任務 請求任務是在 函數 中指定`prvRequestTask`。您可以在 [ Github](https://github.com/FreeRTOS/FreeRTOS/blob/main/FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/HTTP_S3_Download_Multithreaded/DemoTasks/S3DownloadMultithreadedHTTPExample.c#L778-L876) 上找到此函數的原始碼。 請求任務會擷取 Amazon S3 儲存貯體中檔案大小。這會在函數 中完成`prvGetS3ObjectFileSize`。「連線：保持連線」標頭會新增至 Amazon S3 的此請求，以在傳送回應後保持連線開啟。Amazon S3 HTTP 伺服器目前不支援使用預先簽章 URL 的 HEAD 請求，因此請求第 0 個位元組。檔案的大小包含在回應的`Content-Range`標頭欄位中。預期來自伺服器的`206 Partial Content`回應；收到的任何其他回應狀態碼都是錯誤。 您可以在 [ Github](https://github.com/FreeRTOS/FreeRTOS/blob/main/FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/HTTP_S3_Download_Multithreaded/DemoTasks/S3DownloadMultithreadedHTTPExample.c#L757-L774) 上`prvGetS3ObjectFileSize`找到 的原始碼。 擷取檔案大小之後，請求任務會繼續請求檔案的每個範圍。每個範圍請求都會放置在要傳送的主要任務的請求佇列中。檔案範圍是由示範使用者在巨集 中設定`democonfigRANGE_REQUEST_LENGTH`。HTTP 用戶端程式庫 API 使用 函數 原生支援範圍請求`HTTPClient_AddRangeHeader`。函數`prvRequestS3ObjectRange`示範如何使用 `HTTPClient_AddRangeHeader()`。 您可以在 [ Github](https://github.com/FreeRTOS/FreeRTOS/blob/main/FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/HTTP_S3_Download_Multithreaded/DemoTasks/S3DownloadMultithreadedHTTPExample.c#L694-L753) 上`prvRequestS3ObjectRange`找到 函數的原始碼。 ## HTTP 回應任務 回應任務會在回應佇列上等待透過網路收到的回應。主要任務會在成功收到 HTTP 回應時填入回應佇列。此任務會透過記錄狀態碼、標頭和內文來處理回應。例如，實際的應用程式可能會透過將回應內文寫入快閃記憶體來處理回應。如果回應狀態碼不是 `206 partial content`，則任務會通知主要任務示範應失敗。回應任務是在函數 中指定`prvResponseTask`。您可以在 [ Github](https://github.com/FreeRTOS/FreeRTOS/blob/main/FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/HTTP_S3_Download_Multithreaded/DemoTasks/S3DownloadMultithreadedHTTPExample.c#L961-L1047) 上找到此函數的原始碼。