Configuration API for Windows C SDK

Windows C complete API reference for building real-time applications on PubNub, including basic usage and sample code.

Configuration

This page describes the preprocessor definitions (macros) that configure C‑Core. They live in the pubnub_config.h header file. The header file differs by platform. Some definitions that do not apply to a platform may be omitted.

Any definitions that you find in pubnub_config.h and that are not listed here should not be changed.

PUBNUB_CTX_MAX: maximum number of contexts

Maximum number of PubNub contexts that can be used at the same time. It is used only if the contexts are statically allocated. The default on hosted platforms (POSIX, Windows...) is to use dynamically allocated contexts, so this is ignored. This is selected by linking in the "context allocation module" that you wish to use (static or dynamic).

A context is used to publish messages or subscribe to (get) them.

Each context can consume (for our purposes) a significant amount of memory, so don't put some number that is never going to be achieved here.

A typical configuration may consist of a single pubnub context for channel subscription and another pubnub context that will periodically publish messages about device status (with timeout lower than message generation frequency). This only needs two contexts.

Another typical setup may have a single subscription context and maintain a pool of contexts for each publish call triggered by an external event (e.g. a button push). This would need N+1 contexts, N being the number of external events.

Of course, there is nothing wrong with having just one context, but you can't publish and subscribe at the same time on the same context. This isn't as bad as it sounds, but may be a source of headaches (lost messages, etc).

PUBNUB_BUF_MAXLEN: size of HTTP buffer

Size of the HTTP buffer, in bytes. It heavily impacts the context memory size and sets the upper bound on the URL‑encoded message size. For messages up to 2 KB, set about 2500 for PUBNUB_BUF_MAXLEN. For larger messages, increase the buffer.

You can set this via compiler options. If not, change the default value in the header.

PUBNUB_DYNAMIC_REPLY_BUFFER: use dynamic reply buffer

Set to false (0) to use a static buffer and then set its size via PUBNUB_REPLY_MAXLEN. Set to true (anything !=0) to use a dynamic buffer, that is, dynamically try to allocate as much memory as needed for the buffer.

Default on hosted platforms (Windows, POSIX...) is to use a dynamic reply buffer. Be aware that this can involve large amounts of data (megabytes). If memory is constrained, prefer a static reply buffer. If the reply exceeds the size of your statically allocated buffer, the transaction will fail. Choose the option that best suits your application.

PUBNUB_REPLY_MAXLEN: reply static length

This is only significant if PUBNUB_DYNAMIC_REPLY_BUFFER is true. In that case it defines the size, in octets, of the reply buffer. It will hold the whole (HTTP) body of the reply, not the (HTTP) headers.

Replies of API calls longer than this will be discarded and an error will be reported. Specifically, this may cause lost messages returned by subscribe if too many too large messages got queued on the Pubnub server.

PUBNUB_ORIGIN: the DNS hostname of PubNub

This is the DNS hostname for the PubNub network. In most cases, do not change it. If enabled (see PUBNUB_ORIGIN_SETTABLE), you can set origin at runtime.

But, in the case that you do need to change it at compile time, but not at runtime and want to save some RAM in the context, it's OK to change this macro.

PUBNUB_ORIGIN_SETTABLE: is origin settable at runtime

If true (!=0), the origin can be changed at runtime. This adds a small memory cost.

If false (==0), the origin cannot be changed at runtime. Use this to reduce RAM usage.

PUBNUB_DEFAULT_TRANSACTION_TIMER: duration of transaction timeout

Duration of the transaction timeout set during context initialization, in milliseconds. Timeout duration in the context can be changed by the user after initialization (at runtime).

This is used only if timer support is enabled (default on hosted platforms).

PUBNUB_CALLBACK_THREAD_STACK_SIZE_KB: size of the PubNub thread

Stack size (in kilobytes) for the polling thread when using the callback interface. Smaller values save memory, but avoid less than 64 KB.

