> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PartyLocalEndpoint::SendMessage

> 傳送訊息至網路中的其他端點。

傳送訊息至網路中的其他端點。

## 語法

```cpp theme={null}
PartyError SendMessage(  
    uint32_t targetEndpointCount,  
    PartyEndpointArray targetEndpoints,  
    PartySendMessageOptions options,  
    const PartySendMessageQueuingConfiguration* queuingConfiguration,  
    uint32_t dataBufferCount,  
    const PartyDataBuffer* dataBuffers,  
    void* messageIdentifier  
)  
```

### 參數

**`targetEndpointCount`**   uint32\_t

`targetEndpoints` 陣列中的目標端點數目。可以為零，以廣播給網路中的所有遠端端點。接收廣播訊息的裝置，其 [PartyEndpointMessageReceivedStateChange](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partyendpointmessagereceivedstatechange) 的目標端點欄位會填入該裝置的所有本機端點。

**`targetEndpoints`**   [PartyEndpointArray](/zh-TW/services/playfab/multiplayer/networking/reference/typedefs)\
*大小為 `targetEndpointCount` 的輸入陣列*

包含 `targetEndpointCount` 個項目的目標 PartyEndpoint 物件指標陣列，訊息應傳送至這些端點。當 `targetEndpointCount` 為零時會忽略此參數。

**`options`**   [PartySendMessageOptions](/zh-TW/services/playfab/multiplayer/networking/reference/enums/partysendmessageoptions)

零個或多個選項旗標，描述如何傳送訊息。

**`queuingConfiguration`**   [PartySendMessageQueuingConfiguration\*](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partysendmessagequeuingconfiguration)\
*選用*

選用結構，描述訊息在本機佇列中等候傳輸機會時應有的行為。可以是 nullptr，以使用預設的佇列行為。

**`dataBufferCount`**   uint32\_t

`dataBuffers` 陣列中提供的緩衝區結構數目。必須大於 0。

**`dataBuffers`**   [PartyDataBuffer\*](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partydatabuffer)\
*大小為 `dataBufferCount` 的輸入陣列*

包含 `dataBufferCount` 個項目的 PartyDataBuffer 結構陣列，描述要傳送的訊息承載。

**`messageIdentifier`**   void\*\
*選用*

不透明的呼叫者專屬內容指標，Party 程式庫會將其包含在參考此訊息的任何狀態變更中。不會加以解譯或傳輸到遠端。如果不需要訊息識別內容，可以是 nullptr。

### 傳回值

PartyError

`c_partyErrorSuccess` (如果將訊息排入佇列以進行傳輸成功)，否則為錯誤碼。如果此方法失敗，將不會產生任何相關的狀態變更。可透過 [PartyManager::GetErrorMessage()](/zh-TW/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_geterrormessage) 擷取錯誤碼的人類可讀形式。

## 備註

