Utility Methods API for PubNub Windows C SDK

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

Configure proxy to be used from the system

Sets the configuration for the Internet proxy, by reading from the system configuration.

On some platforms (like Windows), there is some (de-facto) standard way of setting a proxy. On others, there may not be. C-core will try to do the best it can on a given platform.

This function can block for a significant time, if system configuration is to do auto-discovery of the proxy. So, call it only on start, restart, wake-up and similar events.

Preconditions

Call this after pubnub_init() on the context

Method(s)

To Configure proxy to be used from the system you can use the following method(s) in the Windows C SDK:

Declaration

int pubnub_set_proxy_from_system(pubnub_t *p, enum pubnub_proxy_type protocol);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The context to set proxy configuration for.
`protocol`	enum pubnub_proxy_type	Yes	Proxy protocol to use on `@p` p context.

Basic Usage

pubnub_set_proxy_from_system(pbp, pbpproxyHTTP_GET);

Returns

Type	Value	Description
`int`	0	OK
	!= 0	Error, specified protocol not supported or error in getting information from the system.

Enums

Enum type: pubnub_res

Result codes for Functions and transactions.

Members

PNR_OK

Success. Transaction finished successfully.

PNR_ADDR_RESOLUTION_FAILED

Pubnub host name resolution failed. We failed to get an IP address from the Pubnub host name (origin). Most of the time, this comes down to a DNS error.

PNR_CONNECT_FAILED

Connecting to Pubnub server failed. Most often, this means a network outage, but could be many things. If using SSL/TLS, it could be some of its errors.

PNR_CONNECTION_TIMEOUT

A time-out happened in the network. Mostly, this is because a network outage happened while being connected to the Pubnub server, but could be other things.

PNR_TIMEOUT

Time-out before the request has completed. This is reported for a time-out detected by Pubnub client itself, not some reported by others (i.e. 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. Can't start a new transaction while the old one is in progress.

PNR_RX_BUFF_NOT_EMPTY

Receive buffer (from previous transaction) not read, new subscription not allowed.

PNR_TX_BUFF_TOO_SMALL

The buffer is too small. Increase #PUBNUB_BUF_MAXLEN.

PNR_INVALID_CHANNEL

Channel specification / name is invalid.

PNR_PUBLISH_FAILED

Publish transaction failed - error returned from Pubnub. To see the reason describing the failure, call pubnub_last_publish_result().

PNR_CHANNEL_REGISTRY_ERROR

A transaction related to channel registry failed - error returned from Pubnub. To see the reason describing the failure, get the value for key message from the response (which is a JSON object) and value for key status for the numeric code of the error.

PNR_REPLY_TOO_BIG

Reply is too big to fit in our reply buffer. This same error is reported if the reply buffer is statically or dynamically allocated.

Enum type: pubnub_trans

Type of Pubnub operation/transaction

Members

PBTT_NONE

No transaction at all

PBTT_SUBSCRIBE

Subscribe operation/transaction

PBTT_PUBLISH

Publish operation/transaction.

PBTT_LEAVE

Leave channel(s) operation/transaction

PBTT_TIME

Time (get from Pubnub server) operation/transaction

PBTT_HISTORY

History V2 (get message history for the channel from Pubnub server) operation/transaction

PBTT_HERENOW

Here-now (get UUIDs of currently present users in channel(s)) operation/transaction

PBTT_GLOBAL_HERENOW

Here-now (get UUIDs of currently present users in channel(s)) operation/transaction

PBTT_WHERENOW

Where-now (get channels in which an user (identified by UUID) is currently present) operation/transaction

PBTT_SET_STATE

Set state (for a user (identified by UUID) on channel(s)) operation/transaction

PBTT_STATE_GET

Get state (for a user (identified by UUID) on channel(s)) operation/transaction

PBTT_REMOVE_CHANNEL_GROUP

Remove a channel group (from the channel-registry) operation/transaction

PBTT_REMOVE_CHANNEL_FROM_GROUP

Remove a channel from a channel group (in the channel-registry) operation/transaction

PBTT_ADD_CHANNEL_TO_GROUP

Add a channel to a channel group (in the channel-registry) operation/transaction

PBTT_LIST_CHANNEL_GROUP

Get a list of all channels in a channel group (from the channel-registry) operation/transaction

Free a context, with waiting

Tries pubnub_free() in a tight loop until either:

It succeeds.
Time specified in @p millisec elapses.

Essentially, it waits for the context to finish its current transaction and then frees it.

This function is much more useful in the callback interface, especially after a pubnub_cancel().

This function is not useful at all in the sync interface if you're using only one thread with the @p pbp context.

Also, if you want to do some other processing while waiting for the transaction to finish, don't use this function.

Method(s)

int pubnub_free_with_timeout(pubnub_t* pbp, unsigned millisec);

Parameter	Type	Required	Description
`pbp`	pubnub_t*	Yes	The Pubnub context which to free.
`millisec`	unsigned	Yes	Max time to wait for freeing to succeed, in `milliseconds`.

Basic Usage

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

Returns

Type	Value	Description
`int`	0	`pubnub_free()` succeeded.
	-1	Failed to `pubnub_free()` in `@p` millisec.

Generate UUID MD5

The name based algorithms (this - v3 and the other - v5) don't need any other state but the arguments they declare. But, they do need a hash, in this case MD5. For various reasons, a particular hash may not be available on a particular platform.

Method(s)

int pubnub_generate_uuid_v3_name_md5(struct Pubnub_UUID *uuid, struct Pubnub_UUID *nsid, void *name, unsigned namelen)

Parameter	Type	Required	Description
`uuid`	struct Pubnub_UUID*	Yes	The place to put the generated `UUID` to.
`nsid`	struct Pubnub_UUID*	Yes	The `UUID` of the namespace used. We provide a few examples.
`name`	void*	Yes	Pointer to the data that defines the `name` you want to use for `UUID` generation.
`namelen`	unsigned	Yes	The length of the `name` data.

Basic Usage

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

Returns

Type	Description
`int`	0: OK (generated), otherwise: error, algorithm not available.

Generate UUID Random

The nice property of this random-base algorithm is that it needs no state what-so-ever. A not so nice property is that it needs a random number generator of good quality, and you may not have that on a particular platform.

Method(s)

int pubnub_generate_uuid_v4_random(struct Pubnub_UUID *uuid)

Parameter	Type	Required	Description
`uuid`	struct Pubnub_UUID*	Yes	The place to put the generated `UUID` to.

Basic Usage

struct Pubnub_UUID uuid;
if (0 == pubnub_generate_uuid_v4_random(&amp;uuid)) {
    puts("UUID generation unsuccessful");
}

Returns

Type	Description
`int`	0: OK (generated), otherwise: error, random number generator not available.

Other Examples

struct Pubnub_UUID uuid;
char channel_name;
if (0 == pubnub_generate_uuid_v4_random(&amp;uuid)) {
    channel_name = pubnub_uuid_to_string(&amp;uuid).uuid;
}
pubnub_t ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}
pubnub_init(ctx, "demo", "demo");
pubnub_subscribe(ctx, channel_name, NULL);
pbresult = pubnub_await(ctx);
if (pbresult != PNR_OK) {
    printf("Failed to subscribe, error %d\n", pbresult);
show all 28 lines

Creating a unique Authentication Key for Access Manager on initialization

struct Pubnub_UUID uuid;
char *auth_key;
if (0 == pubnub_generate_uuid_v4_random(&amp;uuid)) {
    auth_key = pubnub_uuid_to_string(&amp;uuid).uuid;
    pubnub_init(ctx, "demo", "demo");
    pubnub_set_auth(ctx, auth_key);
}

Generate UUID Time

This generates an UUID using the v1 algorithm (time-based). This algorithm has some state, but, a lot of it is "node" identifier, which is the MAC address of your Ethernet-ish network interface, and most applications have one. If you don't have a MAC, you can use some other identifier. If it has less than 6 octets, will use what we have, but UUIDs will be of lesser quality. If you don't have an identifier to use, than you can generate a random number. If you don't have a random number generator, you can either give up, or use the pubnub_time() to obtain a high-resolution time as a pseudo-random number.

Besides that, it has the timestamp, which is a 100ns tick timer that started at midnight 15 October 1582. If you have a clock, just convert it to this format and you're good. Since it requires 64-bit integer support, and that is not always available, we are accepting it as a 8-octet array. If you don't have a clock, but have a timer, you can get time via pubnub_time() operation and later add the timer ticks to it.

Last but not the least, there is the io_clock_seq, which is generally used if the UUID generator gets the i_node and i_timestamp itself and also keep the state, which we don't do, for greater portability. We emulate this, by keeping a copy (in volatile memory) of the last time-stamp and seeing if it changes and assuming that node changes at first call, so we require the user to gives a random number for the clock sequence on first call. So, basically, on the first call, put a random value in io_clock_seq, and later just re-use the same variable, this function will update it as needed. If you don't have random number generator, you can use any pseudo-random number source (say a timer tick or some other event counter) - actually use as many as you have and mix the values (the simplest option is just to XOR the values you have, other is to make a message digest (MD5, SHA-1) of all the values).

While rather complex to use, it is very portable and can be made to work, with effort, on pretty much any platform, without the need to obtain unique identifiers yourself (like you need to do for v3 and v5).

Method(s)

int 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]);

