For AI agents: this page in Markdown: https://www.pubnub.com/docs/sdks/c-core/api-reference/misc.md. Documentation index: https://www.pubnub.com/llms-full.txt.

Utility Methods API for C-Core SDK (legacy)

New SDK available

C-Core (legacy) is still supported. If you are starting a new project, use the new C SDK.

The methods on this page are utility methods that don't fit into other categories.

PubNub alloc​

Returns an allocated context. After successful allocation, call pubnub_init() to prepare the context for regular use. Always obtain a context pointer by calling this function rather than creating one manually.

Method(s)​

1pubnub_t *pubnub_alloc(void)

Sample code​

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

Returns​

TypeDescription
pubnub_t*Context pointer on success, NULL on error.

PubNub free​

Frees a previously allocated context if no transaction is in progress. If a transaction is active, the SDK cancels it (equivalent to calling pubnub_cancel()), but the cancellation may not complete during this call.

You don't need to free a context after every transaction. Free a context only when you're done with PubNub transactions for a significant period of time.

Method(s)​

1int pubnub_free(pubnub_t *pb);
* required
ParameterDescription
pb *
Type: pubnub_t*
The PubNub context to free.

Sample code​

1if (0 != pubnub_free(pbp)) {
2    printf("Freeing PubNub context failed, cancel started.\n");
3}
4else {
5    printf("Pubnub context freed.\n");
6}

Returns​

TypeValueDescription
int0OK, context freed.
int-1Context not freed, transaction cancel started.

Free a context, with waiting​

Retries pubnub_free() in a tight loop until either it succeeds or the specified time elapses. This function waits for the current transaction to finish and then frees the context.

This function is most useful in the callback interface, especially after pubnub_cancel(). It is not useful in the sync interface if you use only one thread with the context.

Method(s)​

1int pubnub_free_with_timeout(pubnub_t* pbp, unsigned millisec);
* required
ParameterDescription
pbp *
Type: pubnub_t*
The PubNub context to free.
millisec *
Type: unsigned
Maximum time to wait for freeing to succeed, in milliseconds.

Sample code​

1if (0 != pubnub_free_with_timeout(pbp, 1000)) {
2    puts("Failed to free the context in due time");
3}

Returns​

TypeValueDescription
int0pubnub_free() succeeded.
int-1Failed to free within the specified time.

PubNub cancel​

Cancels an ongoing API transaction. Once complete, the SDK closes the TCP/IP connection to PubNub. The outcome of any transaction in progress will be PNR_CANCELLED.

In the sync interface, cancellation may finish during this call, but there is no guarantee. In the callback interface, immediate completion is unlikely. Always check the result.

Method(s)​

1enum pubnub_cancel_res pubnub_cancel(pubnub_t* p);
* required
ParameterDescription
p *
Type: pubnub_t*
The PubNub context for which to cancel the transaction.

Sample code​

1pubnub_publish(ctx, "hello_world", "\"Hello from Pubnub C-core docs!\"");
2if (PN_CANCEL_FINISHED == pubnub_cancel(ctx)) {
3    puts("Cancel done");
4}
5else {
6    /* await the result, for the sync interface, it would be: */
7    pubnub_await(ctx);
8}

Returns​

TypeValueDescription
enum pubnub_cancel_resPN_CANCEL_STARTEDCancel started, await the outcome.
enum pubnub_cancel_resPN_CANCEL_FINISHEDCancelled, no need to await.

PubNub get​

Returns a pointer to an arrived message or other element of the transaction response. Messages arrive after a subscribe or history operation. For other operations, this function provides access to the whole response or the next element. Each subsequent call returns the next message, if any.

Method(s)​

1char const * pubnub_get (pubnub_t *p)
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context.

Sample code​

1pubnub_subscribe(ctx, "hello_world", NULL);
2pbresult = pubnub_await(ctx);
3if (pbresult != PNR_OK) {
4    printf("Failed to subscribe, error %d\n", pbresult);
5    pubnub_free(ctx);
6    return -1;
7}
8else {
9    char const *msg = pubnub_get(ctx);
10    while (msg != NULL) {
11        printf("Got message: %s\n", msg);
12        msg = pubnub_get(ctx);
13    }
14}
15pubnub_free(ctx);

Returns​

TypeDescription
char const*Pointer to the message, or NULL if no more messages.

PubNub get channel​

Returns a pointer to the next channel from a subscribe transaction's response. Each subsequent call returns the next channel, if any.

Method(s)​

1char const * pubnub_get_channel (pubnub_t *pb)
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to PubNub client context. Must not be NULL.

Sample code​