目前不支援將訊息傳送至本機端點。如果目標端點陣列包含任何本機目標，此呼叫將以同步方式失敗。 <br /><br /> 指定裝置上的所有目標端點都會收到單一 [PartyEndpointMessageReceivedStateChange](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partyendpointmessagereceivedstatechange)，其中每個目標本機端點都會列在 PartyEndpointMessageReceivedStateChange 的 *receiverEndpoints* 陣列中。   <br /><br /> 如果目標端點陣列指定為零個項目，則訊息會廣播給網路中目前的所有遠端端點。   <br /><br /> 呼叫者會在 `dataBuffers` 陣列中提供 1 個或多個 PartyDataBuffer 結構。結構所參考的記憶體不必是連續的，例如，可以輕鬆地使用固定的標頭緩衝區，後面接著可變的承載。緩衝區會依序組合、傳輸，並以單一連續資料區塊的形式，在 PartyEndpointMessageReceivedStateChange 中傳遞給目標端點。Party 程式庫不會耗用頻寬來傳輸描述原始 PartyDataBuffer 分段的中繼資料。   <br /><br /> 根據預設，呼叫者的 `dataBuffers` 陣列中所描述的緩衝區，會在 SendMessage() 傳回之前複製到已配置的緩衝區。指定 [PartySendMessageOptions::DontCopyDataBuffers](/zh-TW/services/playfab/multiplayer/networking/reference/enums/partysendmessageoptions) 可避免此額外的複製步驟，但呼叫者必須讓每個緩衝區中指定的記憶體保持有效且不被修改，直到 [PartyDataBuffersReturnedStateChange](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partydatabuffersreturnedstatechange) 將記憶體的擁有權傳回給呼叫者為止。PartyDataBuffer 結構本身不需要在 SendMessage() 呼叫傳回後保持有效，只有它們所參考的記憶體需要。   <br /><br /> 使用 PartySendMessageOptions::DontCopyDataBuffers 的呼叫者可以提供呼叫者專屬的 `messageIdentifier` 內容。此指標大小的值會包含在所有 PartyDataBuffersReturnedStateChange 中，讓呼叫者可以輕鬆存取其私人訊息追蹤資訊。實際值會被視為不透明，Party 程式庫不會加以解譯，也不會傳輸到遠端。呼叫者必須負責確保 `messageIdentifier` 可能代表的任何自身記憶體保持有效，直到與該訊息及相關聯 `messageIdentifier` 相關的最後一個要求的狀態變更已處理並透過 [PartyManager::FinishProcessingStateChanges()](/zh-TW/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_finishprocessingstatechanges) 傳回為止。   <br /><br /> 根據連線品質和接收者回應能力等因素，訊息可能不會立即傳輸至目標端點。如果您的傳送速度比與端點之連線目前估計可支援的速度更快，本機傳送佇列就會增長。這會增加記憶體使用量，並可能導致感知的訊息延遲增加，因此強烈建議呼叫者監視和管理本機傳送佇列。您可以使用 [PartyLocalEndpoint::GetEndpointStatistics()](/zh-TW/services/playfab/multiplayer/networking/reference/classes/PartyLocalEndpoint/methods/partylocalendpoint_getendpointstatistics) 擷取傳送佇列的相關資訊。您可以藉由減少傳送的大小和/或頻率、使用 `queuingConfiguration` 選用設定來設定自動讓佇列中停留過久之訊息過期的逾時，或使用 PartyLocalEndpoint::CancelMessages() 明確移除部分或全部佇列中的訊息，來管理傳送佇列。   <br /><br /> 當此方法傳回成功時，表示訊息已開始傳輸，或已成功排入佇列等候未來傳輸。特別是，此方法成功傳回並不表示訊息已成功傳遞給任何收件者。Party API 目前不提供追蹤個別訊息傳遞和處理的方式。[PartyNetwork::GetNetworkStatistics()](/zh-TW/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_getnetworkstatistics) 和 GetEndpointStatistics() 方法可分別用來查詢整個網路或個別本機端點的彙總統計資料。   <br /><br /> 如果 `options` 包含 [PartySendMessageOptions::GuaranteedDelivery](/zh-TW/services/playfab/multiplayer/networking/reference/enums/partysendmessageoptions)，且訊息無法成功傳遞至透明雲端轉送伺服器以轉送給目標端點，則會產生 [PartyNetworkDestroyedStateChange](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partynetworkdestroyedstatechange)。換句話說，具有保證傳遞需求的訊息要不是會被傳遞，就是傳送用戶端會與網路中斷連線。當透明雲端轉送伺服器將保證傳遞訊息轉送給包含一或多個目標端點的每個遠端裝置時，如果訊息無法傳遞，遠端裝置同樣會與網路中斷連線，並以 PartyNetworkDestroyedStateChange 表示。換句話說，無法接收具有保證傳遞需求之訊息的裝置將會與網路中斷連線。   <br /><br /> Party 程式庫會自動分割和重組超過環境所支援大小上限的大型訊息，因此呼叫者不需要自行管理。不過，分割會產生少量的額外負荷。能夠傳送較小訊息，或能自行有效率地自然拆分大型狀態承載的呼叫者，可能會希望這麼做。   <br /><br /> 如果在成功將第一位使用者驗證到網路之前，以零個項目的目標端點陣列叫用 SendMessage()，即使尚未透過 [PartyEndpointCreatedStateChange](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partyendpointcreatedstatechange) 狀態變更回報任何遠端端點 (因此已知存在於網路中)，訊息仍會排入佇列。一旦第一位使用者成功驗證，且此傳送端本機端點已成功建立，佇列中的訊息就會以屆時存在於網路中的所有遠端端點為目標。由於在此情況下，於 SendMessage() 時無法得知網路的未來狀態以及最終接收端點的集合，遊戲應謹慎考量在這類延後廣播訊息中放入哪些內容，或乾脆在此本機裝置和端點完全參與網路之前不要提交這類訊息。

## 需求

**標頭：** Party.h

## 另請參閱

[PartyLocalEndpoint](/zh-TW/services/playfab/multiplayer/networking/reference/classes/PartyLocalEndpoint/partylocalendpoint)\
[PartySendMessageOptions](/zh-TW/services/playfab/multiplayer/networking/reference/enums/partysendmessageoptions)\
[PartySendMessageQueuingConfiguration](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partysendmessagequeuingconfiguration)\
[PartyDataBuffersReturnedStateChange](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partydatabuffersreturnedstatechange)\
[PartyEndpointMessageReceivedStateChange](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partyendpointmessagereceivedstatechange)\
[PartyNetwork::GetNetworkStatistics](/zh-TW/services/playfab/multiplayer/networking/reference/classes/PartyNetwork/methods/partynetwork_getnetworkstatistics)\
[PartyLocalEndpoint::GetEndpointStatistics](/zh-TW/services/playfab/multiplayer/networking/reference/classes/PartyLocalEndpoint/methods/partylocalendpoint_getendpointstatistics)\
[PartyLocalEndpoint::FlushMessages](/zh-TW/services/playfab/multiplayer/networking/reference/classes/PartyLocalEndpoint/methods/partylocalendpoint_flushmessages)


## Related topics

- [PartyLocalEndpoint::FlushMessages](/zh-TW/services/playfab/multiplayer/networking/reference/classes/PartyLocalEndpoint/methods/partylocalendpoint_flushmessages.md)
- [PartySendMessageOptions](/zh-TW/services/playfab/multiplayer/networking/reference/enums/partysendmessageoptions.md)
- [PartyEndpointStatistic](/zh-TW/services/playfab/multiplayer/networking/reference/enums/partyendpointstatistic.md)
- [PartySendMessageQueuingConfiguration](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partysendmessagequeuingconfiguration.md)
- [PartyEndpointMessageReceivedStateChange](/zh-TW/services/playfab/multiplayer/networking/reference/structs/partyendpointmessagereceivedstatechange.md)