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_ccore.h@0:d13755cfb705, 2016-11-10 (annotated)

Committer:
sveljko
Date:
Thu Nov 10 22:20:11 2016 +0000
Revision:
0:d13755cfb705
Initial commit of Pubnub C-core

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_CCORE
sveljko 0:d13755cfb705 3 #define INC_PUBNUB_CCORE
sveljko 0:d13755cfb705 4
sveljko 0:d13755cfb705 5 #include "pubnub_config.h"
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_ccore.h
sveljko 0:d13755cfb705 12
sveljko 0:d13755cfb705 13 The "C core" module is the internal module of the Pubnub C
sveljko 0:d13755cfb705 14 clients, shared by all. It has all the "generic" code (formatting,
sveljko 0:d13755cfb705 15 parsing, HTTP...) while individual C clients deal with
sveljko 0:d13755cfb705 16 interacting with the environment (OS, frameworks, libraries...).
sveljko 0:d13755cfb705 17
sveljko 0:d13755cfb705 18 The interface of this module is subject to change, so user of a
sveljko 0:d13755cfb705 19 Pubnub C client should *not* use this module directly. Use the
sveljko 0:d13755cfb705 20 official and documented API for your environment.
sveljko 0:d13755cfb705 21 */
sveljko 0:d13755cfb705 22
sveljko 0:d13755cfb705 23 /** The 3-state bool. For Electrical Enginners among you, this would
sveljko 0:d13755cfb705 24 be a digital line utilizing high impedance ("High Z"). For
sveljko 0:d13755cfb705 25 mathematicians, it would be a "Maybe monad". For the rest of us,
sveljko 0:d13755cfb705 26 it has `true`, `false` and the third `not set` or `indeterminate`
sveljko 0:d13755cfb705 27 state.
sveljko 0:d13755cfb705 28 */
sveljko 0:d13755cfb705 29 enum pbcc_tribool {
sveljko 0:d13755cfb705 30 pbccFalse,
sveljko 0:d13755cfb705 31 pbccTrue,
sveljko 0:d13755cfb705 32 pbccNotSet
sveljko 0:d13755cfb705 33 };
sveljko 0:d13755cfb705 34
sveljko 0:d13755cfb705 35
sveljko 0:d13755cfb705 36 /** The Pubnub "(C) core" context, contains context data
sveljko 0:d13755cfb705 37 that is shared among all Pubnub C clients.
sveljko 0:d13755cfb705 38 */
sveljko 0:d13755cfb705 39 struct pbcc_context {
sveljko 0:d13755cfb705 40 /** The publish key (to use when publishing) */
sveljko 0:d13755cfb705 41 char const *publish_key;
sveljko 0:d13755cfb705 42 /** The subscribe key (to use when subscribing) */
sveljko 0:d13755cfb705 43 char const *subscribe_key;
sveljko 0:d13755cfb705 44 /** The UUID to be sent to server. If NULL, don't send any */
sveljko 0:d13755cfb705 45 char const *uuid;
sveljko 0:d13755cfb705 46 /** The `auth` parameter to be sent to server. If NULL, don't send
sveljko 0:d13755cfb705 47 * any */
sveljko 0:d13755cfb705 48 char const *auth;
sveljko 0:d13755cfb705 49
sveljko 0:d13755cfb705 50 /** The last used time token. */
sveljko 0:d13755cfb705 51 char timetoken[20];
sveljko 0:d13755cfb705 52
sveljko 0:d13755cfb705 53 /** The result of the last Pubnub transaction */
sveljko 0:d13755cfb705 54 enum pubnub_res last_result;
sveljko 0:d13755cfb705 55
sveljko 0:d13755cfb705 56 /** The "scratch" buffer for HTTP data */
sveljko 0:d13755cfb705 57 char http_buf[PUBNUB_BUF_MAXLEN];
sveljko 0:d13755cfb705 58
sveljko 0:d13755cfb705 59 /** The length of the data currently in the HTTP buffer ("scratch"
sveljko 0:d13755cfb705 60 or reply, depending on the state).
sveljko 0:d13755cfb705 61 */
sveljko 0:d13755cfb705 62 unsigned http_buf_len;
sveljko 0:d13755cfb705 63
sveljko 0:d13755cfb705 64 /** The total length of data to be received in a HTTP reply or
sveljko 0:d13755cfb705 65 chunk of it.
sveljko 0:d13755cfb705 66 */
sveljko 0:d13755cfb705 67 unsigned http_content_len;
sveljko 0:d13755cfb705 68
sveljko 0:d13755cfb705 69 #if PUBNUB_DYNAMIC_REPLY_BUFFER
sveljko 0:d13755cfb705 70 char *http_reply;
sveljko 0:d13755cfb705 71 #else
sveljko 0:d13755cfb705 72 /** The contents of a HTTP reply/reponse */
sveljko 0:d13755cfb705 73 char http_reply[PUBNUB_REPLY_MAXLEN+1];
sveljko 0:d13755cfb705 74 #endif
sveljko 0:d13755cfb705 75
sveljko 0:d13755cfb705 76 /* These in-string offsets are used for yielding messages received
sveljko 0:d13755cfb705 77 * by subscribe - the beginning of last yielded message and total
sveljko 0:d13755cfb705 78 * length of message buffer.
sveljko 0:d13755cfb705 79 */
sveljko 0:d13755cfb705 80 unsigned msg_ofs, msg_end;
sveljko 0:d13755cfb705 81
sveljko 0:d13755cfb705 82 /* Like the offsets for the messages, these are the offsets for
sveljko 0:d13755cfb705 83 the channels. Unlikey the message(s), the channels don't have
sveljko 0:d13755cfb705 84 to be received at all.
sveljko 0:d13755cfb705 85 */
sveljko 0:d13755cfb705 86 unsigned chan_ofs, chan_end;
sveljko 0:d13755cfb705 87
sveljko 0:d13755cfb705 88 #if PUBNUB_CRYPTO_API
sveljko 0:d13755cfb705 89 /** Secret key to use for encryption/decryption */
sveljko 0:d13755cfb705 90 char const *secret_key;
sveljko 0:d13755cfb705 91 #endif
sveljko 0:d13755cfb705 92 };
sveljko 0:d13755cfb705 93
sveljko 0:d13755cfb705 94
sveljko 0:d13755cfb705 95 /** Initializes the Pubnub C core context */
sveljko 0:d13755cfb705 96 void pbcc_init(struct pbcc_context *pbcc, const char *publish_key, const char *subscribe_key);
sveljko 0:d13755cfb705 97
sveljko 0:d13755cfb705 98 /** Deinitializes the Pubnub C core context */
sveljko 0:d13755cfb705 99 void pbcc_deinit(struct pbcc_context *p);
sveljko 0:d13755cfb705 100
sveljko 0:d13755cfb705 101 /** Reallocates the reply buffer in the C core context @p p to have
sveljko 0:d13755cfb705 102 @p bytes.
sveljko 0:d13755cfb705 103 @return 0: OK, allocated, -1: failed
sveljko 0:d13755cfb705 104 */
sveljko 0:d13755cfb705 105 int pbcc_realloc_reply_buffer(struct pbcc_context *p, unsigned bytes);
sveljko 0:d13755cfb705 106
sveljko 0:d13755cfb705 107 /** Returns the next message from the Pubnub C Core context. NULL if
sveljko 0:d13755cfb705 108 there are no (more) messages
sveljko 0:d13755cfb705 109 */
sveljko 0:d13755cfb705 110 char const *pbcc_get_msg(struct pbcc_context *pb);
sveljko 0:d13755cfb705 111
sveljko 0:d13755cfb705 112 /** Returns the next channel from the Pubnub C Core context. NULL if
sveljko 0:d13755cfb705 113 there are no (more) messages.
sveljko 0:d13755cfb705 114 */
sveljko 0:d13755cfb705 115 char const *pbcc_get_channel(struct pbcc_context *pb);
sveljko 0:d13755cfb705 116
sveljko 0:d13755cfb705 117 /** Sets the UUID for the context */
sveljko 0:d13755cfb705 118 void pbcc_set_uuid(struct pbcc_context *pb, const char *uuid);
sveljko 0:d13755cfb705 119
sveljko 0:d13755cfb705 120 /** Sets the `auth` for the context */
sveljko 0:d13755cfb705 121 void pbcc_set_auth(struct pbcc_context *pb, const char *auth);
sveljko 0:d13755cfb705 122
sveljko 0:d13755cfb705 123 /** Parses the string received as a response for a subscribe operation
sveljko 0:d13755cfb705 124 (transaction). This checks if the response is valid, and, if it
sveljko 0:d13755cfb705 125 is, prepares for giving the messages (and possibly channels) that
sveljko 0:d13755cfb705 126 are received in the response to the user (via pbcc_get_msg() and
sveljko 0:d13755cfb705 127 pbcc_get_channel()).
sveljko 0:d13755cfb705 128
sveljko 0:d13755cfb705 129 @param p The Pubnub C core context to parse the response "in"
sveljko 0:d13755cfb705 130 @return 0: OK, -1: error (invalid response)
sveljko 0:d13755cfb705 131 */
sveljko 0:d13755cfb705 132 int pbcc_parse_subscribe_response(struct pbcc_context *p);
sveljko 0:d13755cfb705 133
sveljko 0:d13755cfb705 134 /** Parses the string received as a response for a publish operation
sveljko 0:d13755cfb705 135 (transaction). This checks if the response is valid, and, if it
sveljko 0:d13755cfb705 136 is, enables getting it as the gotten message (like for
sveljko 0:d13755cfb705 137 `subscribe`).
sveljko 0:d13755cfb705 138
sveljko 0:d13755cfb705 139 @param p The Pubnub C core context to parse the response "in"
sveljko 0:d13755cfb705 140 @return The result of the parsing, expressed as the "Pubnub
sveljko 0:d13755cfb705 141 result" enum
sveljko 0:d13755cfb705 142 */
sveljko 0:d13755cfb705 143 enum pubnub_res pbcc_parse_publish_response(struct pbcc_context *p);
sveljko 0:d13755cfb705 144
sveljko 0:d13755cfb705 145 /** Parses the string received as a response for a time operation
sveljko 0:d13755cfb705 146 (transaction). This checks if the response is valid, and, if it
sveljko 0:d13755cfb705 147 is, enables getting it as the gotten message (like for
sveljko 0:d13755cfb705 148 `subscribe`).
sveljko 0:d13755cfb705 149
sveljko 0:d13755cfb705 150 @param p The Pubnub C core context to parse the response "in"
sveljko 0:d13755cfb705 151 @return 0: OK, -1: error (invalid response)
sveljko 0:d13755cfb705 152 */
sveljko 0:d13755cfb705 153 int pbcc_parse_time_response(struct pbcc_context *p);
sveljko 0:d13755cfb705 154
sveljko 0:d13755cfb705 155 /** Parses the string received as a response for a history v2
sveljko 0:d13755cfb705 156 operation (transaction). This checks if the response is valid,
sveljko 0:d13755cfb705 157 and, if it is, enables getting the gotten message, as a JSON
sveljko 0:d13755cfb705 158 array, and the timestamps for the first and last of them.
sveljko 0:d13755cfb705 159
sveljko 0:d13755cfb705 160 @param p The Pubnub C core context to parse the response "in"
sveljko 0:d13755cfb705 161 @return 0: OK, -1: error (invalid response)
sveljko 0:d13755cfb705 162 */
sveljko 0:d13755cfb705 163 int pbcc_parse_history_response(struct pbcc_context *p);
sveljko 0:d13755cfb705 164
sveljko 0:d13755cfb705 165 /** Parses the string received as a response for a presence query
sveljko 0:d13755cfb705 166 operation (transaction). Presence query is done on several
sveljko 0:d13755cfb705 167 user requests: "where-now", "here-now", etc.
sveljko 0:d13755cfb705 168
sveljko 0:d13755cfb705 169 This checks if the response is valid (a JSON object), and, if it
sveljko 0:d13755cfb705 170 is, enables getting it, as a whole, in one pubnub_get().
sveljko 0:d13755cfb705 171
sveljko 0:d13755cfb705 172 @param p The Pubnub C core context to parse the response "in"
sveljko 0:d13755cfb705 173 @return 0: OK, -1: error (invalid response)
sveljko 0:d13755cfb705 174 */
sveljko 0:d13755cfb705 175 int pbcc_parse_presence_response(struct pbcc_context *p);
sveljko 0:d13755cfb705 176
sveljko 0:d13755cfb705 177 /** Parses the string received as a response for a channel-registry
sveljko 0:d13755cfb705 178 operation (transaction). It is done on several user requests
sveljko 0:d13755cfb705 179 (add/remove channel (from/to) channel group, list (channels
sveljko 0:d13755cfb705 180 in a) channel group, remove channel group).
sveljko 0:d13755cfb705 181
sveljko 0:d13755cfb705 182 This checks if the response is valid (a JSON object), and, if it
sveljko 0:d13755cfb705 183 is, enables getting it, as a whole, in one pubnub_get().
sveljko 0:d13755cfb705 184
sveljko 0:d13755cfb705 185 @param p The Pubnub C core context to parse the response "in"
sveljko 0:d13755cfb705 186 @return The result of the parsing, expressed as the "Pubnub
sveljko 0:d13755cfb705 187 result" enum
sveljko 0:d13755cfb705 188 */
sveljko 0:d13755cfb705 189 enum pubnub_res pbcc_parse_channel_registry_response(struct pbcc_context *p);
sveljko 0:d13755cfb705 190
sveljko 0:d13755cfb705 191 /** Prepares the Publish operation (transaction), mostly by
sveljko 0:d13755cfb705 192 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 193 */
sveljko 0:d13755cfb705 194 enum pubnub_res pbcc_publish_prep(struct pbcc_context *pb, const char *channel, const char *message, bool store_in_history, bool eat_after_reading);
sveljko 0:d13755cfb705 195
sveljko 0:d13755cfb705 196 /** Prepares the Subscribe operation (transaction), mostly by
sveljko 0:d13755cfb705 197 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 198 */
sveljko 0:d13755cfb705 199 enum pubnub_res pbcc_subscribe_prep(struct pbcc_context *p, const char *channel, const char *channel_group, unsigned *heartbeat);
sveljko 0:d13755cfb705 200
sveljko 0:d13755cfb705 201 /** Prepares the Leave operation (transaction), mostly by
sveljko 0:d13755cfb705 202 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 203 */
sveljko 0:d13755cfb705 204 enum pubnub_res pbcc_leave_prep(struct pbcc_context *p, const char *channel, const char *channel_group);
sveljko 0:d13755cfb705 205
sveljko 0:d13755cfb705 206 /** Prepares the Time operation (transaction), mostly by
sveljko 0:d13755cfb705 207 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 208 */
sveljko 0:d13755cfb705 209 enum pubnub_res pbcc_time_prep(struct pbcc_context *p);
sveljko 0:d13755cfb705 210
sveljko 0:d13755cfb705 211 /** Prepares the History v2 operation (transaction), mostly by
sveljko 0:d13755cfb705 212 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 213 */
sveljko 0:d13755cfb705 214 enum pubnub_res pbcc_history_prep(struct pbcc_context *p, const char *channel, unsigned count, bool include_token);
sveljko 0:d13755cfb705 215
sveljko 0:d13755cfb705 216 /** Prepares the Heartbeat operation (transaction), mostly by
sveljko 0:d13755cfb705 217 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 218 */
sveljko 0:d13755cfb705 219 enum pubnub_res pbcc_heartbeat_prep(struct pbcc_context *p, const char *channel, const char *channel_group);
sveljko 0:d13755cfb705 220
sveljko 0:d13755cfb705 221 /** Prepares the Here-now operation (transaction), mostly by
sveljko 0:d13755cfb705 222 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 223 */
sveljko 0:d13755cfb705 224 enum pubnub_res pbcc_here_now_prep(struct pbcc_context *p, const char *channel, const char *channel_group, enum pbcc_tribool disable_uuids, enum pbcc_tribool state);
sveljko 0:d13755cfb705 225
sveljko 0:d13755cfb705 226 /** Prepares the Where-now operation (transaction), mostly by
sveljko 0:d13755cfb705 227 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 228 */
sveljko 0:d13755cfb705 229 enum pubnub_res pbcc_where_now_prep(struct pbcc_context *p, const char *uuid);
sveljko 0:d13755cfb705 230
sveljko 0:d13755cfb705 231 /** Prepares the Set state operation (transaction), mostly by
sveljko 0:d13755cfb705 232 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 233 */
sveljko 0:d13755cfb705 234 enum pubnub_res pbcc_set_state_prep(struct pbcc_context *p, char const *channel, char const *channel_group, const char *uuid, char const *state);
sveljko 0:d13755cfb705 235
sveljko 0:d13755cfb705 236 /** Prepares the Get state operation (transaction), mostly by
sveljko 0:d13755cfb705 237 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 238 */
sveljko 0:d13755cfb705 239 enum pubnub_res pbcc_state_get_prep(struct pbcc_context *p, char const *channel, char const *channel_group, const char *uuid);
sveljko 0:d13755cfb705 240
sveljko 0:d13755cfb705 241 /** Preparse the Remove channel group operation (transaction) , mostly by
sveljko 0:d13755cfb705 242 formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 243 */
sveljko 0:d13755cfb705 244 enum pubnub_res pbcc_remove_channel_group_prep(struct pbcc_context *p, char const *channel_group);
sveljko 0:d13755cfb705 245
sveljko 0:d13755cfb705 246 /** Preparse an operation (transaction) against the channel registry,
sveljko 0:d13755cfb705 247 mostly by formatting the URI of the HTTP request.
sveljko 0:d13755cfb705 248 */
sveljko 0:d13755cfb705 249 enum pubnub_res pbcc_channel_registry_prep(struct pbcc_context *p, char const *channel_group, char const *param, char const *channel);
sveljko 0:d13755cfb705 250
sveljko 0:d13755cfb705 251 #endif /* !defined INC_PUBNUB_CCORE */