Parameter	Type	Required	Description
`o_uuid`	struct Pubnub_UUID*	Yes	The place to put the generated `UUID` to.
`io_clock_seq`	uint16_t*	Yes	Clock Sequence - initialize to a random value on first call, later just reuse.
`i_timestamp`	uint8_t const[8]	Yes	Count of 100- nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian calendar).
`i_node`	uint8_t const[6]	Yes	A 6-octet "node" identity. Designed to be an IEEE 802 MAC address, but if you don't have it on your system, you can use something else.

Basic Usage

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

Returns

Type	Description
`int`	0: OK (generated), otherwise: error, algorithm not available

Get a list of system DNS servers

Reads the DNS servers in the system configuration. Will read at most @p n servers, even if more are configured. Keep in mind that modern systems have complex configurations and often (especially on Linux) this will yield just one DNS server which listens on the loopback IP address, while the "real" DNS configuration is not available through standard means.

On POSIX systems, this will read from /etc/resolv.conf, looking for nameserver lines. On Windows, this will use system functions to get the info. On other systems, if available, will read the system configuration as best it can.

Method(s)

To Configure proxy to be used from the system you can use the following method(s) in the Windows C SDK:

Declaration

int pubnub_dns_read_system_servers_ipv4(struct pubnub_ipv4_address* o_ipv4, size_tn);

Parameters

Parameters	Type	Required	Description
`o_ipv4`	struct pubnub_ipv4_address*	Yes	The array where to put the system DNS servers. allocated by the caller for `@p` `n` elements.
`n`	size_t	Yes	The number of elements allocated for the `@p` `o_ipv4`.

Basic Usage

struct pubnub_ipv4_address addr[MAX_DNS_SRV];
int c =  pubnub_dns_read_system_servers(addr, MAX_DNS_SRV);
if (c != 0) {
    printf("Can't get list of system DNS servers!\n");
}
else {
    int i;
    for (i = 0; i < c; ++i) {
        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]
    }
}

Returns

Type	Value	Description
`int`	-1	Error: can't read system DNS servers.
`int`	otherwise	The number of DNS servers read.

Get current proxy authentication scheme

Returns the current HTTP proxy authentication scheme for context @p p. This is set dynamically, in the communication with the proxy.

Method(s)

To Get current proxy authentication scheme you can use the following method(s) in the Windows C SDK:

Declaration

enum pubnub_http_authentication_scheme pubnub_proxy_authentication_scheme_get(pubnub_t *p);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The context to get proxy scheme for.

Basic Usage

enum pubnub_http_authentication_scheme sch = pubnub_authentication_scheme_get(pbp);
switch (sch) {
    case pbhtauBasic:
        puts("Basic authentication scheme");
    break;
    case pbhtauDigest:
        puts("Digest authentication scheme");
    break;
    case pbhtauNTLM:
        puts("Microsoft NTLM authentication scheme");
    break;
    case pbhtauNone:
        puts("No authentication scheme");
    break;
}

Returns

Type	Value	Description
`enum pubnub_http_authentication_scheme`	Any from the enum	The scheme used - `pbhtauNone` if no scheme is used (i.e. proxy is not an authenticating proxy).

Get current proxy protocol for a context

Returns the current proxy type/protocol for the context @p p.

