Utility Methods API for C-Core 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

Type	Description
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

Parameter	Description
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

Type	Value	Description
int	0	OK, context freed.
int	-1	Context 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

Parameter	Description
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

Type	Value	Description
int	0	pubnub_free() succeeded.
int	-1	Failed 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

Parameter	Description
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

Type	Value	Description
enum pubnub_cancel_res	PN_CANCEL_STARTED	Cancel started, await the outcome.
enum pubnub_cancel_res	PN_CANCEL_FINISHED	Cancelled, 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

Parameter	Description
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

Type	Description
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

Parameter	Description
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    }
16}
17pubnub_free(ctx);

show all 17 lines

Returns

Type	Description
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:

• pubnub_set_blocking_io
• pubnub_set_non_blocking_io

Method(s)

1int pubnub_last_result(pubnub_t *p)

* required

Parameter	Description
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

Type	Description
enum pubnub_res	Result 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

Parameter	Description
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

Type	Description
int	HTTP 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

Parameter	Description
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

Type	Description
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

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

Sample code

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

Returns

Type	Description
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

Parameter	Description
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}
16res = pubnub_await(pbp);
17

18if (PNR_PUBLISH_FAILED == res) {
19  enum pubnub_publish_res publ_res = pubnub_parse_publish_result(pubnub_last_publish_result(pbp));
20  switch (publ_res) {
21  case PNPUB_INVALID_JSON: printf("Invalid JSON was sent in the publish message\n"); break;
22  default: break;
23  }
24}

show all 24 lines

Returns

Type	Description
enum pubnub_publish_res	Parsed 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

Parameter	Description
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}
16res = pubnub_await(pbp);
17printf("Response %s\n",pubnub_res_2_string(res));

show all 17 lines

Returns

Type	Description
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

Parameter	Description
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;
16        case pbccNotSet:
17            puts("Publish failed, but we decided not to retry");
18        break;
19    }
20

21    break;
22}

show all 22 lines

Returns

Type	Value	Description
enum pubnub_tribool	pbccTrue	Safe to retry, though success is not guaranteed.
enum pubnub_tribool	pbccFalse	Retrying the same transaction will not help.
enum pubnub_tribool	pbccNotSet	Retry 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

Parameter	Description
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

Type	Description
enum pubnub_res	PNR_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

Parameter	Description
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

Parameter	Description
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

Type	Value	Description
pubnub_subloop_t*	NULL	Failed to create a descriptor.
pubnub_subloop_t*	other	The 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

Parameter	Description
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

Type	Description
struct pubnub_subloop_descriptor	The 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

Parameter	Description
pbsld * Type: pubnub_subloop_t*	The subscribe loop descriptor of the loop to start.

Sample code

1pubnub_subloop_start(pbsld);

Returns

Type	Value	Description
enum pubnub_res	PNR_OK	Subscribe loop started.
enum pubnub_res	other	Indicates 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

Parameter	Description
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

Parameter	Description
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

Type	Value	Description
enum pubnub_res	PNR_OK	Message was fetched successfully.
enum pubnub_res	other	Indicates 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

Parameter	Description
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

Parameter	Description
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

Type	Description
enum pubnub_res	PNR_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

Parameter	Description
pb * Type: pubnub_t*	PubNub client context for which to return user data.

Sample code

1void* user_data = pubnub_get_user_data(ctx);

Returns

Type	Description
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

Parameter	Description
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

Type	Description
int	0 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

Parameter	Description
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

Type	Description
int	0 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

Parameter	Description
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

Parameter	Description
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

Parameter	Description
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

Parameter	Description
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 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

Parameter	Description
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

Type	Description
int	0 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

Parameter	Description
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

Type	Description
int	Current 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

Parameter	Description
p * Type: pubnub_t*	PubNub context to get the origin from.

Sample code

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

Returns

Type	Description
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 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

Parameter	Description
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

Type	Value	Description
int	0	OK.
int	non-zero	Error: 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

Parameter	Description
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

Type	Value	Description
int	0	OK.
int	non-zero	Error: 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

Parameter	Description
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

Type	Description
enum pubnub_proxy_type	The 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

Parameter	Description
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

Type	Description
enum pubnub_http_authentication_scheme	The 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 C-core's built-in 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

Parameter	Description
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

Type	Value	Description
int	0	OK.
int	non-zero	Error: 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

