Srdjan Veljkovic / Pubnub_c_core

The Pubnub C-core library. It's home is on https://github.com/pubnub/c_core, this is a copy

Dependents:   Pubnub_c_core_mbed2_pal Pubnub_c_core_mbed2_pal Pubnub_c_core_mbed2_pal2

pubnub_coreapi.h@2:d85e42c1125d, 2016-11-22 (annotated)

Committer:
sveljko
Date:
Tue Nov 22 22:21:39 2016 +0000
Revision:
2:d85e42c1125d
Parent:
0:d13755cfb705 
Added `pubnub_helper` module

Who changed what in which revision?

UserRevisionLine numberNew contents of line
sveljko 0:d13755cfb705 1 /* -*- c-file-style:"stroustrup"; indent-tabs-mode: nil -*- */
sveljko 0:d13755cfb705 2 #if !defined INC_PUBNUB_COREAPI
sveljko 0:d13755cfb705 3 #define INC_PUBNUB_COREAPI
sveljko 0:d13755cfb705 4
sveljko 0:d13755cfb705 5
sveljko 0:d13755cfb705 6 #include "pubnub_api_types.h"
sveljko 0:d13755cfb705 7
sveljko 0:d13755cfb705 8 #include <stdbool.h>
sveljko 0:d13755cfb705 9
sveljko 0:d13755cfb705 10
sveljko 0:d13755cfb705 11 /** @file pubnub_coreapi.h
sveljko 0:d13755cfb705 12 This is the "Core" API of the Pubnub client library.
sveljko 0:d13755cfb705 13 It has the functions that are present in all variants and
sveljko 0:d13755cfb705 14 platforms and have the same interface in all of them.
sveljko 0:d13755cfb705 15 For the most part, they have the same implementation in
sveljko 0:d13755cfb705 16 all of them, too.
sveljko 0:d13755cfb705 17 */
sveljko 0:d13755cfb705 18
sveljko 0:d13755cfb705 19
sveljko 0:d13755cfb705 20 /** Append this to a name of the channel to form the name of its
sveljko 0:d13755cfb705 21 "presence" channel. A "presence" channel is a pseudo-channel on
sveljko 0:d13755cfb705 22 which notifications of presence changes of a channel are announced
sveljko 0:d13755cfb705 23 (sent by the Pubnub network). These notifications are JSON objects
sveljko 0:d13755cfb705 24 with the following keys:
sveljko 0:d13755cfb705 25
sveljko 0:d13755cfb705 26 - "action": the event that happened, can be "leave", "join", "timeout",
sveljko 0:d13755cfb705 27 "state-change"
sveljko 0:d13755cfb705 28 - "timestamp": the timestamp of the moment the event happened
sveljko 0:d13755cfb705 29 - "uuid": ID of the user that the event pertains to
sveljko 0:d13755cfb705 30 - "occupancy": current number of present users in the channel
sveljko 0:d13755cfb705 31
sveljko 0:d13755cfb705 32 There is no special support for these (pseudo) channels in our
sveljko 0:d13755cfb705 33 Pubnub client. If you wish to receive presence events, simply
sveljko 0:d13755cfb705 34 append this suffix to the name of the channel and subscribe to
sveljko 0:d13755cfb705 35 that "combined" name. For example, to receive presence events on
sveljko 0:d13755cfb705 36 channel "my_channel", subscribe to "my_channel-pnpres".
sveljko 0:d13755cfb705 37
sveljko 0:d13755cfb705 38 Actually, you can subscribe to both a "regular" channel and a
sveljko 0:d13755cfb705 39 "presence" channel at the same time, and you'll receive both the
sveljko 0:d13755cfb705 40 presence events (on the "presence channel") and the published
sveljko 0:d13755cfb705 41 messages (on the "regular" channel).
sveljko 0:d13755cfb705 42 */
sveljko 0:d13755cfb705 43 #define PUBNUB_PRESENCE_SUFFIX "-pnpres"
sveljko 0:d13755cfb705 44
sveljko 0:d13755cfb705 45 /** Initialize a given pubnub context @p p to the @p publish_key and @p
sveljko 0:d13755cfb705 46 subscribe_key. You can customize other parameters of the context by
sveljko 0:d13755cfb705 47 the configuration function calls below.
sveljko 0:d13755cfb705 48
sveljko 0:d13755cfb705 49 @note The @p publish_key and @p subscribe key are expected to be
sveljko 0:d13755cfb705 50 valid (ASCIIZ string) pointers throughout the use of context @p p,
sveljko 0:d13755cfb705 51 that is, until either you call pubnub_done(), or the otherwise
sveljko 0:d13755cfb705 52 stop using it (like when the whole software/ firmware stops
sveljko 0:d13755cfb705 53 working). So, the contents of these keys are not copied to the
sveljko 0:d13755cfb705 54 Pubnub context @p p.
sveljko 0:d13755cfb705 55
sveljko 0:d13755cfb705 56 @pre Call this after TCP initialization.
sveljko 0:d13755cfb705 57 @pre @p subscribe_key can't be NULL
sveljko 0:d13755cfb705 58 @param p The Context to initialize (use pubnub_alloc() to
sveljko 0:d13755cfb705 59 obtain it)
sveljko 0:d13755cfb705 60 @param publish_key The string of the key to use when publishing
sveljko 0:d13755cfb705 61 messages (if you don't want to publish, you can pass NULL)
sveljko 0:d13755cfb705 62 @param subscribe_key The string of the key to use when subscribing
sveljko 0:d13755cfb705 63 to messages
sveljko 0:d13755cfb705 64 @return Returns the @p p context
sveljko 0:d13755cfb705 65 */
sveljko 0:d13755cfb705 66 pubnub_t* pubnub_init(pubnub_t *p, const char *publish_key, const char *subscribe_key);
sveljko 0:d13755cfb705 67
sveljko 0:d13755cfb705 68 /** Set the UUID identification of PubNub client context @p p to @p
sveljko 0:d13755cfb705 69 uuid. Pass NULL to unset.
sveljko 0:d13755cfb705 70
sveljko 0:d13755cfb705 71 @note The @p uuid is expected to be valid (ASCIIZ string) pointers
sveljko 0:d13755cfb705 72 throughout the use of context @p p, that is, until either you call
sveljko 0:d13755cfb705 73 pubnub_done() on @p p, or the otherwise stop using it (like when
sveljko 0:d13755cfb705 74 the whole software/ firmware stops working). So, the contents of
sveljko 0:d13755cfb705 75 the @p uuid string is not copied to the Pubnub context @p p. */
sveljko 0:d13755cfb705 76 void pubnub_set_uuid(pubnub_t *p, const char *uuid);
sveljko 0:d13755cfb705 77
sveljko 0:d13755cfb705 78 /** Get the UUID identification of PubNub client context @p p.
sveljko 0:d13755cfb705 79 After pubnub_init(), it will return `NULL` until you change it
sveljko 0:d13755cfb705 80 to non-`NULL` via pubnub_set_uuid().
sveljko 0:d13755cfb705 81 */
sveljko 0:d13755cfb705 82 char const *pubnub_uuid_get(pubnub_t *p);
sveljko 0:d13755cfb705 83
sveljko 0:d13755cfb705 84 /** Set the authentication information of PubNub client context @p
sveljko 0:d13755cfb705 85 p. Pass NULL to unset.
sveljko 0:d13755cfb705 86
sveljko 0:d13755cfb705 87 @note The @p auth is expected to be valid (ASCIIZ string) pointers
sveljko 0:d13755cfb705 88 throughout the use of context @p p, that is, until either you call
sveljko 0:d13755cfb705 89 pubnub_done() on @p p, or the otherwise stop using it (like when
sveljko 0:d13755cfb705 90 the whole software/ firmware stops working). So, the contents of
sveljko 0:d13755cfb705 91 the auth string is not copied to the Pubnub context @p p. */
sveljko 0:d13755cfb705 92 void pubnub_set_auth(pubnub_t *p, const char *auth);
sveljko 0:d13755cfb705 93
sveljko 0:d13755cfb705 94 /** Returns the current authentication information for the
sveljko 0:d13755cfb705 95 context @p p.
sveljko 0:d13755cfb705 96 After pubnub_init(), it will return `NULL` until you change it
sveljko 0:d13755cfb705 97 to non-`NULL` via pubnub_set_auth().
sveljko 0:d13755cfb705 98 */
sveljko 0:d13755cfb705 99 char const *pubnub_auth_get(pubnub_t *p);
sveljko 0:d13755cfb705 100
sveljko 0:d13755cfb705 101 /** Cancel an ongoing API transaction. The outcome of the transaction
sveljko 0:d13755cfb705 102 in progress, if any, will be #PNR_CANCELLED. */
sveljko 0:d13755cfb705 103 void pubnub_cancel(pubnub_t *p);
sveljko 0:d13755cfb705 104
sveljko 0:d13755cfb705 105 /** Publish the @p message (in JSON format) on @p p channel, using the
sveljko 0:d13755cfb705 106 @p p context. This actually means "initiate a publish
sveljko 0:d13755cfb705 107 transaction".
sveljko 0:d13755cfb705 108
sveljko 0:d13755cfb705 109 You can't publish if a transaction is in progress in @p p context.
sveljko 0:d13755cfb705 110
sveljko 0:d13755cfb705 111 If transaction is not successful (@c PNR_PUBLISH_FAILED), you can
sveljko 0:d13755cfb705 112 get the string describing the reason for failure by calling
sveljko 0:d13755cfb705 113 pubnub_last_publish_result().
sveljko 0:d13755cfb705 114
sveljko 0:d13755cfb705 115 Keep in mind that the time token from the publish operation
sveljko 0:d13755cfb705 116 response is _not_ parsed by the library, just relayed to the
sveljko 0:d13755cfb705 117 user. Only time-tokens from the subscribe operation are parsed
sveljko 0:d13755cfb705 118 by the library.
sveljko 0:d13755cfb705 119
sveljko 0:d13755cfb705 120 Also, for all error codes known at the time of this writing, the
sveljko 0:d13755cfb705 121 HTTP error will be set also, so the result of the Pubnub operation
sveljko 0:d13755cfb705 122 will not be @c PNR_OK (but you will still be able to get the
sveljko 0:d13755cfb705 123 result code and the description).
sveljko 0:d13755cfb705 124
sveljko 0:d13755cfb705 125 @param p The pubnub context. Can't be NULL
sveljko 0:d13755cfb705 126 @param channel The string with the channel (or comma-delimited list
sveljko 0:d13755cfb705 127 of channels) to publish to.
sveljko 0:d13755cfb705 128 @param message The message to publish, expected to be in JSON format
sveljko 0:d13755cfb705 129
sveljko 0:d13755cfb705 130 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 131 */
sveljko 0:d13755cfb705 132 enum pubnub_res pubnub_publish(pubnub_t *p, const char *channel, const char *message);
sveljko 0:d13755cfb705 133
sveljko 0:d13755cfb705 134 /** Publish the @p message (in JSON format) on @p p channel, using the
sveljko 0:d13755cfb705 135 @p p context, utilizing the v2 API. This actually means "initiate
sveljko 0:d13755cfb705 136 a publish transaction".
sveljko 0:d13755cfb705 137
sveljko 0:d13755cfb705 138 Basically, this is an extension to the pubnub_publish() (v1),
sveljko 0:d13755cfb705 139 with some additional options.
sveljko 0:d13755cfb705 140
sveljko 0:d13755cfb705 141 You can't publish if a transaction is in progress in @p p context.
sveljko 0:d13755cfb705 142
sveljko 0:d13755cfb705 143 @param p The pubnub context. Can't be NULL
sveljko 0:d13755cfb705 144 @param channel The string with the channel (or comma-delimited list
sveljko 0:d13755cfb705 145 of channels) to publish to.
sveljko 0:d13755cfb705 146 @param message The message to publish, expected to be in JSON format
sveljko 0:d13755cfb705 147 @param store_in_history If `false`, message will not be stored in
sveljko 0:d13755cfb705 148 history of the channel
sveljko 0:d13755cfb705 149 @param eat_after_reading If `true`, message will not be stored for
sveljko 0:d13755cfb705 150 delayed or repeated retrieval or display
sveljko 0:d13755cfb705 151
sveljko 0:d13755cfb705 152 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 153 */
sveljko 0:d13755cfb705 154 enum pubnub_res pubnub_publishv2(pubnub_t *p, const char *channel, const char *message, bool store_in_history, bool eat_after_reading);
sveljko 0:d13755cfb705 155
sveljko 0:d13755cfb705 156 /** Returns a pointer to an arrived message or other element of the
sveljko 0:d13755cfb705 157 response to an operation/transaction. Message(s) arrive on finish
sveljko 0:d13755cfb705 158 of a subscribe operation or history operation, while for some
sveljko 0:d13755cfb705 159 other operations this will give access to the whole response,
sveljko 0:d13755cfb705 160 or the next element of the response. That is documented in
sveljko 0:d13755cfb705 161 the function that starts the operation.
sveljko 0:d13755cfb705 162
sveljko 0:d13755cfb705 163 Subsequent call to this function will return the next message (if
sveljko 0:d13755cfb705 164 any). All messages are from the channel(s) the last operation was
sveljko 0:d13755cfb705 165 for.
sveljko 0:d13755cfb705 166
sveljko 0:d13755cfb705 167 @note Context doesn't keep track of the channel(s) you subscribed
sveljko 0:d13755cfb705 168 to. This is a memory saving design decision, as most users won't
sveljko 0:d13755cfb705 169 change the channel(s) they subscribe too.
sveljko 0:d13755cfb705 170
sveljko 0:d13755cfb705 171 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 172
sveljko 0:d13755cfb705 173 @return Pointer to the message, NULL on error
sveljko 0:d13755cfb705 174 @see pubnub_subscribe
sveljko 0:d13755cfb705 175 */
sveljko 0:d13755cfb705 176 char const* pubnub_get(pubnub_t *p);
sveljko 0:d13755cfb705 177
sveljko 0:d13755cfb705 178 /** Returns a pointer to an fetched subscribe operation/transaction's
sveljko 0:d13755cfb705 179 next channel. Each transaction may hold a list of channels, and
sveljko 0:d13755cfb705 180 this functions provides a way to read them. Subsequent call to
sveljko 0:d13755cfb705 181 this function will return the next channel (if any).
sveljko 0:d13755cfb705 182
sveljko 0:d13755cfb705 183 @note You don't have to read all (or any) of the channels before
sveljko 0:d13755cfb705 184 you start a new transaction.
sveljko 0:d13755cfb705 185
sveljko 0:d13755cfb705 186 @param pb The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 187
sveljko 0:d13755cfb705 188 @return Pointer to the channel, NULL on error
sveljko 0:d13755cfb705 189 @see pubnub_subscribe
sveljko 0:d13755cfb705 190 @see pubnub_get
sveljko 0:d13755cfb705 191 */
sveljko 0:d13755cfb705 192 char const *pubnub_get_channel(pubnub_t *pb);
sveljko 0:d13755cfb705 193
sveljko 0:d13755cfb705 194 /** Subscribe to @p channel and/or @p channel_group. This actually
sveljko 0:d13755cfb705 195 means "initiate a subscribe operation/transaction". The outcome
sveljko 0:d13755cfb705 196 will be retrieved by the "notification" API, which is different
sveljko 0:d13755cfb705 197 for different platforms. There are two APIs that are widely
sveljko 0:d13755cfb705 198 available - "sync" and "callback".
sveljko 0:d13755cfb705 199
sveljko 0:d13755cfb705 200 Messages published on @p channel and/or @p channel_group since the
sveljko 0:d13755cfb705 201 last subscribe transaction will be fetched, unless this is the
sveljko 0:d13755cfb705 202 first subscribe on this context after initialization or a serious
sveljko 0:d13755cfb705 203 error. In that "first" case, this will just retrieve the current
sveljko 0:d13755cfb705 204 time token, and that event is called "connect" in many pubnub
sveljko 0:d13755cfb705 205 SDKs, but in C-core we don't treat it any different. For that
sveljko 0:d13755cfb705 206 "first" case, you will receive a notification that subscribe has
sveljko 0:d13755cfb705 207 finished OK, but there will be no messages in the reply.
sveljko 0:d13755cfb705 208
sveljko 0:d13755cfb705 209 The @p channel and @p channel_group strings may contain multiple
sveljko 0:d13755cfb705 210 comma-separated channel (channel group) names, so only one call is
sveljko 0:d13755cfb705 211 needed to fetch messages from multiple channels (channel groups).
sveljko 0:d13755cfb705 212
sveljko 0:d13755cfb705 213 If @p channel is NULL, then @p channel_group cannot be NULL and
sveljko 0:d13755cfb705 214 you will subscribe only to the channel group(s). It goes both
sveljko 0:d13755cfb705 215 ways: if @p channel_group is NULL, then @p channel cannot be NULL
sveljko 0:d13755cfb705 216 and you will subscribe only to the channel(s).
sveljko 0:d13755cfb705 217
sveljko 0:d13755cfb705 218 You can't subscribe if a transaction is in progress on the context.
sveljko 0:d13755cfb705 219
sveljko 0:d13755cfb705 220 Also, you can't subscribe if there are unread messages in the
sveljko 0:d13755cfb705 221 context (you read messages with pubnub_get()).
sveljko 0:d13755cfb705 222
sveljko 0:d13755cfb705 223 @param p The pubnub context. Can't be NULL
sveljko 0:d13755cfb705 224 @param channel The string with the channel name (or comma-delimited list
sveljko 0:d13755cfb705 225 of channel names) to subscribe to.
sveljko 0:d13755cfb705 226 @param channel_group The string with the channel group name (or
sveljko 0:d13755cfb705 227 comma-delimited list of channel group names) to subscribe to.
sveljko 0:d13755cfb705 228
sveljko 0:d13755cfb705 229 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 230
sveljko 0:d13755cfb705 231 @see pubnub_get
sveljko 0:d13755cfb705 232 */
sveljko 0:d13755cfb705 233 enum pubnub_res pubnub_subscribe(pubnub_t *p, const char *channel, const char *channel_group);
sveljko 0:d13755cfb705 234
sveljko 0:d13755cfb705 235 /** Leave the @p channel. This actually means "initiate a leave
sveljko 0:d13755cfb705 236 transaction". You should leave channel(s) when you want to
sveljko 0:d13755cfb705 237 subscribe to another in the same context to avoid loosing
sveljko 0:d13755cfb705 238 messages. Also, it is useful for tracking presence.
sveljko 0:d13755cfb705 239
sveljko 0:d13755cfb705 240 You can't leave if a transaction is in progress on the context.
sveljko 0:d13755cfb705 241
sveljko 0:d13755cfb705 242 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 243 @param channel The string with the channel name (or
sveljko 0:d13755cfb705 244 comma-delimited list of channel names) to leave from.
sveljko 0:d13755cfb705 245 @param channel_group The string with the channel group name (or
sveljko 0:d13755cfb705 246 comma-delimited list of channel group names) to leave from.
sveljko 0:d13755cfb705 247
sveljko 0:d13755cfb705 248 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 249 */
sveljko 0:d13755cfb705 250 enum pubnub_res pubnub_leave(pubnub_t *p, const char *channel, const char *channel_group);
sveljko 0:d13755cfb705 251
sveljko 0:d13755cfb705 252 /** Get the current Pubnub time token . This actually means "initiate
sveljko 0:d13755cfb705 253 a time transaction". Since time token is in the response to most
sveljko 0:d13755cfb705 254 Pubnub REST API calls, this is reserved mostly when you want to
sveljko 0:d13755cfb705 255 get a high-quality seed for a random number generator, or some
sveljko 0:d13755cfb705 256 such thing.
sveljko 0:d13755cfb705 257
sveljko 0:d13755cfb705 258 If transaction is successful, the gotten time will be the only
sveljko 0:d13755cfb705 259 message you can get with pubnub_get(). It will be a (large) JSON
sveljko 0:d13755cfb705 260 integer.
sveljko 0:d13755cfb705 261
sveljko 0:d13755cfb705 262 You can't get time if a transaction is in progress on the context.
sveljko 0:d13755cfb705 263
sveljko 0:d13755cfb705 264 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 265
sveljko 0:d13755cfb705 266 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 267 */
sveljko 0:d13755cfb705 268 enum pubnub_res pubnub_time(pubnub_t *p);
sveljko 0:d13755cfb705 269
sveljko 0:d13755cfb705 270 /** Get the message history for the @p channel. This actually
sveljko 0:d13755cfb705 271 means "initiate a history transaction/operation".
sveljko 0:d13755cfb705 272
sveljko 0:d13755cfb705 273 If transaction is successful, the gotten messages will be
sveljko 0:d13755cfb705 274 available via the pubnub_get(). Using pubnub_get() will give
sveljko 0:d13755cfb705 275 you exactly three messages (or, rather, elements). The first will
sveljko 0:d13755cfb705 276 be a JSON array of gotten messages, and the second and third will be
sveljko 0:d13755cfb705 277 the timestamps of the first and the last message from that array.
sveljko 0:d13755cfb705 278
sveljko 0:d13755cfb705 279 Also, if you select to @c include_token, then the JSON array
sveljko 0:d13755cfb705 280 you get will not be a simple array of gotten messages, but
sveljko 0:d13755cfb705 281 rather an array of JSON objects, having keys `message` with
sveljko 0:d13755cfb705 282 value the actual message, and `timetoken` with the time token
sveljko 0:d13755cfb705 283 of that particular message.
sveljko 0:d13755cfb705 284
sveljko 0:d13755cfb705 285 You can't get history if a transaction is in progress on the context.
sveljko 0:d13755cfb705 286
sveljko 0:d13755cfb705 287 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 288 @param channel The string with the channel name to get message
sveljko 0:d13755cfb705 289 history for. This _can't_ be a comma separated list of channels.
sveljko 0:d13755cfb705 290 @param count Maximum number of messages to get. If there are less
sveljko 0:d13755cfb705 291 than this available on the @c channel, you'll get less, but you
sveljko 0:d13755cfb705 292 can't get more.
sveljko 0:d13755cfb705 293 @param include_token If true, include the time token for every
sveljko 0:d13755cfb705 294 gotten message
sveljko 0:d13755cfb705 295
sveljko 0:d13755cfb705 296 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 297 */
sveljko 0:d13755cfb705 298 enum pubnub_res pubnub_history(pubnub_t *p, const char *channel, unsigned count, bool include_token);
sveljko 0:d13755cfb705 299
sveljko 0:d13755cfb705 300 /** Inform Pubnub that we're still working on @p channel and/or @p
sveljko 0:d13755cfb705 301 channel_group. This actually means "initiate a heartbeat
sveljko 0:d13755cfb705 302 transaction". It can be thought of as an update against the
sveljko 0:d13755cfb705 303 "presence database".
sveljko 0:d13755cfb705 304
sveljko 0:d13755cfb705 305 If transaction is successful, the response will be a available
sveljko 0:d13755cfb705 306 via pubnub_get() as one message, a JSON object. Following keys
sveljko 0:d13755cfb705 307 are always present:
sveljko 0:d13755cfb705 308 - "status": the HTTP status of the operation (200 OK, 40x error, etc.)
sveljko 0:d13755cfb705 309 - "message": the string/message describing the status ("OK"...)
sveljko 0:d13755cfb705 310 - "service": should be "Presence"
sveljko 0:d13755cfb705 311
sveljko 0:d13755cfb705 312 If @p channel is NULL, then @p channel_group cannot be NULL and
sveljko 0:d13755cfb705 313 you will subscribe only to the channel group(s). It goes both ways:
sveljko 0:d13755cfb705 314 if @p channel_group is NULL, then @p channel cannot be NULL and
sveljko 0:d13755cfb705 315 you will subscribe only to the channel(s).
sveljko 0:d13755cfb705 316
sveljko 0:d13755cfb705 317 You can't get list of currently present users if a transaction is
sveljko 0:d13755cfb705 318 in progress on the context.
sveljko 0:d13755cfb705 319
sveljko 0:d13755cfb705 320 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 321 @param channel The string with the channel name (or
sveljko 0:d13755cfb705 322 comma-delimited list of channel names) to get presence info for.
sveljko 0:d13755cfb705 323 @param channel_group The string with the channel name (or
sveljko 0:d13755cfb705 324 comma-delimited list of channel group names) to get presence info for.
sveljko 0:d13755cfb705 325
sveljko 0:d13755cfb705 326 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 327 */
sveljko 0:d13755cfb705 328 enum pubnub_res pubnub_heartbeat(pubnub_t *p, const char* channel, const char* channel_group);
sveljko 0:d13755cfb705 329
sveljko 0:d13755cfb705 330 /** Get the currently present users on a @p channel and/or @p
sveljko 0:d13755cfb705 331 channel_group. This actually means "initiate a here_now
sveljko 0:d13755cfb705 332 transaction". It can be thought of as a query against the
sveljko 0:d13755cfb705 333 "presence database".
sveljko 0:d13755cfb705 334
sveljko 0:d13755cfb705 335 If transaction is successful, the response will be a available
sveljko 0:d13755cfb705 336 via pubnub_get() as one message, a JSON object. Following keys
sveljko 0:d13755cfb705 337 are always present:
sveljko 0:d13755cfb705 338 - "status": the HTTP status of the operation (200 OK, 40x error, etc.)
sveljko 0:d13755cfb705 339 - "message": the string/message describing the status ("OK"...)
sveljko 0:d13755cfb705 340 - "service": should be "Presence"
sveljko 0:d13755cfb705 341
sveljko 0:d13755cfb705 342 If doing a query on a single channel, following keys are present:
sveljko 0:d13755cfb705 343 - "uuids": an array of UUIDs of currently present users
sveljko 0:d13755cfb705 344 - "occupancy": the number of currently present users in the channel
sveljko 0:d13755cfb705 345
sveljko 0:d13755cfb705 346 If doing a query on more channels, a key "payload" is present,
sveljko 0:d13755cfb705 347 which is a JSON object whose keys are:
sveljko 0:d13755cfb705 348
sveljko 0:d13755cfb705 349 - "channels": a JSON object with keys being the names of the
sveljko 0:d13755cfb705 350 channels and their values JSON objects with keys "uuids" and
sveljko 0:d13755cfb705 351 "occupancy" with the meaning the same as for query on a single
sveljko 0:d13755cfb705 352 channel
sveljko 0:d13755cfb705 353 - "total_channels": the number of channels for which the
sveljko 0:d13755cfb705 354 presence is given (in "payload")
sveljko 0:d13755cfb705 355 - "total_occupancy": total number of users present in all channels
sveljko 0:d13755cfb705 356
sveljko 0:d13755cfb705 357 If @p channel is NULL, then @p channel_group cannot be NULL and
sveljko 0:d13755cfb705 358 you will subscribe only to the channel group(s). It goes both ways:
sveljko 0:d13755cfb705 359 if @p channel_group is NULL, then @p channel cannot be NULL and
sveljko 0:d13755cfb705 360 you will subscribe only to the channel(s).
sveljko 0:d13755cfb705 361
sveljko 0:d13755cfb705 362 You can't get list of currently present users if a transaction is
sveljko 0:d13755cfb705 363 in progress on the context.
sveljko 0:d13755cfb705 364
sveljko 0:d13755cfb705 365 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 366 @param channel The string with the channel name (or
sveljko 0:d13755cfb705 367 comma-delimited list of channel names) to get presence info for.
sveljko 0:d13755cfb705 368 @param channel_group The string with the channel name (or
sveljko 0:d13755cfb705 369 comma-delimited list of channel group names) to get presence info for.
sveljko 0:d13755cfb705 370
sveljko 0:d13755cfb705 371 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 372 */
sveljko 0:d13755cfb705 373 enum pubnub_res pubnub_here_now(pubnub_t *p, const char *channel, const char *channel_group);
sveljko 0:d13755cfb705 374
sveljko 0:d13755cfb705 375
sveljko 0:d13755cfb705 376 /** Get the currently present users on all channel. This actually
sveljko 0:d13755cfb705 377 means "initiate a global here_now transaction". It can be thought
sveljko 0:d13755cfb705 378 of as a query against the "presence database".
sveljko 0:d13755cfb705 379
sveljko 0:d13755cfb705 380 If transaction is successful, the response will be the same
sveljko 0:d13755cfb705 381 as for "multi-channel" response for pubnub_here_now(), if
sveljko 0:d13755cfb705 382 we queried against all currently available channels.
sveljko 0:d13755cfb705 383
sveljko 0:d13755cfb705 384 You can't get list of currently present users if a transaction is
sveljko 0:d13755cfb705 385 in progress on the context.
sveljko 0:d13755cfb705 386
sveljko 0:d13755cfb705 387 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 388
sveljko 0:d13755cfb705 389 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 390 */
sveljko 0:d13755cfb705 391 enum pubnub_res pubnub_global_here_now(pubnub_t *p);
sveljko 0:d13755cfb705 392
sveljko 0:d13755cfb705 393 /** Get the currently present users on a @p channel and/or @p
sveljko 0:d13755cfb705 394 channel_group. This actually means "initiate a here_now
sveljko 0:d13755cfb705 395 transaction". It can be thought of as a query against the
sveljko 0:d13755cfb705 396 "presence database".
sveljko 0:d13755cfb705 397
sveljko 0:d13755cfb705 398 If transaction is successful, the response will be a available
sveljko 0:d13755cfb705 399 via pubnub_get() as one message, a JSON object with keys:
sveljko 0:d13755cfb705 400
sveljko 0:d13755cfb705 401 - "status": the HTTP status of the operation (200 OK, 40x error, etc.)
sveljko 0:d13755cfb705 402 - "message": the string/message describing the status ("OK"...)
sveljko 0:d13755cfb705 403 - "service": should be "Presence"
sveljko 0:d13755cfb705 404 - "payload": JSON object with a key "channels" which is an
sveljko 0:d13755cfb705 405 array of channels this user is present in
sveljko 0:d13755cfb705 406
sveljko 0:d13755cfb705 407 You can't get channel presence for the user if a transaction is
sveljko 0:d13755cfb705 408 in progress on the context.
sveljko 0:d13755cfb705 409
sveljko 0:d13755cfb705 410 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 411 @param uuid The UUID of the user to get the channel presence.
sveljko 0:d13755cfb705 412 If NULL, the current UUID of the @c p context will be used.
sveljko 0:d13755cfb705 413
sveljko 0:d13755cfb705 414 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 415 */
sveljko 0:d13755cfb705 416 enum pubnub_res pubnub_where_now(pubnub_t *p, const char *uuid);
sveljko 0:d13755cfb705 417
sveljko 0:d13755cfb705 418 /** Sets some state for the @p channel and/or @channel_group for a
sveljko 0:d13755cfb705 419 user, identified by @p uuid. This actually means "initiate a set
sveljko 0:d13755cfb705 420 state transaction". It can be thought of as an update against the
sveljko 0:d13755cfb705 421 "presence database".
sveljko 0:d13755cfb705 422
sveljko 0:d13755cfb705 423 "State" has to be a JSON object (IOW, several "key-value" pairs).
sveljko 0:d13755cfb705 424
sveljko 0:d13755cfb705 425 If transaction is successful, the response will be a available
sveljko 0:d13755cfb705 426 via pubnub_get() as one message, a JSON object with following keys:
sveljko 0:d13755cfb705 427 - "status": the HTTP status of the operation (200 OK, 40x error, etc.)
sveljko 0:d13755cfb705 428 - "message": the string/message describing the status ("OK"...)
sveljko 0:d13755cfb705 429 - "service": should be "Presence"
sveljko 0:d13755cfb705 430 - "payload" the state
sveljko 0:d13755cfb705 431
sveljko 0:d13755cfb705 432 This will set the same state to all channels identified by
sveljko 0:d13755cfb705 433 @p channel and @p channel_group.
sveljko 0:d13755cfb705 434
sveljko 0:d13755cfb705 435 If @p channel is NULL, then @p channel_group cannot be NULL and
sveljko 0:d13755cfb705 436 you will set state only to the channel group(s). It goes both
sveljko 0:d13755cfb705 437 ways: if @p channel_group is NULL, then @p channel cannot be NULL
sveljko 0:d13755cfb705 438 and you will set state only to the channel(s).
sveljko 0:d13755cfb705 439
sveljko 0:d13755cfb705 440 You can't set state of channels if a transaction is in progress on
sveljko 0:d13755cfb705 441 the context.
sveljko 0:d13755cfb705 442
sveljko 0:d13755cfb705 443 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 444 @param channel The string with the channel name (or
sveljko 0:d13755cfb705 445 comma-delimited list of channel names) to set state for.
sveljko 0:d13755cfb705 446 @param channel_group The string with the channel name (or
sveljko 0:d13755cfb705 447 comma-delimited list of channel group names) to set state for.
sveljko 0:d13755cfb705 448 @param uuid The UUID of the user for which to set state for.
sveljko 0:d13755cfb705 449 If NULL, the current UUID of the @c p context will be used.
sveljko 0:d13755cfb705 450 @param state Has to be a JSON object
sveljko 0:d13755cfb705 451
sveljko 0:d13755cfb705 452 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 453 */
sveljko 0:d13755cfb705 454 enum pubnub_res pubnub_set_state(pubnub_t *p, char const *channel, char const *channel_group, const char *uuid, char const *state);
sveljko 0:d13755cfb705 455
sveljko 0:d13755cfb705 456
sveljko 0:d13755cfb705 457 /** Gets some state for the @p channel and/or @p channel_group for a
sveljko 0:d13755cfb705 458 user, identified by @p uuid. This actually means "initiate a get
sveljko 0:d13755cfb705 459 state transaction". It can be thought of as a query against the
sveljko 0:d13755cfb705 460 "presence database".
sveljko 0:d13755cfb705 461
sveljko 0:d13755cfb705 462 If transaction is successful, the response will be a available
sveljko 0:d13755cfb705 463 via pubnub_get() as one message, a JSON object with following keys:
sveljko 0:d13755cfb705 464 - "status": the HTTP status of the operation (200 OK, 40x error, etc.)
sveljko 0:d13755cfb705 465 - "message": the string/message describing the status ("OK"...)
sveljko 0:d13755cfb705 466 - "service": should be "Presence"
sveljko 0:d13755cfb705 467 - "payload": if querying against one channel the gotten state
sveljko 0:d13755cfb705 468 (a JSON object), otherwise a JSON object with the key "channels"
sveljko 0:d13755cfb705 469 whose value is a JSON object with keys the name of the channels
sveljko 0:d13755cfb705 470 and their respective values JSON objects of the gotten state
sveljko 0:d13755cfb705 471
sveljko 0:d13755cfb705 472 If @p channel is NULL, then @p channel_group cannot be NULL and
sveljko 0:d13755cfb705 473 you will get state only for the channel group(s). It goes both
sveljko 0:d13755cfb705 474 ways: if @p channel_group is NULL, then @p channel cannot be NULL
sveljko 0:d13755cfb705 475 and you will get state only for the channel(s).
sveljko 0:d13755cfb705 476
sveljko 0:d13755cfb705 477 You can't get state of channel(s) if a transaction is in progress
sveljko 0:d13755cfb705 478 on the context.
sveljko 0:d13755cfb705 479
sveljko 0:d13755cfb705 480 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 481 @param channel The string with the channel name (or
sveljko 0:d13755cfb705 482 comma-delimited list of channel names) to get state from.
sveljko 0:d13755cfb705 483 @param channel_group The string with the channel name (or
sveljko 0:d13755cfb705 484 comma-delimited list of channel group names) to get state from.
sveljko 0:d13755cfb705 485 @param uuid The UUID of the user for which to get state for.
sveljko 0:d13755cfb705 486 If NULL, the current UUID of the @p p context will be used.
sveljko 0:d13755cfb705 487
sveljko 0:d13755cfb705 488 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 489 */
sveljko 0:d13755cfb705 490 enum pubnub_res pubnub_state_get(pubnub_t *p, char const *channel, char const *channel_group, const char *uuid);
sveljko 0:d13755cfb705 491
sveljko 0:d13755cfb705 492 /** Removes a @p channel_group and all its channels. This actually
sveljko 0:d13755cfb705 493 means "initiate a remove_channel_group transaction". It can be
sveljko 0:d13755cfb705 494 thought of as an update against the "channel group database".
sveljko 0:d13755cfb705 495
sveljko 0:d13755cfb705 496 If transaction is successful, the response will be a available via
sveljko 0:d13755cfb705 497 pubnub_get_channel() as one "channel", a JSON object with keys:
sveljko 0:d13755cfb705 498
sveljko 0:d13755cfb705 499 - "service": should be "channel-registry"
sveljko 0:d13755cfb705 500 - "status": the HTTP status of the operation (200 OK, 40x error, etc.)
sveljko 0:d13755cfb705 501 - "error": true on error, false on success
sveljko 0:d13755cfb705 502 - "message": the string/message describing the status ("OK"...)
sveljko 0:d13755cfb705 503
sveljko 0:d13755cfb705 504 You can't remove a channel group if a transaction is in progress
sveljko 0:d13755cfb705 505 on the context.
sveljko 0:d13755cfb705 506
sveljko 0:d13755cfb705 507 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 508 @param channel_group The channel group to remove
sveljko 0:d13755cfb705 509
sveljko 0:d13755cfb705 510 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 511 */
sveljko 0:d13755cfb705 512 enum pubnub_res pubnub_remove_channel_group(pubnub_t *p, char const *channel_group);
sveljko 0:d13755cfb705 513
sveljko 0:d13755cfb705 514 /** Removes a @p channel from the @p channel_group . This actually
sveljko 0:d13755cfb705 515 means "initiate a remove_channel_from_channel_group
sveljko 0:d13755cfb705 516 transaction". It can be thought of as an update against the
sveljko 0:d13755cfb705 517 "channel group database".
sveljko 0:d13755cfb705 518
sveljko 0:d13755cfb705 519 You can't remove the last channel from a channel group. To do
sveljko 0:d13755cfb705 520 that, remove the channel group itself.
sveljko 0:d13755cfb705 521
sveljko 0:d13755cfb705 522 If transaction is successful, the response will be a available via
sveljko 0:d13755cfb705 523 pubnub_get_channel() as one "channel", a JSON object with keys:
sveljko 0:d13755cfb705 524
sveljko 0:d13755cfb705 525 - "service": should be "channel-registry"
sveljko 0:d13755cfb705 526 - "status": the HTTP status of the operation (200 OK, 40x error, etc.)
sveljko 0:d13755cfb705 527 - "error": true on error, false on success
sveljko 0:d13755cfb705 528 - "message": the string/message describing the status ("OK"...)
sveljko 0:d13755cfb705 529
sveljko 0:d13755cfb705 530 You can't remove a channel from a channel group if a transaction
sveljko 0:d13755cfb705 531 is in progress on the context.
sveljko 0:d13755cfb705 532
sveljko 0:d13755cfb705 533 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 534 @param channel_group The channel to remove
sveljko 0:d13755cfb705 535 @param channel_group The channel group to remove from
sveljko 0:d13755cfb705 536
sveljko 0:d13755cfb705 537 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 538 */
sveljko 0:d13755cfb705 539 enum pubnub_res pubnub_remove_channel_from_group(pubnub_t *p, char const *channel, char const *channel_group);
sveljko 0:d13755cfb705 540
sveljko 0:d13755cfb705 541 /** Adds a @p channel to the @p channel_group . This actually means
sveljko 0:d13755cfb705 542 "initiate a add_channel_to_channel_group transaction". It can be
sveljko 0:d13755cfb705 543 thought of as an update against the "channel group database".
sveljko 0:d13755cfb705 544
sveljko 0:d13755cfb705 545 If the channel group doesn't exist, this implicitly adds (creates)
sveljko 0:d13755cfb705 546 it.
sveljko 0:d13755cfb705 547
sveljko 0:d13755cfb705 548 If transaction is successful, the response will be a available
sveljko 0:d13755cfb705 549 via pubnub_get_channel() as one "channel", a JSON object with keys:
sveljko 0:d13755cfb705 550
sveljko 0:d13755cfb705 551 - "service": should be "channel-registry"
sveljko 0:d13755cfb705 552 - "status": the HTTP status of the operation (200 OK, 40x error, etc.)
sveljko 0:d13755cfb705 553 - "error": true on error, false on success
sveljko 0:d13755cfb705 554 - "message": the string/message describing the status ("OK"...)
sveljko 0:d13755cfb705 555
sveljko 0:d13755cfb705 556 You can't add a channel to a channel group if a transaction
sveljko 0:d13755cfb705 557 is in progress on the context.
sveljko 0:d13755cfb705 558
sveljko 0:d13755cfb705 559 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 560 @param channel The channel to add
sveljko 0:d13755cfb705 561 @param channel_group The channel group to add to
sveljko 0:d13755cfb705 562
sveljko 0:d13755cfb705 563 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 564 */
sveljko 0:d13755cfb705 565 enum pubnub_res pubnub_add_channel_to_group(pubnub_t *p, char const *channel, char const *channel_group);
sveljko 0:d13755cfb705 566
sveljko 0:d13755cfb705 567 /** Lists all channels of a @p channel_group. This actually
sveljko 0:d13755cfb705 568 means "initiate a list_channel_group transaction". It can be
sveljko 0:d13755cfb705 569 thought of as a query against the "channel group database".
sveljko 0:d13755cfb705 570
sveljko 0:d13755cfb705 571 If transaction is successful, the response will be a available via
sveljko 0:d13755cfb705 572 pubnub_get_channel() as one "channel", a JSON object with keys:
sveljko 0:d13755cfb705 573
sveljko 0:d13755cfb705 574 - "service": should be "channel-registry"
sveljko 0:d13755cfb705 575 - "status": the HTTP status of the operation (200 OK, 40x error, etc.)
sveljko 0:d13755cfb705 576 - "error": true on error, false on success
sveljko 0:d13755cfb705 577 - "payload": JSON object with keys "group" with value the string
sveljko 0:d13755cfb705 578 of the channel group name and "channels" with value a JSON array
sveljko 0:d13755cfb705 579 of strings with names of the channels that belong to the group
sveljko 0:d13755cfb705 580
sveljko 0:d13755cfb705 581 You can't remove a channel group if a transaction is in progress
sveljko 0:d13755cfb705 582 on the context.
sveljko 0:d13755cfb705 583
sveljko 0:d13755cfb705 584 @param p The Pubnub context. Can't be NULL.
sveljko 0:d13755cfb705 585 @param channel_group The channel group to list
sveljko 0:d13755cfb705 586
sveljko 0:d13755cfb705 587 @return #PNR_STARTED on success, an error otherwise
sveljko 0:d13755cfb705 588 */
sveljko 0:d13755cfb705 589 enum pubnub_res pubnub_list_channel_group(pubnub_t *p, char const *channel_group);
sveljko 0:d13755cfb705 590
sveljko 0:d13755cfb705 591 /** Returns the result of the last transaction in the @p p context.
sveljko 0:d13755cfb705 592 This _may_ block if using blocking I/O. It will _not_ block if using
sveljko 0:d13755cfb705 593 non-blocking I/O.
sveljko 0:d13755cfb705 594
sveljko 0:d13755cfb705 595 @see pubnub_set_blocking_io
sveljko 0:d13755cfb705 596 @see pubnub_set_non_blocking_io
sveljko 0:d13755cfb705 597 */
sveljko 0:d13755cfb705 598 enum pubnub_res pubnub_last_result(pubnub_t *p);
sveljko 0:d13755cfb705 599
sveljko 0:d13755cfb705 600 /** Returns the HTTP reply code of the last transaction in the @p p
sveljko 0:d13755cfb705 601 * context. */
sveljko 0:d13755cfb705 602 int pubnub_last_http_code(pubnub_t *p);
sveljko 0:d13755cfb705 603
sveljko 0:d13755cfb705 604 /** Returns the string of the result of the last `publish` transaction,
sveljko 0:d13755cfb705 605 as returned from Pubnub. If the last transaction is not a publish,
sveljko 0:d13755cfb705 606 or there is some other error, it returns NULL. If the Publish
sveljko 0:d13755cfb705 607 was successfull, it will return "Sent", otherwise a description
sveljko 0:d13755cfb705 608 of the error.
sveljko 0:d13755cfb705 609 */
sveljko 0:d13755cfb705 610 char const *pubnub_last_publish_result(pubnub_t *p);
sveljko 0:d13755cfb705 611
sveljko 0:d13755cfb705 612 /** Returns the string of the last received time token on the
sveljko 0:d13755cfb705 613 @c p context. After pubnub_init() this should be "0".
sveljko 0:d13755cfb705 614 @param p Pubnub context to get the last received time token from
sveljko 0:d13755cfb705 615 @return A read only string of the last received time token
sveljko 0:d13755cfb705 616 */
sveljko 0:d13755cfb705 617 char const *pubnub_last_time_token(pubnub_t *p);
sveljko 0:d13755cfb705 618
sveljko 0:d13755cfb705 619 /** Gets the origin to be used for the context @p p.
sveljko 0:d13755cfb705 620 If setting of the origin is not enabled, this will return
sveljko 0:d13755cfb705 621 the default origin.
sveljko 0:d13755cfb705 622 @param p Pubnub context to get the origin from
sveljko 0:d13755cfb705 623 @return A read only string of origin used for context @p p
sveljko 0:d13755cfb705 624 */
sveljko 0:d13755cfb705 625 char const *pubnub_get_origin(pubnub_t *p);
sveljko 0:d13755cfb705 626
sveljko 0:d13755cfb705 627 /** Sets the origin to be used for the context @p p. If setting of
sveljko 0:d13755cfb705 628 the origin is not enabled, this will fail. It may also fail if it
sveljko 0:d13755cfb705 629 detects an invalid origin, but NULL is not an invalid origin - it
sveljko 0:d13755cfb705 630 resets the origin to default.
sveljko 0:d13755cfb705 631
sveljko 0:d13755cfb705 632 @param p Pubnub context to set the origin for
sveljko 0:d13755cfb705 633 @param origin The origin to use for context @p p. If NULL,
sveljko 0:d13755cfb705 634 the default origin will be set
sveljko 0:d13755cfb705 635 @return 0: success, -1: fail
sveljko 0:d13755cfb705 636 */
sveljko 0:d13755cfb705 637 int pubnub_origin_set(pubnub_t *p, char const *origin);
sveljko 0:d13755cfb705 638
sveljko 0:d13755cfb705 639
sveljko 0:d13755cfb705 640 #endif /* defined INC_PUBNUB_COREAPI */