Method(s)

To Get current proxy protocol for a context you can use the following method(s) in the Windows C SDK:

Declaration

enum pubnub_proxy_type pubnub_proxy_protocol_get(pubnub_t *p);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The Pubnub context for which to get the proxy protocol.

Basic Usage

enum pubnub_proxy_type proxy = pubnub_proxy_protocol_get(pbp);

Returns

Type	Value	Description
`enum pubnub_proxy_type`	Any from the enum	The proxy used - `pbpproxyNONE` if no proxy.

Get the Current Origin

Gets the origin to be used for the context p. If setting of the origin is not enabled, this will return the default origin.

Method(s)

To Get the origin of a Pubnub context use:

char const* pubnub_get_origin(pubnub_t *p)

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	Pubnub context to get origin from

Basic Usage

To get the origin currently set for a context

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

Returns

Type	Description
`char const*`	A read only string of `origin` used for the given context

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

Method(s)

To Configure proxy to be used from the system you can use the following method(s) in the Windows C SDK:

Declaration

int pubnub_get_dns_primary_server_ipv4(struct pubnub_ipv4_address* o_ipv4);

Parameters

Parameters	Type	Required	Description
`o_ipv4`	struct pubnub_ipv4_address*	Yes	(pointer to) The IPv4 address of the server used - allocated by the caller.

Basic Usage

struct pubnub_ipv4_address addr;
If (0 != pubnub_get_dns_primary_server(&amp;addr)) {
    printf("Getting primary DNS server failed\n");
}
else {
    printf("Primary DNS server: %d.%d.%d.%d\n", addr.ipv4[0], addr.ipv4[1], addr.ipv4[2], addr.ipv4[3]);
}

Returns

Type	Value	Description
`int`	0	OK.
`int`	-1	Error: Pubnub DNS module not used and can't get the primary DNS server.

Get the Transaction Timeout

Returns the current transaction timeout for the context.

Preconditions

Call this after pubnub_init() on the context

Method(s)

To Get the transaction timeout you can use the following method(s) in the Windows C SDK

int pubnub_transaction_timeout_get(pubnub_t *p)

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	Pointer to Pubnub client context.

Basic Usage

Get current transaction timeout

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

Returns

Type	Description
`int`	Current transaction timeout, in milliseconds (should always be > 0)

IPv4 structure

IPv4 Address, in binary format.

Method(s)

To Configure proxy to be used from the system you can use the following method(s) in the Windows C SDK:

Declaration

struct pubnub_ipv4_address {uint8_t ipv4[4];};

Members

Member	Type	Description
`ipv4`	uint8_t[4]	The four octets of the `IPv4` address.

Parse Publish Result

Parses the given publish result. You usually obtain this with pubnub_last_publish_result().

Method(s)

enum pubnub_publish_res pubnub_parse_publish_result(char const *result)

Parameter	Type	Required	Description
`result`	char const*	Yes	Publish `Result`

Basic Usage

enum pubnub_res res;
pubnub_t *pbp = pubnub_alloc();
if (NULL == pbp) {
    printf("Failed to allocate Pubnub context!\n");
    return -1;
}
pubnub_init(pbp, "demo", "demo");

res = pubnub_publish(pbp, chan, "\"Hello world from sync!\"");
if (res != PNR_STARTED) {
    printf("pubnub_publish() returned unexpected: %d\n", res);
    pubnub_free(pbp);
    return -1;
}
res = pubnub_await(pbp);
show all 23 lines

Returns

Type	Description
`enum pubnub_publish_res`	`result` of `publish` response parsing

PubNub Alloc

Returns an allocated context. After successful allocation, please call pubnub_init() to prepare the context for regular use. Do not make a context on your own - always get a context pointer by calling this funciton.

Method(s)

pubnub_t *pubnub_alloc(void)

Basic Usage

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

Returns

Type	Description
`pubnub_t*`	Context pointer on success, NULL on `error`

PubNub Cancel

Cancels an ongoing API transaction. This will, once it is done, close the (TCP/IP) connection to Pubnub (if it was open). The outcome of the transaction in progress, if any, will be #PNR_CANCELLED.

In the sync interface, it's possible that this cancellation will finish during the execution of a call to this function. But, there's no guarantee, so check the result.

In the callback (async) interface, it's not likely cancellation will be done, but, still, it's possible. So, if this matters to you, it's always best to check the result.

Method(s)

Declaration

enum pubnub_cancel_res pubnub_cancel(pubnub_t* p);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The Pubnub context for which to cancel the transaction..

Basic Usage

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

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 Do Not Use HTTP Keep Alive

Disables the use of HTTP Keep-Alive (persistent connections) on the context @p p.

The default is to _use_ the HTTP Keep-Alive, but, you might want to turn that off - see pubnub_use_http_keep_alive()

Method(s)

void pubnub_dont_use_http_keep_alive (pubnub_t* p)

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	Pointer to Pubnub Client Context.

Basic Usage

pubnub_dont_use_http_keep_alive(pbp);

Returns

None.

PubNub Free

Frees a previously allocated context, if it is not in a transaction. If a context is in a transaction, it will cancel it (as if you called pubnub_cancel()), but there's no guarantee that the cancellation will be finished during this call. More precisely, since it is as if you called pubnub_cancel(), all semantics of pubnub_cancel() apply here, too.

You don't have to free a context when you finish a transaction. Just start a new transaction. Free a context if you're done doing Pubnub transactions for a significant period of time.

Method(s)

Declaration

int pubnub_free(pubnub_t *pb);

Parameters

Parameter	Type	Required	Description
`pb`	pubnub_t*	Yes	The Pubnub context to free.

Basic Usage

if (0 != pubnub_free(pbp)) {
    printf("Freeing pubnub context failed, cancel started.\n");
}
else {
    printf("Pubnub context freed.\n");
}

Returns

Type	Value	Description
`int`	0	OK, context freed.
`int`	-1	Context not freed, transaction cancel started.

PubNub Get

Returns a pointer to an arrived message or other element of the response to an operation/transaction. Message(s) arrive on finish of a subscribe operation or history operation, while for some other operations this will give access to the whole response, or the next element of the response. That is documented in the function that starts the operation. Subsequent call to this function will return the next message (if any). All messages are from the channel(s) the last operation was for.

Method(s)

