Murat Kilivan / PubNub

Put a missing NULL character to clear the string

Fork of PubNub by PubNub

PubNub.h@5:cfcba723d245, 2014-03-24 (annotated)

Committer:
sam_grove
Date:
Mon Mar 24 20:06:55 2014 +0000
Revision:
5:cfcba723d245
Parent:
4:a4759c403023 
Updating documentation

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
sam_grove 5:cfcba723d245 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 1:29cc485dcdb1 67 /** A PubNub Client context. Declare it as a local or global variable,
pasky 1:29cc485dcdb1 68 * then you may start calling the API immediately.
pasky 1:29cc485dcdb1 69 *
pasky 1:29cc485dcdb1 70 * All methods are blocking; if you need to communicate with
pasky 1:29cc485dcdb1 71 * PubNub asynchronously, run PubNub in a dedicated thread.
pasky 1:29cc485dcdb1 72 * Always use the PubNub context only in a single thread at once.
pasky 1:29cc485dcdb1 73 *
pasky 1:29cc485dcdb1 74 * Message are passed as strings instead of JSON structures due
pasky 1:29cc485dcdb1 75 * to much higher RAM efficiency. Often, ad hoc composing and
pasky 1:29cc485dcdb1 76 * parsing JSON messages will work fine in practice. Otherwise,
pasky 1:29cc485dcdb1 77 * take a look at e.g. the picojson library. */
pasky 0:9858347c382d 78 class PubNub {
pasky 0:9858347c382d 79 public:
pasky 0:9858347c382d 80 /** Init a Pubnub Client context
pasky 0:9858347c382d 81 *
pasky 0:9858347c382d 82 * Note that the string parameters are not copied; do not
pasky 0:9858347c382d 83 * overwrite or free the memory where you stored the keys!
pasky 0:9858347c382d 84 * (If you are passing string literals, don't worry about it.)
pasky 0:9858347c382d 85 *
pasky 0:9858347c382d 86 * @param string publish_key required key to send messages.
pasky 0:9858347c382d 87 * @param string subscribe_key required key to receive messages.
pasky 2:d78239c9ebb8 88 * @param string origin optional setting for cloud origin. */
pasky 0:9858347c382d 89 PubNub(const char *publish_key, const char *subscribe_key, const char *origin = "http://pubsub.pubnub.com");
pasky 0:9858347c382d 90
pasky 0:9858347c382d 91 ~PubNub();
pasky 0:9858347c382d 92
pasky 3:36f064f7bdf0 93 /** Publish API call
pasky 0:9858347c382d 94 *
pasky 0:9858347c382d 95 * Send a message (assumed to be well-formed JSON) to a given channel.
pasky 0:9858347c382d 96 *
pasky 0:9858347c382d 97 * Examples:
pasky 3:36f064f7bdf0 98 * @code
pasky 0:9858347c382d 99 p.publish("demo", "\"lala\"");
pasky 3:36f064f7bdf0 100 * @endcode
pasky 0:9858347c382d 101 * or
pasky 3:36f064f7bdf0 102 * @code
pasky 0:9858347c382d 103 if (p.publish("demo", "{\"lala\":1}") != PNR_OK) {
pasky 0:9858347c382d 104 blink_error();
pasky 0:9858347c382d 105 }
pasky 3:36f064f7bdf0 106 * @endcode
pasky 0:9858347c382d 107 *
pasky 0:9858347c382d 108 * @param channel required channel name.
pasky 0:9858347c382d 109 * @param message required JSON message object.
pasky 0:9858347c382d 110 * @param reply optional pointer for passing the returned reply (free() after use).
pasky 0:9858347c382d 111 * @return PNR_OK on success. */
pasky 0:9858347c382d 112 PubNubRes publish(const char *channel, const char *message, char **reply = NULL);
pasky 0:9858347c382d 113
pasky 3:36f064f7bdf0 114 /** Subscribe API call
pasky 0:9858347c382d 115 *
pasky 0:9858347c382d 116 * Listen for a message on a given channel. The function will block
pasky 0:9858347c382d 117 * and return when a message arrives. Typically, you will run this
pasky 0:9858347c382d 118 * function in a loop to keep listening for messages indefinitely.
pasky 0:9858347c382d 119 *
pasky 0:9858347c382d 120 * As a reply, you will get a JSON message. If you are used to
pasky 0:9858347c382d 121 * PubNub API in other environments, you would expect an array
pasky 0:9858347c382d 122 * of messages; here, even if the device received multiple messages
pasky 0:9858347c382d 123 * batched, they are spread over subsequent PubNub.subscribe() calls
pasky 0:9858347c382d 124 * and each returns only a single message. However, *reply can be
pasky 0:9858347c382d 125 * set NULL - in that case, simply retry the call, this indicates
pasky 0:9858347c382d 126 * an empty reply from the server (what happens e.g. after waiting
pasky 0:9858347c382d 127 * for certain interval, or immediately after subscribing).
pasky 0:9858347c382d 128 *
pasky 0:9858347c382d 129 * Contrary to publish(), you should NOT free() the reply yourself!
pasky 0:9858347c382d 130 * Instead, you are expected to call another subscribe() just after
pasky 0:9858347c382d 131 * processing the reply; subscribe() will release any memory it can
pasky 0:9858347c382d 132 * before waiting for new data from the server.
pasky 0:9858347c382d 133 *
pasky 0:9858347c382d 134 * Examples:
pasky 3:36f064f7bdf0 135 * @code
pasky 0:9858347c382d 136 while (1) {
pasky 0:9858347c382d 137 char *reply;
pasky 0:9858347c382d 138 if (p.subscribe("demo", &reply) != PNR_OK) continue;
pasky 0:9858347c382d 139 if (!reply) continue;
pasky 0:9858347c382d 140 int code = -1;
pasky 0:9858347c382d 141 if (sscanf(reply, "{\"code\":%d}", &code) == 1)
pasky 0:9858347c382d 142 printf("received JSON msg with code %d\n", code);
pasky 0:9858347c382d 143 }
pasky 3:36f064f7bdf0 144 * @endcode
pasky 0:9858347c382d 145 *
pasky 0:9858347c382d 146 * @param channel required channel name.
pasky 0:9858347c382d 147 * @param reply required pointer for passing the returned reply (do not free()).
pasky 0:9858347c382d 148 * @return PNR_OK on success. */
pasky 0:9858347c382d 149 PubNubRes subscribe(const char *channel, char **reply);
pasky 0:9858347c382d 150
pasky 0:9858347c382d 151 /* TODO: subscribe_multi */
pasky 0:9858347c382d 152
pasky 3:36f064f7bdf0 153 /** History API call
pasky 0:9858347c382d 154 *
pasky 0:9858347c382d 155 * Receive list of the last N messages on the given channel.
pasky 0:9858347c382d 156 *
pasky 0:9858347c382d 157 * The messages are returned in the reply buffer, with each message
pasky 0:9858347c382d 158 * terminated by a NUL byte, i.e. being a standalone C string; to
pasky 0:9858347c382d 159 * iterate over all the messages, you can use the replysize. reply
pasky 0:9858347c382d 160 * can be NULL if there is no history for this channel.
pasky 0:9858347c382d 161 *
pasky 0:9858347c382d 162 * Example:
pasky 3:36f064f7bdf0 163 * @code
pasky 0:9858347c382d 164 char *reply;
pasky 0:9858347c382d 165 int replysize;
pasky 0:9858347c382d 166 if (p.history("demo", &reply, &replysize) != PNR_OK) return;
pasky 0:9858347c382d 167 if (!reply) return;
pasky 0:9858347c382d 168 for (char *msg = reply; msg < reply + replysize; msg += strlen(msg)+1)
pasky 4:a4759c403023 169 printf("historic message: %s\n", msg);
pasky 0:9858347c382d 170 free(reply);
pasky 3:36f064f7bdf0 171 * @endcode
pasky 0:9858347c382d 172 *
pasky 0:9858347c382d 173 * @param channel required channel name.
pasky 0:9858347c382d 174 * @param reply required pointer for passing the returned reply (free() after use).
pasky 0:9858347c382d 175 * @param replysize required pointer for returning the total reply size.
pasky 0:9858347c382d 176 * @param int limit optional number of messages to retrieve.
pasky 0:9858347c382d 177 * @return PNR_OK on success. */
pasky 0:9858347c382d 178 PubNubRes history(const char *channel, char **reply, int *replysize, int limit = 10);
pasky 0:9858347c382d 179
pasky 3:36f064f7bdf0 180 /** Time API call
pasky 0:9858347c382d 181 *
pasky 0:9858347c382d 182 * Receive the current server timestamp and store it in the
pasky 0:9858347c382d 183 * provided string buffer (a char[32] or larger).
pasky 0:9858347c382d 184 *
pasky 0:9858347c382d 185 * @param ts required pointer to the string buffer.
pasky 0:9858347c382d 186 * @return PNR_OK on success. */
pasky 0:9858347c382d 187 PubNubRes time(char *ts);
pasky 0:9858347c382d 188
pasky 0:9858347c382d 189 /* TODO: here_now */
pasky 0:9858347c382d 190
pasky 0:9858347c382d 191 protected:
pasky 0:9858347c382d 192 const char *m_publish_key, *m_subscribe_key;
pasky 0:9858347c382d 193
pasky 0:9858347c382d 194 const char *m_origin;
pasky 0:9858347c382d 195 const char *origin_hostname();
pasky 0:9858347c382d 196
pasky 0:9858347c382d 197 char m_timetoken[32];
pasky 0:9858347c382d 198 char *m_replybuf;
pasky 0:9858347c382d 199 int m_replylen;
pasky 0:9858347c382d 200
pasky 0:9858347c382d 201 /* Back-end post-processing of subscribe(). free()s *reply
pasky 0:9858347c382d 202 * in the process. */
pasky 0:9858347c382d 203 PubNubRes subscribe_processjson(char *reply, int replylen);
pasky 0:9858347c382d 204 };
pasky 0:9858347c382d 205
pasky 0:9858347c382d 206 #endif