hiredis API

同步API总览

hiredis主要有以下同步API:

/**连接数据库*/
redisContext *redisConnect(const char *ip, int port);
/**发送命令请求*/
void *redisCommand(redisContext *c, const char *format, ...);
void *redisCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);
void redisAppendCommand(redisContext *c, const char *format, ...);
void redisAppendCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);
/*释放资源*/
void freeReplyObject(void *reply);
void redisFree(redisContext *c);

连接redis数据库

函数原型

redisContext *redisConnect(const char *ip, int port);

参数说明

• port：为redis数据监听的端口号，redis默认监听的端口号为6379
• ip：为redis数据库的IP地址，可以是远程的，也可以是本地的127.0.0.1

返回值

返回值是一个指向redisContext对象，下面是redisContext对象的定义。

typedef struct redisContext {
    int err; /* Error flags, 0 when there is no error */
    char errstr[128]; /* String representation of error when applicable */
    int fd;
    int flags;
    char *obuf; /* Write buffer */
    redisReader *reader; /* Protocol reader */
    enum redisConnectionType connection_type;
    struct timeval *timeout;
    struct {
        char *host;
        char *source_addr;
        int port;
    } tcp;
    struct {
        char *path;
    } unix_sock;
} redisContext;

使用例子

redisContext *c = redisConnect("127.0.0.1", 6379);
if (c == NULL || c->err) {
    if (c) {
        printf("Error: %s\n", c->errstr);
        // handle error
    } else {
        printf("Can't allocate redis context\n");
    }
}

这个redisContext不是一个线程安全的对象，也就是说，多个线程同时访问这一个对象可能会出现问题。

使用redisCommand()执行命令

函数原型

void *redisCommand(redisContext *c, const char *format, ...);

参数说明

• 这个函数是一个带有不定参数的。可以按着format格式给出对应的参数，这就和printf函数类似。
• c 是reidsConnect函数返回的一个对象。

返回值

返回值是一个void类型的指针，实际为指向一个redisReply类型的指针，redisReply的定义如下：

/* This is the reply object returned by redisCommand() */
typedef struct redisReply {
    /*命令执行结果的返回类型*/
    int type; /* REDIS_REPLY_* */
    /*存储执行结果返回为整数*/
    long long integer; /* The integer when type is REDIS_REPLY_INTEGER */
    /*字符串值的长度*/
    size_t len; /* Length of string */
    /*存储命令执行结果返回是字符串*/
    char *str; /* Used for both REDIS_REPLY_ERROR and REDIS_REPLY_STRING */
    /*返回结果是数组的大小*/
    size_t elements; /* number of elements, for REDIS_REPLY_ARRAY */
    /*存储执行结果返回是数组*/
    struct redisReply **element; /* elements vector for REDIS_REPLY_ARRAY */
} redisReply;

• 返回结果的类型reply->type,reply 为一个redisReply* 类型的对象。
• REDIS_REPLY_STRING == 1:返回值是字符串,字符串储存在redis->str当中,字符串长度为redis->len。
• REDIS_REPLY_ARRAY == 2：返回值是数组，数组大小存在redis->elements里面，数组值存储在redis->element[i]里面。数组里面存储的是指向redisReply的指针，数组里面的返回值可以通过redis->element[i]->str来访问，数组的结果里全是type==REDIS_REPLY_STRING的redisReply对象指针。
• REDIS_REPLY_INTEGER == 3：返回值为整数 long long。
• REDIS_REPLY_NIL==4：返回值为空表示执行结果为空。
• REDIS_REPLY_STATUS ==5：返回命令执行的状态，比如set foo bar 返回的状态为OK，存储在str当中 reply->str == “OK”。
• REDIS_REPLY_ERROR ==6 ：命令执行错误,错误信息存放在 reply->str当中。

使用redisCommandArgv()批量执行命令

函数原型

void *redisCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);

参数说明

• argvlen这个数组存储了命令参数中，每一个参数的长度，包含命令本身，比如 set foo bar 则argvlen ={3,3,3},如果argvlen为空，那么这个函数内部会自动调用strlen函数对每个参数进行求长度。
• argv 存放每个命令参数的指针，argv={“set”,“foo”,“bar”}
• argc 存放命令参数的个数上面的例子中argc=3
• c 为redisContext对象。
• 为每一个参数指定长度，可以是二进制安全的函数。函数会按着长度来决定字符串的终止，而不是’\0’.