char const * pubnub_get (pubnub_t *p)

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	Pointer to Pubnub Client Context

Basic Usage

pubnub_subscribe(ctx, "hello_world", NULL);
pbresult = pubnub_await(ctx);
if (pbresult != PNR_OK) {
    printf("Failed to subscribe, error %d\n", pbresult);
    pubnub_free(ctx);
    return -1;
}
else {
    char const *msg = pubnub_get(ctx);
    while (msg != NULL) {
        printf("Got message: %s\n", msg);
        msg = pubnub_get(ctx);
    }
}
pubnub_free(ctx);

Returns

Type	Description
`char const*`	Pointer to `message`. NULL on `error`.

PubNub Get Channel

Returns a pointer to an fetched subscribe operation/transaction's next channel. Each transaction may hold a list of channels, and this functions provides a way to read them. Subsequent call to this function will return the next channel (if any).

Method(s)

char const * pubnub_get_channel (pubnub_t *pb)

Parameter	Type	Required	Description
`pb`	pubnub_t*	Yes	Pointer to Pubnub Client Context. Can't be NULL.

Basic Usage

pubnub_subscribe(ctx, "hello_world", NULL);
pbresult = pubnub_await(ctx);
if (pbresult != PNR_OK) {
    printf("Failed to subscribe, error %d\n", pbresult);
    pubnub_free(ctx);
    return -1;
}
else {
    char const *msg = pubnub_get(ctx);
    char const *channel = pubnub_get_channel(ctx);
    while (msg != NULL) {
        printf("Got message: %s on channel %s\n", msg, (NULL == channel) ? "" : channel );
        msg = pubnub_get(ctx);
        channel = pubnub_get_channel(ctx);
    }
show all 17 lines

Returns

Type	Description
`char const*`	Pointer to `channel`. NULL on `error`.

PubNub Get User Data

Returns the user data set with pubnub_register_callback().

Method(s)

void *pubnub_get_user_data(pubnub_t *pb)

Parameter	Type	Required	Description
`pb`	pubnub_t*	Yes	Pubnub Client Context for which to return user data.

Basic Usage

void* user_data = pubnub_get_user_data(ctx);

Returns

Type	Description
`void*`	user data set with `pubnub_register_callback`

PubNub Last HTTP Code

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

Method(s)

enum pubnub_res int pubnub_last_http_code(pubnub_t *p)

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

Basic Usage

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

Returns

Type	Description
`int`	HTTP reply code of the last transaction in the `p` context.

PubNub Last Publish Result

Returns the string of the result of the last publish transaction, as returned from Pubnub. If the last transaction is not a publish, or there is some other error, it returns NULL. If the Publish was successfull, it will return "Sent", otherwise a description of the error.

Method(s)

char const *pubnub_last_publish_result(pubnub_t *p);

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

Basic Usage

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

Returns

Type	Description
`char const*`	`string` of the result of the last `publish` transaction

PubNub Last Result

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

Also have a look at:

pubnub_set_blocking_io
pubnub_set_non_blocking_io

Method(s)

int pubnub_last_result(pubnub_t *p)

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

Basic Usage

pubnub_list_channel_group(ctx, "my_channel_group");
pbresult = pubnub_await(ctx);
printf("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 Time Token

Returns the string of the last received timetoken in a subscribe transaction, on the p context. After pubnub_init() this should be "0".

Method(s)

char const *pubnub_last_time_token(pubnub_t *p);

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

Basic Usage

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

Returns

Type	Description
`char const*`	`string` of the last received timetoken on the context, in a subscribe transaction

PubNub Leave

Leave the channel. This actually means "initiate a leave transaction". You should leave channel(s) when you want to subscribe to another in the same context to avoid loosing messages. Also, it is useful for tracking presence. You can't leave if a transaction is in progress on the context.

Method(s)

Basic Usage

pubnub_leave(ctx, "hello_world", NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
    printf("Leave successful\n");
}
pubnub_free(ctx);

Returns

Type	Description
`enum pubnub_res`	`PNR_STARTED` on success, an `error` otherwise

PubNub Register Callback

Registers a callback function to be called when a transaction ends. While it is OK to register a NULL pointer, which means no callback will be called, it is useful only in very specific circumstances. Also, NULL is the initial value (after calling pubnub_init()), so no need to set it. Don't make any assumptions about the thread on which this function is called.

Method(s)

enum pubnub_res pubnub_register_callback(pubnub_t *pb, pubnub_callback_t cb, void *user_data)

Parameter	Type	Required	Description
`pb`	pubnub_t*	Yes	The Pubnub context for which the `callback` is set
`cb`	pubnub_callback_t	Optional	`cb` Pointer to function to call on end of transaction
`user_data`	void*	Optional	`user_data` Pointer that will be given to the `callback` function

Basic Usage

pubnub_register_callback(ctx, sample_callback, &amp;user_data);

Returns

Type	Description
`enum pubnub_res`	`PNR_OK` on success, a value indicating the `error` otherwise

PubNub Res 2 string

Returns a string (in English) describing a Pubnub result enum

Method(s)

char const* pubnub_res_2_string(enum pubnub_res e)

Parameter	Type	Required	Description
`p`	enum pubnub_res	Yes	Pubnub `result` enum value

Basic Usage

enum pubnub_res res;
pubnub_t *pbp = pubnub_alloc();
if (NULL == pbp) {
    printf("Failed to allocate Pubnub context!\n");
    return -1;
}
pubnub_init(pbp, "demo", "demo");

res = pubnub_publish(pbp, chan, "\"Hello world from sync!\"");
if (res != PNR_STARTED) {
    printf("pubnub_publish() returned unexpected: %d\n", res);
    pubnub_free(pbp);
    return -1;
}
res = pubnub_await(pbp);
show all 16 lines

Returns

Type	Description
`char const*`	`String` describing pubnub `result`

PubNub SDK Name

Returns a string with the name of the Pubnub SDK client you are using.

Method(s)

char const *pubnub_sdk_name(void)

This method has no argument

Basic Usage

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

Returns

Type	Description
`char const*`	`string` with the `name` of the Pubnub SDK client you are using

PubNub SRAND Time

This helper function will call the C standard srand() function with the seed taken from the time returned from Pubnub's time operation (which can be initiated with pubnub_time()).

It's useful if you want a high-fidelity time used for srand() and on embedded system that don't have a Real-Time Clock.

Keep in mind that this requires a round-trip to Pubnub, so it will take some time, depending on your network, at least milliseconds. So, it's best used only once, at the start of your program.

This function assumes the use of the sync interface (it uses pubnub_await() internally).

Method(s)

int srand_from_pubnub_time(pubnub_t *pbp);

Parameter	Type	Required	Description
`pbp`	pubnub_t*	Yes	The Pubnub context to use to get `time`.

Basic Usage

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

Returns

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

PubNub Uname

Returns an URL encoded string with the full identification of the SDK - name, version, possible something more.

Method(s)

char const *pubnub_uname(void)

This method has no arguments

Basic Usage

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

Returns

Type	Description
`char const*`	URL encoded `string` with the full identification of the SDK

PubNub Use HTTP Keep Alive

Enables the use of HTTP Keep-Alive (persistent connections) on the context @p p.

This is the default, but, you can turn it off with pubnub_dont_use_http_keep_alive(). If HTTP Keep-Alive is active, connection to Pubnub will not be closed after the transaction ends. This will avoid connecting again on next transaction on the same context, making the transaction finish (usually much) quicker. But, there's a trade-off here, here are the drawbacks:

pubnub_free() will not work for contexts that are in keep alive state. You need to pubnub_cancel() before you can pubnub_free().
Socket in the keep-alive state will be closed by the Pubnub network (server) after some period of inactivity. While we should be able to handle that, it's possible that some race condition causes a transaction to fail in this case.
Socket in the keep-alive state is allocated, consuming some resources. If you have a constrained number of sockets, relative to Pubnub contexts, this may be an issue.

Method(s)

void pubnub_use_http_keep_alive (pubnub_t* p)

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	Pointer to Pubnub Client Context.

Basic Usage

pubnub_use_http_keep_alive(pbp);

Returns

None.

PubNub Version

Returns a string with the version of the Pubnub SDK client you are using.

Method(s)

char const *pubnub_version(void)

This method has no arguments

Basic Usage

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

Returns

Type	Description
`char const*`	`string` with the version of the Pubnub SDK client

Undefines - releases the subscribe loop descriptor. Call this when you're done with the loop and want to release its resources.

Method(s)

void pubnub_subloop_undef(pubnub_subloop_t* pbsld);

Parameter	Type	Required	Description
`pbsld`	pubnub_subloop_t*	Yes	The subscribe loop descriptor of the loop to undefine/release.

Basic Usage

pubnub_subloop_undef(pbsld);

Returns

None.

Reset username and password for authenticating proxy

Set the context @p p to not use any authentication scheme. This is the default, so you only need to call this function if you're resetting the use of an authentication scheme on the context @p p, for whatever reason.

Preconditions

Call this after pubnub_init() on the context

Method(s)

To Reset username and password for authenticating proxy you can use the following method(s) in the Windows C SDK:

Declaration

int pubnub_set_proxy_authentication_none(pubnub_t *p);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The context to set proxy authentication for.

Basic Usage

pubnub_set_proxy_authentication_none(pbp);

Returns

Type	Value	Description
`int`	0	OK
	!= 0	Error, authentication scheme doesn't support `no` authentication.

Set blocking IO

Sets the usage of blocking I/O for a context. If blocking I/O is supported by a platform (it is on most platforms), it will be used, unless some other reason prevents it.

The exact behavior when using blocking I/O depends on the platform, but, in general:

getting (or trying to get) the outcome of a Pubnub transaction will block the caller's thread until the outcome is actually reached.
if outcome is gotten by polling (calling a Pubnub SDK API to get the outcome), the user will call just once and the poll will return when the outcome is reached (making it impossible for the caller to do anything on that thread until the outcome is reached)
if outcome is gotten via a callback or similar means, it is most likely that the actual I/O is done non-blocking, but, in any case, user would probably see little difference between blocking and non-blocking I/O

In general, blocking I/O gives to simpler code, but that scales poorly.

Method(s)

int pubnub_set_blocking_io(pubnub_t *p)

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The Context to set blocking I/O for

Basic Usage

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

Returns

Type	Description
`int`	0 OK, otherwise: error, blocking I/O not supported

Set CA verify locations

Sets the location(s) of CA certificates for verification purposes. This is only available on targets that have a file system.

By default, both of these are NULL. If both are NULL, C-core shall use the certificates it knows of - but, these certificates may expire or be changed in time. If that happens, you may need to change your code (update C-core). Using this function, if you keep your certificate store up-to-date, you don't need to change the code.

Both parameters are kept as pointers, so, the user is responsible for making them valid during the lifetime of context @p p - or until they are set to NULL.

Preconditions

@p p is a valid context

Method(s)

To Set CA verify locations you can use the following method(s) in the Windows C SDK:

Declaration

int pubnub_set_ssl_verify_locations(pubnub_t *p, char const* sCAfile, char const* sCApath);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	Pubnub context to set locations for.
`sCAfile`	char const*	Optional	The certificate store file. May contain more than one CA certificate. Set to `NULL` if you don't want to use the certificate file.
`sCApath`	char const*	Optional	The certificate store directory. Each file in this directory should contain one CA certificate. Set to `NULL` if you don't want to use the certificate file.

Basic Usage

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

Returns

Type	Value	Description
`int`	0	succeeded
	-1	Failed to set certificate locations.

Set Non Blocking IO

Sets the usage of non-blocking I/O for a context. If non-blocking I/O is supported by a platform, it will be used, unless some other reason prevents it.

The exact behavior when using non-blocking I/O depends on the platform, but, in general:

getting (or trying to get) the outcome of a Pubnub transaction will not block the caller's thread
if outcome is gotten by polling (calling a Punbub SDK API to get the outcome), each poll will indicate whether the outcome is reached or not, so user will have to call until the outcome is reached, though the user, is, of course, free to do other things between two poll calls
if outcome is gotten via a callback or similar means, it is most likely that the actual I/O is done non-blocking anyway, but, in any case, user would probably see little difference between blocking and non-blocking I/O

In general, non-blocking I/O gives to more complex code, but that scales better.

Method(s)

int pubnub_set_non_blocking_io(pubnub_t *p)

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The Context to set `non-blocking I/O` for

Basic Usage

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

Returns

Type	Description
`int`	0 OK, otherwise: error, non-blocking I/O not supported

Set proxy to be used

Sets the configuration for the Internet proxy, by explicitly specifying the protocol to use and the proxy server.

If proxy support is available, pubnub_init() will default to no proxy.

Preconditions

Call this after pubnub_init() on the context
(protocol != pbproxyNONE) => (ip_address_or_url != NULL)

Method(s)

To Set proxy to be used you can use the following method(s) in the Windows C SDK:

Declaration

int pubnub_set_proxy_manual(pubnub_t *p, enum pubnub_proxy_type protocol, char const *ip_address_or_url, uint16_t port);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The context to set proxy configuration for.
`protocol`	enum pubnub_proxy_type	Yes	Proxy `protocol` to use on `@p` p context.
`ip_address_or_url`	char const*	Yes	The string with IP address or URL of the proxy server.
`port`	uint16_t	Yes	The `port` number to use on the proxy - there is no standard, the HTTP port (80) is seldom used, while 3128 seems to be a popular one.

Basic Usage

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

Returns

Type	Value	Description
`int`	0	OK
	!= 0	Error, specified protocol not supported, invalid `@p ip_address_or_url`.

Set the Transaction Timeout

Sets the transaction timeout for the context. This will be used for all subsequent transactions. If a transactions is ongoing and its timeout can be changed, it will be, but if it can't, that would not be reported as an error.

Pubnub SDKs, in general, distinguish the subscribe timeout and other transactions, but, C-core doesn't, to save space, as most contexts are either used for subscribe or for other transactions.

If timer support is available, pubnub_init() will set a default timeout, which is configurable at compile time. So, if the default timeout is fine with you, you don't have to call this function.

Preconditions

Call this after pubnub_init() on the context (and before starting a transaction)
Duration has to be greater than 0

Method(s)

To Set the transaction timeout you can use the following method(s) in the Windows C SDK

int pubnub_set_transaction_timeout(pubnub_t *p, int duration_ms)

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	Pointer to Pubnub client context.
`duration_ms`	int	Yes	Duration of the timeout, in milliseconds

Basic Usage

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

Returns

Type	Description
`int`	0: OK (timeout set), otherwise: error, timers not supported

Set the primary DNS server

Sets the primary DNS server IPv4 address to use when resolving the Pubnub origin, in binary form (network order). Applies to all subsequent DNS queries, if successful.

The DNS module in C-core is not always used. In general, it is used for the callback interface, because it works asynchronously, while system/platform DNS resolvers often don't (i.e. they work in a synchronous/blocking fashion). But, on some platforms, the resolver works asynchronously, so, one can configure C-core to use it.

If DNS module in C-core is not used, then this function is useless and if C-core is configured correctly, won't even be available, but, at the least, it won't succeed.

Method(s)

To Configure proxy to be used from the system you can use the following method(s) in the Windows C SDK:

Declaration

int pubnub_dns_set_primary_server_ipv4(struct pubnub_ipv4_address ipv4);

Parameters

Parameters	Type	Required	Description
`ipv4`	Struct pubnub_ipv4_address	Yes	The `IPv4` address of the server to use. Set all `0` to not use this DNS server.

Basic Usage

struct pubnub_ipv4_address addr = { { 8, 8, 8, 8 } };
If (0 != pubnub_dns_set_primary_server(addr)) {
    printf("Setting primary DNS server failed\n");
}

Returns

Type	Value	Description
`int`	0	OK.
`int`	-1	Error: Pubnub DNS module not used and can't set the primary DNS server.

Set the primary DNS server by string

Sets the primary DNS server IPv4 address from the corresponding numbers-and-dots notation string to use when resolving the Pubnub origin. Applies to all subsequent DNS queries, if successful.

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

Method(s)

To Configure proxy to be used from the system you can use the following method(s) in the Windows C SDK:

Declaration

int pubnub_dns_set_primary_server_ipv4_str(char const* ipv4_str);

Parameters

Parameters	Type	Required	Description
`ipv4_str`	char const*	Yes	The IPv4 address in string (numbers and dots) notation.

Basic Usage

If (0 != pubnub_dns_set_primary_server_str("8.8.8.8")) {
    printf("Setting primary DNS server failed\n");
}

Returns

Type	Value	Description
`int`	0	OK.
`int`	-1	Error: Pubnub DNS module not used and can't set the primary DNS server.

Set user defined / in-memory certificate

Sets the contents of a user-defined, in-memory, PEM certificate to use for @p p context. This will be used in addition to other certificates. Certificate is usually found in a .pem file, from which you can read/copy it to 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 purposes with proxy debuggers (like Fiddler, Charles, etc).

There is only one user-defined PEM certificate per context.

Preconditions

@p p is a valid context

Method(s)

To Set user defined / in-memory certificate you can use the following method(s) in the Windows C SDK:

Declaration

void pubnub_ssl_set_usrdef_pem_cert(pubnub_t *p, char const *contents);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The context for which to set `user-defined`/in-memory PEM certificate.
`contents`	char const*	Yes	String containing the PEM certificate. Assumed to be valid during the lifetime of `@p` p. Use `NULL` if you don't want to use your certificate.

Basic Usage

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

pubnub_ssl_set_usrdef_pem_cert(pbp, my_cert);

Returns

None.

Set username and password for authenticating proxy

Sets the authentication password and scheme to be used for Proxy authentication.

The default username and password are the currently logged on username and password, if such info can be acquired at runtime, or the hardwired C-core's own default username and password (if it can't be acquired).

Preconditions

Call this after pubnub_init() on the context

Method(s)

To Set username and password for authenticating proxy you can use the following method(s) in the Windows C SDK:

Declaration

int pubnub_set_proxy_authentication_username_password(pubnub_t *p, char const *username, char const *password);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The context to set proxy authentication for.
`username`	char const*	Optional	Authentication `username`. Use NULL to let C-core use the default `username`.
`password`	char const*	Optional	Authentication `password`. Use NULL to let C-core use the default `password`.

Basic Usage

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

Returns

Type	Value	Description
`int`	0	OK
	!= 0	Error, setting `username`/`password` failed.

Set/enable use of system certificate store

Instructs C-core to use system certificate store with context @p p. This is only available on targets that have a system certificate store, like Windows.

By default, system certificate store will not be used on a context.

When enabled, using system certificate store takes precedent over other certificates.

If enabled, you can later disable the use of system certificate store by calling pubnub_ssl_dont_use_system_certificate_store().

Preconditions

@p p is a valid context

Method(s)

To Set/enable use of system certificate store you can use the following method(s) in the Windows C SDK:

Declaration

int pubnub_ssl_use_system_certificate_store(pubnub_t *p);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The context for which to use system certificate store.

Basic Usage

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

Returns

Type	Value	Description
`int`	0	succeeded
	-1	System certificate store usage not supported.

Should a failed transaction be retried

Returns whether retrying a Pubnub transaction makes sense. This is mostly interesting for publishing, but is useful in general. It is least useful for subscribing, because you will most probably subscribe again at some later point in time, even if you're not in a subscribe loop.

Method(s)

enum pubnub_tribool pubnub_should_retry(enum pubnub_res e);

Parameter	Type	Required	Description
`e`	enum pubnub_res	Yes	Pubnub result returned by a C-core function, for which the user wants to find out if retrying makes sense.

Basic Usage

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

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

Returns

Type	Value	Description
`enum pubnub_tribool`	pbccTrue	It's safe to retry, though there is no guarantee that it will help.
	pbccFalse	It doesn't benefit you to re-try the same transaction.
	pbccNotSet	Retry might help, but, it also can make things worse. For example, for a `#PNR_TIMEOUT`, it may very well be that the message was delivered to Pubnub, but, the response from Pubnub never reached us due to some networking issue, resulting in a timeout. In that case, retrying would send the same message again, duplicating it.

Starts a subscribe loop.

The callback given in pubnub_subloop_define() will be called for each message received.

A running subscribe loop will take-over the context and it will receive all the callbacks for it.

Context callback

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

Subscribe loop descriptor

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

Method(s)

enum pubnub_res pubnub_subloop_start(pubnub_subloop_t* pbsld);

Parameter	Type	Required	Description
`pbsld`	pubnub_subloop_t*	Yes	The subscribe loop descriptor of the loop to start.

Basic Usage

pubnub_subloop_start(pbsld);

Returns

Type	Value	Description
`enum pubnub_res`	PNR_OK	Subscribe loop started.
	other	Indicates reason for failure.

Stops a subscribe loop. If loop is calling the callback (delivering message(s)), stop will be done once that is finished.

After a stop of the subscribe loop, the context can be used in a regular manner. The callback that was set on the context will be restored.

Method(s)

void pubnub_subloop_stop(pubnub_subloop_t* pbsld);

Parameter	Type	Required	Description
`pbsld`	pubnub_subloop_t*	Yes	The subscribe loop descriptor of the loop to stop.

Basic Usage

pubnub_subloop_stop(pbsld);

Returns

None.

Helper to create a subscribe loop descriptor. For the values that are part of the descriptor, but are not provided as parameters of this function, defaults will be used.

Method(s)

pubnub_subloop_t* pubnub_subloop_define(pubnub_t *p, char const *channel, struct pubnub_subscribe_options options, pubnub_subloop_callback_t cb);

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The Pubnub context to use for the subscribe loop.
`channel`	char const*	Yes	The `channel`(s) to use in the subscribe loop
`options`	struct pubnub_subscribe_options	Yes	Subscribe options to use in the loop
`cb`	pubnub_subloop_callback_t	Yes	The `callback` that will be called on each message that arrived during the execution of the subscribe loop.

Basic Usage

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

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

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

Returns

Type	Value	Description
`pubnub_subloop_t*`	NULL	Failed to create a descriptor.
	other	The descriptor created.

Helper to make a subscribe loop descriptor, which it returns, by value. For the values that are part of the descriptor, but are not provided as parameters of this function, defaults will be used.

Method(s)

struct pubnub_subloop_descriptor pubnub_subloop_define(pubnub_t *p, char const *channel);

Parameter	Type	Required	Description
`p`	pubnub_t *	Yes	The Pubnub context to use for the loop.
`channel`	char const*	Yes	The channel(s) to subscribe to.

Basic Usage

pbsld = pubnub_subloop_define(pbp, "hello_world");

Returns

Type	Value	Description
`struct pubnub_subloop_descriptor`	-	The subscribe loop descriptor made.

Designed to be called once in every iteration of a subscribe loop.

Fetches the next message on the given @p channel and/or @p channel_group using the context @p p, automatically subscribing if there are no messages left in @p p. Thus, this might block for a significant time waiting for message(s) to arrive.

@remark Changing the @p pbsld descriptor during the loop is possible, but your changes may take many iterations of the loop to take effect.

Method(s)

enum pubnub_res pubnub_subloop_fetch(struct pubnub_subloop_descriptor const* pbsld, char const** message);

Parameter	Type	Required	Description
`pbsld`	struct pubnub_subloop_descriptor const*	Yes	The Pubnub sync subscriber loop descriptor to use.
`message`	char const**	Yes	The message that was fetched, or `NULL` if no message fetched.

Basic Usage

for (;;) {
    char const* msg;
    enum pubnub_res pbres = pubnub_subloop_fetch(&amp;pbsld, &amp;msg);
    if (PNR_OK != pbres) {
        printf("Exiting subscribe loop because of error: %d\n", pbres);
        break;
    }
    if (NULL == msg) {
        puts("Everything's OK, yet no message received");
    } else {
        printf("Got message '%s'\n", msg);
    }
}

Returns

Type	Value	Description
`enum pubnub_res`	PNR_OK	success (message was fetched).
	other	Indicates the reason for failure.

Time

This function will return a 17 digit precision Unix epoch.

Timetoken The timetoken is constructed using the following algorithm

timetoken = (Unix epoch time in seconds) * 10000000

Example of creating a timetoken for a specific time and date

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

Method(s)

To fetch Time you can use the following method(s) in Windows C SDK

enum pubnub_res pubnub_time (pubnub_t *p)

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

Basic Usage

Get PubNub Timetoken

pubnub_time(ctx);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
    char const *gotten_time = pubnub_get();
}