Parameter	Description
p * Type: pubnub_t*	The context to reset proxy authentication for.

Sample code

1pubnub_set_proxy_authentication_none(pbp);

Returns

Type	Value	Description
int	0	OK.
int	non-zero	Error: 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. Applies to all subsequent DNS queries.

The C-core 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 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(struct pubnub_ipv4_address ipv4);

* required

Parameter	Description
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(addr)) {
3    printf("Setting primary DNS server failed\n");
4}

Returns

Type	Value	Description
int	0	OK.
int	-1	Error: 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 is not always used, see pubnub_dns_set_primary_server_ipv4().

Method(s)

1int pubnub_dns_set_primary_server_ipv4_str(char const* ipv4_str);

* required

Parameter	Description
ipv4_str * Type: char const*	The IPv4 address in numbers-and-dots notation.

Sample code

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

Returns

Type	Value	Description
int	0	OK.
int	-1	Error: 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 is not always used, see pubnub_dns_set_primary_server_ipv4().

Method(s)

1int pubnub_get_dns_primary_server_ipv4(struct pubnub_ipv4_address* o_ipv4);

* required

Parameter	Description
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(&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

Type	Value	Description
int	0	OK.
int	-1	Error: 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. The secondary server is used if a query to the primary server fails.

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

Method(s)

1int pubnub_dns_set_secondary_server_ipv4(struct pubnub_ipv4_address ipv4);

* required

Parameter	Description
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(addr)) {
3    printf("Setting secondary DNS server failed\n");
4}

Returns

Type	Value	Description
int	0	OK.
int	-1	Error: 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 is not always used, see pubnub_dns_set_primary_server_ipv4().

Method(s)

1int pubnub_dns_set_secondary_server_ipv4_str(char const* ipv4_str);

* required

Parameter	Description
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("8.8.4.4")) {
2    printf("Setting secondary DNS server failed\n");
3}

Returns

Type	Value	Description
int	0	OK.
int	-1	Error: 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 is not always used, see pubnub_dns_set_primary_server_ipv4().

Method(s)

1int pubnub_get_dns_secondary_server_ipv4(struct pubnub_ipv4_address* o_ipv4);

* required

Parameter	Description
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(&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

Type	Value	Description
int	0	OK.
int	-1	Error: 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(struct pubnub_ipv4_address* o_ipv4, size_t n);

* required

Parameter	Description
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(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

Type	Value	Description
int	-1	Error: cannot read system DNS servers.
int	>= 0	The 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. Applies to all subsequent DNS queries.

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(struct pubnub_ipv6_address ipv6);

* required

Parameter	Description
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(addr)) {
4    printf("Setting primary IPv6 DNS server failed\n");
5}

Returns

Type	Value	Description
int	0	OK.
int	-1	Error: 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(struct pubnub_ipv6_address ipv6);

* required

Parameter	Description
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(addr)) {
4    printf("Setting secondary IPv6 DNS server failed\n");
5}

Returns

Type	Value	Description
int	0	OK.
int	-1	Error: 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(char const* ipv6_str);

* required

Parameter	Description
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("2001:4860:4860::8888")) {
2    printf("Setting primary IPv6 DNS server failed\n");
3}

Returns

Type	Value	Description
int	0	OK.
int	-1	Error: 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(char const* ipv6_str);

* required

Parameter	Description
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("2001:4860:4860::8844")) {
2    printf("Setting secondary IPv6 DNS server failed\n");
3}

Returns

Type	Value	Description
int	0	OK.
int	-1	Error: 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(struct pubnub_ipv6_address* o_ipv6);

* required

Parameter	Description
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(&addr)) {
3    printf("Getting primary IPv6 DNS server failed\n");
4}
5else {
6    printf("Primary IPv6 DNS server retrieved successfully\n");
7}

Returns

Type	Value	Description
int	0	OK.
int	-1	Error: 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(struct pubnub_ipv6_address* o_ipv6);

* required

Parameter	Description
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(&addr)) {
3    printf("Getting secondary IPv6 DNS server failed\n");
4}
5else {
6    printf("Secondary IPv6 DNS server retrieved successfully\n");
7}

Returns

Type	Value	Description
int	0	OK.
int	-1	Error: 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(struct pubnub_ipv6_address* o_ipv6, size_t n);

* required