1pubnub_subscribe(ctx, "hello_world", NULL);
2pbresult = pubnub_await(ctx);
3if (pbresult != PNR_OK) {
4    printf("Failed to subscribe, error %d\n", pbresult);
5    pubnub_free(ctx);
6    return -1;
7}
8else {
9    char const *msg = pubnub_get(ctx);
10    char const *channel = pubnub_get_channel(ctx);
11    while (msg != NULL) {
12        printf("Got message: %s on channel %s\n", msg, (NULL == channel) ? "" : channel );
13        msg = pubnub_get(ctx);
14        channel = pubnub_get_channel(ctx);
15    }
show all 17 lines

Returns​

TypeDescription
char const*Pointer to the channel name, or NULL if no more channels.

PubNub last result​

Returns the result of the last transaction in the given context. This may block when using blocking I/O and will not block when using non-blocking I/O.

Related methods:

Method(s)​

1int pubnub_last_result(pubnub_t *p)
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context.

Sample code​

1pubnub_list_channel_group(ctx, "my_channel_group");
2pbresult = pubnub_await(ctx);
3printf("Last result %s\n", pubnub_res_2_string(pubnub_last_result(ctx)));

Returns​

TypeDescription
enum pubnub_resResult of the last transaction in the context.

PubNub last HTTP code​

Returns the HTTP reply code of the last transaction in the context.

Method(s)​

1enum pubnub_res int pubnub_last_http_code(pubnub_t *p)
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context.

Sample code​

1pubnub_list_channel_group(ctx, "my_channel_group");
2pbresult = pubnub_await(ctx);
3printf("HTTP Status Code %d\n", pubnub_last_http_code(ctx));

Returns​

TypeDescription
intHTTP reply code of the last transaction.

PubNub last publish result​

Returns the result string of the last publish transaction as returned from PubNub. If the last transaction was not a publish or an error occurred, the function returns NULL. A successful publish returns "Sent"; otherwise, the function returns an error description.

Method(s)​

1char const *pubnub_last_publish_result(pubnub_t *p);
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context.

Sample code​

1pubnub_init(ctx, "demo", "demo");
2pubnub_set_user_id(ctx, "MyUniqueUser_Id")
3pbres = pubnub_publish(ctx, "hello_world", "\"Hello from Pubnub C-core docs!\"");
4if (pbresult != PNR_OK) {
5    printf("Failed to publish, error %d\n", pbresult);
6    printf("String result of last publish %s\n", pubnub_last_publish_result(ctx));
7    return -1;
8}

Returns​

TypeDescription
char const*Result string of the last publish transaction.

PubNub last time token​

Returns the last received timetoken from a subscribe transaction on the context. After pubnub_init(), the value is "0".

Method(s)​

1char const *pubnub_last_time_token(pubnub_t *p);
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context.

Sample code​

1printf("Last timetoken %s\n", pubnub_last_time_token(ctx));

Returns​

TypeDescription
char const*String of the last received timetoken.

Parse publish result​

Parses a publish result string. You typically obtain this string from pubnub_last_publish_result().

Method(s)​

1enum pubnub_publish_res pubnub_parse_publish_result(char const *result)
* required
ParameterDescription
result *
Type: char const*
Publish result string.

Sample code​

1enum pubnub_res res;
2pubnub_t *pbp = pubnub_alloc();
3if (NULL == pbp) {
4    printf("Failed to allocate Pubnub context!\n");
5    return -1;
6}
7pubnub_init(pbp, "demo", "demo");
8pubnub_set_user_id(pbp, "MyUniqueUser_Id")
9

10res = pubnub_publish(pbp, chan, "\"Hello world from sync!\"");
11if (res != PNR_STARTED) {
12    printf("pubnub_publish() returned unexpected: %d\n", res);
13    pubnub_free(pbp);
14    return -1;
15}
show all 24 lines

Returns​

TypeDescription
enum pubnub_publish_resParsed result of the publish response.

PubNub res 2 string​

Returns a human-readable string describing a pubnub_res enum value.

Method(s)​

1char const* pubnub_res_2_string(enum pubnub_res e)
* required
ParameterDescription
p *
Type: enum pubnub_res
PubNub result enum value.

Sample code​

1enum pubnub_res res;
2pubnub_t *pbp = pubnub_alloc();
3if (NULL == pbp) {
4    printf("Failed to allocate Pubnub context!\n");
5    return -1;
6}
7pubnub_init(pbp, "demo", "demo");
8pubnub_set_user_id(pbp, "MyUniqueUser_Id")
9

10res = pubnub_publish(pbp, chan, "\"Hello world from sync!\"");
11if (res != PNR_STARTED) {
12    printf("pubnub_publish() returned unexpected: %d\n", res);
13    pubnub_free(pbp);
14    return -1;
15}
show all 17 lines

Returns​

TypeDescription
char const*String describing the PubNub result.

Should a failed transaction be retried​

Returns whether retrying a failed PubNub transaction makes sense. This is mostly useful for publishing but applies generally. It is least useful for subscribing, because you will most likely subscribe again later.

Method(s)​

1enum pubnub_tribool pubnub_should_retry(enum pubnub_res e);
* required
ParameterDescription
e *
Type: enum pubnub_res
PubNub result to evaluate for retry.

Sample code​

1for (i = 0; i < my_retry_limit; ++i) {
2    res = pubnub_publish(pbp, chan, msg);
3    if (res != PNR_STARTED) {
4        printf("pubnub_publish() returned unexpected: %d\n", res);
5        pubnub_free(pbp);
6        return -1;
7    }
8

9    res = pubnub_await(pbp);
10    switch (pubnub_should_retry(res)) {
11        case pbccFalse:
12        break;
13        case pbccTrue:
14            printf("Publishing failed with code: %d ('%s')\nRetrying...\n", res, pubnub_res_2_string(res));
15        continue;
show all 22 lines

Returns​

TypeValueDescription
enum pubnub_triboolpbccTrueSafe to retry, though success is not guaranteed.
enum pubnub_triboolpbccFalseRetrying the same transaction will not help.
enum pubnub_triboolpbccNotSetRetry might help but could also make things worse. For example, on PNR_TIMEOUT, the message may have been delivered but the response was lost, so retrying could duplicate the message.

PubNub leave​

Initiates a leave transaction for the specified channel(s). Leave a channel when you want to subscribe to another channel on the same context to avoid losing messages. Leaving is also useful for tracking presence. You cannot leave if a transaction is already in progress on the context.

Method(s)​

1enum pubnub_res pubnub_leave (pubnub_t *p, const char *channel, const char *channel_group)
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context. Must not be NULL.
channel
Type: const char*
Channel name or comma-delimited list of channel names to leave.
channel_group
Type: const char*
Channel group name or comma-delimited list of channel group names to leave.

Sample code​

1pubnub_leave(ctx, "hello_world", NULL);
2pbresult = pubnub_await(ctx);
3if (PNR_OK == pbresult) {
4    printf("Leave successful\n");
5}
6pubnub_free(ctx);

Returns​

TypeDescription
enum pubnub_resPNR_STARTED on success, an error otherwise.

Time​

Returns a 17-digit precision Unix epoch timetoken from the PubNub server.

Timetoken algorithm
1timetoken = (Unix epoch time in seconds) * 10000000

For example:

108/19/2013 @ 9:20pm in UTC = 1376961606
2timetoken = 1376961606 * 10000000
3timetoken = 13769616060000000

Method(s)​

1enum pubnub_res pubnub_time (pubnub_t *p)
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context.

Sample code​

1pubnub_time(ctx);
2pbresult = pubnub_await(ctx);
3if (PNR_OK == pbresult) {
4    char const *gotten_time = pubnub_get();
5}

Rest response from server​

The pubnub_time() function returns a string timetoken:

113769501243685161

Subscribe loop - callback​

Creates a subscribe loop descriptor for the callback interface. Default values are used for descriptor fields not provided as parameters.

Method(s)​

1pubnub_subloop_t* pubnub_subloop_define(pubnub_t *p, char const *channel, struct pubnub_subscribe_options options, pubnub_subloop_callback_t cb);
* required
ParameterDescription
p *
Type: pubnub_t*
The PubNub context to use for the subscribe loop.
channel *
Type: char const*
The channel(s) to use in the subscribe loop.
options *
Type: struct pubnub_subscribe_options
Subscribe options to use in the loop.
cb *
Type: pubnub_subloop_callback_t
Callback called for each message received during the loop.

Sample code​

1static void subloop_callback(char const* message, enum pubnub_res result) {
2    if (PNR_OK == result) {
3        printf("Received message '%s'\n", message);
4    } else {
5            printf("Subscribe failed with code: %d\n", result);
6    }
7}
8

9pbsld = pubnub_subloop_define(pbp, chan, pubnub_subscribe_defopts(), subloop_callback);
10

11if (NULL == pbsld) {
12    printf("Defining a subscribe loop failed\n");
13    pubnub_free(pbp);
14    return -1;
15}

Returns​

TypeValueDescription
pubnub_subloop_t*NULLFailed to create a descriptor.
pubnub_subloop_t*otherThe descriptor created.

Subscribe loop - sync​

Creates a subscribe loop descriptor for the sync interface, returned by value. Default values are used for descriptor fields not provided as parameters.

Method(s)​

1struct pubnub_subloop_descriptor pubnub_subloop_define(pubnub_t *p, char const *channel);
* required
ParameterDescription
p *
Type: pubnub_t*
The PubNub context to use for the loop.
channel *
Type: char const*
The channel(s) to subscribe to.

Sample code​

1pbsld = pubnub_subloop_define(pbp, "hello_world");

Returns​

TypeDescription
struct pubnub_subloop_descriptorThe subscribe loop descriptor.

Start a callback subscribe loop​

Starts a subscribe loop. The callback provided in pubnub_subloop_define() is called for each message received. A running subscribe loop takes over the context and receives all callbacks for it.

Context callback

Changing the callback on the context during a running subscribe loop will break the loop.

Subscribe loop descriptor

Do not change the subscribe loop descriptor while the loop is running. Stop it first with pubnub_subloop_stop().

Method(s)​

1enum pubnub_res pubnub_subloop_start(pubnub_subloop_t* pbsld);
* required
ParameterDescription
pbsld *
Type: pubnub_subloop_t*
The subscribe loop descriptor of the loop to start.

Sample code​

1pubnub_subloop_start(pbsld);

Returns​

TypeValueDescription
enum pubnub_resPNR_OKSubscribe loop started.
enum pubnub_resotherIndicates the reason for failure.

Stop a callback subscribe loop​

Stops a subscribe loop. If the loop is delivering messages through the callback, the stop completes once delivery finishes. After stopping, the context can be used normally and the original callback is restored.

Method(s)​

1void pubnub_subloop_stop(pubnub_subloop_t* pbsld);
* required
ParameterDescription
pbsld *
Type: pubnub_subloop_t*
The subscribe loop descriptor of the loop to stop.

Sample code​

1pubnub_subloop_stop(pbsld);

Returns​

None.

Sync subscribe iteration​

Fetches the next message in a sync subscribe loop, automatically subscribing if no messages remain. This function may block for a significant time while waiting for messages to arrive.

Changing the descriptor during the loop is possible, but changes may take several iterations to take effect.

Method(s)​

1enum pubnub_res pubnub_subloop_fetch(struct pubnub_subloop_descriptor const* pbsld, char const** message);
* required
ParameterDescription
pbsld *
Type: struct pubnub_subloop_descriptor const*
The sync subscribe loop descriptor to use.
message *
Type: char const**
The fetched message, or NULL if no message was fetched.

Sample code​

1for (;;) {
2    char const* msg;
3    enum pubnub_res pbres = pubnub_subloop_fetch(&pbsld, &msg);
4    if (PNR_OK != pbres) {
5        printf("Exiting subscribe loop because of error: %d\n", pbres);
6        break;
7    }
8    if (NULL == msg) {
9        puts("Everything's OK, yet no message received");
10    } else {
11        printf("Got message '%s'\n", msg);
12    }
13}

Returns​

TypeValueDescription
enum pubnub_resPNR_OKMessage was fetched successfully.
enum pubnub_resotherIndicates the reason for failure.

Release/free the callback subscribe loop descriptor​

Releases the subscribe loop descriptor and its resources. Call this when you are done with the loop.

Method(s)​

1void pubnub_subloop_undef(pubnub_subloop_t* pbsld);
* required
ParameterDescription
pbsld *
Type: pubnub_subloop_t*
The subscribe loop descriptor to release.

Sample code​

1pubnub_subloop_undef(pbsld);

Returns​

None.

PubNub register callback​

Registers a callback function to be called when a transaction ends. Registering a NULL pointer (the initial value after pubnub_init()) means no callback will be called. Do not make assumptions about the thread on which this function is called.

Method(s)​

1enum pubnub_res pubnub_register_callback(pubnub_t *pb, pubnub_callback_t cb, void *user_data)
* required
ParameterDescription
pb *
Type: pubnub_t*
The PubNub context for which to set the callback.
cb
Type: pubnub_callback_t
Pointer to the function to call on end of transaction.
user_data
Type: void*
Pointer passed to the callback function.

Sample code​

1pubnub_register_callback(ctx, sample_callback, &user_data);

Returns​

TypeDescription
enum pubnub_resPNR_OK on success, an error value otherwise.

PubNub get user data​

Returns the user data set with pubnub_register_callback().

Method(s)​

1void *pubnub_get_user_data(pubnub_t *pb)
* required
ParameterDescription
pb *
Type: pubnub_t*
PubNub client context for which to return user data.

Sample code​

1void* user_data = pubnub_get_user_data(ctx);

Returns​

TypeDescription
void*User data set with pubnub_register_callback.

Set blocking IO​

Enables blocking I/O for a context. If supported by the platform, blocking I/O is used unless another reason prevents it.

With blocking I/O, polling for a transaction outcome blocks the caller's thread until the outcome is reached. This results in simpler code but scales poorly.

Method(s)​

1int pubnub_set_blocking_io(pubnub_t *p)
* required
ParameterDescription
p *
Type: pubnub_t*
The context to set blocking I/O for.

Sample code​

1pubnub_t *ctx = pubnub_alloc();
2if (NULL == ctx) {
3  puts("Couldn't allocate a Pubnub context");
4  return -1;
5}
6if (0 == pubnub_set_blocking_io(ctx)) {
7  puts("Context set to blocking");
8}

Returns​

TypeDescription
int0 on success; otherwise, blocking I/O is not supported.

Set non blocking IO​

Enables non-blocking I/O for a context. If supported by the platform, non-blocking I/O is used unless another reason prevents it.

With non-blocking I/O, polling for a transaction outcome returns immediately with the current status, so you must poll repeatedly until the outcome is reached. This results in more complex code but scales better.

Method(s)​

1int pubnub_set_non_blocking_io(pubnub_t *p)
* required
ParameterDescription
p *
Type: pubnub_t*
The context to set non-blocking I/O for.

Sample code​

1pubnub_t *ctx = pubnub_alloc();
2if (NULL == ctx) {
3  puts("Couldn't allocate a Pubnub context");
4  return -1;
5}
6if (0 == pubnub_set_non_blocking_io(ctx)) {
7  puts("Context set to non blocking");
8}

Returns​

TypeDescription
int0 on success; otherwise, non-blocking I/O is not supported.

PubNub use HTTP keep alive​

Enables HTTP Keep-Alive (persistent connections) on the context. This is the default behavior. You can disable it with pubnub_dont_use_http_keep_alive().

When active, connections to PubNub remain open after a transaction ends, making subsequent transactions faster. However, keep-alive has trade-offs:

  • pubnub_free() does not work for contexts in a keep-alive state. Call pubnub_cancel() first.
  • The PubNub server may close idle keep-alive connections, which could cause a transaction to fail due to a race condition.
  • Keep-alive sockets remain allocated, consuming resources.

Method(s)​

1void pubnub_use_http_keep_alive (pubnub_t* p)
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context.

Sample code​

1pubnub_use_http_keep_alive(pbp);

Returns​

None.

PubNub do not use HTTP keep alive​

Disables HTTP Keep-Alive (persistent connections) on the context. See pubnub_use_http_keep_alive() for details on the default behavior.

Method(s)​

1void pubnub_dont_use_http_keep_alive (pubnub_t* p)
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context.

Sample code​

1pubnub_dont_use_http_keep_alive(pbp);

Returns​

None.

PubNub use TCP keep alive​

Enables TCP Keep-Alive probes on the context. TCP Keep-Alive sends periodic probes on an idle connection to detect if the remote peer is still reachable.

HTTP Keep-Alive required

This option works only together with HTTP Keep-Alive. Make sure HTTP Keep-Alive is enabled with pubnub_use_http_keep_alive() before using TCP Keep-Alive.

Default values:

  • time: 60 seconds (idle time before first probe)
  • interval: 20 seconds (time between probes)
  • probes: 3 (number of unanswered probes before the connection is deemed broken)

Method(s)​

1void pubnub_use_tcp_keep_alive(
2    pubnub_t* pb,
3    uint8_t   time,
4    uint8_t   interval,
5    uint8_t   probes);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
time *
Type: uint8_t
Seconds of idle time before the first keep-alive probe.
interval *
Type: uint8_t
Seconds between keep-alive probes if the previous one was not acknowledged.
probes *
Type: uint8_t
Number of unacknowledged probes before the connection is deemed broken.

Sample code​

1// Enable HTTP keep-alive first
2pubnub_use_http_keep_alive(pbp);
3

4// Then enable TCP keep-alive with custom parameters:
5// - Start probing after 30 seconds of idle
6// - Send probes every 10 seconds
7// - Give up after 5 unanswered probes
8pubnub_use_tcp_keep_alive(pbp, 30, 10, 5);

Returns​

None.

PubNub do not use TCP keep alive​

Disables TCP Keep-Alive probes on the context.

Method(s)​

1void pubnub_dont_use_tcp_keep_alive(pubnub_t* pb);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.

Sample code​

1pubnub_dont_use_tcp_keep_alive(pbp);

Returns​

None.

Set the transaction timeout​

Sets the transaction timeout for the context. This applies to all subsequent transactions. If an ongoing transaction supports changing its timeout, the change takes effect immediately.

C-Core (legacy) does not distinguish between subscribe and other transaction timeouts to save space. If timer support is available, pubnub_init() sets a default timeout that is configurable at compile time.

Preconditions​

  • Call this after pubnub_init() on the context and before starting a transaction.
  • Duration must be greater than 0.

Method(s)​

1int pubnub_set_transaction_timeout(pubnub_t *p, int duration_ms)
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context.
duration_ms *
Type: int
Duration of the timeout, in milliseconds.

Sample code​

1#include "pubnub_timers.h"
2pubnub_set_transaction_timeout(pn, PUBNUB_DEFAULT_SUBSCRIBE_TIMEOUT);

Returns​

TypeDescription
int0 on success; otherwise, timers are not supported.

Get the transaction timeout​

Returns the current transaction timeout for the context.

Preconditions​

  • Call this after pubnub_init() on the context.

Method(s)​

1int pubnub_transaction_timeout_get(pubnub_t *p)
* required
ParameterDescription
p *
Type: pubnub_t*
Pointer to PubNub client context.

Sample code​

1#include "pubnub_timers.h"
2...
3printf("Current transaction timeout: %d\n", pubnub_transaction_timeout_get(pn));

Returns​

TypeDescription
intCurrent transaction timeout in milliseconds (always greater than 0).

Get the current origin​

Returns the origin used for the context. If setting a custom origin is not enabled, this returns the default origin.

Method(s)​

1char const* pubnub_get_origin(pubnub_t *p)
* required
ParameterDescription
p *
Type: pubnub_t*
PubNub context to get the origin from.

Sample code​

1printf("Current origin: %s\n", pubnub_get_origin(pn));

Returns​

TypeDescription
char const*A read-only string of the origin used for the given context.

Configure proxy to be used from the system​

Sets proxy configuration by reading from the system configuration. On some platforms (like Windows), there is a standard way of setting a proxy. On other platforms, C-Core (legacy) does its best.

This function can block for a significant time if the system is configured for proxy auto-discovery. Call it only at start, restart, wake-up, or similar events.

Preconditions​

  • Call this after pubnub_init() on the context.

Method(s)​

1int pubnub_set_proxy_from_system(pubnub_t *p, enum pubnub_proxy_type protocol);
* required
ParameterDescription
p *
Type: pubnub_t*
The context to set proxy configuration for.
protocol *
Type: enum pubnub_proxy_type
Proxy protocol to use.

Sample code​

1pubnub_set_proxy_from_system(pbp, pbpproxyHTTP_GET);

Returns​

TypeValueDescription
int0OK.
intnon-zeroError: specified protocol not supported or system configuration unavailable.

Set proxy to be used​

Sets the proxy configuration by explicitly specifying the protocol, server, and port. If proxy support is available, pubnub_init() defaults to no proxy.

Preconditions​

  • Call this after pubnub_init() on the context.
  • If protocol is not pbproxyNONE, then ip_address_or_url must not be NULL.

Method(s)​

1int pubnub_set_proxy_manual(pubnub_t *p, enum pubnub_proxy_type protocol, char const *ip_address_or_url, uint16_t port);
* required
ParameterDescription
p *
Type: pubnub_t*
The context to set proxy configuration for.
protocol *
Type: enum pubnub_proxy_type
Proxy protocol to use.
ip_address_or_url *
Type: char const*
IP address or URL of the proxy server.
port *
Type: uint16_t
Port number on the proxy. Port 3128 is commonly used.

Sample code​

1pubnub_set_proxy_manual(pbp, pbpproxyHTTP_GET, "proxy.local", 3128);

Returns​

TypeValueDescription
int0OK.
intnon-zeroError: specified protocol not supported or invalid address/URL.

Get current proxy protocol for a context​

Returns the current proxy type/protocol for the context.

Method(s)​

1enum pubnub_proxy_type pubnub_proxy_protocol_get(pubnub_t *p);
* required
ParameterDescription
p *
Type: pubnub_t*
The PubNub context to get the proxy protocol for.

Sample code​

1enum pubnub_proxy_type proxy = pubnub_proxy_protocol_get(pbp);

Returns​

TypeDescription
enum pubnub_proxy_typeThe proxy protocol used. Returns pbpproxyNONE if no proxy is set.

Get current proxy authentication scheme​

Returns the current HTTP proxy authentication scheme for the context. The scheme is set dynamically during communication with the proxy.

Method(s)​

1enum pubnub_http_authentication_scheme pubnub_proxy_authentication_scheme_get(pubnub_t *p);
* required
ParameterDescription
p *
Type: pubnub_t*
The context to get the proxy authentication scheme for.

Sample code​

1enum pubnub_http_authentication_scheme sch = pubnub_authentication_scheme_get(pbp);
2switch (sch) {
3    case pbhtauBasic:
4        puts("Basic authentication scheme");
5    break;
6    case pbhtauDigest:
7        puts("Digest authentication scheme");
8    break;
9    case pbhtauNTLM:
10        puts("Microsoft NTLM authentication scheme");
11    break;
12    case pbhtauNone:
13        puts("No authentication scheme");
14    break;
15}

Returns​

TypeDescription
enum pubnub_http_authentication_schemeThe authentication scheme used. Returns pbhtauNone if the proxy does not require authentication.

Set username and password for authenticating proxy​

Sets the authentication credentials and scheme for proxy authentication. The default credentials are the currently logged-on username and password (if available at runtime), or the built-in C-Core (legacy) defaults.

Preconditions​

  • Call this after pubnub_init() on the context.

Method(s)​

1int pubnub_set_proxy_authentication_username_password(pubnub_t *p, char const *username, char const *password);
* required
ParameterDescription
p *
Type: pubnub_t*
The context to set proxy authentication for.
username
Type: char const*
Authentication username. Use NULL to use the default.
password
Type: char const*
Authentication password. Use NULL to use the default.

Sample code​

1pubnub_set_proxy_authentication_username_password(pbp, "bond", "007");

Returns​

TypeValueDescription
int0OK.
intnon-zeroError: setting username/password failed.

Reset username and password for authenticating proxy​

Resets the context to not use any proxy authentication scheme. This is the default state, so you only need to call this function to reset a previously configured authentication scheme.

Preconditions​

  • Call this after pubnub_init() on the context.

Method(s)​

1int pubnub_set_proxy_authentication_none(pubnub_t *p);
* required
ParameterDescription
p *
Type: pubnub_t*
The context to reset proxy authentication for.

Sample code​

1pubnub_set_proxy_authentication_none(pbp);

Returns​

TypeValueDescription
int0OK.
intnon-zeroError: authentication scheme doesn't support reset.

Set the primary DNS server​

Sets the primary DNS server IPv4 address (in binary, network order) for resolving the PubNub origin on a specific context. Applies to all subsequent DNS queries on that context.

The C-Core (legacy) DNS module is not always used. It is typically used for the callback interface because it works asynchronously. On platforms with asynchronous system resolvers, C-Core (legacy) can be configured to use those instead. If the DNS module is not used, this function has no effect.

Method(s)​

1int pubnub_dns_set_primary_server_ipv4(pubnub_t* pb, struct pubnub_ipv4_address ipv4);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
ipv4 *
Type: struct pubnub_ipv4_address
The IPv4 address of the server to use. Set all bytes to 0 to disable.

Sample code​

1struct pubnub_ipv4_address addr = { { 8, 8, 8, 8 } };
2if (0 != pubnub_dns_set_primary_server_ipv4(pb, addr)) {
3    printf("Setting primary DNS server failed\n");
4}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used.

Set the primary DNS server by string​

Sets the primary DNS server IPv4 address from a numbers-and-dots notation string for resolving the PubNub origin.

The DNS module in C-Core (legacy) is not always used, see pubnub_dns_set_primary_server_ipv4().

Method(s)​

1int pubnub_dns_set_primary_server_ipv4_str(pubnub_t* pb, char const* ipv4_str);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
ipv4_str *
Type: char const*
The IPv4 address in numbers-and-dots notation.

Sample code​

1if (0 != pubnub_dns_set_primary_server_ipv4_str(pb, "8.8.8.8")) {
2    printf("Setting primary DNS server failed\n");
3}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used.

Get the primary DNS server​

Reads the currently set primary DNS server's IPv4 address, in binary form (network order).

The DNS module in C-Core (legacy) is not always used, see pubnub_dns_set_primary_server_ipv4().

Method(s)​

1int pubnub_get_dns_primary_server_ipv4(pubnub_t* pb, struct pubnub_ipv4_address* o_ipv4);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
o_ipv4 *
Type: struct pubnub_ipv4_address*
Pointer to the IPv4 address struct, allocated by the caller.

Sample code​

1struct pubnub_ipv4_address addr;
2if (0 != pubnub_get_dns_primary_server_ipv4(pb, &addr)) {
3    printf("Getting primary DNS server failed\n");
4}
5else {
6    printf("Primary DNS server: %d.%d.%d.%d\n", addr.ipv4[0], addr.ipv4[1], addr.ipv4[2], addr.ipv4[3]);
7}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used.

Set the secondary DNS server​

Sets the secondary DNS server IPv4 address (in binary, network order) for resolving the PubNub origin on a specific context. The secondary server is used if a query to the primary server fails.

The DNS module in C-Core (legacy) is not always used, see pubnub_dns_set_primary_server_ipv4().

Method(s)​

1int pubnub_dns_set_secondary_server_ipv4(pubnub_t* pb, struct pubnub_ipv4_address ipv4);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
ipv4 *
Type: struct pubnub_ipv4_address
The IPv4 address of the server to use. Set all bytes to 0 to disable.

Sample code​

1struct pubnub_ipv4_address addr = { { 8, 8, 4, 4 } }; // Google secondary DNS
2if (0 != pubnub_dns_set_secondary_server_ipv4(pb, addr)) {
3    printf("Setting secondary DNS server failed\n");
4}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used.

Set the secondary DNS server by string​

Sets the secondary DNS server IPv4 address from a numbers-and-dots notation string for resolving the PubNub origin. The secondary server is used if a query to the primary server fails.

The DNS module in C-Core (legacy) is not always used, see pubnub_dns_set_primary_server_ipv4().

Method(s)​

1int pubnub_dns_set_secondary_server_ipv4_str(pubnub_t* pb, char const* ipv4_str);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
ipv4_str *
Type: char const*
The IPv4 address in numbers-and-dots notation. Set "0.0.0.0" to disable.

Sample code​

1if (0 != pubnub_dns_set_secondary_server_ipv4_str(pb, "8.8.4.4")) {
2    printf("Setting secondary DNS server failed\n");
3}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used.

Get the secondary DNS server​

Reads the currently set secondary DNS server's IPv4 address, in binary form (network order).

The DNS module in C-Core (legacy) is not always used, see pubnub_dns_set_primary_server_ipv4().

Method(s)​

1int pubnub_get_dns_secondary_server_ipv4(pubnub_t* pb, struct pubnub_ipv4_address* o_ipv4);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
o_ipv4 *
Type: struct pubnub_ipv4_address*
Pointer to the IPv4 address struct, allocated by the caller.

Sample code​

1struct pubnub_ipv4_address addr;
2if (0 != pubnub_get_dns_secondary_server_ipv4(pb, &addr)) {
3    printf("Getting secondary DNS server failed\n");
4}
5else {
6    printf("Secondary DNS server: %d.%d.%d.%d\n", addr.ipv4[0], addr.ipv4[1], addr.ipv4[2], addr.ipv4[3]);
7}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used.

Get a list of system DNS servers​

Reads IPv4 DNS servers from the system configuration. Reads at most n servers, even if more are configured. On modern systems, this may return only one DNS server listening on the loopback address.

On POSIX systems, this reads from /etc/resolv.conf. On Windows, this uses system functions.

Method(s)​

1int pubnub_dns_read_system_servers_ipv4(pubnub_t* pb, struct pubnub_ipv4_address* o_ipv4, size_t n);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
o_ipv4 *
Type: struct pubnub_ipv4_address*
Array to store the DNS server addresses, allocated by the caller for n elements.
n *
Type: size_t
Number of elements allocated for o_ipv4.

Sample code​

1struct pubnub_ipv4_address addr[MAX_DNS_SRV];
2int c = pubnub_dns_read_system_servers_ipv4(pb, addr, MAX_DNS_SRV);
3if (c < 0) {
4    printf("Can't get list of system DNS servers!\n");
5}
6else {
7    int i;
8    for (i = 0; i < c; ++i) {
9        printf("System DNS server %d.: %d.%d.%d.%d\n", i, addr[i].ipv4[0], addr[i].ipv4[1], addr[i].ipv4[2], addr[i].ipv4[3]);
10    }
11}

Returns​

TypeValueDescription
int-1Error: cannot read system DNS servers.
int>= 0The number of DNS servers read.

Set the primary DNS server (IPv6)​

Sets the primary DNS server IPv6 address (in binary, network order) for resolving the PubNub origin on a specific context. Applies to all subsequent DNS queries on that context.

Availability

This function is only available when the SDK is built with both PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS enabled. For more information, see PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS.

When IPv6 is enabled, the SDK tries user-provided IPv6 DNS servers first, then falls back to user-provided IPv4 servers, and finally falls back to well-known DNS providers.

Method(s)​

1int pubnub_dns_set_primary_server_ipv6(pubnub_t* pb, struct pubnub_ipv6_address ipv6);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
ipv6 *
Type: struct pubnub_ipv6_address
The IPv6 address of the server to use. Set all bytes to 0 to disable.

Sample code​

1struct pubnub_ipv6_address addr = { { 0x20, 0x01, 0x48, 0x60, 0x48, 0x60, 0x00, 0x00,
2                                      0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x88, 0x88 } }; // Google IPv6 DNS
3if (0 != pubnub_dns_set_primary_server_ipv6(pb, addr)) {
4    printf("Setting primary IPv6 DNS server failed\n");
5}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used or IPv6 not enabled.

Set the secondary DNS server (IPv6)​

Sets the secondary DNS server IPv6 address (in binary, network order) for resolving the PubNub origin. The secondary server is used if a query to the primary server fails.

Availability

This function is only available when the SDK is built with both PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS enabled. For more information, see PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS.

Method(s)​

1int pubnub_dns_set_secondary_server_ipv6(pubnub_t* pb, struct pubnub_ipv6_address ipv6);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
ipv6 *
Type: struct pubnub_ipv6_address
The IPv6 address of the server to use. Set all bytes to 0 to disable.

Sample code​

1struct pubnub_ipv6_address addr = { { 0x20, 0x01, 0x48, 0x60, 0x48, 0x60, 0x00, 0x00,
2                                      0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x88, 0x44 } }; // Google secondary IPv6 DNS
3if (0 != pubnub_dns_set_secondary_server_ipv6(pb, addr)) {
4    printf("Setting secondary IPv6 DNS server failed\n");
5}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used or IPv6 not enabled.

Set the primary DNS server by string (IPv6)​

Sets the primary DNS server IPv6 address from a numbers-and-colons notation string for resolving the PubNub origin.

Availability

This function is only available when the SDK is built with both PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS enabled.

Method(s)​

1int pubnub_dns_set_primary_server_ipv6_str(pubnub_t* pb, char const* ipv6_str);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
ipv6_str *
Type: char const*
The IPv6 address in numbers-and-colons notation. Use "::0" to disable.

Sample code​

1if (0 != pubnub_dns_set_primary_server_ipv6_str(pb, "2001:4860:4860::8888")) {
2    printf("Setting primary IPv6 DNS server failed\n");
3}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used or IPv6 not enabled.

Set the secondary DNS server by string (IPv6)​

Sets the secondary DNS server IPv6 address from a numbers-and-colons notation string for resolving the PubNub origin.

Availability

This function is only available when the SDK is built with both PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS enabled. For more information, see PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS.

Method(s)​

1int pubnub_dns_set_secondary_server_ipv6_str(pubnub_t* pb, char const* ipv6_str);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
ipv6_str *
Type: char const*
The IPv6 address in numbers-and-colons notation. Use "::0" to disable.

Sample code​

1if (0 != pubnub_dns_set_secondary_server_ipv6_str(pb, "2001:4860:4860::8844")) {
2    printf("Setting secondary IPv6 DNS server failed\n");
3}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used or IPv6 not enabled.

Get the primary DNS server (IPv6)​

Reads the currently set primary DNS server's IPv6 address, in binary form (network order).

Availability

This function is only available when the SDK is built with both PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS enabled. For more information, see PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS.

Method(s)​

1int pubnub_get_dns_primary_server_ipv6(pubnub_t* pb, struct pubnub_ipv6_address* o_ipv6);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
o_ipv6 *
Type: struct pubnub_ipv6_address*
Pointer to the IPv6 address struct, allocated by the caller.

Sample code​

1struct pubnub_ipv6_address addr;
2if (0 != pubnub_get_dns_primary_server_ipv6(pb, &addr)) {
3    printf("Getting primary IPv6 DNS server failed\n");
4}
5else {
6    printf("Primary IPv6 DNS server retrieved successfully\n");
7}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used or IPv6 not enabled.

Get the secondary DNS server (IPv6)​

Reads the currently set secondary DNS server's IPv6 address, in binary form (network order).

Availability

This function is only available when the SDK is built with both PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS enabled. For more information, see PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS.

Method(s)​

1int pubnub_get_dns_secondary_server_ipv6(pubnub_t* pb, struct pubnub_ipv6_address* o_ipv6);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
o_ipv6 *
Type: struct pubnub_ipv6_address*
Pointer to the IPv6 address struct, allocated by the caller.

Sample code​

1struct pubnub_ipv6_address addr;
2if (0 != pubnub_get_dns_secondary_server_ipv6(pb, &addr)) {
3    printf("Getting secondary IPv6 DNS server failed\n");
4}
5else {
6    printf("Secondary IPv6 DNS server retrieved successfully\n");
7}

Returns​

TypeValueDescription
int0OK.
int-1Error: PubNub DNS module not used or IPv6 not enabled.

Get a list of system DNS servers (IPv6)​

Reads IPv6 DNS servers from the system configuration. Reads at most n servers, even if more are configured.

On POSIX systems, this reads from /etc/resolv.conf. On Windows, this uses system functions.

Availability

This function is only available when the SDK is built with both PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS enabled. For more information, see PUBNUB_USE_IPV6 and PUBNUB_SET_DNS_SERVERS.

Method(s)​

1int pubnub_dns_read_system_servers_ipv6(pubnub_t* pb, struct pubnub_ipv6_address* o_ipv6, size_t n);
* required
ParameterDescription
pb *
Type: pubnub_t*
Pointer to the PubNub context.
o_ipv6 *
Type: struct pubnub_ipv6_address*
Array to store the DNS server addresses, allocated by the caller for n elements.
n *
Type: size_t
Number of elements allocated for o_ipv6.

Sample code​

1#define MAX_DNS_SRV 4
2struct pubnub_ipv6_address addr[MAX_DNS_SRV];
3int c = pubnub_dns_read_system_servers_ipv6(pb, addr, MAX_DNS_SRV);
4if (c < 0) {
5    printf("Can't get list of system IPv6 DNS servers!\n");
6}
7else {
8    printf("Found %d IPv6 DNS servers\n", c);
9}

Returns​

TypeValueDescription
int-1Error: cannot read system DNS servers.
int>= 0The number of DNS servers read.

Set CA verify locations​

Sets the CA certificate locations for SSL/TLS verification. This function is only available on targets with a file system.

By default, both parameters are NULL, and C-Core (legacy) uses its built-in certificates. If built-in certificates expire, you can use this function with an up-to-date certificate store to avoid code changes.

Both parameters are stored as pointers, so the caller must keep the strings valid for the lifetime of the context or until they are set to NULL.

Preconditions​

  • The context must be valid.

Method(s)​

1int pubnub_set_ssl_verify_locations(pubnub_t *p, char const* sCAfile, char const* sCApath);
* required
ParameterDescription
p *
Type: pubnub_t*
PubNub context to set locations for.
sCAfile
Type: char const*
Path to a certificate store file (may contain multiple CA certificates). Set to NULL to skip.
sCApath
Type: char const*
Path to a certificate store directory (each file should contain one CA certificate). Set to NULL to skip.

Sample code​

1if (0 != pubnub_set_ssl_verify_locations(pbp, "/etc/ssl/certs/ca-certificates.crt", "/usr/share/ca-certificates/mozilla")) {
2    puts("Failed to set SSL verify locations");
3}

Returns​

TypeValueDescription
int0OK.
int-1Failed to set certificate locations.

Set user defined / in-memory certificate​

Sets a user-defined, in-memory PEM certificate for the context. This certificate is used in addition to other certificates. Copy the certificate from a .pem file into a string and pass it to this function.

Unlike other certificate-handling functions, this one is available on any platform, including deeply embedded ones. It is meant primarily for debugging with proxy debuggers (such as Fiddler or Charles). There is only one user-defined PEM certificate per context.

Preconditions​

  • The context must be valid.

Method(s)​

1void pubnub_ssl_set_usrdef_pem_cert(pubnub_t *p, char const *contents);
* required
ParameterDescription
p *
Type: pubnub_t*
The context to set the PEM certificate for.
contents *
Type: char const*
String containing the PEM certificate. Must remain valid for the lifetime of the context. Use NULL to remove the certificate.

Sample code​

1static char const my_cert[] = "-----BEGIN CERTIFICATE-----\n"
2...
3    "-----END CERTIFICATE-----\n";
4

5pubnub_ssl_set_usrdef_pem_cert(pbp, my_cert);

Returns​

None.

Set/enable use of system certificate store​

Instructs C-Core (legacy) to use the system certificate store for the context. This is only available on targets with a system certificate store (such as Windows).

By default, the system certificate store is not used. When enabled, it takes precedence over other certificates. To disable it later, call pubnub_ssl_dont_use_system_certificate_store().

Preconditions​

  • The context must be valid.

Method(s)​

1int pubnub_ssl_use_system_certificate_store(pubnub_t *p);
* required
ParameterDescription
p *
Type: pubnub_t*
The context for which to enable the system certificate store.

Sample code​

1if (0 != pubnub_ssl_use_system_certificate_store(pbp)) {
2    puts("Using system certificate store not supported");
3}

Returns​

TypeValueDescription
int0OK.
int-1System certificate store not supported.

Unset/disable use of system certificate store​

Disables the system certificate store for the context (this is also the default). Use this function only to reverse a previous call to pubnub_ssl_use_system_certificate_store().

Preconditions​

  • The context must be valid.

Method(s)​

1void pubnub_ssl_dont_use_system_certificate_store(pubnub_t *p);
* required
ParameterDescription
p *
Type: pubnub_t*
The context for which to disable the system certificate store.

Sample code​

1pubnub_ssl_dont_use_system_certificate_store(pbp);

Returns​

None.

Generate UUID random​

Generates a UUID using the v4 algorithm (random-based). This algorithm needs no state but requires a random number generator of good quality, which may not be available on all platforms.

Method(s)​

1int pubnub_generate_uuid_v4_random(struct Pubnub_UUID *uuid)
* required
ParameterDescription
uuid *
Type: struct Pubnub_UUID*
Pointer to store the generated UUID.

Sample code​

1struct Pubnub_UUID uuid;
2if (0 == pubnub_generate_uuid_v4_random(&uuid)) {
3    puts("UUID generation unsuccessful");
4}

Returns​

TypeDescription
int0: generated successfully. Non-zero: random number generator not available.

Other examples​

Subscribe to a channel with a unique name​

1struct Pubnub_UUID uuid;
2char channel_name;
3if (0 == pubnub_generate_uuid_v4_random(&uuid)) {
4    channel_name = pubnub_uuid_to_string(&uuid).uuid;
5}
6pubnub_t ctx = pubnub_alloc();
7if (NULL == ctx) {
8    puts("Couldn't allocate a Pubnub context");
9    return -1;
10}
11pubnub_init(ctx, "demo", "demo");
12pubnub_subscribe(ctx, channel_name, NULL);
13pbresult = pubnub_await(ctx);
14if (pbresult != PNR_OK) {
15    printf("Failed to subscribe, error %d\n", pbresult);
show all 28 lines

Create a unique authentication key for Access Manager​

1struct Pubnub_UUID uuid;
2char *auth_key;
3if (0 == pubnub_generate_uuid_v4_random(&uuid)) {
4    auth_key = pubnub_uuid_to_string(&uuid).uuid;
5    pubnub_init(ctx, "demo", "demo");
6    pubnub_set_auth(ctx, auth_key);
7}

Generate UUID MD5​

Generates a UUID using the v3 algorithm (name-based with MD5 hash). MD5 may not be available on all platforms.

Method(s)​

1int pubnub_generate_uuid_v3_name_md5(struct Pubnub_UUID *uuid, struct Pubnub_UUID *nsid, void *name, unsigned namelen)
* required
ParameterDescription
uuid *
Type: struct Pubnub_UUID*
Pointer to store the generated UUID.
nsid *
Type: struct Pubnub_UUID*
UUID of the namespace.
name *
Type: void*
Pointer to the data that defines the name for UUID generation.
namelen *
Type: unsigned
Length of the name data.

Sample code​

1char *name = "abcd";
2struct Pubnub_UUID uuid;
3struct Pubnub_UUID nsid =  { {'x', 'y', 'z', 0} };;
4if (0 != pubnub_generate_uuid_v3_name_md5(&uuid, &nsid, name, 4)) {
5    puts("UUID generation unsuccessful");
6}

Returns​

TypeDescription
int0: generated successfully. Non-zero: algorithm not available.

Generate UUID time​

Generates a UUID using the v1 algorithm (time-based). This algorithm uses the MAC address (or another identifier) as the node identity, a 100-nanosecond timestamp since October 15, 1582, and a clock sequence.

On the first call, provide a random value in io_clock_seq. On subsequent calls, reuse the same variable; the function updates it as needed. If you don't have a random number generator, use any pseudo-random source (such as a timer tick) and mix the values with XOR.

While complex to use, this algorithm is highly portable and can work on virtually any platform without needing to obtain unique identifiers yourself.

Method(s)​

1int pubnub_generate_uuid_v1_time(struct Pubnub_UUID *o_uuid, uint16_t *io_clock_seq, uint8_t const i_timestamp[8], uint8_t const i_node[6]);
* required
ParameterDescription
o_uuid *
Type: struct Pubnub_UUID*
Pointer to store the generated UUID.
io_clock_seq *
Type: uint16_t*
Clock sequence. Initialize to a random value on first call, then reuse.
i_timestamp *
Type: uint8_t const[8]
Count of 100-nanosecond intervals since 00:00:00.00, 15 October 1582.
i_node *
Type: uint8_t const[6]
A 6-octet node identity (typically an IEEE 802 MAC address).

Sample code​

1struct Pubnub_UUID uuid;
2uint16_t clock_seq = 4443; /* some random value */
3uint8_t timestamp[8]; /* get a time stamp somehow */
4uint8_t node[6] = { 0x5F, 0x82, 0x11, 0x58, 0x02, 0x61 }; /* example MAC address */
5if (0 != pubnub_generate_uuid_v1_time(&uuid, &clock_seq, timestamp, node)) {
6    printf("Failed to generate a v1 (time based) UUID\n");
7}

Returns​

TypeDescription
int0: generated successfully. Non-zero: algorithm not available.

UUID compare​

Compares two UUIDs and returns an integer indicating their relative order: 0 if equal, less than 0 if left is smaller, greater than 0 if left is larger.

Method(s)​

1int pubnub_uuid_compare(struct Pubnub_UUID const *left, struct Pubnub_UUID const *right)
* required
ParameterDescription
left *
Type: struct Pubnub_UUID const*
First UUID to compare.
right *
Type: struct Pubnub_UUID const*
Second UUID to compare.

Sample code​

1struct Pubnub_UUID left;
2struct Pubnub_UUID right;
3if (0 != pubnub_generate_uuid_v4_random(&left) || 0 != pubnub_generate_uuid_v4_random(&right)) {
4    puts("UUID generation unsuccessful");
5}
6int RC = pubnub_uuid_compare(left, right);
7if (0 == RC) puts ("left == right");
8else if (RC > 0) puts("left > right");
9else puts ("left < right");

Returns​

TypeDescription
int0 if equal, <0 if left < right, >0 if left > right.

UUID to string​

Returns a UUID as a standard hexadecimal string representation.

Method(s)​

1struct Pubnub_UUID_String pubnub_uuid_to_string(struct Pubnub_UUID const *uuid)
* required
ParameterDescription
uuid *
Type: struct Pubnub_UUID const*
UUID to convert to string.

Sample code​

1struct Pubnub_UUID uuid;
2if (0 == pubnub_generate_uuid_v4_random(&uuid)) {
3    printf("UUID generation successful. UUID is %s", pubnub_uuid_to_string(&uuid).uuid);
4}

Returns​

TypeDescription
struct Pubnub_UUID_StringString representation of the UUID.

PubNub SDK name​

Returns a string with the name of the PubNub SDK client.

Method(s)​

1char const *pubnub_sdk_name(void)

This method has no arguments.

Sample code​

1printf("SDK name  : %s", pubnub_sdk_name());

Returns​

TypeDescription
char const*Name of the PubNub SDK client.

PubNub version​

Returns a string with the version of the PubNub SDK client.

Method(s)​

1char const *pubnub_version(void)

This method has no arguments.

Sample code​

1printf("VERSION : %s", pubnub_version());

Returns​

TypeDescription
char const*Version of the PubNub SDK client.

PubNub uname​

Returns a URL-encoded string with the full identification of the SDK, including name, version, and possibly additional metadata.

Method(s)​

1char const *pubnub_uname(void)

This method has no arguments.

Sample code​

1printf("uname : %s", pubnub_uname());

Returns​

TypeDescription
char const*URL-encoded string with full SDK identification.

PubNub SRAND time​

Seeds the C standard srand() function using the time returned from PubNub's time operation. This is useful for systems without a Real-Time Clock (RTC) that need a high-fidelity time seed.

This function requires a round-trip to PubNub and assumes the sync interface (it uses pubnub_await() internally). Call it only once at program start.

Method(s)​

1int srand_from_pubnub_time(pubnub_t *pbp);
* required
ParameterDescription
pbp *
Type: pubnub_t*
The PubNub context to use to get time.

Sample code​

1printf("srand from pubnub time %s\n", srand_from_pubnub_time(ctx));

Returns​

TypeDescription
int0: OK. -1: error (srand() was not called).

Enums​

pubnub_res​

Result codes for functions and transactions.

MemberDescription
PNR_OKSuccess. Transaction finished successfully.
PNR_ADDR_RESOLUTION_FAILEDPubNub host name resolution failed. Could not get an IP address from the PubNub host name (origin). Most often caused by a DNS error.
PNR_CONNECT_FAILEDConnecting to the PubNub server failed. Usually indicates a network outage. If using SSL/TLS, it could also be a TLS error.
PNR_CONNECTION_TIMEOUTA timeout occurred in the network, typically because of a network outage while connected to the PubNub server.
PNR_TIMEOUTTimeout before the request completed. Detected by the PubNub client itself, not the TCP/IP stack.
PNR_ABORTEDConnection to PubNub aborted (in most cases, a TCP reset was received).
PNR_IO_ERRORCommunication error (network or HTTP response format).
PNR_HTTP_ERRORHTTP error. Call pubnub_last_http_code() to get the error code.
PNR_FORMAT_ERRORUnexpected input in received JSON.
PNR_CANCELLEDRequest cancelled by user.
PNR_STARTEDTransaction started. Await the outcome.
PNR_IN_PROGRESSTransaction already ongoing. Cannot start a transaction while another is in progress.
PNR_RX_BUFF_NOT_EMPTYReceive buffer (from previous transaction) not read; cannot start a subscription.
PNR_TX_BUFF_TOO_SMALLThe buffer is too small. Increase PUBNUB_BUF_MAXLEN.
PNR_INVALID_CHANNELChannel specification or name is invalid.
PNR_PUBLISH_FAILEDPublish transaction failed. Call pubnub_last_publish_result() to see the reason.
PNR_CHANNEL_REGISTRY_ERRORChannel registry transaction failed. Get the value for key message from the JSON response for the error description, and key status for the numeric error code.
PNR_REPLY_TOO_BIGReply is too big to fit in the reply buffer (whether statically or dynamically allocated).

pubnub_trans​

Type of PubNub operation/transaction.

MemberDescription
PBTT_NONENo transaction.
PBTT_SUBSCRIBESubscribe operation.
PBTT_PUBLISHPublish operation.
PBTT_LEAVELeave channel(s) operation.
PBTT_TIMETime (get server time) operation.
PBTT_HISTORYHistory V2 (get message history for a channel) operation.
PBTT_HERENOWHere-now (get user IDs of users present in channel(s)) operation.
PBTT_GLOBAL_HERENOWGlobal here-now (get user IDs of users present across all channels) operation.
PBTT_WHERENOWWhere-now (get channels where a user is present) operation.
PBTT_SET_STATESet state (for a user on channel(s)) operation.
PBTT_STATE_GETGet state (for a user on channel(s)) operation.
PBTT_REMOVE_CHANNEL_GROUPRemove a channel group operation.
PBTT_REMOVE_CHANNEL_FROM_GROUPRemove a channel from a channel group operation.
PBTT_ADD_CHANNEL_TO_GROUPAdd a channel to a channel group operation.
PBTT_LIST_CHANNEL_GROUPList all channels in a channel group operation.

IPv4 structure​

IPv4 address in binary format.

Method(s)​

1struct pubnub_ipv4_address {uint8_t ipv4[4];};

Members​

MemberTypeDescription
ipv4uint8_t[4]The four octets of the IPv4 address.

IPv6 structure​

IPv6 address in binary format.

Availability

This structure is only available when the SDK is built with PUBNUB_USE_IPV6 enabled. For more information, see PUBNUB_USE_IPV6.

Method(s)​

1struct pubnub_ipv6_address {uint8_t ipv6[16];};

Members​

MemberTypeDescription
ipv6uint8_t[16]The 8 double octets (big endian) of the IPv6 address.

Was this page useful?

Last updated on