Rest Response from Server

The pubnub_time() function returns a string timetoken in the following format:

13769501243685161

UUID Compare

Compares two UUIDs (left and right) and returns: - 0: equal - <0: left < right - >0: left > right

Method(s)

int pubnub_uuid_compare(struct Pubnub_UUID const *left, struct Pubnub_UUID const *right)

Parameter	Type	Required	Description
`left`	struct Pubnub_UUID const*	Yes	`uuid` to be compared
`right`	struct Pubnub_UUID const*	Yes	`uuid` to be compared

Basic Usage

struct Pubnub_UUID left;
struct Pubnub_UUID right;
if (0 != pubnub_generate_uuid_v4_random(&amp;left) || 0 != pubnub_generate_uuid_v4_random(&amp;right)) {
    puts("UUID generation unsuccessful");
}
int RC = pubnub_uuid_compare(left, right);
if (0 == RC) puts ("left == right");
else if (RC > 0) puts("left > right");
else puts ("left < right");

Returns

Type	Description
`int`	0 if equal, <0: left < right, >0: left > right

UUID to String

Returns UUID as a standard HEX-based representation

Method(s)

struct Pubnub_UUID_String pubnub_uuid_to_string(struct Pubnub_UUID const *uuid)

Parameter	Type	Required	Description
`uuid`	struct Pubnub_UUID const*	Yes	`uuid` to be converted to `string`