Parameter	Description
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(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

Type	Value	Description
int	-1	Error: cannot read system DNS servers.
int	>= 0	The 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 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

Parameter	Description
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

Type	Value	Description
int	0	OK.
int	-1	Failed 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

Parameter	Description
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 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

Parameter	Description
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

Type	Value	Description
int	0	OK.
int	-1	System 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

Parameter	Description
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

Parameter	Description
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

Type	Description
int	0: 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);
16    pubnub_free(ctx);
17    return -1;
18}
19else {
20    char const msg = pubnub_get(ctx);
21    char const channel = pubnub_get_channel(ctx);
22    while (msg != NULL) {
23        printf("Got message: %s on channel %s\n", msg, (NULL == channel) ? "" : channel );
24        msg = pubnub_get(ctx);
25        channel = pubnub_get_channel(ctx);
26    }
27}
28pubnub_free(ctx);

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

Parameter	Description
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

Type	Description
int	0: 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

Parameter	Description
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

Type	Description
int	0: 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

Parameter	Description
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

Type	Description
int	0 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

Parameter	Description
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

Type	Description
struct Pubnub_UUID_String	String 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

Type	Description
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

Type	Description
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

Type	Description
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

Parameter	Description
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

Type	Description
int	0: OK. -1: error (srand() was not called).

Enums

pubnub_res

Result codes for functions and transactions.

Member	Description
PNR_OK	Success. Transaction finished successfully.
PNR_ADDR_RESOLUTION_FAILED	PubNub 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_FAILED	Connecting to the PubNub server failed. Usually indicates a network outage. If using SSL/TLS, it could also be a TLS error.
PNR_CONNECTION_TIMEOUT	A timeout occurred in the network, typically because of a network outage while connected to the PubNub server.
PNR_TIMEOUT	Timeout before the request completed. Detected by the PubNub client itself, not the TCP/IP stack.
PNR_ABORTED	Connection to PubNub aborted (in most cases, a TCP reset was received).
PNR_IO_ERROR	Communication error (network or HTTP response format).
PNR_HTTP_ERROR	HTTP error. Call pubnub_last_http_code() to get the error code.
PNR_FORMAT_ERROR	Unexpected input in received JSON.
PNR_CANCELLED	Request cancelled by user.
PNR_STARTED	Transaction started. Await the outcome.
PNR_IN_PROGRESS	Transaction already ongoing. Cannot start a transaction while another is in progress.
PNR_RX_BUFF_NOT_EMPTY	Receive buffer (from previous transaction) not read; cannot start a subscription.
PNR_TX_BUFF_TOO_SMALL	The buffer is too small. Increase PUBNUB_BUF_MAXLEN.
PNR_INVALID_CHANNEL	Channel specification or name is invalid.
PNR_PUBLISH_FAILED	Publish transaction failed. Call pubnub_last_publish_result() to see the reason.
PNR_CHANNEL_REGISTRY_ERROR	Channel 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_BIG	Reply is too big to fit in the reply buffer (whether statically or dynamically allocated).

pubnub_trans

Type of PubNub operation/transaction.

Member	Description
PBTT_NONE	No transaction.
PBTT_SUBSCRIBE	Subscribe operation.
PBTT_PUBLISH	Publish operation.
PBTT_LEAVE	Leave channel(s) operation.
PBTT_TIME	Time (get server time) operation.
PBTT_HISTORY	History V2 (get message history for a channel) operation.
PBTT_HERENOW	Here-now (get user IDs of users present in channel(s)) operation.
PBTT_GLOBAL_HERENOW	Global here-now (get user IDs of users present across all channels) operation.
PBTT_WHERENOW	Where-now (get channels where a user is present) operation.
PBTT_SET_STATE	Set state (for a user on channel(s)) operation.
PBTT_STATE_GET	Get state (for a user on channel(s)) operation.
PBTT_REMOVE_CHANNEL_GROUP	Remove a channel group operation.
PBTT_REMOVE_CHANNEL_FROM_GROUP	Remove a channel from a channel group operation.
PBTT_ADD_CHANNEL_TO_GROUP	Add a channel to a channel group operation.
PBTT_LIST_CHANNEL_GROUP	List 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

Member	Type	Description
ipv4	uint8_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

Member	Type	Description
ipv6	uint8_t[16]	The 8 double octets (big endian) of the IPv6 address.