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 C 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 the Solace C API.
  • 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 Solace C API supports the following SDTs.

Supported Structured Data Types
Data Type Solace C API

Boolean

solClient_bool_t

8-bit signed integer

solClient_int8_t

8-bit unsigned integer

solClient_uint8_t

16-bit signed integer

solClient_int16_t

16-bit unsigned integer

solClient_uint16_t

32-bit signed integer

solClient_int32_t

32-bit unsigned integer

solClient_uint32_t

64-bit signed integer

solClient_int64_t

64-bit unsigned integer

solClient_uint64_t

32-bit floating point

float

64-bit floating point

double

character (16-bit unicode)

solClient_wchar_t

byte array

solClient_uint8_t

string (UTF-8 encoded)

const char *

destination (Topic or Queue physical names)

solClient_
destination_t

SMF message

solclient_uint8_t *

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

solClient_
opaqueContainer_pt

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

solClient_
opaqueContainer_pt

Unknown (a validly formatted but unrecognized data type)

solClient_uint8_t

Null or unspecified

Supports add and get operations for the NULL data in structured data. By definition there is no ‘C’ type or size for NULL.

Structured Data Type Conversion

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

Possible Structured Data Type Conversions in Solace C 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 Solace 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.