Murat Kilivan / PubNub

Put a missing NULL character to clear the string

Fork of PubNub by PubNub

PubNub.h@0:9858347c382d, 2014-03-02 (annotated)

Committer:
pasky
Date:
Sun Mar 02 01:32:54 2014 +0000
Revision:
0:9858347c382d
Child:
1:29cc485dcdb1
Initial version: Basic working API + short docs with examples. Please refer to PubNubDemo program for a reference usage code.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
pasky 0:9858347c382d 1 /* PubNub.h */
pasky 0:9858347c382d 2 /* Copyright (c) 2013 PubNub Inc.
pasky 0:9858347c382d 3 * http://www.pubnub.com/
pasky 0:9858347c382d 4 * http://www.pubnub.com/terms
pasky 0:9858347c382d 5 *
pasky 0:9858347c382d 6 * Permission is hereby granted, free of charge, to any person obtaining a copy
pasky 0:9858347c382d 7 * of this software and associated documentation files (the "Software"), to deal
pasky 0:9858347c382d 8 * in the Software without restriction, including without limitation the rights
pasky 0:9858347c382d 9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
pasky 0:9858347c382d 10 * copies of the Software, and to permit persons to whom the Software is
pasky 0:9858347c382d 11 * furnished to do so, subject to the following conditions:
pasky 0:9858347c382d 12 *
pasky 0:9858347c382d 13 * The above copyright notice and this permission notice shall be included in
pasky 0:9858347c382d 14 * all copies or substantial portions of the Software.
pasky 0:9858347c382d 15 *
pasky 0:9858347c382d 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
pasky 0:9858347c382d 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
pasky 0:9858347c382d 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
pasky 0:9858347c382d 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
pasky 0:9858347c382d 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
pasky 0:9858347c382d 21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
pasky 0:9858347c382d 22 * THE SOFTWARE.
pasky 0:9858347c382d 23 */
pasky 0:9858347c382d 24
pasky 0:9858347c382d 25 /** \file
pasky 0:9858347c382d 26 PubNub Client header file
pasky 0:9858347c382d 27 */
pasky 0:9858347c382d 28
pasky 0:9858347c382d 29 #ifndef PubNub_h
pasky 0:9858347c382d 30 #define PubNub_h
pasky 0:9858347c382d 31
pasky 0:9858347c382d 32 #include "TCPSocketConnection.h"
pasky 0:9858347c382d 33
pasky 0:9858347c382d 34
pasky 0:9858347c382d 35 /* TODO: UUID */
pasky 0:9858347c382d 36 /* TODO: secret_key */
pasky 0:9858347c382d 37 /* TODO: cipher_key */
pasky 0:9858347c382d 38 /* TODO: timeout support */
pasky 0:9858347c382d 39
pasky 0:9858347c382d 40 /* Maximum length of the HTTP reply. This buffer is dynamically allocated
pasky 0:9858347c382d 41 * only when loading the reply from the network. */
pasky 0:9858347c382d 42 /* XXX: Replies of API calls longer than this will be discarded and instead,
pasky 0:9858347c382d 43 * PNR_FORMAT_ERROR will be reported. Specifically, this may cause lost
pasky 0:9858347c382d 44 * messages returned by subscribe if too many too large messages got queued. */
pasky 0:9858347c382d 45 #ifndef PUBNUB_REPLY_MAXLEN
pasky 0:9858347c382d 46 #define PUBNUB_REPLY_MAXLEN (2048-8-1)
pasky 0:9858347c382d 47 #endif
pasky 0:9858347c382d 48
pasky 0:9858347c382d 49
pasky 0:9858347c382d 50 /* Result codes for PubNub methods. */
pasky 0:9858347c382d 51 enum PubNubRes {
pasky 0:9858347c382d 52 /* Success. */
pasky 0:9858347c382d 53 PNR_OK,
pasky 0:9858347c382d 54 /* Time out before the request has completed. */
pasky 0:9858347c382d 55 PNR_TIMEOUT,
pasky 0:9858347c382d 56 /* Communication error (network or HTTP response format). */
pasky 0:9858347c382d 57 PNR_IO_ERROR,
pasky 0:9858347c382d 58 /* HTTP error. */
pasky 0:9858347c382d 59 PNR_HTTP_ERROR,
pasky 0:9858347c382d 60 /* Unexpected input in received JSON. */
pasky 0:9858347c382d 61 PNR_FORMAT_ERROR,
pasky 0:9858347c382d 62 /* PubNub JSON reply indicates failure. */
pasky 0:9858347c382d 63 PNR_PUBNUB_ERROR,
pasky 0:9858347c382d 64 };
pasky 0:9858347c382d 65
pasky 0:9858347c382d 66
pasky 0:9858347c382d 67 class PubNub {
pasky 0:9858347c382d 68 public:
pasky 0:9858347c382d 69 /** Init a Pubnub Client context
pasky 0:9858347c382d 70 *
pasky 0:9858347c382d 71 * Note that the string parameters are not copied; do not
pasky 0:9858347c382d 72 * overwrite or free the memory where you stored the keys!
pasky 0:9858347c382d 73 * (If you are passing string literals, don't worry about it.)
pasky 0:9858347c382d 74 *
pasky 0:9858347c382d 75 * All methods are blocking; if you need to communicate with
pasky 0:9858347c382d 76 * PubNub asynchronously, run PubNub in a dedicated thread.
pasky 0:9858347c382d 77 * Always use the PubNub context only in a single thread at once.
pasky 0:9858347c382d 78 *
pasky 0:9858347c382d 79 * Message are passed as strings instead of JSON structures due
pasky 0:9858347c382d 80 * to much higher RAM efficiency. Often, ad hoc composing and
pasky 0:9858347c382d 81 * parsing JSON messages will work fine in practice. Otherwise,
pasky 0:9858347c382d 82 * take a look at e.g. the picojson library.
pasky 0:9858347c382d 83 *
pasky 0:9858347c382d 84 * @param string publish_key required key to send messages.
pasky 0:9858347c382d 85 * @param string subscribe_key required key to receive messages.
pasky 0:9858347c382d 86 * @param string origin optional setting for cloud origin.
pasky 0:9858347c382d 87 * @return boolean whether begin() was successful. */
pasky 0:9858347c382d 88 PubNub(const char *publish_key, const char *subscribe_key, const char *origin = "http://pubsub.pubnub.com");
pasky 0:9858347c382d 89
pasky 0:9858347c382d 90 ~PubNub();
pasky 0:9858347c382d 91
pasky 0:9858347c382d 92 /** Publish
pasky 0:9858347c382d 93 *
pasky 0:9858347c382d 94 * Send a message (assumed to be well-formed JSON) to a given channel.
pasky 0:9858347c382d 95 *
pasky 0:9858347c382d 96 * Examples:
pasky 0:9858347c382d 97 p.publish("demo", "\"lala\"");
pasky 0:9858347c382d 98 * or
pasky 0:9858347c382d 99 if (p.publish("demo", "{\"lala\":1}") != PNR_OK) {
pasky 0:9858347c382d 100 blink_error();
pasky 0:9858347c382d 101 }
pasky 0:9858347c382d 102 *
pasky 0:9858347c382d 103 * @param channel required channel name.
pasky 0:9858347c382d 104 * @param message required JSON message object.
pasky 0:9858347c382d 105 * @param reply optional pointer for passing the returned reply (free() after use).
pasky 0:9858347c382d 106 * @return PNR_OK on success. */
pasky 0:9858347c382d 107 PubNubRes publish(const char *channel, const char *message, char **reply = NULL);
pasky 0:9858347c382d 108
pasky 0:9858347c382d 109 /** Subscribe
pasky 0:9858347c382d 110 *
pasky 0:9858347c382d 111 * Listen for a message on a given channel. The function will block
pasky 0:9858347c382d 112 * and return when a message arrives. Typically, you will run this
pasky 0:9858347c382d 113 * function in a loop to keep listening for messages indefinitely.
pasky 0:9858347c382d 114 *
pasky 0:9858347c382d 115 * As a reply, you will get a JSON message. If you are used to
pasky 0:9858347c382d 116 * PubNub API in other environments, you would expect an array
pasky 0:9858347c382d 117 * of messages; here, even if the device received multiple messages
pasky 0:9858347c382d 118 * batched, they are spread over subsequent PubNub.subscribe() calls
pasky 0:9858347c382d 119 * and each returns only a single message. However, *reply can be
pasky 0:9858347c382d 120 * set NULL - in that case, simply retry the call, this indicates
pasky 0:9858347c382d 121 * an empty reply from the server (what happens e.g. after waiting
pasky 0:9858347c382d 122 * for certain interval, or immediately after subscribing).
pasky 0:9858347c382d 123 *
pasky 0:9858347c382d 124 * Contrary to publish(), you should NOT free() the reply yourself!
pasky 0:9858347c382d 125 * Instead, you are expected to call another subscribe() just after
pasky 0:9858347c382d 126 * processing the reply; subscribe() will release any memory it can
pasky 0:9858347c382d 127 * before waiting for new data from the server.
pasky 0:9858347c382d 128 *
pasky 0:9858347c382d 129 * Examples:
pasky 0:9858347c382d 130 while (1) {
pasky 0:9858347c382d 131 char *reply;
pasky 0:9858347c382d 132 if (p.subscribe("demo", &reply) != PNR_OK) continue;
pasky 0:9858347c382d 133 if (!reply) continue;
pasky 0:9858347c382d 134 int code = -1;
pasky 0:9858347c382d 135 if (sscanf(reply, "{\"code\":%d}", &code) == 1)
pasky 0:9858347c382d 136 printf("received JSON msg with code %d\n", code);
pasky 0:9858347c382d 137 }
pasky 0:9858347c382d 138 *
pasky 0:9858347c382d 139 * @param channel required channel name.
pasky 0:9858347c382d 140 * @param reply required pointer for passing the returned reply (do not free()).
pasky 0:9858347c382d 141 * @return PNR_OK on success. */
pasky 0:9858347c382d 142 PubNubRes subscribe(const char *channel, char **reply);
pasky 0:9858347c382d 143
pasky 0:9858347c382d 144 /* TODO: subscribe_multi */
pasky 0:9858347c382d 145
pasky 0:9858347c382d 146 /** History
pasky 0:9858347c382d 147 *
pasky 0:9858347c382d 148 * Receive list of the last N messages on the given channel.
pasky 0:9858347c382d 149 *
pasky 0:9858347c382d 150 * The messages are returned in the reply buffer, with each message
pasky 0:9858347c382d 151 * terminated by a NUL byte, i.e. being a standalone C string; to
pasky 0:9858347c382d 152 * iterate over all the messages, you can use the replysize. reply
pasky 0:9858347c382d 153 * can be NULL if there is no history for this channel.
pasky 0:9858347c382d 154 *
pasky 0:9858347c382d 155 * Example:
pasky 0:9858347c382d 156 char *reply;
pasky 0:9858347c382d 157 int replysize;
pasky 0:9858347c382d 158 if (p.history("demo", &reply, &replysize) != PNR_OK) return;
pasky 0:9858347c382d 159 if (!reply) return;
pasky 0:9858347c382d 160 for (char *msg = reply; msg < reply + replysize; msg += strlen(msg)+1)
pasky 0:9858347c382d 161 printf("historic message: %s", msg);
pasky 0:9858347c382d 162 free(reply);
pasky 0:9858347c382d 163 *
pasky 0:9858347c382d 164 * @param channel required channel name.
pasky 0:9858347c382d 165 * @param reply required pointer for passing the returned reply (free() after use).
pasky 0:9858347c382d 166 * @param replysize required pointer for returning the total reply size.
pasky 0:9858347c382d 167 * @param int limit optional number of messages to retrieve.
pasky 0:9858347c382d 168 * @return PNR_OK on success. */
pasky 0:9858347c382d 169 PubNubRes history(const char *channel, char **reply, int *replysize, int limit = 10);
pasky 0:9858347c382d 170
pasky 0:9858347c382d 171 /** Time
pasky 0:9858347c382d 172 *
pasky 0:9858347c382d 173 * Receive the current server timestamp and store it in the
pasky 0:9858347c382d 174 * provided string buffer (a char[32] or larger).
pasky 0:9858347c382d 175 *
pasky 0:9858347c382d 176 * @param ts required pointer to the string buffer.
pasky 0:9858347c382d 177 * @return PNR_OK on success. */
pasky 0:9858347c382d 178 PubNubRes time(char *ts);
pasky 0:9858347c382d 179
pasky 0:9858347c382d 180 /* TODO: here_now */
pasky 0:9858347c382d 181
pasky 0:9858347c382d 182 protected:
pasky 0:9858347c382d 183 const char *m_publish_key, *m_subscribe_key;
pasky 0:9858347c382d 184
pasky 0:9858347c382d 185 const char *m_origin;
pasky 0:9858347c382d 186 const char *origin_hostname();
pasky 0:9858347c382d 187
pasky 0:9858347c382d 188 char m_timetoken[32];
pasky 0:9858347c382d 189 char *m_replybuf;
pasky 0:9858347c382d 190 int m_replylen;
pasky 0:9858347c382d 191
pasky 0:9858347c382d 192 /* Back-end post-processing of subscribe(). free()s *reply
pasky 0:9858347c382d 193 * in the process. */
pasky 0:9858347c382d 194 PubNubRes subscribe_processjson(char *reply, int replylen);
pasky 0:9858347c382d 195 };
pasky 0:9858347c382d 196
pasky 0:9858347c382d 197 #endif