Utility Methods API for PubNub FreeRTOS 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 autodiscovery 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 FreeRTOS SDK:

Declaration

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

Parameters

ParameterTypeRequiredDescription
ppubnub_t*YesThe context to set proxy configuration for.
protocolenum pubnub_proxy_typeYesProxy protocol to use on @p p context.

Basic Usage

pubnub_set_proxy_from_system(pbp, pbpproxyHTTP_GET);

Returns

TypeValueDescription
int0OK
!= 0Error, 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 (that is, 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:

  1. It succeeds.
  2. 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);
ParameterTypeRequiredDescription
pbppubnub_t*YesThe Pubnub context which to free.
millisecunsignedYesMax 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

TypeValueDescription
int0pubnub_free() succeeded.
-1Failed 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)
ParameterTypeRequiredDescription
uuidstruct Pubnub_UUID*YesThe place to put the generated UUID to.
nsidstruct Pubnub_UUID*YesThe UUID of the namespace used. We provide a few examples.
namevoid*YesPointer to the data that defines the name you want to use for UUID generation.
namelenunsignedYesThe 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(&uuid, &nsid, name, 4)) {
puts("UUID generation unsuccessful");
}

Returns

TypeDescription
int0: 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)
ParameterTypeRequiredDescription
uuidstruct Pubnub_UUID*YesThe place to put the generated UUID to.

Basic Usage

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

Returns

TypeDescription
int0: OK (generated), otherwise: error, random number generator not available.

Other Examples

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

struct Pubnub_UUID uuid;
char channel_name;
if (0 == pubnub_generate_uuid_v4_random(&uuid)) {
channel_name = pubnub_uuid_to_string(&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(&uuid)) {
auth_key = pubnub_uuid_to_string(&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]);
ParameterTypeRequiredDescription
o_uuidstruct Pubnub_UUID*YesThe place to put the generated UUID to.
io_clock_sequint16_t*YesClock Sequence - initialize to a random value on first call, later just reuse.
i_timestampuint8_t const[8]YesCount of 100- nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian calendar).
i_nodeuint8_t const[6]YesA 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(&uuid, &clock_seq, timestamp, node)) {
printf("Failed to generate a v1 (time based) UUID\n");
}

Returns

TypeDescription
int0: 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 FreeRTOS SDK:

Declaration

int pubnub_dns_read_system_servers_ipv4(struct pubnub_ipv4_address* o_ipv4, size_tn);

Parameters

ParametersTypeRequiredDescription
o_ipv4struct pubnub_ipv4_address*YesThe array where to put the system DNS servers. allocated by the caller for @p n elements.
nsize_tYesThe 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

TypeValueDescription
int-1Error: can't read system DNS servers.
intotherwiseThe 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 FreeRTOS SDK:

Declaration

enum pubnub_http_authentication_scheme pubnub_proxy_authentication_scheme_get(pubnub_t *p);

Parameters

ParameterTypeRequiredDescription
ppubnub_t*YesThe 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

TypeValueDescription
enum pubnub_http_authentication_schemeAny from the enumThe scheme used - pbhtauNone if no scheme is used (that is, the 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 FreeRTOS SDK:

Declaration

enum pubnub_proxy_type pubnub_proxy_protocol_get(pubnub_t *p);

Parameters

ParameterTypeRequiredDescription
ppubnub_t*YesThe Pubnub context for which to get the proxy protocol.

Basic Usage

enum pubnub_proxy_type proxy = pubnub_proxy_protocol_get(pbp);

Returns

TypeValueDescription
enum pubnub_proxy_typeAny from the enumThe 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)
ParameterTypeRequiredDescription
ppubnub_t*YesPubnub 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

TypeDescription
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 FreeRTOS SDK:

Declaration

int pubnub_get_dns_primary_server_ipv4(struct pubnub_ipv4_address* o_ipv4);

Parameters

ParametersTypeRequiredDescription
o_ipv4struct 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(&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

TypeValueDescription
int0OK.
int-1Error: 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 FreeRTOS SDK:

int pubnub_transaction_timeout_get(pubnub_t *p)
ParameterTypeRequiredDescription
ppubnub_t*YesPointer 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

TypeDescription
intCurrent 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 FreeRTOS SDK:

Declaration

struct pubnub_ipv4_address {uint8_t ipv4[4];};

Members

MemberTypeDescription
ipv4uint8_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)
ParameterTypeRequiredDescription
resultchar const*YesPublish 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

TypeDescription
enum pubnub_publish_resresult 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

