Configuration API for C-Core SDK

C-Core complete Application Programming Interface (API) reference for building real-time applications on PubNub, including basic usage and sample code. This guide focuses on configuring the C-Core Software Development Kit (SDK) so you can build a working prototype quickly.

Configuration

This page describes the preprocessor definitions (macros) that configure C-Core. They live in the pubnub_config.h header file.

Any definitions that you may find in pubnub_config.h, 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. Applies only to statically allocated contexts. On hosted platforms (POSIX, Windows...), contexts are dynamic by default, so this is ignored. Choose the allocation module (static or dynamic) at link time.

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

Each context consumes memory. Set a realistic limit.

A common setup uses one context for subscription and another that periodically publishes device status. That requires two contexts.

Another setup uses one subscription context and a pool of publish contexts created per external event (for example, a button press). That requires N+1 contexts, where N is the number of events.

You can use a single context, but you cannot publish and subscribe on it at the same time. This may cause lost messages.

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 longer than this are discarded and an error is reported. Large subscribe replies can cause lost messages.

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.

If you must set it at compile time to save RAM and do not need runtime changes, edit 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 only used if timers support is used, which is the default on hosted platforms (POSIX, Windows...).

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_CRYPTO_API: enable automatic encryption/decryption

Set true (!=0) to enable automatic encryption and decryption for publish, subscribe, and storage. Call pubnub_set_crypto_module() with the provider. Otherwise, encryption is off.

Set false (==0) to obtain pubnub_crypto_provider_t and use it manually.

For details and examples, see the Encryption API.

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.

PUBNUB_RAND_INIT_VECTOR: use random initialization vector

When true (default) the initialization vector (IV) is random for all requests. When false the IV is hard-coded for all requests. This setting is true by default.

Disabling random initialization vector

Disable random initialization vector (IV) only for backward compatibility (<3.0.0) with existing applications. Never disable random IV on new applications.

PUBNUB_USE_RETRY_CONFIGURATION: use automatic retry configuration

When ON (default), the SDK retries subscribe operations exponentially. It retries up to 6 times. Delays grow from 2 to 150 seconds.

Depending on your compiler, you use different values to turn this flag on and off:

• CMake - uses ON (enable) and OFF (disable)
• make - uses 1 (enable) and 0 (disable)

If you use one of our build systems, the flag name is USE_RETRY_CONFIGURATION.

For more information on how to configure the reconnection policy in the C-Core SDK, refer to Reconnection Policy. For general information, refer to SDK Connection lifecycle.

PUBNUB_USE_SUBSCRIBE_EVENT_ENGINE: use the standardized subscribe loop

When ON (default) the SDK will use the new subscribe loop.

Use of old subscribe methods

You cannot use the pubnub_subscribe and pubnub_subscribe_v2 functions when PUBNUB_USE_SUBSCRIBE_EVENT_ENGINE is enabled because they may interfere with the internal cursors and buffers in the C-Core SDK.

Depending on your compiler, you use different values to turn this flag on and off:

• CMake - uses ON (enable) and OFF (disable)
• make - uses 1 (enable) and 0 (disable)

If you use one of our build systems, the flag name is USE_SUBSCRIBE_EVENT_ENGINE.

PUBNUB_NTF_RUNTIME_SELECTION: runtime selection of the calling pattern

Select the calling pattern at runtime for a PubNub context: sync or callback. Defaults to sync.

Depending on your compiler, you use different values to turn this flag on and off:

• CMake - USE_NTF_RUNTIME_SELECTION, uses ON (enable) and OFF (disable)
• make - use the version pubnub_ntf_runtime_selection of this SDK

If you use one of our build systems, the flag name is PUBNUB_NTF_RUNTIME_SELECTION.

Initialization

There is no installer. Clone the repository, or download a ZIP or tarball from https://github.com/pubnub/c-core/releases. The repo includes 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.

Including the header

Your calling pattern (synchronous or callback) determines which header to import. Learn more later 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>

Memory allocation

This client uses dynamic memory for contexts. Create a context with pubnub_alloc() (check the return value) and free it with pubnub_free().

Required User ID

Always set the user_id to uniquely identify the user or device that connects to PubNub. This user_id should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the user_id, 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

