Publish
Particle.publish - Publish
Since 6.2.0:
Particle.publish publishes an event from a device. This can be received by zero or more subscribers, including:
- External services using a webhook
- A Logic block to perform operations in the cloud
- Another device using
Particle.subscribe()
- The server-sent events (SSE) data stream
There are a variety of overloads for this function, including:
// PROTOTYPES
particle::Future<bool> publish(const char* name, const char* data, particle::ContentType type, PublishFlags flags = PublishFlags());
particle::Future<bool> publish(const char* name, const String& data, particle::ContentType type, PublishFlags flags = PublishFlags());
particle::Future<bool> publish(const char* name, const char* data, size_t size, particle::ContentType type, PublishFlags flags = PublishFlags());
particle::Future<bool> publish(const char* name, const particle::EventData& data, PublishFlags flags = PublishFlags());
name - Particle.publish - Publish
This is the name of the event, which can be 1 - 64 ASCII characters.
data (string) - Particle.publish - Publish
The event data can consist of UTF-8 characters. The length depends on the device and Device OS version, but is typically limited to 1024 bytes.
This can be specified as a const char *
(pointer to c-string, null-terminated), or a reference to a String
object.
data (pointer and length) - Particle.publish - Publish
In Device OS 6.2 and later, the data can be specified with a pointer and length. This is typically used for binary data, and in particular, data that can contain a null byte. It can be used for text if your data source is not null-terminated.
data (EventData) - Particle.publish - Publish
The EventData
overload does not require a ContentType
value because it is used for structured data in a Variant
and is always
encoded as CBOR over-the-air, and JSON in webhooks and other locations. It can optionally include binary data.
contentType
Content Type Constant | MIME Type |
---|---|
ContentType::TEXT |
text/plain; charset=utf-8 |
ContentType::JPEG |
image/jpeg |
ContentType::PNG |
image/png |
ContentType::BINARY |
application/octet-stream |
The content type provides a hint to the receiver for what the data is. This includes the console, which can render some types of data in the event stream.
Future - Particle.publish - Publish
The return type of the Particle.publish
function is particle::Future<bool>
. There are three common ways to use this:
// EXAMPLE 1
Particle.publish("myEvent");
// EXAMPLE 2
bool bResult = Particle.publish("myEvent", eventData, WITH_ACK);
// EXAMPLE 3
Future<bool> futureResult = Particle.publish("myEvent");
In Example 1, you do not care about whether the call succeeds or not, and this will not wait for the data to be acknowledged by the cloud.
In Example 2, you can check bResult. If true, the publish was successfully made to the cloud. This will block until the packet is acknowledged by the cloud.
In Example 3, you use the future which decouples the waiting and the getting results. This can be useful if you are using a finite state machine. See Future for more information.