C-Core API & SDK Docs 5.1.1
SDK version
Always use the latest SDK version to have access to the newest features and avoid security vulnerabilities, bugs, and performance issues.
Get Code: Source
https://github.com/pubnub/c-core
Hello World
There is no installation of this SDK. Just clone the Git(Hub) repo, or download a ZIP or tarball of a release from https://github.com/pubnub/c-core/releases It has the code and example Makefiles to get you started.
Makefiles
Use the Makefiles as a starting point in your own projects (whether they are based on Make or some other build tool / system or IDE).
Makefile without SSL/TLS Support
The Makefile for POSIX without SSL/TLS support is available at /posix/posix.mk See /posix/README.md for info on how to build on POSIX (and POSIX-like) systems.
Makefile with SSL/TLS Support
The Makefile for POSIX with SSL/TLS, (via OpenSSL) is available at /openssl/posix.mk in the repo. See /openssl/README.md for info on how to build w/OpenSSL on POSIX and other OpenSSL related data.
Makefile with UWP Support
The Makefile for Windows C with UWP support is available at /windows/uwp.mk in the repo. See /windows/README.md for info on how to build with UWP on Windows.
Makefile with UWP and SSL/TLS Support
The Makefile for Windows C with UWP and SSL/TLS, (via OpenSSL) is available at /openssl/uwp.mk in the repo. See /openssl/README.md for info on how to build with UWP on Windows.
Including the Header
The calling pattern you choose to use with PubNub (Synchronous vs Callback) will determine which header to import. More information on these calling patterns can be found later on in this guide.
Sync
If using the synchronous (sync) pattern, import only pubnub_sync.h:
#include "pubnub_sync.h"
Callback
If using the callback pattern, import pubnub_callback.h and pthread.h:
#include "pubnub_callback.h"
#include <pthread.h>
Runtime Selection
If using the runtime selection pattern, import pubnub_ntf_enforcement.h:
#include "core/pubnub_ntf_enforcement.h"
Memory Allocation
This client uses dynamic memory allocation for the PubNub contexts, but the usage is the same as for any other Pubnub C client - always use pubnub_alloc() to create a context (and check its return value) and always use pubnub_free() to dispose of a context.
Required UUID
Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the UUID, you won't be able to connect to PubNub.
#include "pubnub_alloc.h"
#include <stdio.h>
int main()
{
pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
puts("Couldn't allocate a Pubnub context");
return -1;
}
/* Do something with ctx...
and then: */
pubnub_free(ctx);
return 0
}
Timers
We only provide one timer - the (total) transaction timer. In general, it is started when a transaction is started and stopped when a transaction is finished. If it expires, the transaction will be cancelled. Keep in mind that this canceling is local, so, for example, if you already published a message, but, for some reason, the HTTP response didn't arrive in time, this canceling will not revoke the publish - it will just stop the wait for response.
If the transaction timer expires, the outcome of the transaction will be timeout - different than when you cancel a transaction yourself.
The actual duration of the timer is at least as long as you set it. It could be significantly higher, depending on various platform issues. But, in general, it will be close to what you set.
You should set the timer after initializing the context and before starting a transaction. The duration you set will be used for all subsequent transactions, regardless of their type (i.e. for publish and subscribe and all other).
Thread safety
C-core supports thread-safe operation, though, for performance, you may think about not using it. To use thread-safety support, define the preprocessor symbol PUBNUB_THREADSAFE (just define it, the value does not matter).
Thread-safe Usage
Thread safety is internal. Just because you can access the PubNub context through the PubNub C-core SDK API from different threads safely, doesn't mean you're off the hook for your own data that is related to a context. For example, if you're using the callback interface and signalling an event from it to other (worker) thread(s), you have to synchronise that data transfer yourself.
If you compiled thread-safety support in, you are free to access the same context from different threads, pretty much in any way you wish. However, there are some advised guidelines you should follow:
- If you're using the sync blocking interface, threads that come to wait on the context may wait a long time, so try to avoid it (also, re-think your whole need for a thread-safe C-core)
- If you're using the sync non-blocking interface by calling
pubnub_await, things are pretty much the same as for sync blocking interface - If you're using the sync non-blocking interface and avoid
pubnub_await, waiting threads will not block so long, but, pretty much the only useful thing you can do is cancel a transaction from another thread. - Using the sync interface, it's perfectly fine to call
pubnub_awaitorpubnub_last_resultin different threads, but, you probably shouldn't do that, as it will make debugging harder. - If you're using the callback interface, it's perfectly fine to call Functions from your callback, but, you should avoid doing that, except for some helper functions. Following this guideline will make your debugging, thus life, a lot easier
Thread-unsafe usage
If you compile without thread-safety support, obviously, you will have an SDK which is not thread safe - that is, it is not safe to use a single context from more than one thread at the same time. So, if you're using such SDK configuration in a multithreaded code, which, on POSIX, you likely are, then:
- If at all possible, use a single context from only one thread - the one that created it
- If 1. is not possible, provide some synchronization yourself, for example, using pthread condition variables, or just mutexes, or some higher abstraction, like message queues
- As a special case, if you're using the callback interface, you can start a transaction in one thread and then don't touch the context from that thread any more - use it only in the callback. This is safe.
Context usage
Keep in mind that it is perfectly safe to use different contexts from different threads at the same time. To each (thread) its own (context).
Transaction and Operation
The C-Core SDK operates as a set of transactions. A transaction is initiated by the client SDK and is defined as a single message exchange between the SDK and PubNub service. Every interaction that the client SDK initiates with PubNub is sequenced as a series of transactions which ultimately results in a PubNub service-specific operation.
Status and Events
The SDK provides a set of status and event identifiers which can help developers interact with the library. The status identifier codes are returned as part of the SDK's API invocation. These are used by the developer to check for status of transactions or for detecting normal / abnormal conditions in an API call. Some of the commonly used status codes are as follows
PNR_OK: Success, the transaction finished successfullyPNR_STARTED: The previously initiated transaction has started.PNR_IN_PROGRESS: Indicates that the previous transaction with PubNub service is still in progress.
Refer to the API docs for a complete list of status identifiers supported by the library.
Events refer to the PubNub REST operations which are initiated by the client SDK. The most common example of events are subscribe and publish. A client subscribing for a channel is a subscribe event and a client publishing a message on a channel is a publish event.
Some of the common event identifiers are as follows:
PBTT_SUBSCRIBE: Subscriber operationPBTT_PUBLISH: Publish operation
Refer to the API docs for a complete list of operations supported by the SDK.
Calling Patterns
This SDK provides sync, callback (notification), and runtime_selection (runtime selection of the calling pattern) interfaces for retrieving the outcome of a Pubnub request/transaction/operation.
Sync
The sync interface works like this:
- Start a transaction (say, publish - using
pubnub_publish()) - Either
pubnub_await()the outcome, or use your own loop in which you checkif (PNR_STARTED != pubnub_last_result()) - Handle the outcome as you wish
This is illustrated in the Hello World example below (which is the same for any platform that supports sync interface).
Callback
The callback interface is somewhat more flexible, uses less CPU resources, but is, in general, a little harder to use. One way to use it is to emulate the sync interface:
- Create a callback function (
my_callback) per the prototype required bypubnub_register_callback() - In
my_callback(), use a condition variable to signal that outcome was received - Set the callback via
pubnub_register_callback() - Start a transaction (say, publish - using
pubnub_publish()) - Wait on the condition variable (the same one used in
my_callback) - Handle the outcome as you wish
This is illustrated in the Hello World example below, using pthreads condition variable. Obviously, on platforms that don't support pthreads you will use some similar API (for example, SetEvent/WaitForSingleObject on Windows).
There are other ways to use the callback interface, like the state machine or similar, where the callback will handle the outcome of a transaction but will also start the next Pubnub transaction, or do other stuff that it needs to do. This is very application specific, so we don't provide an example here.
Runtime Selection
The runtime_selection interface allows you to select the calling pattern at runtime for PubNub context. You can select the sync or callback interfaces. By default it selects the sync API.
#include "core/pubnub_ntf_enforcement.h"
// other necessary includes
pubnub_t* pbp_sync = pubnub_alloc();
pubnub_t* pbp_callback = pubnub_alloc();
// you MUST enforce the calling pattern before initializing the context
pubnub_enforce_api(pbp_sync, PNA_SYNC);
pubnub_enforce_api(pbp_callback, PNA_CALLBACK);
pubnub_init(pbp_sync, "my_publish_key", "my_subscribe_key");
pubnub_init(pbp_callback, "my_publish_key", "my_subscribe_key");
Proxy Configuration
Proxy setting
You need to link in the required modules and set the proxy. Use int pubnub_set_proxy_manual() from pubnub_proxy.h. If the proxy server is an authenticating one, you may need to set the username/password, with pubnub_set_proxy_authentication_username_password().
Sync Code Sample - portable
Required UUID
Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the UUID, you won't be able to connect to PubNub.
#include "pubnub_sync.h"
#include <stdio.h>
int main()
{
enum pubnub_res pbresult;
pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
puts("Couldn't allocate a Pubnub context");
return -1;
}
pubnub_init(ctx, "demo", "demo");
pubnub_set_user_id(ctx, "myUniqueUser_Id");
/* Initial Subscribe on the "hello_world" channel */
pubnub_subscribe(ctx, "hello_world", NULL);
pbresult = pubnub_await(ctx);
Callback Code Sample - Syncing with main, Posix Specific
#include "pubnub_callback.h"
#include <pthread.h>
#include <stdio.h>
struct MyUserData {
pthread_mutex_t mut;
bool triggered;
pthread_cond_t cond;
};
static struct MyUserData m_user_data;
void example_callback(pubnub_t *pb, enum pubnub_trans trans, enum pubnub_res result, void *user_data)
{
struct MyUserData *my_user_data = user_data;
/* Signal that we received the outcome, without looking at it,
Copy and paste examples
In addition to the Hello World sample code, we also provide some copy and paste snippets of common API functions:
Init
Instantiate a new Pubnub instance. Only the subscribe_key is mandatory. Also include publish_key if you intend to publish from this instance, and the secret_key if you wish to perform Access Manager administrative operations from this C-Core instance.
Secret key security
It is not a best practice to include the secret key in client-side code for security reasons.
When you init with secret_key, you get root permissions for the Access Manager. With this feature you don't have to grant access to your servers to access channel data. The servers get all access on all channels.
Required UUID
Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the UUID, you won't be able to connect to PubNub.
pubnub_init(ctx, /*publish key*/"demo", /*subscribe key*/"demo");
pubnub_set_user_id(ctx, "myUniqueUser_Id");
Time
Call pubnub_time() to verify the client connectivity to the origin:
pubnub_time(ctx);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
char const *gotten_time = pubnub_get();
}
Subscribe
Subscribe (listen on) a channel (it's async!):
Message retrieval
Typically, you will want two separate contexts for publish and subscribe. When changing the active set of subscribed channels, first call pubnub_leave() on the old set. The pubnub_subscribe() interface is essentially a transaction to start listening on the channel for arrival of next message. This has to be followed by pubnub_get() call to retrieve the actual message, once the subscribe transaction completes successfully. This needs to be performed every time it is desired to retrieve a message from the channel.
pubnub_subscribe(ctx, "my_channel", NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
char const *message = pubnub_get(ctx);
while (message != NULL) {
message = pubnub_get(ctx);
}
}
Publish
Publish a message to a channel:
pubnub_publish(ctx, "my_channel", "\"message\"");
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
/* Published successfully */
}
Here Now
Get occupancy of who's here now on the channel by UUID:
Presence
Requires you to enable the Presence add-on for your key. Refer to the How do I enable add-on features for my keys? knowledge base article for details on enabling features.
// Sync
pubnub_here_now(ctx, "my_channel", NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
char const *json_response = pubnub_get(ctx);
}
//callback
int here_now(pubnub_t *pn) {
char const *chan = "my_channel";
char const *msg;
enum pubnub_res res;
Presence
Subscribe to real-time Presence events, such as join, leave, and timeout, by UUID. Setting the presence attribute to a callback will subscribe to presents events on my_channel:
Presence
Requires you to enable the Presence add-on for your key. Refer to the How do I enable add-on features for my keys? knowledge base article for details on enabling features.
// Sync
char *presence_channel = malloc(strlen(channel) + strlen(PUBNUB_PRESENCE_SUFFIX) + 1);
strcpy(presence_channel, channel);
strcat(presence_channel, PUBNUB_PRESENCE_SUFFIX);
pubnub_subscribe(ctx, presence_channel, NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
char const *presence_event = pubnub_get(ctx);
while (presnce_event != NULL) {
presence_event = pubnub_get(ctx);
}
}
// Callback
History
Retrieve published messages from archival storage:
Message Persistence
Requires that the Message Persistence add-on is enabled for your key. How do I enable add-on features for my keys? - see https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
// Sync
enum pubnub_res res;
pubnub_history(pn, "history_channel", 10, false);
res = pubnub_await(pn);
if (PNR_OK == res) {
puts("Got history! Messages:");
for (;;) {
const char *msg = pubnub_get(pn);
if (NULL == msg) {
break;
}
puts(msg);
}
Unsubscribe
Stop subscribing (listening) to a channel.
To unsubscribe, you need to cancel a subscribe transaction.
-
If you configured the SDK to be thread-safe, you can cancel at any time, but, the cancelling may actually fail - i.e., your thread may wait for another thread to finish working with the context, and by the time your cancel request gets processed, the transaction may finish.
-
If you configured the SDK to not be thread-safe, the only safe way to do it is to use the
syncinterface and:- Set the context to use
non-blocking I/O. - Wait for the outcome in a loop, checking for
pubnub_last_result()- rather than callingpubnub_await(). - If a condition occurs that prompts you to
unsubscribe, callpubnub_cancel(). - Wait for the cancellation to finish (here you can call
pubnub_await(), unless you want to do other stuff while you wait).
- Set the context to use
pbresult = pubnub_subscribe(ctx, "my_channel", NULL);
/* If we don't set non-blocking I/O, we can't get out of a blocked read */
pubnub_set_non_blocking_io(ctx);
/* Can't use pubnub_await() here, it will block */
while (PNR_STARTED == pbresult) {
pbresult = pubnub_last_result(ctx);
/* Somehow decide we want to quit / unsubscribe */
if (should_stop()) {
pubnub_cancel(ctx);
/* If we don't have anything else to do, it's OK to await now,
but you could again have a loop "against" pubnub_last_result()
*/
pbresult = pubnub_await(ctx);
break;
}