Set 0 to use the default. Ignored by the sync interface.

PUBNUB_PROXY_API: enable proxy support

Set true (!=0) to enable proxy support (default on hosted platforms). Configure host, port, and protocol with the C‑Core APIs.

Set false (==0) to disable proxy support and reduce code size.

Depending on your build, you may also need to exclude proxy modules from compilation and linking. See the sample makefiles.

PUBNUB_MAX_PROXY_HOSTNAME_LENGTH: max length of proxy hostname

Maximum length (characters) of the proxy host name stored in the context. Set this to fit your proxy names. One host name is stored per context.

PUBNUB_ONLY_PUBSUB: use only publish&subscribe

Set true (!=0) to support only Publish and Subscribe. Default is false on hosted platforms.

This reduces code size if you do not need other transactions.

If you compile modules not needed in this mode, the build may warn. Many linkers drop unused modules automatically, but behavior depends on your toolchain.

You can set this via compiler options or edit the header default.

Initialization

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.

Makefile

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 WINDOWS without SSL/TLS support is available at /windows/windows.mk See /windows/README.md for info on how to build on WINDOWS (and WINDOWS-like) systems.

Makefile with SSL/TLS support

The Makefile for WINDOWS with SSL/TLS, (via OpenSSL) is available at /openssl/windows.mk in the repo. See /openssl/README.md for info on how to build w/OpenSSL on WINDOWS and other OpenSSL related data.

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, include pubnub_callback.h :

#include "pubnub_callback.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. Not setting the UUID can significantly impact your billing if your account uses the Monthly Active Users (MAUs) based pricing model, and can also lead to unexpected behavior if you have Presence enabled.

#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_await or pubnub_last_result in 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 WINDOWS, 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 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 Windows C 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 successfully
PNR_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 operation
PBTT_PUBLISH : Publish operation

Refer to the API docs for a complete list of operations supported by the SDK.

Calling patterns

This SDK provides sync and callback (notification) interfaces for retrieving the outcome of a PubNub request, transaction, or 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 check if (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 by pubnub_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 SetEvent/WaitForSingleObject.

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.

Proxy configuration

Proxy

You can also use int pubnub_set_proxy_from_system() which will use the facto Standard Windows configurations for proxy.

Sample makefile

This function is used for initializing the PubNub Client API context. This function must be called before attempting to utilize any API functionality in order to establish account level credentials such as publish_key and subscribe_key.

Method(s)

To Initialize Pubnub you can use the following method(s) in the Windows C SDK:

void pubnub_init (pubnub_t *p, const char *publish_key, const char *subscribe_key)

* required

Parameter	Description
`p` * Type: pubnub_t*	Pointer to the Context to initialize (use `pubnub_alloc()` to obtain it)
`publish_key` * Type: char *	Pointer to the `string` of the key to use when publishing messages.
`subscribe_key` * Type: char *	Pointer to the `string` of the key to use when subscribing to messages

Sample code

Initialize the PubNub client API

Required UUID

pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}
pubnub_init(ctx, "demo", "demo");
pubnub_set_uuid(ctx, "myUniqueUUID");
pubnub_set_ssl_options(ctx, true, true, true);

Returns

It returns the Pubnub instance for invoking PubNub APIs like pubnub_publish(), pubnub_subscribe(), pubnub_history(), pubnub_here_now(), etc.

Other examples

Initialize the client

Required UUID

pubnub_init(ctx, /*publish key*/"demo", /*subscribe key*/"demo");
pubnub_set_uuid(ctx, "myUniqueUUID");

Initialization for a Read-Only client

In the case where a client will only read messages and never publish to a channel, you can simply omit the publish_key when initializing the client:

Required UUID

pubnub_init(ctx, "", "demo");

Use a custom UUID

Set a custom UUID to identify your users.

Required UUID

pubnub_t *pn = pubnub_alloc();
pubnub_init(pn, "myPublishKey", "mySubscribeKey");
pubnub_set_uuid(pn, "myUniqueUUID");