Basic Usage

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

Returns

Type	Description
`struct Pubnub_UUID_String`	String representation of uuid

Unset/disable use of system certificate store

Instructs C-core to not use system certificate store with context @p p, which is also the default.

The only reason to use this functions is to disable use of system certificate store which was previously set with pubnub_ssl_use_system_certificate_store().

Preconditions

@p p is a valid context

Method(s)

To Unset/disable use of system certificate store you can use the following method(s) in the Windows C SDK:

Declaration

void pubnub_ssl_dont_use_system_certificate_store(pubnub_t *p);

Parameters

Parameter	Type	Required	Description
`p`	pubnub_t*	Yes	The context for which to use system certificate store.

Basic Usage

pubnub_ssl_dont_use_system_certificate_store(pbp);

Returns

None.

Configure proxy to be used from the system​

Preconditions​

Method(s)​

Declaration​

Parameters​

Basic Usage​

Returns​

Enums​

Enum type: pubnub_res​

Members​

PNR_OK​

PNR_ADDR_RESOLUTION_FAILED​

PNR_CONNECT_FAILED​

PNR_CONNECTION_TIMEOUT​

PNR_TIMEOUT​

PNR_ABORTED​

PNR_IO_ERROR​

PNR_HTTP_ERROR​

PNR_FORMAT_ERROR​