There is one timer: the total transaction timer. It starts when a transaction starts and stops when it finishes. If it expires, the transaction is cancelled locally. If a publish already reached the server, cancellation does not roll it back.

When the timer expires, the result is timeout.

The actual duration can exceed what you set due to platform factors, but it is usually close.

Set the timer after initializing the context and before starting transactions. The setting applies to all transaction types.

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 to the SDK. It protects the PubNub context, not your application data. If you signal from callbacks to worker threads, synchronize your own data.

If you enabled thread-safety support, you can access the same context from different threads. Follow these guidelines:

• With the sync blocking interface, waiting threads may block for a long time. Avoid this if possible.
• With the sync non-blocking interface and pubnub_await, behavior is similar to the blocking interface.
• With the sync non-blocking interface and without pubnub_await, waiting threads block less. The main useful action is cancelling a transaction from another thread.
• Avoid calling pubnub_await or pubnub_last_result from different threads; it makes debugging harder.
• With the callback interface, avoid calling SDK functions from your callback except small helpers. It simplifies debugging.

Thread-unsafe usage

If you compile without thread-safety support, the SDK is not thread safe. Do not use one context from more than one thread at the same time. In multithreaded code:

1. Prefer using a context from only the thread that created it.
2. If that is not possible, add your own synchronization (for example, condition variables, mutexes, or message queues).
3. With the callback interface, you can start a transaction in one thread and then use the context 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 one message exchange between the SDK and the PubNub service. The SDK sequences transactions that together implement an operation.

Status and Events

The SDK exposes status and event identifiers. Status codes help you track transaction outcomes and detect normal or error conditions. Common status codes include:

1. PNR_OK : Success, the transaction finished successfully
2. PNR_STARTED : The previously initiated transaction has started.
3. 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” are PubNub REST operations initiated by the SDK, such as subscribe and publish.

Some of the common event identifiers are as follows:

1. PBTT_SUBSCRIBE : Subscriber operation
2. 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, 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:

1. Start a transaction (say, publish - using pubnub_publish())
2. Either pubnub_await() the outcome, or use your own loop in which you check if (PNR_STARTED != pubnub_last_result())
3. 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 more flexible and uses less CPU, but it is harder to use. One approach is to emulate the sync interface:

1. Create a callback function (my_callback) per the prototype required by pubnub_register_callback()
2. In my_callback(), use a condition variable to signal that outcome was received
3. Set the callback via pubnub_register_callback()
4. Start a transaction (say, publish - using pubnub_publish())
5. Wait on the condition variable (the same one used in my_callback)
6. Handle the outcome as you wish

This is shown in the Hello World example below using a pthreads condition variable. On platforms without pthreads, use a similar API (for example, SetEvent/WaitForSingleObject on Windows).

You can also build a state machine. The callback can handle the result of one transaction and start the next. This is application‑specific, so examples are not included.

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().

Sample makefile

Use this function to initialize the PubNub client context and set account credentials such as publish_key and subscribe_key.

Method(s)

To Initialize PubNub you can use the following method(s) in the C-Core 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 User ID

Always set the user_id to uniquely identify the user or device that connects to PubNub. This user_id should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the user_id, you won't be able to connect to PubNub.

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");
pubnub_set_ssl_options(ctx, true, true);

Returns

Returns a PubNub instance for APIs like pubnub_publish(), pubnub_subscribe(), pubnub_history(), and pubnub_here_now().

Other examples

Initialize the client

Required User ID

Always set the user_id to uniquely identify the user or device that connects to PubNub. This user_id should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the user_id, 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");

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 User ID

Always set the user_id to uniquely identify the user or device that connects to PubNub. This user_id should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the user_id, you won't be able to connect to PubNub.

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

Use a custom user_id

Set a custom user_id to identify your users.

Required User ID

Always set the user_id to uniquely identify the user or device that connects to PubNub. This user_id should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the user_id, you won't be able to connect to PubNub.

pubnub_t *pn = pubnub_alloc();
pubnub_init(pn, "myPublishKey", "mySubscribeKey");
pubnub_set_user_id(pn, "myUniqueUser_Id");

Initializing with SSL enabled

This example shows how to enable SSL. Initialize the client with SSL options set to true, then subscribe and publish as usual.

Required User ID

