Arduino-Redis
A Redis library for Arduino.
Classes | Public Types | Public Member Functions | List of all members
Redis Class Reference

Detailed Description

Redis-for-Arduino client interface.

The sole constructor takes a reference to any instance of a Client subclass, allowing it to be used with any library that abstracts the client bytestream in this way (such as the built-in Ethernet class or the WiFiClient for devices such as the ESP8266).

Definition at line 72 of file Redis.h.

Public Types

typedef void(* RedisMsgCallback) (Redis *, String channel, String message)
 
typedef void(* RedisMsgErrorCallback) (Redis *, RedisMessageError)
 

Public Member Functions

 Redis (Client &client)
 
 ~Redis ()
 
 Redis (const Redis &)=delete
 
Redisoperator= (const Redis &)=delete
 
 Redis (const Redis &&)=delete
 
Redisoperator= (const Redis &&)=delete
 
RedisReturnValue authenticate (const char *password)
 
bool set (const char *key, const char *value)
 
String get (const char *key)
 
bool del (const char *key)
 
bool exists (const char *key)
 
int append (const char *key, const char *value)
 
int publish (const char *channel, const char *message)
 
bool expire (const char *key, int seconds)
 
bool expire_at (const char *key, int timestamp)
 
bool pexpire (const char *key, int ms)
 
bool pexpire_at (const char *key, int timestamp)
 
bool persist (const char *key)
 
int pttl (const char *key)
 
int ttl (const char *key)
 
bool hset (const char *key, const char *field, const char *value)
 
bool hsetnx (const char *key, const char *field, const char *value)
 
String hget (const char *key, const char *field)
 
bool hdel (const char *key, const char *field)
 
int hlen (const char *key)
 
int hstrlen (const char *key, const char *field)
 
bool hexists (const char *key, const char *field)
 
String lindex (const char *key, int index)
 
int llen (const char *key)
 
String lpop (const char *key)
 
int lpos (const char *key, const char *element)
 
int lpush (const char *key, const char *value, bool exclusive=false)
 
std::vector< String > lrange (const char *key, int start, int stop)
 
int lrem (const char *key, int count, const char *element)
 
bool lset (const char *key, int index, const char *element)
 
bool ltrim (const char *key, int start, int stop)
 
String rpop (const char *key)
 
int rpush (const char *key, const char *value, bool exclusive=false)
 
bool subscribe (const char *channel)
 
bool psubscribe (const char *pattern)
 
bool unsubscribe (const char *channelOrPattern)
 
RedisSubscribeResult startSubscribing (RedisMsgCallback messageCallback, RedisMsgErrorCallback errorCallback=nullptr)
 
void stopSubscribing ()
 
String info (const char *section)
 
void setTestContext (const void *context)
 
const void * getTestContext ()
 

#include <Redis.h>

Member Typedef Documentation

◆ RedisMsgCallback

typedef void(* Redis::RedisMsgCallback) (Redis *, String channel, String message)

Called upon successful receipt of a pub/sub message on subscribed channel

Definition at line 76 of file Redis.h.

◆ RedisMsgErrorCallback

typedef void(* Redis::RedisMsgErrorCallback) (Redis *, RedisMessageError)

Called upon an error in the receipt of a pub/sub message

Definition at line 78 of file Redis.h.

Constructor & Destructor Documentation

◆ Redis() [1/3]

Redis::Redis ( Client &  client)
inline

Create a Redis connection using Client reference client.

Parameters
clientA Client instance representing the connection to a Redis server.
Returns
An initialized Redis client using client to communicate with the server.

Definition at line 85 of file Redis.h.

◆ ~Redis()

Redis::~Redis ( )
inline

Definition at line 87 of file Redis.h.

◆ Redis() [2/3]

Redis::Redis ( const Redis )
delete

◆ Redis() [3/3]

Redis::Redis ( const Redis &&  )
delete

Member Function Documentation