PNR_CANCELLED​

PNR_STARTED​

PNR_IN_PROGRESS​

PNR_RX_BUFF_NOT_EMPTY​

PNR_TX_BUFF_TOO_SMALL​

PNR_INVALID_CHANNEL​

PNR_PUBLISH_FAILED​

PNR_CHANNEL_REGISTRY_ERROR​

PNR_REPLY_TOO_BIG​

Enum type: pubnub_trans​

Members​

PBTT_NONE​

PBTT_SUBSCRIBE​

PBTT_PUBLISH​

PBTT_LEAVE​

PBTT_TIME​

PBTT_HISTORY​

PBTT_HERENOW​

PBTT_GLOBAL_HERENOW​

PBTT_WHERENOW​

PBTT_SET_STATE​

PBTT_STATE_GET​

PBTT_REMOVE_CHANNEL_GROUP​

PBTT_REMOVE_CHANNEL_FROM_GROUP​

PBTT_ADD_CHANNEL_TO_GROUP​

PBTT_LIST_CHANNEL_GROUP​

Free a context, with waiting​

Method(s)​

Basic Usage​

Returns​

Generate UUID MD5​

Method(s)​

Basic Usage​

Returns​

Generate UUID Random​

Method(s)​

Basic Usage​

Returns​

Other Examples​