Always set the user_id to uniquely identify the user or device that connects to PubNub. This user_id should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the user_id, you won't be able to connect to PubNub.

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");
pubnub_set_ssl_options(ctx, true, true);

Event listeners

PubNub SDKs provide several sources for real-time updates:

• The PubNub client can receive updates from all subscriptions: all channels, channel groups, channel metadata, and users.
• The pubnub_subscription_t object can receive updates only for the particular object for which it was created: channel, channel group, channel metadata, or user.
• The pubnub_subscription_set_t object can receive updates for all objects for which a list of subscription objects was created.

To work with these sources, the SDK provides local representations of server entities, so you can subscribe and add handlers per entity. For details, see Publish & Subscribe.

USER_ID

Set or get a user ID at runtime.

Method(s)

To set/get user_id you can use the following method(s) in the C-Core SDK:

void pubnub_set_user_id (
    pubnub_t *p,
    const char *user_id
)

* required

Parameter	Description
p * Type: pubnub_t*	Pointer to PubNub context
user_id * Type: const char*	Pointer to user_id string

char const *pubnub_user_id_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_user_id().

Sample code

Set USER_ID

Required User ID

Always set the user_id to uniquely identify the user or device that connects to PubNub. This user_id should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the user_id, you won't be able to connect to PubNub.

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

Get USER_ID

printf("User_Id is %s", pubnub_user_id_get(ctx));

Returns

Get returns:

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

Other examples

Initializing with a custom user_id

Required User ID

Always set the user_id to uniquely identify the user or device that connects to PubNub. This user_id should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the user_id, you won't be able to connect to PubNub.

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(&uuid)) {
    random_uuid = pubnub_uuid_to_string(&uuid).uuid;
    pubnub_init(ctx, "myPublishKey", "mySubscribeKey");
    pubnub_set_uuid(ctx, random_uuid);
}

pubnub_free(ctx);

Authentication key

Set and get the user's 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

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

Method

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 *	The 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

Set the origin to the European data center:

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

Returns

Type	Description
int	0: success, -1: fail

Set SSL options

Set 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 client connect to PubNub using SSL? Default: true.
ignoreSecureConnectionRequirement * Type: bool	When SSL is enabled, should the client fall back to non‑SSL if handshakes fail (for example, local proxies or firewalls)? Default: true.

Sample code

pubnub_set_ssl_options(ctx, true, true);

Returns

None

Crypto

Configure the cryptography module for encryption and decryption.

The crypto provider encrypts and decrypts messages. From 4.4.0 onward, you can configure the algorithms.

Each PubNub SDK is bundled with two ways of encryption: the legacy encryption with 128-bit cipher key entropy and the recommended 256-bit AES-CBC encryption. For more general information on how encryption works, refer to Message Encryption.

For detailed crypto module configuration, implementation methods, and practical examples, see the dedicated Encryption page.

Legacy encryption with 128-bit cipher key entropy

You don't have to change your encryption configuration if you want to keep using the legacy encryption. If you want to use the recommended 256-bit AES-CBC encryption, you must explicitly set that in PubNub config.

Reconnection policy

Configure reconnection parameters.

You can specify one or more endpoint groups for which the retry policy won't be applied.

Method(s)

To configure the reconnection policy using the following method(s) in the C-Core SDK:

Set retry configuration

void pubnub_set_retry_configuration(
    pubnub_t*                     pb,
    pubnub_retry_configuration_t* configuration);

Parameter	Description
pb Type: pubnub_t*	Pointer to the PubNub context which failed to complete the transaction and will retry according to the configuration.
configuration Type: pubnub_retry_configuration_t*	Pointer to the request retry configuration used to compute delays between retry attempts.

Sample code

// Create default configuration with linear retry policy.
pubnub_retry_configuration_t* configuration =
    pubnub_retry_configuration_linear_alloc(void);
pubnub_set_retry_configuration(pb, configuration);

Create a request retry configuration with a linear retry policy

pubnub_retry_configuration_t*
    pubnub_retry_configuration_linear_alloc(void);

A linear retry policy will use equal delays between retry attempts. The default implementation uses a 2 second delay and 10 maximum retry attempts.

Sample code

pubnub_retry_configuration_t* configuration =
    pubnub_retry_configuration_linear_alloc(void);

