PublishQueueExt Class Reference

Class for asynchronous publishing of events. More...

#include <PublishQueueExtRK.h>

Data Structures
struct	QueueFileTrailer
	This structure is at the end of the publish queue file. More...

Public Member Functions
PublishQueueExt &	withFileQueueSize (size_t size)
	Sets the file-based queue size (default is 100)
size_t	getFileQueueSize () const
	Gets the file queue size.
PublishQueueExt &	withDirPath (const char *dirPath)
	Sets the directory to use as the queue directory. This is required!
const char *	getDirPath () const
	Gets the directory path set using withDirPath()
PublishQueueExt &	withPublishCompleteUserCallback (std::function< void(const CloudEvent &event)> cb)
	Adds a callback function to call with publish is complete.
void	setup ()
	You must call this from setup() to initialize this library.
void	loop ()
	You must call the loop method from the global loop() function!
bool	publish (CloudEvent event)
	Publish an event.
bool	publish (const char *eventName)
	Overload for publishing an event.
bool	publish (const char *eventName, const char *data)
	Overload for publishing an event.
bool	publish (const char *eventName, const Variant &data)
	Overload for publishing an event from a Variant.
bool	publish (const char *eventName, const Variant &data, ContentType type)
	Overload for publishing an event with a Variant and ContentType.
void	clearQueues ()
	Empty the file based queue. Any queued events are discarded and the files deleted.
void	setPausePublishing (bool value)
	Pause or resume publishing events.
bool	getPausePublishing () const
	Gets the state of the pause publishing flag.
bool	getCanSleep () const
	Determine if it's a good time to go to sleep.
size_t	getNumEvents ()
	Gets the total number of events queued.
void	checkQueueLimits ()
	Check the queue limit, discarding events as necessary.
void	lock ()
	Lock the queue protection mutex.
bool	tryLock ()
	Attempt the queue protection mutex.
void	unlock ()
	Unlock the queue protection mutex.

Static Public Member Functions
static PublishQueueExt &	instance ()
	Gets the singleton instance of this class.

Static Public Attributes
static const uint32_t	kQueueFileTrailerMagic = 0x55fcab58
	Magic bytes stored in the QueueFileTrailer structure.

Protected Member Functions
	PublishQueueExt ()
	Constructor.
virtual	~PublishQueueExt ()
	Destructor.
	PublishQueueExt (const PublishQueueExt &)=delete
	This class is not copyable.
PublishQueueExt &	operator= (const PublishQueueExt &)=delete
	This class is not copyable.
void	deleteCurEvent ()
	Delete the current event in curFileNum.
void	stateConnectWait ()
	State handler for waiting to connect to the Particle cloud.
void	stateWaitEvent ()
	State handler for waiting for an event.
void	statePublishWait ()
	State handler for waiting for publish to complete.

Protected Attributes
SequentialFile	fileQueue
	SequentialFileRK library object for maintaining the queue of files on the POSIX file system.
String	tempFileName = "temp.dat"
	File used for temporary data.
String	tempFilePath
	Fill path name to tempFileName.
size_t	fileQueueSize = 100
	size of the queue on the flash file system
os_mutex_recursive_t	mutex
	mutex for protecting the queue
CloudEvent	curEvent
	Current event being published.
int	curFileNum = 0
	Current file number being published.
unsigned long	stateTime = 0
	millis() value when entering the state, used for stateWait
unsigned long	durationMs = 0
	how long to wait before publishing in milliseconds, used in stateWait
bool	pausePublishing = false
	flag to pause publishing (used from automated test)
bool	canSleep = false
	returns true if this is a good time to go to sleep
unsigned long	waitAfterConnect = 500
	time to wait after Particle.connected() before publishing
unsigned long	waitBetweenPublish = 10
	how long to wait in milliseconds between publishes
unsigned long	waitAfterFailure = 30000
	how long to wait after failing to publish before trying again
std::function< void(const CloudEvent &event)	publishCompleteUserCallback ) = 0
	User callback for publish complete.
std::function< void(PublishQueueExt &)	stateHandler ) = 0
	state handler (stateConnectWait, stateWait, etc).

Static Protected Attributes
static PublishQueueExt *	_instance
	singleton instance of this class

Detailed Description

Class for asynchronous publishing of events.

Constructor & Destructor Documentation

PublishQueueExt()

PublishQueueExt::PublishQueueExt ( )

protected

Constructor.

This class is a singleton; you never create one of these directly. Use PublishQueueExt::instance() to get the singleton instance.

~PublishQueueExt()

PublishQueueExt::~PublishQueueExt ( )

protectedvirtual

Destructor.

This class is never deleted; once the singleton is created it cannot be destroyed.

Member Function Documentation

getCanSleep()

bool PublishQueueExt::getCanSleep ( ) const

inline

Determine if it's a good time to go to sleep.

If a publish is not in progress and the queue is empty, returns true.

If pausePublishing is true, then return true if either the current publish has completed, or not cloud connected.

getDirPath()

const char * PublishQueueExt::getDirPath ( ) const

inline

Gets the directory path set using withDirPath()

The returned path will not end with a slash.

getNumEvents()

size_t PublishQueueExt::getNumEvents

(

)

Gets the total number of events queued.

