EdgeEventQueueRK Class Reference

Class for managing a private queue of events on the flash file system. More...

#include <EdgeEventQueueRK.h>

Public Member Functions
	EdgeEventQueueRK ()
	Constructor.
virtual	~EdgeEventQueueRK ()
	Destructor.
int	setup ()
	Call during setup(), the main application setup function.
void	loop ()
	Call during loop(), the main application loop function.
EdgeEventQueueRK &	withPriority (size_t priority)
	Sets the priority to use for publishing. Default is 0.
EdgeEventQueueRK &	withPublishFlags (PublishFlags flags)
	Sets the publish flags such as NO_ACK.
EdgeEventQueueRK &	withSizeLimit (size_t sizeLimit)
	Set the disk queue size limit (in bytes). Default is 0 (not limited).
EdgeEventQueueRK &	withDiskQueuePolicy (DiskQueuePolicy policy)
	Sets the disk queue policy for deleting events when the queue is full.
EdgeEventQueueRK &	withQueuePath (const char *path)
	Sets the queue path. Default is "/usr/privateq". Typically put in "/usr/" directory.
int	publish (const char *eventName, const char *eventData)
	Add an event to the publish queue on the flash file system.

Static Public Member Functions
static int	cloudServicePublish (const char *eventName, const char *eventData, PublishFlags publishFlags={}, size_t priority=0, std::function< int(CloudServiceStatus)> cb=0)
	Publishes an event using the cloud service without using the disk queue.

Detailed Description

Class for managing a private queue of events on the flash file system.

The CloudService has a different prototype on Tracker Edge and Monitor Edge. These defines can be used to determine which Edge firmware you are using. This class defines a common API so you don't have to worry about it from your code.

Only available on devices using TrackerEdge or MonitorEdge, as it utilizes the DiskQueue and CloudService classes.

When metering out events to stay within the rate limit, this interleaves your private events and the system events so you won't exceed the rate limit.

A queue size limit specified in this class is independent of the one set in the cloud configuration. There is no checking done to make sure there's enough disk space available across all queues.

Constructor & Destructor Documentation

EdgeEventQueueRK()

EdgeEventQueueRK::EdgeEventQueueRK

(

)

Constructor.

Construct one of these object for each queue. Often there will only be one, but the code supports multiple queues. It is typically constructed as a global object.

~EdgeEventQueueRK()

EdgeEventQueueRK::~EdgeEventQueueRK ( )

virtual

Destructor.

This is typically not used as the object is typically instantiated as a global object.

Member Function Documentation

cloudServicePublish()

int EdgeEventQueueRK::cloudServicePublish ( const char *  eventName, const char *  eventData, PublishFlags  publishFlags = {}, size_t  priority = 0, std::function< int(CloudServiceStatus)>  cb = 0  )

static

Publishes an event using the cloud service without using the disk queue.

Parameters

eventName	The event name, as is used in Particle.publish.
eventData	The event data, as is used in Particle.publish
publishFlags	Publish flags, as is used in Particle.publish. This is optional, and if omitted the default flags are used.
priority	0 or 1. 0 is the default queue and 1 is the low priority queue.
cb	Callback function to be called on successful completion or error. Optional. Not called if an immediate error results in a non-zero result code; callback is only called if the return value is 0.

Returns

int 0 on success or a non-zero error code

The callback function has this prototype:

int callback(CloudServiceStatus status)

• status is particle::Error::NONE (0) or an system error code on error

It is a std::function so you can pass a lambda, which allows you to pass additional data via capture variables, or call a C++ class method and instance easily.

The eventName and eventValue are copied and do not need to remain valid until the callback is called. Once the cloudServicePublish call returns, the variables can go out of scope, so it's safe for them to be local variables on the stack.

Using cloudServicePublish interleaves your event with others in the system in a queue in RAM. The queue is finite in size (currently 8 elements per priority queue) and if the queue is full, -EBUSY (-16) is returned.

Note that this function does not use the disk queue! It's a low-level function used by the publish method in this class, or you can use it for your own purposes if you want to publish events that are not saved to disk if the device is currently offline.

loop()

void EdgeEventQueueRK::loop

(

)

Call during loop(), the main application loop function.

Typically used as: EdgeEventQueueRK::instance().loop();

publish()

int EdgeEventQueueRK::publish	(	const char *	eventName,
		const char *	eventData
	)

Add an event to the publish queue on the flash file system.

Parameters

eventName	The event name, as is used in Particle.publish
eventData	The event data, as is used in Particle.publish

Returns

int 0 on success or a non-zero error code

The eventName and eventValue are copied and do not need to remain valid until the callback is called. Once the publish call returns, the variables can go out of scope, so it's safe for them to be local variables on the stack.

setup()

int EdgeEventQueueRK::setup

(

)

Call during setup(), the main application setup function.

Returns

0 on success or a non-zero error code

Typically used as: EdgeEventQueueRK::instance().setup();

Call the withXXX() methods to set configuration parameters before setup!

withDiskQueuePolicy()

EdgeEventQueueRK & EdgeEventQueueRK::withDiskQueuePolicy ( DiskQueuePolicy  policy )

inline

Sets the disk queue policy for deleting events when the queue is full.

Parameters

policy

DiskQueuePolicy::FifoDeleteOld (default) or DiskQueuePolicy::FifoDeleteNew

Returns

EdgeEventQueueRK& Reference to this object to chain, fluent-style

withPriority()

EdgeEventQueueRK & EdgeEventQueueRK::withPriority ( size_t  priority )

inline

Sets the priority to use for publishing. Default is 0.

Parameters

priority

0 or 1. 0 is the default queue and 1 is the low priority queue.

Returns

EdgeEventQueueRK& Reference to this object to chain, fluent-style

withPublishFlags()

EdgeEventQueueRK & EdgeEventQueueRK::withPublishFlags ( PublishFlags  flags )

inline

Sets the publish flags such as NO_ACK.

Parameters

flags

Returns

EdgeEventQueueRK&

withQueuePath()

EdgeEventQueueRK & EdgeEventQueueRK::withQueuePath ( const char *  path )

inline

Sets the queue path. Default is "/usr/privateq". Typically put in "/usr/" directory.

Parameters

path	Typically put in "/usr/" directory. Does not need to exist; will be created if it does not exist.

Returns

EdgeEventQueueRK& Reference to this object to chain, fluent-style

withSizeLimit()

EdgeEventQueueRK & EdgeEventQueueRK::withSizeLimit ( size_t  sizeLimit )

inline

Set the disk queue size limit (in bytes). Default is 0 (not limited).

Returns

EdgeEventQueueRK& Reference to this object to chain, fluent-style

---

The documentation for this class was generated from the following files:

• src/EdgeEventQueueRK.h
• src/EdgeEventQueueRK.cpp