Using Structured Data

SDTs are structured, language-independent, and architecture-independent data types. SDTs can be used in messages to facilitate the exchange of binary data in a heterogeneous network that has clients that use different hardware architectures and programming languages.

The Solace .NET API supports the ability to carry structured data in the binary attachment of the message or as user-defined message header fields.

All structured data must be added to or read from complex data structures (maps and streams), generically called containers. Containers themselves are structured data types. Therefore, a map or stream can contain simple SDT types or other maps or streams.

Related Samples

  • For an example of how to work with SDTs when publishing and receiving messages, see the RequestReply samples (RRDirectRequester, RRDirectReplier, RRGuaranteedRequester, and RRGuaranteedReplier).
  • For an example of how to add SDT payloads to a message, see the SDTPubSubMsgIndep or SDTPubSubMsgDep samples.
    • In the SDTPubSubMsgIndep sample, SDT containers are created using application memory.
    • In the SDTPubSubMsgDep sample, SDT containers are created using API‑controlled memory.

      For more information on creating SDT containers with application memory or API‑controlled memory, see Creating Structured Data Maps and Streams.

Supported Structured Data Types

The messaging APIs support the following SDTs.

Supported Structured Data Types
Data Type .Solace .NET API

Boolean

System.Boolean

8-bit signed integer

System.Int16

8-bit unsigned integer

System.Byte

16-bit signed integer

System.Int16

16-bit unsigned integer

System.Int16

32-bit signed integer

System.Int32

32-bit unsigned integer

System.Int64

64-bit signed integer

Int64

64-bit unsigned integer

Int64 (when there is no loss of precision)

32-bit floating point

float

64-bit floating point

double

character (16-bit unicode)

System.Char

byte array

byte[]

string (UTF-8 encoded)

System.string

destination (Topic or Queue physical names)

IDestination

SMF message

IMessage

Map (a structured data container of a sequence of named fields. Each field must be one of the supported data types.)

IMapContainer

Stream (a structured data container of a sequence of unnamed fields. Each field must be one of the supported data types.)

IStreamContainer

Unknown (a validly formatted but unrecognized data type)

IUnknownSDTField

Null or unspecified

null

Structured Data Type Conversion

The table below lists how the supported SDTs in a received message can be read by the Solace .NET API.

Possible Structured Data Type Conversions in the Solace .NET API

 

Read As

 

 

Bool

Byte Array

Char

Dest

Dbl

Float

Integer

String

NULL

Written As

Bool

✓

 

 

 

 

 

✓

 

 

Byte Array

 

✓

 

 

 

 

 

 

 

Char

 

 

✓

 

 

 

 

 

 

Dest

 

 

 

✓

 

 

 

 

 

Dbl

2

 

 

 

✓

 

 

 

 

Float

2

 

 

 

 

✓

 

 

 

Integer

2

 

 

 

 

 

3

 

 

String

1

✓

4

 

✓

✓

✓

✓

 

NULL

5

5

5

5

5

5

5

5

✓
  1. Returns a boolean with a value represented by the specified string. The boolean returned represents a true value if the string argument is not null and is equal, ignoring case, to the string “true” or 1.
  2. Returns boolean 0 or 1 if the integer byte is non‑zero.
  3. 8, 16, 32, and 64-bit signed and unsigned integers are supported structured data types. A client can receive one type of integer and read it as another as long the conversion will not result in a loss of information.
  4. When using the C API, if the string length is 1, getChar() returns the single character in the string.
  5. Any field can be skipped by reading it as a NULL.

Creating Custom Message Header Fields

To create a custom message header field, you can create a map with custom user properties fields. The user properties are carried in the message separate from the payload.

When using the Solace .NET API, you can create a user property map for a message through a single method call. Each field in a user properties map is a SDT field. Once the map is created, data for fields in the map can be added with the container methods. For a comprehensive list of the available container methods, see the Solace Messaging APIs documentation.

Creating a User Properties Map

In the Solace .NET API, use:

IMessage.CreateUserPropertyMap()