PubNub / PubNub

Build Realtime Apps With The Real-Time Network - the mbed PubNub API+SDK

Dependents:   PubNubDemo Cellular_PubNubDemo lpc4088_ebb_ublox_Cellular_PubNubDemo PubNubDemo_LPC4088 ... more

Fork of PubNub by Petr Baudis

PubNub

The PubNub library enables your mbed board to communicate with the world via the PubNub cloud messaging system.

The library provides a PubNub class that is tied to a particular set of keys and offers methods that correspond to the appropriate API methods - publish, subscribe, history, etc. The JSON encoded messages are passed as raw strings to conserve memory, but at your option, you can use e.g. picojson library to deal with JSON. The API is synchronous - use multiple rtos threads to talk to PubNub on the background.

Getting Started

Can't wait to try it out? Connect your mbed application board and proceed to the demo project:

Import programPubNubDemo

Reference demo of the PubNub library for the mbed application board - control your board over the internet!

Last commit 13 Mar 2014 by PubNub

Library Usage

Import library
PubNub - PubNub Class Reference

Public Member Functions

PubNub (const char *publish_key, const char *subscribe_key, const char *origin="http://pubsub.pubnub.com")
Init a Pubnub Client context.
PubNubRes publish (const char *channel, const char *message, char **reply=NULL)
Publish API call.
PubNubRes subscribe (const char *channel, char **reply)
Subscribe API call.
PubNubRes history (const char *channel, char **reply, int *replysize, int limit=10)
History API call.
PubNubRes time (char *ts)
Time API call.

PubNub.h@8:c9f79982b5ca, 2014-11-20 (annotated)

Committer:
pasky
Date:
Thu Nov 20 21:30:10 2014 +0000
Revision:
8:c9f79982b5ca
Parent:
5:cfcba723d245 
Merge

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