使用例子

char hkey[] = "123456";
char hset[] = "hset";
char key[] = "testkey";
char hvalue[] = "3210";
int argc = 4;
char *argv[] = {hset,key,hkey,hvalue};
size_t argvlen[] = {4,6,4,3};
redisCommandArgv(context,argc,argv,argvlen);

使用redisAppendCommand()利用管道执行命令

函数原型

void redisAppendCommand(redisContext *c, const char *format, ...);
void redisAppendCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);

参数说明

• redisAppendCommand函数和redisCommand函数参数一致，format可以指定特定参数的类型。
• c 为redisContext对象。
• redisAppendCommandArgv函数和redisCommandArgv函数类似，参数含义也相同。

与redisCommand()和redisCommandArgv()不同的是，这两个函数是把多个命令存放在缓冲区内，然后一起发送给redis服务器，一次执行。可以通过redisGetReply函数从redisContext中取出返回的结果。

使用例子

redisReply *reply;
/*添加命令set */
redisAppendCommand(context,"SET foo bar");
/*添加命令get */
redisAppendCommand(context,"GET foo");
/*获取set命令结果*/
redisGetReply(context,&reply); // reply for SET
freeReplyObject(reply);
/*获取get命令结果*/
redisGetReply(context,&reply); // reply for GET
freeReplyObject(reply);

也可以使用这个功能来实现发布订阅功能

reply = redisCommand(context,"SUBSCRIBE foo");
freeReplyObject(reply);
while(redisGetReply(context,&reply) == REDIS_OK) {
    // 处理所订阅频道的消息
    freeReplyObject(reply);
}

所有的返回结果都需要释放资源调用freeReplyObject函数。这个函数会递归的释放数组中的资源，不需要手动释放数组资源。

获取命令的执行结果

函数原型

redisGetReply函数用来获得执行的结果的一条返回，并存储在reply所指的对象当中。成功返回REDIS_OK,否则返回REIDS_ERR。多条命令的一次性返回结果都存放在redisContext里面。

int redisGetReply(redisContext *context,redisReply** reply);

参数说明

• context 为redisContext对象。
• reply 为执行命令函数的返回值。

使用例子

redisReply *reply = nullptr;
while (REDIS_OK == redisGetReply(this->_subcribe_context, (void **)&reply))
{
    //订阅收到的消息是一个带三元素的数组
    if (reply != nullptr && reply->element[2] != nullptr && reply->element[2]->str != nullptr)
    {
        //给业务层上报通道上发生的消息
        _notify_message_handler(atoi(reply->element[1]->str) , reply->element[2]->str);
    }
    freeReplyObject(reply);
}

释放资源

函数原型

void freeReplyObject(void *reply);
void redisFree(redisContext *c);

参数说明

• freeReplyObject函数中reply 实际为指向redisReply结构体的指针，可能是redisCommand的返回值，后续可以看到以也能是管道命令执行结果的返回值。
• redisFree函数中c实际为指向redisContext对象，这个函数会清理连接资源并释放连接。

异步API总览

异步API的使用方式和同步API差不多，下面列出不同的函数：

//连接redis服务器
redisAsyncContext *c = redisAsyncConnect("127.0.0.1", 6379);
if (c->err) {
        printf("Error: %s\n", c->errstr);
            // handle error
}

//设置连接、断开的钩子函数
int redisAsyncSetConnectCallback(redisAsyncContext *ac, redisConnectCallback *fn);
int redisAsyncSetDisconnectCallback(redisAsyncContext *ac, redisDisconnectCallback *fn);

//插入命令信息
int redisAsyncCommand(redisAsyncContext *ac, redisCallbackFn *fn, void *privdata,const char *format, ...);
int redisAsyncCommandArgv( redisAsyncContext *ac, redisCallbackFn *fn, void *privdata, int argc, const char **argv, const size_t *argvlen);

//关闭连接
void redisAsyncDisconnect(redisAsyncContext *ac);