Initializing with SSL enabled

This examples demonstrates how to enable PubNub Transport Layer Encryption with SSL. Just initialize the client with 2nd set to true. The hard work is done, now the PubNub API takes care of the rest. Just subscribe and publish as usual and you are good to go.

Required UUID

pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}
pubnub_init(ctx, "demo", "demo");
pubnub_set_uuid(ctx, "myUniqueUUID");
pubnub_set_ssl_options(ctx, true, true, true);

UUID

These functions are used to set/get a user ID on the fly.

Method(s)

To set/get UUID you can use the following method(s) in Windows C SDK

void pubnub_set_uuid (pubnub_t *p, const char *uuid)

* required

Parameter	Description
`p` * Type: pubnub_t*	Pointer to pubnub context
`uuid` * Type: const char*	Pointer to `uuid` `string`

char const *pubnub_uuid_get(pubnub_t *p)

* required

Parameter	Description
`p` * Type: pubnub_t*	Pointer to pubnub client context.

After pubnub_init(), it will return NULL until you change it to non-NULL via pubnub_set_uuid().

Sample code

Set UUID

Required UUID

pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}
pubnub_init(ctx, "myPublishKey", "mySubscribeKey");
pubnub_set_uuid(ctx, "myUniqueUUID");

Get UUID

printf("UUID is %s", pubnub_uuid_get(ctx));

Returns

Get UUID returns the following output:

Type	Description
`char const*`	`UUID` for context. Null if not set.

Other examples

Initializing with a custom uuid

Required UUID

pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}

struct Pubnub_UUID uuid;
char random_uuid;
if (0 == pubnub_generate_uuid_v4_random(&amp;uuid)) {
    random_uuid = pubnub_uuid_to_string(&amp;uuid).uuid;
    pubnub_init(ctx, "myPublishKey", "mySubscribeKey");
    pubnub_set_uuid(ctx, random_uuid);
}

pubnub_free(ctx);

Authentication key

Setter and getter for users auth key.

Method(s)

pubnub_set_auth(pubnub_t* p, const char* auth)

* required

Parameter	Description
`p` * Type: pubnub_t*	Pointer to pubnub client context
`auth` Type: const char*	Pointer to `auth` `string`. NULL to unset

char const *pubnub_auth_get(pubnub_t *p)

* required

Parameter	Description
`p` * Type: pubnub_t*	Pointer to pubnub client context

Sample code

Set auth key

pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}
pubnub_init(ctx, "demo", "demo");
pubnub_set_auth(ctx, "my_new_authkey");

Get auth key

pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}
pubnub_init(ctx, "demo", "demo");
pubnub_set_auth(ctx, "my_auth_key");
printf("Auth Key is %s", pubnub_auth_get(ctx));

Returns

Get Auth key returns the current authentication key.

Origin

Sets the origin (DNS host) for context p. If runtime origin is disabled, the call fails. NULL resets the origin to the default.

Method(s)

To set the origin for a Pubnub context use:

int pubnub_origin_set(pubnub_t *p, char const *origin)

* required

Parameter	Description
`p` * Type: pubnub_t *	Pubnub context to set `origin` for
`Origin` Type: char const*	The `origin` to use for context `p`. If NULL, the default `origin` will be set. To request a custom domain, contact support and follow the request process.

Sample code

To set the origin to the European data center explicitly:

pubnub_origin_set(pn, "ps.pndsn.com");

Returns

Type	Description
`int`	0: success, -1: fail

Set SSL options

Sets the SSL options for a context.

Method(s)

void pubnub_set_ssl_options(pubnub_t *p, bool useSSL, bool ignoreSecureConnectionRequirement)

* required

Parameter	Description
`p` * Type: pubnub_t*	Pointer to pubnub client context
`useSSL` * Type: bool	Should the PubNub client establish the connection to PubNub using `SSL`?Default: `true`
`ignoreSecureConnectionRequirement` * Type: bool	ignoreSecureConnectionRequirement When `SSL` is enabled, should the client fallback to a non-SSL connection if it experiences issues handshaking across local proxies, firewalls, etc?Default: `true`