Create a request retry configuration with a linear retry policy and list of API groups which won't be retried

pubnub_retry_configuration_t*
pubnub_retry_configuration_linear_alloc_with_excluded(int excluded, ...);

Parameter	Description
excluded Type: int	Endpoint for which the retry shouldn't be used. For a list of endpoints that can be excluded, refer to the enum list.
... Type: list	Variadic list of endpoints for which retry shouldn't be used. The list should be terminated by -1.

Sample code

pubnub_retry_configuration_t* configuration =
    pubnub_retry_configuration_linear_alloc_with_excluded(
        PNRC_MESSAGE_SEND_ENDPOINT,
        PNRC_MESSAGE_STORAGE_ENDPOINT,
        -1);

Create a request retry configuration with a linear retry policy and list of API groups which won't be retried and custom options

pubnub_retry_configuration_t*
pubnub_retry_configuration_linear_alloc_with_options(
    int delay,
    int maximum_retry,
    int excluded,
    ...);

Parameter	Description
delay Type: int	Seconds between the retries of failed requests. The minimum value is 2.0.
maximum_retry Type: int	The maximum number of retries before reporting an error. The maximum value is 10.
excluded Type: int	Endpoint for which the retry shouldn't be used. For a list of endpoints that can be excluded, refer to the enum list.
... Type: list	Variadic list of endpoints for which retry shouldn't be used. The list should be terminated by -1.

Sample code

pubnub_retry_configuration_t* configuration =
    pubnub_retry_configuration_linear_alloc_with_options(
        5,
        3,
        PNRC_MESSAGE_SEND_ENDPOINT,
        PNRC_MESSAGE_STORAGE_ENDPOINT,
        -1);

Create a request retry configuration with a exponential retry policy

pubnub_retry_configuration_t*
    pubnub_retry_configuration_exponential_alloc(void);

Exponential retry uses a minimum_delay that grows with each failed retry. Defaults: 2‑second minimum, 150‑second maximum, and 6 maximum attempts.

Sample code

pubnub_retry_configuration_t* configuration =
    pubnub_retry_configuration_exponential_alloc(void);

Create a request retry configuration with a exponential retry policy and list of API groups which won't be retried

pubnub_retry_configuration_t*
pubnub_retry_configuration_exponential_alloc_with_excluded(int excluded, ...);

Parameter	Description
excluded Type: int	Endpoint for which the retry shouldn't be used. For a list of endpoints that can be excluded, refer to the enum list.
... Type: list	Variadic list of endpoints for which retry shouldn't be used. The list should be terminated by -1.

Sample code

pubnub_retry_configuration_t* configuration =
    pubnub_retry_configuration_exponential_alloc_with_excluded(
        PNRC_MESSAGE_SEND_ENDPOINT,
        PNRC_MESSAGE_STORAGE_ENDPOINT,
        -1);

Create a request retry configuration with a exponential retry policy and list of API groups which won't be retried and custom options

pubnub_retry_configuration_t*
pubnub_retry_configuration_exponential_alloc_with_options(
    int minimum_delay,
    int maximum_delay,
    int maximum_retry,
    int excluded,
    ...);

Parameter	Description
minimum_delay Type: int	Base delay used to calculate the next delay depending on the number of retry attempts. The minimum value is 2.
maximum_delay Type: int	Maximum allowed computed delay that should be used between retry attempts.
maximum_retry Type: int	The maximum number of retries before reporting an error. The maximum value is 10.
excluded Type: int	Endpoint for which the retry shouldn't be used. For a list of endpoints that can be excluded, refer to the enum list.
... Type: list	Variadic list of endpoints for which retry shouldn't be used. The list should be terminated by -1.

Sample code

pubnub_retry_configuration_t* configuration =
    pubnub_retry_configuration_linear_alloc_with_options(
        5,
        20,
        6,
        PNRC_MESSAGE_SEND_ENDPOINT,
        PNRC_MESSAGE_STORAGE_ENDPOINT,
        -1);

Release resources used by request retry configuration object

void pubnub_retry_configuration_free(
    pubnub_retry_configuration_t** configuration);

Parameter	Description
configuration Type: pubnub_retry_configuration_t**	Pointer to the configuration object which should free up resources.