DeviceNameHelper Class Reference

Generic base class used by all storage methods. More...

#include <DeviceNameHelperRK.h>

Inheritance diagram for DeviceNameHelper:

Public Member Functions
void	loop ()
	You must call this from loop on every call to loop()
DeviceNameHelper &	withNameCallback (std::function< void(const char *)> nameCallback)
	Adds a function to call when the name is known. More...
DeviceNameHelper &	withCheckPeriod (std::chrono::seconds checkPeriod)
	Sets. More...
bool	hasName () const
	Returns true if the name has been retrived and is non-empty.
const char *	getName () const
	Returns the device name as a c-string. More...
long	getLastNameCheckTime () const
	Get the time the name was last fetched. More...
void	checkName ()
	Request the name again. More...
void	subscriptionRemoved ()
	Call if you've called Particle.unsubscribe. More...

Static Public Member Functions
static DeviceNameHelper *	getInstance ()
	Special generic instance getter. More...

Static Public Attributes
static const uint32_t	DATA_MAGIC = 0x7787a2f2
	Magic bytes used to detect if EEPROM or retained memory has been initialized.

Protected Member Functions
	DeviceNameHelper ()
	Constructor - You never instantiate this class directly. More...
virtual	~DeviceNameHelper ()
	This class is a singleton and never deleted.
	DeviceNameHelper (const DeviceNameHelper &)=delete
	This class is not copyable.
DeviceNameHelper &	operator= (const DeviceNameHelper &)=delete
	This class is not copyable.
void	commonSetup ()
	All of the storage-method specific setup methods call that at the end.
virtual void	save ()
	This method is called to save the DeviceNameHelperData. More...
void	stateStart ()
	State handler, entry point when starting up. More...
void	stateSubscribe ()
	Add a subscription handler, if necessary. More...
void	stateWaitConnected ()
	Waits until Particle.connected() and Time.isValid() are true. More...
void	stateWaitRequest ()
	Waits POST_CONNECT_WAIT_MS milliseconds (2 seconds) then publishes the request for device name event "particle/device/name". More...
void	stateWaitResponse ()
	Waits for a device name event to be received. More...
void	stateWaitRetry ()
	Waits 5 minutes (RETRY_WAIT_MS) and tries requesting the name again. More...
void	stateWaitRecheck ()
	Wait until it's time to check the name again. More...
void	subscriptionHandler (const char *eventName, const char *eventData)
	Subscription handler for the "particle/device/name" event. More...

Protected Attributes
DeviceNameHelperData *	data = 0
	DeviceNameHelperData structure pointer. More...
std::chrono::seconds	checkPeriod = 0s
	How often to fetch the name again in seconds (0 = never check again)
std::function< void(const char *)>	nameCallback = 0
	Optional function or C++11 lambda to call when the name is known. More...
std::function< void(DeviceNameHelper &)>	stateHandler = 0
	Current state handler, or NULL if in done state.
unsigned long	stateTime = 0
	Some states use this for timing. It's a value from millis() if used.
bool	hasSubscribed = false
	true if Particle.subscribe has been called
bool	gotResponse = false
	true if the event subscription handler was called. The name is stored in data.name.
bool	forceCheck = false
	Used by checkName() to force the name to be checked again.

Static Protected Attributes
static const unsigned long	POST_CONNECT_WAIT_MS = 2000
	Amount of time to wait after connection for the subscription to be activated (milliseconds)
static const unsigned long	RESPONSE_WAIT_MS = 15000
	How long to wait for a device name response before timing out and waiting to retry (milliseconds)
static const unsigned long	RETRY_WAIT_MS = 5 * 60 * 1000
	How long to wait to retry a request to get the device name (in milliseconds)
static DeviceNameHelper *	_instance = 0
	Singleton instance pointer, set by the subclass instance() methods.

Detailed Description

Generic base class used by all storage methods.

You can't instantiate one of these, you need to instantiate a specific subclass such as DeviceNameHelperEEPROM, DeviceNameHelperRetained, or DeviceNameHelperNoStorage.

Constructor & Destructor Documentation

DeviceNameHelper()

DeviceNameHelper::DeviceNameHelper ( )

protected

Constructor - You never instantiate this class directly.

Instead, get a singleton instance of a subclass by using DeviceNameHelperRetained::instance(), DeviceNameHelperEEPROM.instance(), DeviceNameHelperNoStorage::instance(), or DeviceNameHelperFile::instance().

Member Function Documentation

checkName()

void DeviceNameHelper::checkName

(

)

Request the name again.

This overrides the periodic check period and requests the name to be checked now, even if it's known and it's not time to check.

getInstance()

static DeviceNameHelper* DeviceNameHelper::getInstance ( )

inlinestatic

Special generic instance getter.

Returns

A DeviceNameHelper*, or NULL if it hasn't been instantiated yet.

Normally you use a specific instance getter like DeviceNameHelperEEPROM::instance() which will create the singleton instance if it has not been instantiated yet.

