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 87 of file Redis.h.

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

Public Member Functions
	Redis (Client &client)
	~Redis ()
	Redis (const Redis &)=delete
Redis &	operator= (const Redis &)=delete
	Redis (const Redis &&)=delete
Redis &	operator= (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)
bool	tsadd (const char *key, long timestamp, const int value)
int	xack (const char *key, const char *group, const char *id)
String	xadd (const char *key, const char *id, const char *field, const char *value)
std::vector< String >	xautoclaim (const char *key, const char *group, const char *consumer, unsigned int min_idle_time, const char *start, unsigned int count, bool justid)
std::vector< String >	xclaim (const char *key, const char *group, const char *consumer, unsigned int min_idle_time, const char *id, unsigned int idle_ms, unsigned int time_ms, unsigned int retrycount, bool force, bool justid, const char *lastid)
int	xdel (const char *key, const char *id)
bool	xgroup_create (const char *key, const char *group, const char *id, bool mkstream)
int	xgroup_createconsumer (const char *key, const char *group, const char *consumer)
int	xgroup_delconsumer (const char *key, const char *group, const char *consumer)
int	xgroup_destroy (const char *key, const char *group)
bool	xgroup_setid (const char *key, const char *group, const char *id)
std::vector< String >	xinfo_consumers (const char *key, const char *group)
std::vector< String >	xinfo_groups (const char *key)
std::vector< String >	xinfo_stream (const char *key, bool full, unsigned int count)
int	xlen (const char *key)
std::vector< String >	xpending (const char *key, const char *group, unsigned int min_idle_time, const char *start, const char *end, unsigned int count, const char *consumer)
std::vector< String >	xrange (const char *key, const char *start, const char *end, unsigned int count)
std::vector< String >	xread (unsigned int count, unsigned int block, const char *key, const char *id)
std::vector< String >	xreadgroup (const char *group, const char *consumer, unsigned int count, unsigned int block_ms, bool noack, const char *key, const char *id)
std::vector< String >	xrevrange (const char *key, const char *end, const char *start, unsigned int count)
int	xtrim (const char *key, const char *strategy, XtrimCompareType compare, int threshold, int count)
bool	isErrorReturn (std::vector< String > &returnVec)
bool	isNilReturn (String returnString)
RedisSubscribeResult	startSubscribing (RedisMsgCallback messageCallback, RedisMsgErrorCallback errorCallback=nullptr)
RedisSubscribeResult	startSubscribingNonBlocking (RedisMsgCallback messageCallback, LoopCallback loopCallback, RedisMsgErrorCallback errorCallback=nullptr)
void	stopSubscribing ()
String	info (const char *section)
void	setTestContext (const void *context)
const void *	getTestContext ()

#include <Redis.h>

Member Typedef Documentation

LoopCallback

typedef void(* Redis::LoopCallback) ()

Definition at line 92 of file Redis.h.

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 91 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 94 of file Redis.h.

Constructor & Destructor Documentation

Redis() [1/3]

Redis::Redis ( Client &  client )

inline

Create a Redis connection using Client reference client.

Parameters

client

A Client instance representing the connection to a Redis server.

Returns

An initialized Redis client using client to communicate with the server.

Definition at line 101 of file Redis.h.

~Redis()

Redis::~Redis ( )

inline

Definition at line 103 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

password

The 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

key	The key name for which to set expire time.
seconds	The 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 170 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

key	The key name for which to set expire time.
timestamp	The UNIX timestamp at which this key will expire.

Returns

true if the expire time was set successfully, false otherwise.

Definition at line 179 of file Redis.h.

get()

String Redis::get

(

const char *

key

)

Get key.

Parameters

key	The key name to retrieve.

Returns

The key's value as a string or "(nil)" if the key does not exist. Use isNilReturn() to check for the latter in a future-proof way.

Definition at line 32 of file Redis.cpp.

getTestContext()

const void* Redis::getTestContext ( )

inline

Definition at line 636 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 or "(nil)" if the key does not exist. Use isNilReturn() to check for the latter in a future-proof way.

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 228 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 237 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 597 of file Redis.cpp.

isErrorReturn()

bool Redis::isErrorReturn

(

std::vector< String > &

returnVec

)

Check returnVec's first element for a first byte of "-":

Parameters

returnVec

Returns

true if returnVec is an error, false otherwise

Definition at line 722 of file Redis.cpp.