◆ append()

int Redis::append ( const char *  key,
const char *  value 
)

Appends value to key.

Parameters
key
value
Returns
The length of the string after the append operation.

Definition at line 42 of file Redis.cpp.

◆ authenticate()

RedisReturnValue Redis::authenticate ( const char *  password)

Authenticate with the given password.

Parameters
passwordThe password with which to authenticate.
Returns
RedisReturnValue detailing the result

Definition at line 4 of file Redis.cpp.

◆ del()

bool Redis::del ( const char *  key)

Delete key.

Parameters
key
Returns
true if key was removed.

Definition at line 37 of file Redis.cpp.

◆ exists()

bool Redis::exists ( const char *  key)

Determine if key exists.

Parameters
key
Returns
true if key exists.

Definition at line 52 of file Redis.cpp.

◆ expire()

bool Redis::expire ( const char *  key,
int  seconds 
)
inline

Expire a key in seconds.

Parameters
keyThe key name for which to set expire time.
secondsThe number of seconds (from "now") at which this key will expire.
Returns
true if the expire time was set successfully, false otherwise.

Definition at line 154 of file Redis.h.

◆ expire_at()

bool Redis::expire_at ( const char *  key,
int  timestamp 
)
inline

Expire a key at UNIX timestamp timestamp (seconds since January 1, 1970).

Note
A timestamp in the past will delete the key immediately.
Parameters
keyThe key name for which to set expire time.
timestampThe UNIX timestamp at which this key will expire.
Returns
true if the expire time was set successfully, false otherwise.

Definition at line 163 of file Redis.h.

◆ get()

String Redis::get ( const char *  key)

Get key.

Parameters
keyThe key name to retrieve.
Returns
The key`s value as a string, null if the key does not exist.

Definition at line 32 of file Redis.cpp.

◆ getTestContext()

const void* Redis::getTestContext ( )
inline

Definition at line 382 of file Redis.h.

◆ hdel()

bool Redis::hdel ( const char *  key,
const char *  field 
)

Delete the field stored in hash at key.

Parameters
key
field
Returns
true if deleted

Definition at line 82 of file Redis.cpp.

◆ hexists()

bool Redis::hexists ( const char *  key,
const char *  field 
)

Determine if field exists in hash at key.

Parameters
key
field
Returns
true if key exists.

Definition at line 97 of file Redis.cpp.

◆ hget()

String Redis::hget ( const char *  key,
const char *  field 
)

Gets field stored in hash at key.

Parameters
key
field
Returns
The field`s value.

Definition at line 77 of file Redis.cpp.

◆ hlen()

int Redis::hlen ( const char *  key)

Gets the number of fields stored in hash at key.

Parameters
key
Returns
The number of fields.

Definition at line 87 of file Redis.cpp.

◆ hset()

bool Redis::hset ( const char *  key,
const char *  field,
const char *  value 
)
inline

Set field in hash at key to value.

Parameters
key
field
value
Returns
true if set, false if was updated

Definition at line 212 of file Redis.h.

◆ hsetnx()

bool Redis::hsetnx ( const char *  key,
const char *  field,
const char *  value 
)
inline

Set field in hash at key to value i.f.f. field does not yet exist.

Parameters
key
field
value
Returns
true if set, false if field already existed

Definition at line 221 of file Redis.h.

◆ hstrlen()

int Redis::hstrlen ( const char *  key,
const char *  field 
)

Gets the length of the string at field in hash named key.

Parameters
key
field
Returns
The field's string length value.

Definition at line 92 of file Redis.cpp.

◆ info()

String Redis::info ( const char *  section)

Definition at line 150 of file Redis.cpp.

◆ lindex()

String Redis::lindex ( const char *  key,
int  index 
)

Returns the element of the list stored at index.

Parameters
key
endZero-based element index.
Returns
The element's contents as a String.

Definition at line 110 of file Redis.cpp.

◆ llen()