This operation is fast; the file queue length is stored in RAM, so this command does not need to access the file system.

If an event is currently being sent, the result includes this event.

instance()

PublishQueueExt & PublishQueueExt::instance ( )

static

Gets the singleton instance of this class.

You cannot construct a PublishQueueExt object as a global variable, stack variable, or with new. You can only request the singleton instance.

lock()

void PublishQueueExt::lock ( )

inline

Lock the queue protection mutex.

This is done internally; you probably won't need to call this yourself. It needs to be public for the WITH_LOCK() macro to work properly.

publish() [1/5]

bool PublishQueueExt::publish

(

CloudEvent

event

)

Publish an event.

Parameters

event

Returns

true

false

publish() [2/5]

bool PublishQueueExt::publish

(

const char *

eventName

)

Overload for publishing an event.

Parameters

eventName

The name of the event (63 character maximum).

Returns

true if the event was queued or false if it was not.

This function almost always returns true. If you queue more events than fit in the buffer the oldest (sometimes second oldest) is discarded.

publish() [3/5]

bool PublishQueueExt::publish	(	const char *	eventName,
		const char *	data )

Overload for publishing an event.

Parameters

eventName	The name of the event (63 character maximum).
data	The UTF-8 text event data as a c-string. It is copied by this method.

Returns

true if the event was queued or false if it was not.

This function almost always returns true. If you queue more events than fit in the buffer the oldest (sometimes second oldest) is discarded.

publish() [4/5]

bool PublishQueueExt::publish	(	const char *	eventName,
		const Variant &	data )

Overload for publishing an event from a Variant.

Parameters

eventName	The name of the event (63 character maximum).
data	Reference to a Variant object holding the data. It is copied by this method.

Returns

true if the event was queued or false if it was not.

This function almost always returns true. If you queue more events than fit in the buffer the oldest (sometimes second oldest) is discarded.

In some cases the content type can be inferred, such as when the Variant is a VariantMap but normally you will want to use the overload with a ContentType.

publish() [5/5]

bool PublishQueueExt::publish	(	const char *	eventName,
		const Variant &	data,
		ContentType	type )

Overload for publishing an event with a Variant and ContentType.

Parameters

eventName	The name of the event (63 character maximum).
data	Reference to a Variant object holding the data. It is copied by this method.
type	The ContentType of the data

Returns

true if the event was queued or false if it was not.

This function almost always returns true. If you queue more events than fit in the buffer the oldest (sometimes second oldest) is discarded.

Content Type Constant MIME Type Value ContentType::TEXT text/plain; charset=utf-8 0 ContentType::JPEG image/jpeg 22 ContentType::PNG image/png 23 ContentType::BINARY application/octet-stream 42 ContentType::STRUCTURED 65001

setPausePublishing()

void PublishQueueExt::setPausePublishing

(

bool

value

)

Pause or resume publishing events.

Parameters

value

The value to set, true = pause, false = normal operation

If called while a publish is in progress, that publish will still proceed, but the next event (if any) will not be attempted.

This is used by the automated test tool; you probably won't need to manually manage this under normal circumstances.

stateConnectWait()

void PublishQueueExt::stateConnectWait ( )

protected

State handler for waiting to connect to the Particle cloud.

Next state: stateWait

statePublishWait()

void PublishQueueExt::statePublishWait ( )

protected

State handler for waiting for publish to complete.

Next state: stateWait

stateWaitEvent()

void PublishQueueExt::stateWaitEvent ( )

protected

State handler for waiting for an event.

stateTime and durationMs determine whether to stay in this state waiting, or whether to publish and go into statePublishWait.

Next state: stateWaitRateLimit or stateConnectWait

withDirPath()

PublishQueueExt & PublishQueueExt::withDirPath ( const char * dirPath )

inline

Sets the directory to use as the queue directory. This is required!

Parameters

dirPath

the pathname, Unix-style with / as the directory separator.

Typically you create your queue either at the top level ("/myqueue") or in /usr ("/usr/myqueue"). The directory will be created if necessary, however only one level of directory will be created. The parent must already exist.

The dirPath can end with a slash or not, but if you include it, it will be removed.

You must call this as you cannot use the root directory as a queue!

withFileQueueSize()

PublishQueueExt & PublishQueueExt::withFileQueueSize

(

size_t

size

)

Sets the file-based queue size (default is 100)

Parameters

size	The maximum number of files to store (one event per file)

If you exceed this number of events, the oldest event is discarded.

withPublishCompleteUserCallback()

PublishQueueExt & PublishQueueExt::withPublishCompleteUserCallback ( std::function< void(const CloudEvent &event)> cb )

inline

Adds a callback function to call with publish is complete.

Parameters

cb	Callback function or C++ lambda.

Returns

PublishQueueExt&

The callback has this prototype and can be a function or a C++11 lambda, which allows the callback to be a class method.

void callback(const CloudEvent &event)

The parameters are:

• event: The CloudEvent object that was just sent

You can determine success/failure, examine the event. or the event data, by using methods of the CloudEvent class

Note that this callback will be called from the background thread used for publishing. You should not perform any lengthy operations and you should avoid using large amounts of stack space during this callback.

---

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

• src/PublishQueueExtRK.h
• src/PublishQueueExtRK.cpp