TypeDescription
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

ParameterTypeRequiredDescription
ppubnub_t*YesThe 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

TypeValueDescription
enum pubnub_cancel_resPN_CANCEL_STARTEDCancel started, await the outcome.
enum pubnub_cancel_resPN_CANCEL_FINISHEDCancelled, 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)
ParameterTypeRequiredDescription
ppubnub_t*YesPointer 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

ParameterTypeRequiredDescription
pbpubnub_t*YesThe 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

TypeValueDescription
int0OK, context freed.
int-1Context 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)
ParameterTypeRequiredDescription
ppubnub_t*YesPointer 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

TypeDescription
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)
ParameterTypeRequiredDescription
pbpubnub_t*YesPointer 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

TypeDescription
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)
ParameterTypeRequiredDescription
pbpubnub_t*YesPubnub Client Context for which to return user data.

Basic Usage

void* user_data = pubnub_get_user_data(ctx);

Returns

TypeDescription
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)
ParameterTypeRequiredDescription
ppubnub_t*YesPointer 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

TypeDescription
intHTTP 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);
ParameterTypeRequiredDescription
ppubnub_t*YesPointer 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

TypeDescription
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:

Method(s)

int pubnub_last_result(pubnub_t *p)
ParameterTypeRequiredDescription
ppubnub_t*YesPointer 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

TypeDescription
enum pubnub_resresult 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);
ParameterTypeRequiredDescription
ppubnub_t*YesPointer to pubnub client context

Basic Usage

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

Returns

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

enum pubnub_res pubnub_leave (pubnub_t *p, const char *channel, const char *channel_group)
ParameterTypeRequiredDescription
ppubnub_t*YesPointer to PubNub client context. Can't be NULL.
channelconst char*OptionalThe string with the channel name (or comma-delimited list of channel names) to leave from.
channel_groupconst char *OptionalThe string with the channel group name (or comma-delimited list of channel group names) to leave from.

Basic Usage

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

Returns

TypeDescription
enum pubnub_resPNR_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)
ParameterTypeRequiredDescription
pbpubnub_t*YesThe Pubnub context for which the callback is set
cbpubnub_callback_tOptionalcb Pointer to function to call on end of transaction
user_datavoid*Optionaluser_data Pointer that will be given to the callback function

Basic Usage

pubnub_register_callback(ctx, sample_callback, &user_data);

Returns

TypeDescription
enum pubnub_resPNR_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)
ParameterTypeRequiredDescription
penum pubnub_resYesPubnub 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

TypeDescription
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

TypeDescription
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);
ParameterTypeRequiredDescription
pbppubnub_t*YesThe Pubnub context to use to get time.

Basic Usage

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

Returns

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

PubNub Uname

Returns a 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

TypeDescription
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)
ParameterTypeRequiredDescription
ppubnub_t*YesPointer 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

TypeDescription
char const*string with the version of the PubNub SDK client

Release/free the callback subscribe loop descriptor

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);
ParameterTypeRequiredDescription
pbsldpubnub_subloop_t*YesThe 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 FreeRTOS SDK:

Declaration

int pubnub_set_proxy_authentication_none(pubnub_t *p);

Parameters

ParameterTypeRequiredDescription
ppubnub_t*YesThe context to set proxy authentication for.

Basic Usage

pubnub_set_proxy_authentication_none(pbp);

Returns

TypeValueDescription
int0OK
!= 0Error, 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)
ParameterTypeRequiredDescription
ppubnub_t*YesThe 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

TypeDescription
int0 OK, otherwise: error, blocking I/O not supported

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)
ParameterTypeRequiredDescription
ppubnub_t*YesThe 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

TypeDescription
int0 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 FreeRTOS 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

ParameterTypeRequiredDescription
ppubnub_t*YesThe context to set proxy configuration for.
protocolenum pubnub_proxy_typeYesProxy protocol to use on @p p context.
ip_address_or_urlchar const*YesThe string with IP address or URL of the proxy server.
portuint16_tYesThe 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

TypeValueDescription
int0OK
!= 0Error, 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 FreeRTOS SDK:

int pubnub_set_transaction_timeout(pubnub_t *p, int duration_ms)
ParameterTypeRequiredDescription
ppubnub_t*YesPointer to PubNub client context.
duration_msintYesDuration of the timeout, in milliseconds

Basic Usage

Set the transaction timeout to the default subscribe timeout

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

Returns

