SendMessage Method

Sends a message on the specified link.

Syntax

public void SendMessage(string linkName);
Public Sub SendMessage(ByVal LinkName As String)

Remarks

This method sends a message on the link specified by LinkName.

The Message property holds an AMQPMessage object whose fields are used to construct the message to send. At minimum, specify a Value and a ValueType; all other fields are optional. The ResetMessage method can be used to reset the Message property.

amqp.Message.ValueType = AMQPValueTypes.mvtString;
amqp.Message.Value = "Hello World!";
amqp.SendMessage("SenderLinkName");

Message Settlement

AMQP provides the ability to negotiate delivery guarantees through the system of "message settlement". When a link is created, both the sender and the receiver negotiate a settle mode (one for each role) to use. Senders will operate in one of these modes:
  • Settled - All messages will be sent in a settled state.
  • Unsettled - All messages will be sent in an unsettled state.
  • Mixed - Messages may be sent either settled or unsettled.
and receivers will operate in one of these modes:
  • First - Incoming messages will be settled immediately (and the sender will be notified that the message has been received, if the message was not already settled when sent).
  • Second - Incoming messages will be settled after the sender has settled them (and the sender will be notified when a message has been received, if the message was not already settled when sent).

Together, the sender's and receiver's settle modes can form the following delivery guarantees:

Sender's Settle Mode Receiver's Settle Mode Effective Delivery Guarantee
Settled (Any) At most once
Unsettled First At least once
Unsettled Second Exactly once

(Note that, if the sender's settle mode is Mixed, the values in the "Sender's Settle Mode" column apply for each individual message.)

It is important to note that the message settlement system has a big caveat: Whichever party opens the link can only request that the other end use a specific settle mode. For example, if the component opens a sender link, it has control over the sender settle mode it will use, but it can only request that the remote host use a specific receiver settle mode; so if the component requests that the receiver use Second, the receiver can instead choose to use First (if, e.g., it doesn't support Second).

The component currently only ever requests (and itself only supports) the First receiver settle mode since no other AMQP implementations appear to support the Second receiver settle mode at this time.

The component requests (and uses) the Mixed sender settle mode by default, but supports all of the sender settle modes (the default can be changed using the DefaultSenderSettleMode configuration setting). Sender links created with the Mixed sender use the value of the Message.Settled field to determine whether to send messages as settled or unsettled.

Sending Composite Data

The AMQP 1.0 protocol's data model includes the concept of "composite data". Composite data is comprised of one or more type-value pairs (including data structure types), plus a descriptor that describes what the overall data represents.

Composite Data JSON Schema
The component uses JSON with a well-defined schema to represent composite data. The composite data JSON schema consists almost entirely of "type-value" objects, which hold an AMQP typename and a value. The syntax for a type-value object is:

{
  "type": "typename",
  "value": value
}

The following table provides a complete list of valid typenames, and describes how the associated values should be represented:

Typename Description Value Format
null Null null
boolean Boolean true or false
ubyte Unsigned byte 0 to 255
ushort Unsigned short 0 to 65535
uint Unsigned integer 0 to 4294967295
ulong Unsigned long 0 to 18446744073709551615
byte Byte -128 to 127
short Short -32768 to 32767
int Integer -2147483648 to 2147483647
long Long -9223372036854775808 to 9223372036854775807
float Float [IEEE 754 32-bit floating point number]
double Double [IEEE 754 64-bit floating point number]
decimal Decimal Hex-encoded byte string like "0A1B2C3D"
char Char "c"
timestamp Timestamp [Number of milliseconds since the Unix epoch (January 1, 1970 00:00:00 UTC)]
uuid UUID Hex-encoded UUID string like "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" (hyphens optional, case-insensitive)
binary Binary data Hex-encoded byte string like "0A1B2C3D"
string String "UTF-8 string (correctly escaped for JSON)"
symbol Symbolic value "ASCII string"
array AMQP array JSON array with zero or more type-value objects of the same type
list AMQP list JSON array with zero or more type-value objects
map AMQP map JSON array with even number of type-value objects representing keys and values; no duplicate keys allowed

Note that typenames must be lowercase in order to be parsed correctly.

Arrays, Lists, and Maps
The AMQP data model defines three data structure types: array, list, and map. In the composite data JSON schema, their value is always a JSON array that contains zero or more type-value objects. Data structure types may be nested arbitrarily to any depth.

Note that the array and map data structures each have restrictions on their content:

  • The elements in an array must all be of the same type (e.g., their typenames must match).
  • The elements in a map represent keys (odd-numbered elements) and values (even-numbered elements). There must be an even number of elements (or none), and the values of the "key" elements must be unique.

{
  "type": "map",
  "value": [
    { "type": "symbol", "value": "key1" },
    { "type": "string", "value": "value1" },
    { "type": "symbol", "value": "key2" },
    { "type": "int", "value": 100 }
  ]
}

Described Types
As noted above, AMQP's data model includes the idea of "described types", which is simply a normal AMQP type annotated by a descriptor. The descriptor defines what the data it is associated with represents as a whole.

In the composite data JSON schema, a described type object is just a normal type-value object with an extra "descriptor" property on it (and the "descriptor" property's value is itself a normal type-value object). The syntax for a described type object is:

{
  "descriptor": { "type": "typename", "value": value },
  "type": "typename",
  "value": value
}

Described type objects can be used anywhere that normal type-value objects can be, except as the value of the "descriptor" property for another described type object, which must be a normal type-value object.

Note that, according to the AMQP specification, the type of the descriptor itself ulong or symbol, but the component does not enforce this.

Abbreviated Value Syntax
For brevity, it is possible to abbreviate both normal type-value objects and described type objects when their value type is null, boolean, or string.

For normal type-value objects, instead of using the standard syntax (e.g., { "type": "string", "value": "Hello, world!" }), just use the raw value itself (e.g., "Hello, world!"). Keep in mind that the abbreviated value must still be valid JSON; notably, strings must still be surrounded by quotes (e.g., "value", not value).

The abbreviated syntax for a described type object is a bit different; the "descriptor" property still needs to be associated with the value using a JSON object. To abbreviate a described type object, just exclude the "type" property, like so:

{
  "descriptor": { "type": "typename", "value": value },
  "value": value
}

The abbreviated value syntax can be used anywhere that an unabbreviated type-value object or described type object would normally be used.

The component defaults to using the abbreviated syntax when returning composite data JSON. This can be configured using the SimplifiedJSONFormat configuration setting.

Composite Data JSON Example

{
  "descriptor": { "type": "symbol", "value": "nsoftware:compositeDataExample" },
  "type": "list",
  "value": [
    "Shorthand string value",
    null,
    true,
    { "type": "uuid", "value": "12345678-0000-1000-8000-00805F9B34FB" },
    {
      "type": "array",
      "value": [
        { "type": "uint", "value": 23 },
        { "type": "uint", "value": 52 },
        { "type": "uint", "value": 153325 }
      ]
    },
    {
      "type": "map",
      "value": [
        { "type": "symbol", "value": "name" },
        "Freezer temperature",
        { "type": "symbol", "value": "unit" },
        "Fahrenheit",
        { "type": "symbol", "value": "value" },
        { "type": "int", "value": -2 }
      ]
    },
    {
      "descriptor": { "type": "symbol", "value": "nsoftware:utf8Bytes" },
      "type": "binary",
      "value": "48656C6C6F2C20776F726C6421"
    }
  ]
}

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks IoT 2020 .NET Edition - Version 20.0 [Build 8265]