Build Realtime Apps With The Real-Time Network - the mbed PubNub API+SDK
PubNub Class Reference
A PubNub Client context. More...
#include <PubNub.h>
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. |
Detailed Description
A PubNub Client context.
Declare it as a local or global variable, then you may start calling the API immediately.
All methods are blocking; if you need to communicate with PubNub asynchronously, run PubNub in a dedicated thread. Always use the PubNub context only in a single thread at once.
Message are passed as strings instead of JSON structures due to much higher RAM efficiency. Often, ad hoc composing and parsing JSON messages will work fine in practice. Otherwise, take a look at e.g. the picojson library.
Definition at line 78 of file PubNub.h.
Constructor & Destructor Documentation
PubNub | ( | const char * | publish_key_, |
const char * | subscribe_key_, | ||
const char * | origin_ = "http://pubsub.pubnub.com" |
||
) |
Init a Pubnub Client context.
PubNub API.
Note that the string parameters are not copied; do not overwrite or free the memory where you stored the keys! (If you are passing string literals, don't worry about it.)
- Parameters:
-
string publish_key required key to send messages. string subscribe_key required key to receive messages. string origin optional setting for cloud origin.
Definition at line 270 of file PubNub.cpp.
Member Function Documentation
PubNubRes history | ( | const char * | channel, |
char ** | reply, | ||
int * | replysize, | ||
int | limit = 10 |
||
) |
History API call.
Receive list of the last N messages on the given channel.
The messages are returned in the reply buffer, with each message terminated by a NUL byte, i.e. being a standalone C string; to iterate over all the messages, you can use the replysize. reply can be NULL if there is no history for this channel.
Example:
char *reply; int replysize; if (p.history("demo", &reply, &replysize) != PNR_OK) return; if (!reply) return; for (char *msg = reply; msg < reply + replysize; msg += strlen(msg)+1) printf("historic message: %s\n", msg); free(reply);
- Parameters:
-
channel required channel name. reply required pointer for passing the returned reply (free() after use). replysize required pointer for returning the total reply size. int limit optional number of messages to retrieve.
- Returns:
- PNR_OK on success.
Definition at line 447 of file PubNub.cpp.
PubNubRes publish | ( | const char * | channel, |
const char * | message, | ||
char ** | reply = NULL |
||
) |
Publish API call.
Send a message (assumed to be well-formed JSON) to a given channel.
Examples:
p.publish("demo", "\"lala\"");
or
if (p.publish("demo", "{\"lala\":1}") != PNR_OK) { blink_error(); }
- Parameters:
-
channel required channel name. message required JSON message object. reply optional pointer for passing the returned reply (free() after use).
- Returns:
- PNR_OK on success.
Definition at line 292 of file PubNub.cpp.
PubNubRes subscribe | ( | const char * | channel, |
char ** | reply | ||
) |
Subscribe API call.
Listen for a message on a given channel. The function will block and return when a message arrives. Typically, you will run this function in a loop to keep listening for messages indefinitely.
As a reply, you will get a JSON message. If you are used to PubNub API in other environments, you would expect an array of messages; here, even if the device received multiple messages batched, they are spread over subsequent PubNub.subscribe() calls and each returns only a single message. However, *reply can be set NULL - in that case, simply retry the call, this indicates an empty reply from the server (what happens e.g. after waiting for certain interval, or immediately after subscribing).
Contrary to publish(), you should NOT free() the reply yourself! Instead, you are expected to call another subscribe() just after processing the reply; subscribe() will release any memory it can before waiting for new data from the server.
Examples:
while (1) { char *reply; if (p.subscribe("demo", &reply) != PNR_OK) continue; if (!reply) continue; int code = -1; if (sscanf(reply, "{\"code\":%d}", &code) == 1) printf("received JSON msg with code %d\n", code); }
- Parameters:
-
channel required channel name. reply required pointer for passing the returned reply (do not free()).
- Returns:
- PNR_OK on success.
Definition at line 324 of file PubNub.cpp.
PubNubRes time | ( | char * | ts ) |
Time API call.
Receive the current server timestamp and store it in the provided string buffer (a char[32] or larger).
- Parameters:
-
ts required pointer to the string buffer.
- Returns:
- PNR_OK on success.
Definition at line 502 of file PubNub.cpp.
Generated on Tue Jul 12 2022 13:56:24 by
![doxygen](doxygen.png)