TypeDescription
int0: 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 (that is, 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 FreeRTOS SDK:

Declaration

int pubnub_dns_set_primary_server_ipv4(struct pubnub_ipv4_address ipv4);

Parameters

ParametersTypeRequiredDescription
ipv4Struct pubnub_ipv4_addressYesThe 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

TypeValueDescription
int0OK.
int-1Error: 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 FreeRTOS SDK:

Declaration

int pubnub_dns_set_primary_server_ipv4_str(char const* ipv4_str);

Parameters

ParametersTypeRequiredDescription
ipv4_strchar const*YesThe 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

TypeValueDescription
int0OK.
int-1Error: Pubnub DNS module not used and can't set the primary DNS server.

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 FreeRTOS SDK:

Declaration

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

Parameters

ParameterTypeRequiredDescription
ppubnub_t*YesThe context to set proxy authentication for.
usernamechar const*OptionalAuthentication username. Use NULL to let C-core use the default username.
passwordchar const*OptionalAuthentication password. Use NULL to let C-core use the default password.

Basic Usage

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

Returns

TypeValueDescription
int0OK
!= 0Error, setting username/password failed.

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);
ParameterTypeRequiredDescription
eenum pubnub_resYesPubnub 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

TypeValueDescription
enum pubnub_triboolpbccTrueIt's safe to retry, though there is no guarantee that it will help.
pbccFalseIt doesn't benefit you to re-try the same transaction.
pbccNotSetRetry 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.

Start a callback subscribe loop

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 callbacks

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);
ParameterTypeRequiredDescription
pbsldpubnub_subloop_t*YesThe subscribe loop descriptor of the loop to start.

Basic Usage

pubnub_subloop_start(pbsld);

Returns

TypeValueDescription
enum pubnub_resPNR_OKSubscribe loop started.
otherIndicates reason for failure.

Stop a callback subscribe loop

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);
ParameterTypeRequiredDescription
pbsldpubnub_subloop_t*YesThe subscribe loop descriptor of the loop to stop.

Basic Usage

pubnub_subloop_stop(pbsld);

Returns

None.

Subscribe loop - callback

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);
ParameterTypeRequiredDescription
ppubnub_t*YesThe Pubnub context to use for the subscribe loop.
channelchar const*YesThe channel(s) to use in the subscribe loop
optionsstruct pubnub_subscribe_optionsYesSubscribe options to use in the loop
cbpubnub_subloop_callback_tYesThe 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

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

Subscribe loop - sync

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);
ParameterTypeRequiredDescription
ppubnub_t *YesThe Pubnub context to use for the loop.
channelchar const*YesThe channel(s) to subscribe to.

Basic Usage

pbsld = pubnub_subloop_define(pbp, "hello_world");

Returns

TypeValueDescription
struct pubnub_subloop_descriptor-The subscribe loop descriptor made.

Sync subscribe iteration

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);
ParameterTypeRequiredDescription
pbsldstruct pubnub_subloop_descriptor const*YesThe Pubnub sync subscriber loop descriptor to use.
messagechar const**YesThe message that was fetched, or NULL if no message fetched.

Basic Usage

for (;;) {
char const* msg;
enum pubnub_res pbres = pubnub_subloop_fetch(&pbsld, &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

TypeValueDescription
enum pubnub_resPNR_OKsuccess (message was fetched).
otherIndicates the reason for failure.

Time

This function will return a 17 digit precision Unix epoch.

Algorithm constructing the timetoken
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 FreeRTOS SDK:

enum pubnub_res pubnub_time (pubnub_t *p)
ParameterTypeRequiredDescription
ppubnub_t*YesPointer to pubnub client context

Basic Usage

Get PubNub Timetoken

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

// Callback

void some_function(pubnub_t *ctx)
{
pubnub_time(ctx);
}

void example_callback(pubnub_t *pb, enum pubnub_trans trans, enum pubnub_res result, void *user_data)
show all 20 lines

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)
ParameterTypeRequiredDescription
leftstruct Pubnub_UUID const*Yesuuid to be compared
rightstruct Pubnub_UUID const*Yesuuid to be compared

Basic Usage

struct Pubnub_UUID left;
struct Pubnub_UUID right;
if (0 != pubnub_generate_uuid_v4_random(&left) || 0 != pubnub_generate_uuid_v4_random(&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

TypeDescription
int0 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)
ParameterTypeRequiredDescription
uuidstruct Pubnub_UUID const*Yesuuid to be converted to string

Basic Usage

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

Returns

TypeDescription
struct Pubnub_UUID_StringString representation of uuid
Last updated on
On this page