AzureIoTHubSendMsg

AzureIoTHubSendMsg sends a message through an Azure IoT Hub connection. See Notes for more information.

Syntax

AzureIoTHubSendMsg(strAlias, strMsg, [optStrType], [optStrProperties])

strAlias

The name of the Azure IoT Hub connection that you want to use. The connection can be created either during project development (in the Project ExplorerTasks tab Internet of Things folder) or during project run time (by calling the AzureIoTHubOpen function).

strMsg

This is message to send through the Azure IoT Hub connection specified by strAlias. Specific optStrType values require certain formats as explained below:

• If optStrType is HEX, the value of strMsg should be formatted in hexadecimal with two characters per byte. For example: 48656C6C6F20776F726C64

• If optStrType is BASE64, the value of strMsg should be formatted in Base64. For example: SGVsbG8gd29ybGQ=

• If optStrType is FILE, the value of strMsg should be a file path and name. If the file is located in the project folder, the path can be relative to that folder. If the file is located elsewhere on the computer or network, the path should be absolute.

  optStrType

  This is an option parameter specifying the message type or encoding. Possible values are: "UTF8", "UTF16", "UTF32", "ASCII", "HEX", "BASE64", "FILE". If not specified, the default value "UTF8" is used.

  optStrProperties

  List of properties of the message. Optional parameter. The format is "PropertyName1=PropertyValue1, PropertyName2=PropertyValue2"

Return value

If successful, this function returns the message ID (a positive integer).

If unsuccessful, this function returns 0 (zero), indicating that an invalid alias is used in the function (possibly not defined or closed), or one of the following negative integer values:

Notes

Messages are kept in the Gateway ("alive" in the IoT Hub queue) for up to 10 minutes before they are deleted from the queue. (The settings for messages are currently configured in the IoT Hub settings.) The Gateway has a limit of 100 messages per connection; older messages (in terms of creation time) will be deleted to make room for newer messages.

This function doesn't require an existing connection to send a message, though it can use an existing connection. If it creates a connection on the Gateway, that connection can be used by the other IoT functions AzureIoTHubGetQueueSize, AzureIoTHubGetMsgId, and AzureIoTHubClearQueue, using the same strAlias value.

Examples

As used in a Math worksheet: