diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | README | 116 | ||||
| -rw-r--r-- | TODO | 2 |
3 files changed, 119 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5761abc --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +*.o @@ -0,0 +1,116 @@ +HIREDIS OVERVIEW +---------------- + +Hiredis is a minimalistic C client library for the Redis Database. + +It is minimalistic because it just adds minimal support for the protocol, but +at the same time it uses an high level printf-alike API in order to make it +much higher level than otherwise suggested by its minimal code base and the +lack of explicit bindings for every Redis command. + +Hiredis only supports the Redis new protocol, so you can use it with any +Redis version >= 1.2.0. + +HIREDIS API +----------- + +Hiredis exports only three function calls: + +redisReply *redisConnect(int *fd, char *ip, int port); +redisReply *redisCommand(int fd, char *format, ...); +void freeReplyObject(redisReply *r); + +The first function is used in order to create a connection to the Redis server: + + redisReply *reply; + int fd; + + reply = redisConnect(&fd,"127.0.0.1",6379); + +to test for connection errors all it is needed to do is checking if reply +is not NULL: + + if (reply != NULL) { + printf("Connection error: %s\n", reply->reply); + freeReplyObject(reply); + exit(1); + } + +When a reply object returns an error, the reply->type is set to the value +REDIS_REPLY_ERROR, and reply->reply points to a C string with the description +of the error. + +In the above example we don't check for reply->type as redisConnect() can +only return NULL or a reply object that is actually an error. + +As you can see redisConnect() will just set (by reference) the fd variable +to the file descriptor of the open socket connected to our Redis server. + +Calls to redisCommand() will require this file descriptor as first argument. + +SENDING COMMNADS +---------------- + +Commands are sent using a printf-alike format. In the simplest form it is +like that: + + reply = redisCommand("SET foo bar"); + +But you can use "%s" and "%b" format specifiers to create commands in a +printf-alike fashion: + + reply = redisComand("SET foo %s", somevalue); + +If your arguments are binary safe, you can use %b that receives the pointer +to the buffer and a size_t integer with the length of the buffer. + + reply = redisCommand("SET %s %b", "foo", somevalue, somevalue_length); + +Internally Hiredis will split the command in different arguments and will +convert it to the actual protocol used to communicate with Redis. +Every space will separate arguments, so you can use interpolation. +The following example is valid: + + reply = redisCommand("SET key:%s %s", myid, value); + +USING REPLIES +------------- + +redisCommand() returns a reply object. In order to use this object you +need to test the reply->type field, that can be one of the following types: + +REDIS_REPLY_ERROR + The command returned an error string, that can be read accessing to + the reply->reply field. + +REDIS_REPLY_STRING + The command returned a string, that can be read accessing to the + reply->reply field. The string is always nul-termined, but when you + need to work with binary-safe strings you can obtain the exact length + of the reply with: sdslen(reply->reply). + +REDIS_REPLY_ARRAY + The command returned an array of reply->elements elements. + Every element is a redisReply object, stored at redis->element[..index..] + Redis may reply with nexted arrays but this is fully supported. + +REDIS_REPLY_INTEGER + The command replies with an integer. It's possible to access this integer + using the reply->integer field that is of type "long long". + +REDIS_REPLY_NIL + The command replies with a NIL special object. There is no data to access. + +FREEING REPLIES +--------------- + +Replies should be freed using the freeReplyObject() function. +Note that this function will take care of freeing sub-replies objects +contained in arrays and nested arrays, so there is no need for the user to +free the sub replies (it is actually harmful and will corrupt the memory). + +AUHTOR +------ + +Hiredis was written by Salvatore Sanfilippo (antirez at gmail) and is +released under the BSD license. @@ -0,0 +1,2 @@ +- add redisCommandVector() +- add tests |