Sample code

pubnub_set_ssl_options(ctx, true, true);

Returns

None

Configuration​

PUBNUB_CTX_MAX: maximum number of contexts​

PUBNUB_BUF_MAXLEN: size of HTTP buffer​

PUBNUB_DYNAMIC_REPLY_BUFFER: use dynamic reply buffer​

PUBNUB_REPLY_MAXLEN: reply static length​

PUBNUB_ORIGIN: the DNS hostname of PubNub​

PUBNUB_ORIGIN_SETTABLE: is origin settable at runtime​

PUBNUB_DEFAULT_TRANSACTION_TIMER: duration of transaction timeout​

PUBNUB_CALLBACK_THREAD_STACK_SIZE_KB: size of the PubNub thread​

PUBNUB_PROXY_API: enable proxy support​

PUBNUB_MAX_PROXY_HOSTNAME_LENGTH: max length of proxy hostname​

PUBNUB_ONLY_PUBSUB: use only publish&subscribe​

Initialization​

Makefile

Makefile without SSL/TLS support​

Makefile with SSL/TLS support​

Including the header​

Sync​

Callback​

Memory allocation​

Required UUID

Timers​

Thread safety​

Thread-safe usage​

Thread-unsafe usage​

Context usage

Transaction and operation​

Status and Events​

Calling patterns​

Sync​

Callback​

Proxy configuration​

Proxy

Method(s)​

Sample code​

Initialize the PubNub client API​

Required UUID

Returns​

Other examples​

Initialize the client​

Required UUID

Initialization for a Read-Only client​

Required UUID

Use a custom UUID​

Required UUID

Initializing with SSL enabled​

Required UUID

UUID​

Method(s)​

Sample code​

Set UUID​

Required UUID

Get UUID​

Returns​

Other examples​

Initializing with a custom uuid​

Required UUID

Authentication key​

Method(s)​

Sample code​

Set auth key​

Get auth key​

Returns​

Origin​

Method(s)​

Sample code​

Returns​

Set SSL options​

Method(s)​

Sample code​

Returns​

Configuration

PUBNUB_CTX_MAX: maximum number of contexts

PUBNUB_BUF_MAXLEN: size of HTTP buffer

PUBNUB_DYNAMIC_REPLY_BUFFER: use dynamic reply buffer

PUBNUB_REPLY_MAXLEN: reply static length

PUBNUB_ORIGIN: the DNS hostname of PubNub

PUBNUB_ORIGIN_SETTABLE: is origin settable at runtime

PUBNUB_DEFAULT_TRANSACTION_TIMER: duration of transaction timeout

PUBNUB_CALLBACK_THREAD_STACK_SIZE_KB: size of the PubNub thread

PUBNUB_PROXY_API: enable proxy support

PUBNUB_MAX_PROXY_HOSTNAME_LENGTH: max length of proxy hostname

PUBNUB_ONLY_PUBSUB: use only publish&subscribe

Initialization

Makefile without SSL/TLS support

Makefile with SSL/TLS support

Including the header

Sync

Callback

Memory allocation

Timers

Thread safety

Thread-safe usage

Thread-unsafe usage

Transaction and operation

Status and Events

Calling patterns

Sync

Callback

Proxy configuration

Method(s)

Sample code

Initialize the PubNub client API

Returns

Other examples

Initialize the client

Initialization for a Read-Only client

Use a custom UUID

Initializing with SSL enabled

UUID

Method(s)

Sample code

Set UUID

Get UUID

Returns

Other examples

Initializing with a custom uuid

Authentication key

Method(s)

Sample code

Set auth key

Get auth key

Returns

Origin

Method(s)

Sample code

Returns

Set SSL options

Method(s)

Sample code

Returns