In some rare cases, you may want to get the generic instance pointer, if an instance has been created. You'd typically do this if you wanted to get the name if DeviceNameHelperNoStorage has been set up, without having to know which storage method was used.

Note that this method will not instantiate the singleton if it does not exist since it doesn't know which one you want. Thus it returns a pointer to the object not a reference, so it can return NULL if the instance does not exist yet.

getLastNameCheckTime()

long DeviceNameHelper::getLastNameCheckTime ( ) const

inline

Get the time the name was last fetched.

Value is from from Time.now(), seconds past January 1, 1970, UTC.

getName()

const char* DeviceNameHelper::getName ( ) const

inline

Returns the device name as a c-string.

May return an empty string if the name has not been retrieved yet

save()

void DeviceNameHelper::save ( )

protectedvirtual

This method is called to save the DeviceNameHelperData.

This is called always. This base class does nothing. The DeviceNameHelperEEPROM and DeviceNameHelperFile subclasses override this to save the data.

Reimplemented in DeviceNameHelperFile, and DeviceNameHelperEEPROM.

stateStart()

void DeviceNameHelper::stateStart ( )

protected

State handler, entry point when starting up.

If the device name is saved, this will return quickly without enabling the device name subscription handler.

Next state: stateWaitRecheck - If the device name is set stateSubscribe - If the device name needs to be retrieved

stateSubscribe()

void DeviceNameHelper::stateSubscribe ( )

protected

Add a subscription handler, if necessary.

Next state: stateWaitConnected

stateWaitConnected()

void DeviceNameHelper::stateWaitConnected ( )

protected

Waits until Particle.connected() and Time.isValid() are true.

Next state: stateWaitRequest

stateWaitRecheck()

void DeviceNameHelper::stateWaitRecheck ( )

protected

Wait until it's time to check the name again.

Next state: stateSubscribe if it's time to check the name again NULL if we're done

stateWaitRequest()

void DeviceNameHelper::stateWaitRequest ( )

protected

Waits POST_CONNECT_WAIT_MS milliseconds (2 seconds) then publishes the request for device name event "particle/device/name".

Next state: stateWaitResponse

stateWaitResponse()

void DeviceNameHelper::stateWaitResponse ( )

protected

Waits for a device name event to be received.

If the name is received, it is saved (if necessary) and the name callback is called (if present).

Next state: stateWaitRecheck - name was found stateWaitRetry - timeout (RESPONSE_WAIT_MS, 15 seconds) or empty name

stateWaitRetry()

void DeviceNameHelper::stateWaitRetry ( )

protected

Waits 5 minutes (RETRY_WAIT_MS) and tries requesting the name again.

Next state: stateWaitConnected

subscriptionHandler()

void DeviceNameHelper::subscriptionHandler ( const char *  eventName, const char *  eventData  )

protected

Subscription handler for the "particle/device/name" event.

Since there's no way to unsubscribe a single subscription handler, it's never removed. See subscriptionRemoved() if you call Particle.unsubscribe() from your code (which is rare).

subscriptionRemoved()

void DeviceNameHelper::subscriptionRemoved ( )

inline

Call if you've called Particle.unsubscribe.

There is no function to remove a single subscription handler; Particle.unsubscribe unsubscribes all handlers. Also, there is no way to tell if a subscription handler has been added when using a C++ class as the handler. Thus we use a flag to keep track if whether we've subscribed or not.

But if you call Particle.unsubscribe() the flag could be set but the subscription would no longer exist, so the subscription wouldn't work and the device name could not be retrieved.

This function is used to rectify this rare condition.

withCheckPeriod()

DeviceNameHelper& DeviceNameHelper::withCheckPeriod ( std::chrono::seconds  checkPeriod )

inline

Sets.

Parameters

checkPeriod

How often to check. You can use chrono literals such as 24h for to check once a day, for example.

Returns

*this, so you can chain the withXXX() calls, fluent-style.

The default is to check once. After the name has been retrieved it will not be retrieved again. This also means that if the name is ever changed, the change would not be detected.

withNameCallback()

DeviceNameHelper & DeviceNameHelper::withNameCallback

(

std::function< void(const char *)>

nameCallback

)

Adds a function to call when the name is known.

Parameters

nameCallback

The function to call. It can be a C++11 lambda.

Returns

*this, so you can chain the withXXX() calls, fluent-style.

The name callback function has the prototype:

void callback(const char *name)

The name is the device name, as a c-string (null terminated).

Field Documentation

data

DeviceNameHelperData* DeviceNameHelper::data = 0

protected

DeviceNameHelperData structure pointer.

For DeviceNameHelperRetained, this points to the actual retained memory. For all other storage members, it points to a class member variable for the singleton instance.

nameCallback

std::function<void(const char *)> DeviceNameHelper::nameCallback = 0

protected

Optional function or C++11 lambda to call when the name is known.

This can occur during setup() if the name is saved, otherwise it will occur later, after connecting to the cloud.

---

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

• src/DeviceNameHelperRK.h
• src/DeviceNameHelperRK.cpp