Class for the library.
More...
#include <SmsWebhookRK.h>
Class for the library.
It's a singleton, so you always access it using SmsWebhook::instance(). You never allocate one as a global variable, stack variable, or with new.
You must call SmsWebhook::instance().setup() from your global application setup().
You must call SmsWebhook::instance().loop() from your global application loop(). Failure to do so will cause no messages to ever be sent.
To queue a message to be sent, use SmsWebhook::instance().queueSms(mesg). If the device is connected to the Particle cloud, it will go out almost immediately. If an error occurs, it will retry later.
◆ SmsWebhook()
| SmsWebhook::SmsWebhook |
( |
| ) |
|
|
protected |
Constructor (protected)
You never construct one of these - use the singleton instance using SmsWebhook::instance().
◆ ~SmsWebhook()
| SmsWebhook::~SmsWebhook |
( |
| ) |
|
|
protectedvirtual |
Destructor - never used.
The singleton cannot be deleted.
◆ getEventName()
| const char* SmsWebhook::getEventName |
( |
| ) |
const |
|
inline |
Get the previously set event name (or the default, if it hasn't been set yet)
- Returns
- A c-string (null terminated)
◆ getPublishRateLimitMs()
| unsigned long SmsWebhook::getPublishRateLimitMs |
( |
| ) |
const |
|
inline |
Get the previously set publish rate limit value (or the default, if it hasn't been set yet)
- Returns
- An unsigned long value of milliseconds.
◆ getRetryNoRecipientMs()
| unsigned long SmsWebhook::getRetryNoRecipientMs |
( |
| ) |
const |
|
inline |
Get the previously set retry when no recipient is specified value (or the default, if it hasn't been set yet)
- Returns
- An unsigned long value of milliseconds.
◆ getRetryPublishFailMs()
| unsigned long SmsWebhook::getRetryPublishFailMs |
( |
| ) |
const |
|
inline |
Get the previously set retry when publish fails value (or the default, if it hasn't been set yet)
- Returns
- An unsigned long value of milliseconds.
◆ loop()
| void SmsWebhook::loop |
( |
| ) |
|
You must call loop() from global application loop()!
It's normally done like:
Failure to call loop will prevent the library from sending messages.
◆ queueSms()
| void SmsWebhook::queueSms |
( |
SmsMessage |
smsMessage | ) |
|
Queue a SmsMessage to send.
- Parameters
-
| smsMessage | Information about the message to be sent, typically containing a recipient phone number and the message content. |
The smsMessage object is copied by this call. It's safe to make this call from other threads. It cannot be made at ISR time as it does memory allocation.
◆ setup()
| void SmsWebhook::setup |
( |
| ) |
|
You must call setup() from global application setup()!
It's normally done like:
Failure to call setup will prevent the library from doing anything.
◆ withEventName()
| SmsWebhook& SmsWebhook::withEventName |
( |
const char * |
eventName | ) |
|
|
inline |
Sets the event name to use. This must match the webhook. Default is "SendSmsEvent".
- Parameters
-
| eventName | the event name to use |
Event naming rules: 1 - 64 ASCII characters; only use letters, numbers, underscores, dashes and slashes. Spaces and special characters should not be used). Also note that the event name is a prefix, so any event name beginning with that string will trigger the webhook.
◆ withPublishRateLimitMs()
| SmsWebhook& SmsWebhook::withPublishRateLimitMs |
( |
unsigned long |
milliseconds | ) |
|
|
inline |
Sets publish rate limit. If multiple publishes are required, wait this long between publishes. Default is 1010 milliseconds.
- Parameters
-
| milliseconds | New value in milliseconds |
In addition to the Particle publish rate limit, you could also hit a rate limit at Twilio if you need to send a lot of SMS messages.
◆ withRecipientCallback()
| SmsWebhook& SmsWebhook::withRecipientCallback |
( |
std::function< bool(String &phone)> |
recipientCallback | ) |
|
|
inline |
Sets a function to call to get the recipient if the SmsMessage recipient field is black.
- Parameters
-
| recipientCallback | the function to call to find the recipient |
- Returns
- *this, so you can chain this function fluent-style.
The recipientCallback has this prototype:
bool recipientCallback(String &phone);
The callback returns true if the recipient is know, or false if not. The if false is returned, then an attempt will be made again after the timeout.
The phone number must begin with "+" and the country code, so, for example in the US: +15558675310 .
◆ withRetryNoRecipientMs()
| SmsWebhook& SmsWebhook::withRetryNoRecipientMs |
( |
unsigned long |
milliseconds | ) |
|
|
inline |
Sets the retry time when no recipient is specified in milliseconds. Default is 15 seconds.
- Parameters
-
| milliseconds | New value in milliseconds |
If the recipient is not specified in the SmsMessage object, then the recipient callback is used. If the recipient callback returns false (not known yet), the message is left in the queue. This is common if the recipient SMS is sent from the cloud (Particle function, device notes, or Google sheets). This parameter determines how long to wait before checking again.
◆ withRetryPublishFailMs()
| SmsWebhook& SmsWebhook::withRetryPublishFailMs |
( |
unsigned long |
milliseconds | ) |
|
|
inline |
Sets the retry time if the publish fails. Default is 15 seconds.
- Parameters
-
| milliseconds | New value in milliseconds |
If Particle.publish() fails, this is how long to wait before retrying. Note that if the webhook fails this is not consulted, but does take care of the situation where you have poor connectivity and the publish is not able to be sent.
◆ _instance
Singleton instance of this class.
Use instance() to obtain this, dereferenced.
◆ JSON_BUF_SIZE
| const size_t SmsWebhook::JSON_BUF_SIZE = 256 |
|
staticprotected |
Sets the temporary buffer for the JSON data for the publish.
This is allocated on the stack, but is only done from loop() which as a 6K stack. It doesn't make sense for this to be larger than the maximum publish size (622 bytes). Currently the only thing in it is the message and recipient, which probably fit in 160-ish bytes but 256 leaves a little extra room just in case.
◆ publishFuture
| particle::Future<bool> SmsWebhook::publishFuture |
|
protected |
Future used to monitor the state of Particle.publish().
The publish call uses a future so it does not block loop until completion.
◆ retryTimeMs
| unsigned long SmsWebhook::retryTimeMs = 0 |
|
protected |
How long to wait for retry in stateWaitRetry.
This is compared to stateTime in a way that works across millis() rollover every 49 days.
◆ sendQueue
Queue of SmsMessage objects to send.
Objects are enqueued using queueSms() and removed from the state handlers called from loop().
◆ stateHandler
| std::function<void(SmsWebhook &)> SmsWebhook::stateHandler = 0 |
|
protected |
State handler for the main state machine.
The state handler are class method with the prototype:
void stateHandlerMethod();
The documentation for this class was generated from the following files:
static SmsWebhook & instance()
Get the singleton instance of this class.
Definition: SmsWebhookRK.cpp:9