int Redis::llen ( const char *  key)

Returns the length of the list stored at key. If key does not exist, it is interpreted as an empty list and 0 is returned. An error is returned when the value stored at key is not a list.

Parameters
key
Returns
The length of the list at key.

Definition at line 115 of file Redis.cpp.

◆ lpop()

String Redis::lpop ( const char *  key)

Removes and returns the first element of the list stored at key.

Parameters
key
Returns
The value of the first element, or nil when key does not exist.

Definition at line 120 of file Redis.cpp.

◆ lpos()

int Redis::lpos ( const char *  key,
const char *  element 
)

Returns the index of the first matched element when scanning from head to tail

Parameters
key
element
Returns
The index of the first element, or nil when key does not exist.

Definition at line 125 of file Redis.cpp.

◆ lpush()

int Redis::lpush ( const char *  key,
const char *  value,
bool  exclusive = false 
)

Insert the specified value at the head of the list stored at key (or 'LPUSHX' semantics if exclusive is true)

Parameters
key
value
exclusiveIf set, issues 'LPUSHX' instead of 'LPUSH' which pushes value only if key already exists and holds a list. In contrary to LPUSH, no operation will be performed when key does not yet exist.
Returns
The length of the list after the push operations.

Definition at line 130 of file Redis.cpp.

◆ lrange()

std::vector< String > Redis::lrange ( const char *  key,
int  start,
int  stop 
)

Returns the specified elements of the list stored at key.

Parameters
key
startZero-based starting index (can be negative to indicate end-of-list offset).
endZero-based ending index.
Returns
The list of elements, as a vector of Strings; or an empty vector if error/DNE.

Definition at line 102 of file Redis.cpp.

◆ lrem()

int Redis::lrem ( const char *  key,
int  count,
const char *  element 
)

Removes the first count occurrences of elements equal to element from the list stored at key.

Parameters
key
countif less than zero: removes elements moving from head to tail; if greater than zero, removes from tail to head. if zero, removes all.
element
Returns
The value of the first element, or nil when key does not exist.

Definition at line 135 of file Redis.cpp.

◆ lset()

bool Redis::lset ( const char *  key,
int  index,
const char *  element 
)

Sets the list element at index to element.

Parameters
key
index
element
Returns
success or failure

Definition at line 140 of file Redis.cpp.

◆ ltrim()

bool Redis::ltrim ( const char *  key,
int  start,
int  stop 
)

Trim an existing list so that it will contain only the specified range of elements specified. Both start and stop are zero-based indexes.

Parameters
key
start
stop
Returns
success or failure

Definition at line 145 of file Redis.cpp.

◆ operator=() [1/2]

Redis& Redis::operator= ( const Redis &&  )
delete

◆ operator=() [2/2]

Redis& Redis::operator= ( const Redis )
delete

◆ persist()

bool Redis::persist ( const char *  key)

Persist key (remove any expiry).

Parameters
keyThe key to persist.
Returns
true if the timeout was removed, false if key DNE or had no expiry.

Definition at line 62 of file Redis.cpp.

◆ pexpire()

bool Redis::pexpire ( const char *  key,
int  ms 
)
inline

Expire a key in milliseconds.

Parameters
keyThe key name for which to set expire time.
millisecondsThe number of milliseconds (from "now") at which this key will expire.
Returns
true if the expire time was set successfully, false otherwise.

Definition at line 171 of file Redis.h.

◆ pexpire_at()

bool Redis::pexpire_at ( const char *  key,
int  timestamp 
)
inline

Expire a key at UNIX timestamp timestamp (milliseconds since January 1, 1970).

Note
A timestamp in the past will delete the key immediately.
Parameters
keyThe key name for which to set expire time.
timestampThe UNIX timestamp at which this key will expire.
Returns
true if the expire time was set successfully, false otherwise.

Definition at line 180 of file Redis.h.

◆ psubscribe()