Creating a function to subscribe to a channel with a unique name​

Creating a unique Authentication Key for Access Manager on initialization​

Generate UUID Time​

Method(s)​

Basic Usage​

Returns​

Get a list of system DNS servers​

Method(s)​

Declaration​

Parameters​

Basic Usage​

Returns​

Get current proxy authentication scheme​

Method(s)​

Declaration​

Parameters​

Basic Usage​

Returns​

Get current proxy protocol for a context​

Method(s)​

Declaration​

Parameters​

Configure proxy to be used from the system

Preconditions

Method(s)

Declaration

Parameters

Basic Usage

Returns

Enums

Enum type: pubnub_res

Members

PNR_OK

PNR_ADDR_RESOLUTION_FAILED

PNR_CONNECT_FAILED

PNR_CONNECTION_TIMEOUT

PNR_TIMEOUT

PNR_ABORTED

PNR_IO_ERROR

PNR_HTTP_ERROR

PNR_FORMAT_ERROR

PNR_CANCELLED

PNR_STARTED

PNR_IN_PROGRESS

PNR_RX_BUFF_NOT_EMPTY

PNR_TX_BUFF_TOO_SMALL

PNR_INVALID_CHANNEL

PNR_PUBLISH_FAILED

PNR_CHANNEL_REGISTRY_ERROR

PNR_REPLY_TOO_BIG

Enum type: pubnub_trans

Members

PBTT_NONE

PBTT_SUBSCRIBE

PBTT_PUBLISH

PBTT_LEAVE

PBTT_TIME

PBTT_HISTORY

PBTT_HERENOW

PBTT_GLOBAL_HERENOW

PBTT_WHERENOW

PBTT_SET_STATE

PBTT_STATE_GET

PBTT_REMOVE_CHANNEL_GROUP

PBTT_REMOVE_CHANNEL_FROM_GROUP

PBTT_ADD_CHANNEL_TO_GROUP

PBTT_LIST_CHANNEL_GROUP

Free a context, with waiting

Method(s)

Basic Usage

Returns

Generate UUID MD5

Method(s)

Basic Usage

Returns

Generate UUID Random

Method(s)

Basic Usage

Returns

Other Examples

Creating a function to subscribe to a channel with a unique name

Creating a unique Authentication Key for Access Manager on initialization

Generate UUID Time

Method(s)

Basic Usage

Returns

Get a list of system DNS servers

Method(s)

Declaration

Parameters

Basic Usage

Returns

Get current proxy authentication scheme

Method(s)

Declaration

Parameters

Basic Usage

Returns

Get current proxy protocol for a context

Method(s)

Declaration

Parameters