# Poco::Redis

# class Client

Library: Redis
Package: Redis
Header: Poco/Redis/Client.h

## Description

Represents a connection to a Redis server.

A command is always made from an Array and a reply can be a signed 64 bit integer, a simple string, a bulk string, an array or an error. The first element of the command array is the Redis command. A simple string is a string that cannot contain a CR or LF character. A bulk string is implemented as an alias for Poco::Nullable<std::string>. This is because a bulk string can represent a Null value.

    BulkString bs = client.execute<BulkString>(...);
    if ( bs.isNull() )
    {
       // We have a Null value
    }
    else
    {
       // We have a string value
    }

To create Redis commands, the factory methods of the Command class can be used or the Array class can be used directly.

    Command llen = Command::llen("list");

is the same as:

    Array command;
    command.add("LLEN").add("list");

or:

    Array command;
    command << "LLEN" << "list";

or even:

    Command command("LLEN");
    command << "list";

Redis client owns a lazily-created AsyncNotificationCenter that can be used to register for connect, disconnect, and error notifications. Use this to monitor the state of the client.

## Member Summary

Member Functions: address, connect, disconnect, execute, flush, isConnected, notificationCenter, readReply, sendCommand, sendCommands, setReceiveTimeout

## Types Aliases

### NotificationCenterPtr

using NotificationCenterPtr = std::shared_ptr < AsyncNotificationCenter >;

### Ptr

using Ptr = SharedPtr < Client >;

## Constructors

### Client

Client();

Creates an unconnected Client. Use this when you want to connect later on.

### Client

Client(
const std::string & hostAndPort
);

Constructor which connects to the given Redis host/port. The host and port must be separated with a colon.

### Client

Client(
const Net::SocketAddress & addrs
);

Constructor which connects to the given Redis host/port.

### Client

Client(
const Net::StreamSocket & socket
);

Constructor which connects using an existing TCP connection. This can be used to connect via TLS, if the given socket is a Poco::Net::SecureStreamSocket.

### Client

Client(
const std::string & host,
int port
);

Constructor which connects to the given Redis host/port.

## Destructor

### ~Client

virtual ~Client();

Destroys the Client.

## Member Functions

### address

Net::SocketAddress address() const;

Returns the address of the Redis connection.

### connect

void connect(
const std::string & hostAndPort
);

Connects to the given Redis server. The host and port must be separated with a colon.

### connect

void connect(
const std::string & host,
int port
);

Connects to the given Redis server.

### connect

void connect(
const Net::SocketAddress & addrs
);

Connects to the given Redis server.

### connect

void connect(
const std::string & hostAndPort,
const Timespan & timeout
);

Connects to the given Redis server. The host and port must be separated with a colon.

### connect

void connect(
const std::string & host,
int port,
const Timespan & timeout
);

Connects to the given Redis server.

### connect

void connect(
const Net::SocketAddress & addrs,
const Timespan & timeout
);

Connects to the given Redis server.

### connect

void connect(
const Net::StreamSocket & socket
);

Connects to the given Redis server using an existing TCP connection. This can be used to connect via TLS, if the given socket is a Poco::Net::SecureStreamSocket.

### disconnect

void disconnect();

Disconnects from the Redis server.

### execute

template < typename T > T execute(
const Array & command
);

Sends the Redis Command to the server. It gets the reply and tries to convert it to the given template type.

A specialization exists for type void, which doesn't read the reply. If the server sends a reply, it is your responsibility to read it. Use this for pipelining.

A Poco::BadCastException will be thrown when the reply couldn't be converted. Supported types are Int64, std::string, BulkString, Array and void. When the reply is an Error, it will throw a RedisException.

### flush

void flush();

Flush the output buffer to Redis. Use this when commands are stored in the buffer to send them all at once to Redis.

### isConnected

bool isConnected() const;

Returns true if and only if the Client is connected to a Redis server.

### notificationCenter

NotificationCenterPtr notificationCenter();

Returns the notification center for this client.

### readReply

RedisType::Ptr readReply();

Read a reply from the Redis server.

### readReply

template < typename T > void readReply(
T & result
);

Read a reply from the Redis server and tries to convert that reply to the template type. When the reply is a Redis error, it will throw a RedisException. A BadCastException will be thrown, when the reply is not of the given type.

### sendCommand

RedisType::Ptr sendCommand(
const Array & command
);

Sends a Redis command to the server and returns the reply. Use this when the type of the reply isn't known.

### sendCommands

Array sendCommands(
const std::vector < Array > & commands
);

Sends all commands (pipelining) to the Redis server before getting all replies.

### setReceiveTimeout

void setReceiveTimeout(
const Timespan & timeout
);

Sets a receive timeout.