bool Redis::psubscribe ( const char *  pattern)
inline

Sets up a subscription for messages published to any channels matching pattern. May be called in any mode & from message handlers.

Definition at line 354 of file Redis.h.

◆ pttl()

int Redis::pttl ( const char *  key)
inline

Query remaining time-to-live (time-until-expiry) for key.

Parameters
keyThe query whose TTL to query.
Returns
The key`s TTL in milliseconds, or a negative value signaling error: -1 if the key exists but has no associated expire, -2 if the key DNE.

Definition at line 195 of file Redis.h.

◆ publish()

int Redis::publish ( const char *  channel,
const char *  message 
)

Publish message to channel.

Parameters
channelThe channel on which to publish the message.
messageThe message to be published to the channel.
Returns
The number of subscribers to the published message.

Definition at line 47 of file Redis.cpp.

◆ rpop()

String Redis::rpop ( const char *  key)

Removes and returns the last element of the list stored at key.

Parameters
key
Returns
The value of the last element, or nil when key does not exist.

Definition at line 155 of file Redis.cpp.

◆ rpush()

int Redis::rpush ( const char *  key,
const char *  value,
bool  exclusive = false 
)

Insert the specified value at the tail of the list stored at key (or 'RPUSHX' semantics if exclusive is true)

Parameters
key
value
exclusiveIf set, issues 'RPUSHX' instead of 'RPUSH' which pushes value only if key already exists and holds a list. In contrary to RPUSH, no operation will be performed when key does not yet exist.
Returns
The length of the list after the push operations.

Definition at line 160 of file Redis.cpp.

◆ set()

bool Redis::set ( const char *  key,
const char *  value 
)

Set key to value.

Note
Current implementation only supports basic SET without behavioral modification options added in Redis 2.6.12. To expire a set key, use the expire() method below.
Parameters
keyThe key name to set
valueThe value to set for key
Returns
true if key was set to value, false if error.

Definition at line 27 of file Redis.cpp.

◆ setTestContext()

void Redis::setTestContext ( const void *  context)
inline

Definition at line 381 of file Redis.h.

◆ startSubscribing()

RedisSubscribeResult Redis::startSubscribing ( RedisMsgCallback  messageCallback,
RedisMsgErrorCallback  errorCallback = nullptr 
)

Enters subscription mode and subscribes to all channels/patterns setup via subscribe()/psubscribe(). On success, this call will block until stopSubscribing() is called (meaning loop() will never be called!), and only then will return RedisSubscribeSuccess. On remote disconnect, this call will end with the return value RedisSubscribeServerDisconnected, which is generally non-fatal. On failure, this call will return immediately with a return value indicated the failure mode. Calling stopSubscribing() will force this method to exit on the next recieved message.

Parameters
messageCallbackThe function to be called on each successful message receipt.
errorCallbackThe function to be called if message receipt processing produces an error. Call stopSubscribing() on the passed-in instance to end all further message processing.

Definition at line 191 of file Redis.cpp.

◆ stopSubscribing()

void Redis::stopSubscribing ( )
inline

Stops message processing on receipt of next message. Can be called from message handlers.

Definition at line 376 of file Redis.h.

◆ subscribe()

bool Redis::subscribe ( const char *  channel)
inline

Sets up a subscription for messages published to channel. May be called in any mode & from message handlers.

Definition at line 349 of file Redis.h.

◆ ttl()

int Redis::ttl ( const char *  key)
inline

Query remaining time-to-live (time-until-expiry) for key.

Parameters
keyThe query whose TTL to query.
Returns
The key's TTL in seconds, or a negative value signaling error: -1 if the key exists but has no associated expire, -2 if the key DNE.

Definition at line 203 of file Redis.h.

◆ unsubscribe()

bool Redis::unsubscribe ( const char *  channelOrPattern)

Removes a subscription for channelOrPattern. May be called from message handlers.

Definition at line 178 of file Redis.cpp.