isNilReturn()

bool Redis::isNilReturn ( String  returnString )

inline

Check returnString for the nil return value (currently "(nil)" to match Redis' underlying value)

Parameters

returnString

Returns

true if returnString is the nil return value, false otherwise

Definition at line 612 of file Redis.h.

lindex()

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

Returns the element of the list stored at index.

Parameters

key
end	Zero-based element index.

Returns

The element's contents as a String or "(nil)" if the index does not exist. Use isNilReturn() to check for the latter in a future-proof way.

Definition at line 121 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 126 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. Use isNilReturn() to check for the latter in a future-proof way.

Definition at line 131 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 136 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
exclusive	If 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 141 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
start	Zero-based starting index (can be negative to indicate end-of-list offset).
end	Zero-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
count	if 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 146 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 151 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 156 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

key	The 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

key	The key name for which to set expire time.
milliseconds	The 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 187 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

key	The key name for which to set expire time.
timestamp	The UNIX timestamp at which this key will expire.

Returns

true if the expire time was set successfully, false otherwise.

Definition at line 196 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 370 of file Redis.h.

pttl()

int Redis::pttl ( const char *  key )

inline

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

Parameters

key	The 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 211 of file Redis.h.

publish()

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

Publish message to channel.

Parameters

channel	The channel on which to publish the message.
message	The 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. Use isNilReturn() to check for the latter in a future-proof way.

Definition at line 602 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
exclusive	If 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 607 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

key	The key name to set
value	The 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 635 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

messageCallback	The function to be called on each successful message receipt.
errorCallback	The 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 717 of file Redis.cpp.

startSubscribingNonBlocking()

RedisSubscribeResult Redis::startSubscribingNonBlocking	(	RedisMsgCallback	messageCallback,
		LoopCallback	loopCallback,
		RedisMsgErrorCallback	errorCallback = nullptr
	)

Definition at line 638 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 630 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 365 of file Redis.h.

tsadd()

bool Redis::tsadd	(	const char *	key,
		long	timestamp,
		const int	value
	)

Append a sample to a time series. If the time series does not exist, it will be automatically created.

Parameters

key	Key name for time series.
timestamp	UNIX sample timestamp in milliseconds. Any negative value given for this parameter will request an automatic timestamp from the system clock.
value	Numeric data value of the sample.

Definition at line 161 of file Redis.cpp.

ttl()

int Redis::ttl ( const char *  key )

inline

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

Parameters

key	The 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 219 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 625 of file Redis.cpp.

xack()

int Redis::xack	(	const char *	key,
		const char *	group,
		const char *	id
	)

Removes one message from the Pending Entries List

Parameters

key
group
id

Returns

The number of the messages successfully acknowledged.

Definition at line 173 of file Redis.cpp.

xadd()

String Redis::xadd	(	const char *	key,
		const char *	id,
		const char *	field,
		const char *	value
	)

Appends the specified stream entry to the stream stored at key.

Parameters

key
id
field
value

Definition at line 178 of file Redis.cpp.

xautoclaim()

std::vector< String > Redis::xautoclaim	(	const char *	key,
		const char *	group,
		const char *	consumer,
		unsigned int	min_idle_time,
		const char *	start,
		unsigned int	count,
		bool	justid
	)

Transfers ownership of pending stream entries that match the criteria. It is equivalent to calling XPENDING and then XCLAIM

Parameters

key
group
min_idle_time
start
count
justid

Definition at line 184 of file Redis.cpp.

xclaim()

std::vector< String > Redis::xclaim	(	const char *	key,
		const char *	group,
		const char *	consumer,
		unsigned int	min_idle_time,
		const char *	id,
		unsigned int	idle_ms,
		unsigned int	time_ms,
		unsigned int	retrycount,
		bool	force,
		bool	justid,
		const char *	lastid
	)

Change the ownership of a pending message

Parameters

key
group
min_idle_time
start
count
justid

Definition at line 218 of file Redis.cpp.

xdel()

int Redis::xdel	(	const char *	key,
		const char *	id
	)

Removes the specified entries from a stream, and returns the number of entries deleted.

Parameters

key
id

Returns

Number of entries deleted.

Definition at line 276 of file Redis.cpp.

xgroup_create()

bool Redis::xgroup_create	(	const char *	key,
		const char *	group,
		const char *	id,
		bool	mkstream
	)

Create a new consumer group uniquely identified by groupname for the stream stored at key

Parameters

key
group
id
mkstream

Returns

The number of the messages successfully acknowledged.

Definition at line 281 of file Redis.cpp.

xgroup_createconsumer()

int Redis::xgroup_createconsumer	(	const char *	key,
		const char *	group,
		const char *	consumer
	)

Create a consumer named consumername in the consumer group groupname of the stream that's stored at key

Parameters

key
id
field
value

Definition at line 294 of file Redis.cpp.

xgroup_delconsumer()

int Redis::xgroup_delconsumer	(	const char *	key,
		const char *	group,
		const char *	consumer
	)

Deletes consumer from the consumer group.

Parameters

key
group
consumer

Returns

The number of pending messages that consumer had before deletion

Definition at line 300 of file Redis.cpp.

xgroup_destroy()

int Redis::xgroup_destroy	(	const char *	key,
		const char *	group
	)

Completely destroys a consumer group

Parameters

key
group

Returns

The number of destroyed consumer groups (0 or 1)

Definition at line 306 of file Redis.cpp.

xgroup_setid()

bool Redis::xgroup_setid	(	const char *	key,
		const char *	group,
		const char *	id
	)

Set the last delivered ID for a consumer group

Parameters

key
group
id

Returns

OK on success

Definition at line 311 of file Redis.cpp.

xinfo_consumers()

std::vector< String > Redis::xinfo_consumers	(	const char *	key,
		const char *	group
	)

Returns the list of consumers that belong to the group consumer group of the stream stored at key

Parameters

key
group

Returns

A formatted vector<String>

Definition at line 316 of file Redis.cpp.

xinfo_groups()

std::vector< String > Redis::xinfo_groups

(

const char *

key

)

Returns the list of all consumer groups of the stream stored at key group of the stream stored at key

Parameters

key

Returns

A formatted vector<String>

Definition at line 335 of file Redis.cpp.

xinfo_stream()

std::vector< String > Redis::xinfo_stream	(	const char *	key,
		bool	full,
		unsigned int	count
	)

Returns the list of all consumer groups of the stream stored at key group of the stream stored at key

Parameters

key
full
count

Returns

A formatted vector<String>

Definition at line 354 of file Redis.cpp.

xlen()

int Redis::xlen

(

const char *

key

)

Returns the number of entries inside a stream at the specified key.

Parameters

key

Returns

Number of entries inside the stream

Definition at line 387 of file Redis.cpp.

xpending()

std::vector< String > Redis::xpending	(	const char *	key,
		const char *	group,
		unsigned int	min_idle_time,
		const char *	start,
		const char *	end,
		unsigned int	count,
		const char *	consumer
	)

Inspect the list of pending messages

Parameters

key
group
min_idle_time
start
end
count
consumer

Definition at line 392 of file Redis.cpp.

xrange()

std::vector< String > Redis::xrange	(	const char *	key,
		const char *	start,
		const char *	end,
		unsigned int	count
	)

Returns the stream entries matching a given range of IDs

Parameters

key
start
end
count

Returns

A formatted vector<String>

Definition at line 433 of file Redis.cpp.

xread()

std::vector< String > Redis::xread	(	unsigned int	count,
		unsigned int	block,
		const char *	key,
		const char *	id
	)

Read data from one stream, only returning entries with an ID greater than the last received ID reported by the caller

Parameters

key
id

Definition at line 461 of file Redis.cpp.

xreadgroup()

std::vector< String > Redis::xreadgroup	(	const char *	group,
		const char *	consumer,
		unsigned int	count,
		unsigned int	block_ms,
		bool	noack,
		const char *	key,
		const char *	id
	)

XREAD version supporting groups

Parameters

group
consumer
count
block
noack
key
id

Definition at line 499 of file Redis.cpp.

xrevrange()

std::vector< String > Redis::xrevrange	(	const char *	key,
		const char *	end,
		const char *	start,
		unsigned int	count
	)

Returns a range with entries in reverse order

Parameters

key
end
start
count

Definition at line 547 of file Redis.cpp.

xtrim()

int Redis::xtrim	(	const char *	key,
		const char *	strategy,
		XtrimCompareType	compare,
		int	threshold,
		int	count
	)

Trims the stream by evicting older entries if needed

Parameters

key
strategy
exact
threshold
count

Definition at line 575 of file Redis.cpp.