创建结构化数据映射和流
创建映射和流所需的内存可以由客户端应用程序分配，以创建与消息无关的映射和流（参阅与消息无关的映射和流），也可以由 API 自动分配，以创建与消息相关的映射和流（参阅与消息相关的映射和流）。
与消息无关的映射和流适用于所有消息 API；而与消息相关的映射和流仅适用于 C 和 .NET API。
与消息无关的映射和流
通常，映射或流是在独立于特定消息的应用程序内存中创建的。这允许将容器添加到其他容器中，或者添加到多个消息的二进制消息部分。如果希望将容器重复添加到不同的消息或现有容器中作为通用容器，则使用与消息无关的容器会非常有用。
对于 JavaScript、Node.js 和 .NET API，创建容器时，内存是从堆中分配的。
对于 C API，您必须传入指向接收容器指针的位置的指针，以及指向创建 容器的位置的指针。
以下部分讨论如何使用与消息无关的容器：
- 创建结构化数据映射
- 创建结构化数据流
- 将容器内容复制到消息中
- 通过引用将容器内容添加到消息中
- 将容器添加到现有容器中
创建结构化数据映射
| PubSub+ 消息 API | 使用方法 |
|---|---|
| C | solClient_container_createMap() |
| .NET | SDTUtils.CreateMap(...) |
应用程序完成映射后，显式调用 Dispose() 以确保释放分配的内存。 | |
| JavaScript 和 Node.js | 创建一个新的 solace.SDTMapContainer 对象 |
如何创建结构化数据映射
创建结构化数据流
| PubSub+ 消息 API | 使用方法 |
|---|---|
| C | solClient_container_createStream(...) |
| .NET | SDTUtils.CreateStream(...) 并传入流的最大大小（以字节为单位）。 |
应用程序完成流后，显式调用 Dispose() 以确保释放分配的内存。 | |
| JavaScript 和 Node.js | 创建一个新的 solace.SDTStreamContainer 对象 |
如何创建结构化数据流
将容器内容复制到消息中
要将数据从容器复制到消息的二进制附件中，请调用以下列出的函数或方法之一。传入内容所属的消息以及包含要复制内容的容器。对于 C API，使用消息和容器的指针。
如果在调用函数或方法之前存在二进制附件，则会在复制新数据之前将其移除。
调用函数或方法后，对容器内容的任何进一步更改都不会传播到引用的消息中。
| PubSub+ 消息 API | 使用方法 |
|---|---|
| C | solClient_msg_setBinaryAttachmentContainer(...) |
| .NET | SDTUtils.SetSDTContainer(...) |
| JavaScript 和 Node.js | 不适用 |
如何将容器内容复制到消息中
通过引用将容器内容添加到消息中
要 通过容器引用将映射或流中的数据添加到消息的二进制附件中，请调用下表中列出的方法或函数之一，并传入接收内容的消息引用以及包含要添加内容的容器。
如果消息已经包含二进制附件，则会移除该附件，仅传输引用的映射。
C API
通过不透明容器指针引用将映射或流中的数据添加到消息的二进制附件中可以提高系统性能，因为它避免了将应用程序内存复制到消息二进制附件中。
当调用 solClient_session_sendMsg() 函数并发送消息时，二进制附件内容将直接从应用程序内存复制到传输套接字或缓冲区。
调用 solClient_msg_setBinaryAttachmentContainerPtr() 后，对容器数据的任何进一步更改可能导致传输消息的容器内容损坏，因此在消息成功传输并确认（如果是保证消息）之前，不得修改容器。
| PubSub+ 消息 API | 使用方法 |
|---|---|
| C | solClient_msg_setBinaryAttachmentContainerPtr(solClient_opaqueMsg_pt msg_p, solClient_opaqueContainer_pt cont_p) |
| .NET | 不适用 |
| JavaScript 和 Node.js | 创建一个新的 SDT 字段对象，使用 solace.SDTField.create(...) 传入要通过引用添加的 SDT 映射或流容器对象，然后将 SDT 字段对象传入 message.setSdtContainer(...)。 |
如何通过引用添加容器内容
将容器添加到现有容器中
要将现有容器添加到映射或流中，请调用下表中列出的函数或方法之一，并传入父容器以及要添加到其中的子容器。
C API
使用消息和容器的指针。此外，如果父容器是映射，则还必须传入要添加容器的字段名称，如果父容器是流，则 name 参数必须为 NULL。
| PubSub+ 消息 API | 使用方法 |
|---|---|
| C | solClient_container_addContainer(...) |
| .NET | - IMapContainer.AddSDTContainer(...) |
- IStreamContainer.AddSDTContainer(...) |
| JavaScript 和 Node.js | 创建一个新的 SDT 字段对象，使用
solace.SDTField.create(...)传入要添加的 SDT 映射或流容器对象，然后使用addField(...)方法将其添加到 SDT 映射或流容器中。 |
如何将容器添加到现有容器中
与消息相关的映射和流
对于 C 和 .NET API，还可以直接在消息的二进制附件中创建容 器，使用由消息 API 管理的内存块；在这种情况下，容器依赖于特定消息，不能被其他消息重用。对于 JavaScript 和 Node.js API，容器只能独立于特定消息创建。
创建与消息相关的映射和流
当使用 C 或 .NET API 时，客户端可以直接在消息的二进制附件中创建结构化数据的映射或流。以这种方式添加的结构化数据不是在可以重用的应用程序内存容器中创建的。然而，它避免了内存复制操作，并将内存管理任务从应用程序卸载，以便消息 API 负责管理为容器分配的内存。
要创建与消息相关的映射或流，请调用以下列出的方法之一，直接在特定消息的二进制附件中创建映射或流。
| PubSub+ 消息 API | 使用方法 |
|---|---|
| C | - solClient_msg_createBinaryAttachmentMap(...) |
- solClient_msg_createBinaryAttachmentStream(...) | | .NET | - SDTUtils.CreateMap(...)
- SDTUtils.CreateStream(...) | | JavaScript 和 Node.js | 不适用 |
如何创建与消息相关的映射和流
当使用这些函数或方法之一时，您必须指定为创建映射或流而分配的数据块大小（以字节为单位）。
如果设置了特定的数据块大小，但随后创建的映射或流太大而无法适应，则在添加数据时会分配更大的数据块，并将现有的结构化数据复制到新的缓冲区中。这种重新分配可能会对性能产生负面影响。
如果您希望使用尽可能少的消息 API 内存，请将大小参数设置为 0。在这种情况下，API 使用尽可能小的数据块（默认为 10,240 字节）来构建容器。如果这还不够，则会发生重新分配，并将所有现有数据复制到新的、更大的缓冲区中。
可以使用 SDT 添加方法或函数创建数据字段、子映射和子流。接收消息的应用程序也可以在重新传输或转发数据之前执行此操作。有关可用容器方法和函数的完整列表，请参阅适用于相应消息 API 的 PubSub+ 消息 API 文档。
删除字段会导致映射的其余部分进行缓冲区复制。