CWindows CWindows CFreeRTOSmbedPosix CWindows C Misc API Reference for Realtime Apps

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.

  • Call this after pubnub_init() on the context

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

  1. int pubnub_set_proxy_from_system(pubnub_t *p, enum pubnub_proxy_type protocol);
    ParameterTypeRequiredDescription
    ppubnub_t*YesThe context to set proxy configuration for.
    protocolenum pubnub_proxy_typeYesProxy protocol to use on @p p context.
pubnub_set_proxy_from_system(pbp, pbpproxyHTTP_GET);
TypeValueDescription
int0OK
!= 0Error, specified protocol not supported or error in getting information from the system.

Result codes for Pubnub functions and transactions.

Success. Transaction finished successfully.

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.

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.

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.

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

Connection to Pubnub aborted (in most cases, a TCP reset was received)

Communication error (network or HTTP response format).

HTTP error. Call pubnub_last_http_code() to get the error code.

Unexpected input in received JSON

Request cancelled by user.

Transaction started. Await the outcome.

Transaction (already) ongoing. Can't start a new transaction while the old one is in progress.

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

The buffer is too small. Increase #PUBNUB_BUF_MAXLEN.

Channel specification / name is invalid.

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

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.

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

Type of Pubnub operation/transaction

No transaction at all

Subscribe operation/transaction

Publish operation/transaction.

Leave channel(s) operation/transaction

Time (get from Pubnub server) operation/transaction

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

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

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

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

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

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

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

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

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

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

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.

  1. ParameterTypeRequiredDescription
    pbppubnub_t*YesThe Pubnub context which to free.
    millisecunsignedYesMax time to wait for freeing to succeed, in milliseconds.
if (0 != pubnub_free_with_timeout(pbp, 1000)) {
    puts("Failed to free the context in due time");
}
TypeValueDescription
int0pubnub_free() succeeded.
-1Failed to pubnub_free() in @p millisec.
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.
  1. 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.
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");
}
TypeDescription
int
0: OK (generated), otherwise: error, algorithm not available.
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.
  1. ParameterTypeRequiredDescription
    uuidstruct Pubnub_UUID*YesThe place to put the generated UUID to.
struct Pubnub_UUID uuid;
if (0 == pubnub_generate_uuid_v4_random(&uuid)) {
    puts("UUID generation unsuccessful");
}
TypeDescription
int
0: OK (generated), otherwise: error, random number generator not available.
  1. 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);
        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);
        }
    }
    pubnub_free(ctx);
  2. 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);
    }

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

  1. 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.
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");
}
TypeDescription
int
0: OK (generated), otherwise: error, algorithm not available

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.

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

  1. int pubnub_dns_read_system_servers_ipv4(struct pubnub_ipv4_address* o_ipv4, size_tn);
    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.
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]
    }
}
TypeValueDescription
int-1Error: can't read system DNS servers.
intotherwiseThe number of DNS servers read.

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

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

  1. enum pubnub_http_authentication_scheme pubnub_proxy_authentication_scheme_get(pubnub_t *p);
    ParameterTypeRequiredDescription
    ppubnub_t*YesThe context to get proxy scheme for.
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;
}
TypeValueDescription
enum pubnub_http_authentication_schemeAny from the enumThe scheme used - pbhtauNone if no scheme is used (i.e. proxy is not an authenticating proxy).

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

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

  1. enum pubnub_proxy_type pubnub_proxy_protocol_get(pubnub_t *p);
    ParameterTypeRequiredDescription
    ppubnub_t*YesThe Pubnub context for which to get the proxy protocol.
enum pubnub_proxy_type proxy = pubnub_proxy_protocol_get(pbp);
TypeValueDescription
enum pubnub_proxy_typeAny from the enumThe proxy used - pbpproxyNONE if no proxy.

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

To Get the origin of a Pubnub context use:

  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPubnub context to get origin from
printf("Current origin: %s\n", pubnub_get_origin(pn));
TypeDescription
char const*A read only string of origin used for the given context

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

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

  1. int pubnub_get_dns_primary_server_ipv4(struct pubnub_ipv4_address* o_ipv4);
    ParametersTypeRequiredDescription
    o_ipv4struct pubnub_ipv4_address*Yes(pointer to) The IPv4 address of the server used - allocated by the caller.
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]);
}
TypeValueDescription
int0OK.
int-1Error: Pubnub DNS module not used and can't get the primary DNS server.

Returns the current transaction timeout for the context.

  • Call this after pubnub_init() on the context

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

  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub client context.
#include "pubnub_timers.h"
...
printf("Current transaction timeout: %d\n", pubnub_transaction_timeout_get(pn));
TypeDescription
intCurrent transaction timeout, in milliseconds (should always be > 0)
IPv4 Address, in binary format.

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

  1. struct pubnub_ipv4_address {uint8_t ipv4[4];};
    MemberTypeDescription
    ipv4uint8_t[4]The four octets of the IPv4 address.
Parses the given publish result. You usually obtain this with pubnub_last_publish_result().
  1. ParameterTypeRequiredDescription
    resultchar const*YesPublish Result
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);

if (PNR_PUBLISH_FAILED == res) {
  enum pubnub_publish_res publ_res = pubnub_parse_publish_result(pubnub_last_publish_result(pbp));
  switch (publ_res) {
  case PNPUB_INVALID_JSON: printf("Invalid JSON was sent in the publish message\n"); break;
  default: break;
  }
}
TypeDescription
enum pubnub_publish_res
result of publish response parsing
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.
pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}
TypeDescription
pubnub_t*
Context pointer on success, NULL on error

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.

  1. enum pubnub_cancel_res pubnub_cancel(pubnub_t* p);
    ParameterTypeRequiredDescription
    ppubnub_t*YesThe Pubnub context for which to cancel the transaction..
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);		
}
TypeValueDescription
enum pubnub_cancel_resPN_CANCEL_STARTEDCancel started, await the outcome.
enum pubnub_cancel_resPN_CANCEL_FINISHEDCancelled, no need to await.

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

  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub Client Context.
pubnub_dont_use_http_keep_alive(pbp);
None.

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.

  1. int pubnub_free(pubnub_t *pb);
    ParameterTypeRequiredDescription
    pbpubnub_t*YesThe Pubnub context to free.
if (0 != pubnub_free(pbp)) {
    printf("Freeing pubnub context failed, cancel started.\n");
}
else {
    printf("Pubnub context freed.\n");
}
TypeValueDescription
int0OK, context freed.
int-1Context not freed, transaction cancel started.
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.
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub Client Context
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);
TypeDescription
char const*
Pointer to message. NULL on error.
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).
  1. ParameterTypeRequiredDescription
    pbpubnub_t*YesPointer to Pubnub Client Context. Can't be NULL.
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);
    }
}
pubnub_free(ctx);
TypeDescription
char const*Pointer to channel. NULL on error.
Returns the user data set with pubnub_register_callback().
  1. ParameterTypeRequiredDescription
    pbpubnub_t*YesPubnub Client Context for which to return user data.
void* user_data = pubnub_get_user_data(ctx);
TypeDescription
void*
user data set with pubnub_register_callback
Returns the HTTP reply code of the last transaction in the p context.
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to pubnub client context
pubnub_list_channel_group(ctx, "my_channel_group");
pbresult = pubnub_await(ctx);
printf("HTTP Status Code %d\n", pubnub_last_http_code(ctx));
TypeDescription
int
HTTP reply code of the last transaction in the p context.
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.
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to pubnub client context
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;
}
TypeDescription
char const*
string of the result of the last publish transaction

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:

  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to pubnub client context
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)));
TypeDescription
enum pubnub_resresult of the last transaction in the context.
Returns the string of the last received time token in a subscribe transaction, on the p context. After pubnub_init() this should be "0".
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to pubnub client context
printf("Last time token %s\n", pubnub_last_time_token(ctx));
TypeDescription
char const*string of the last received time token on the context, in a subscribe transaction
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.
pubnub_leave(ctx, "hello_world", NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
    printf("Leave successful\n");
}
pubnub_free(ctx);
TypeDescription
enum pubnub_res
PNR_STARTED on success, an error otherwise
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.
  1. 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
pubnub_register_callback(ctx, sample_callback, &user_data);
TypeDescription
enum pubnub_res
PNR_OK on success, a value indicating the error otherwise
Returns a string (in English) describing a Pubnub result enum
  1. ParameterTypeRequiredDescription
    penum pubnub_resYesPubnub result enum value
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);
printf("Response %s\n",pubnub_res_2_string(res));
TypeDescription
char const*
String describing pubnub result
Returns a string with the name of the Pubnub SDK client you are using.
  1. This method has no argument

printf("SDK name  : %s", pubnub_sdk_name());
TypeDescription
char const*
string with the name of the Pubnub SDK client you are using

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

  1. ParameterTypeRequiredDescription
    pbppubnub_t*YesThe Pubnub context to use to get time.
printf("srand from pubnub time %s\n", srand_from_pubnub_time(ctx));
TypeDescription
int0: OK, -1: error (srand() was not called).
Returns an URL encoded string with the full identification of the SDK - name, version, possible something more.
  1. This method has no arguments

printf("uname : %s", pubnub_uname());
TypeDescription
char const*URL encoded string with the full identification of the SDK

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.
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub Client Context.
pubnub_use_http_keep_alive(pbp);
None.
Returns a string with the version of the Pubnub SDK client you are using.
  1. This method has no arguments

printf("VERSION : %s", pubnub_version());
TypeDescription
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.

  1. ParameterTypeRequiredDescription
    pbsldpubnub_subloop_t*YesThe subscribe loop descriptor of the loop to undefine/release.
pubnub_subloop_undef(pbsld);
None.

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.

  • Call this after pubnub_init() on the context

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

  1. int pubnub_set_proxy_authentication_none(pubnub_t *p);
    ParameterTypeRequiredDescription
    ppubnub_t*YesThe context to set proxy authentication for.
pubnub_set_proxy_authentication_none(pbp);
TypeValueDescription
int0OK
!= 0Error, authentication scheme doesn't support no authentication.

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.

  1. ParameterTypeRequiredDescription
    ppubnub_t*YesThe Context to set blocking I/O for
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");
}
TypeDescription
int
0 OK, otherwise: error, blocking I/O not supported

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.

  • @p p is a valid context

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

  1. int pubnub_set_ssl_verify_locations(pubnub_t *p, char const* sCAfile, char const* sCApath);
    ParameterTypeRequiredDescription
    ppubnub_t*YesPubnub context to set locations for.
    sCAfilechar const*OptionalThe certificate store file. May contain more than one CA certificate. Set to NULL if you don't want to use the certificate file.
    sCApathchar const*OptionalThe 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.
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");
}
TypeValueDescription
int0succeeded
-1Failed to set certificate locations.

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.

  1. ParameterTypeRequiredDescription
    ppubnub_t*YesThe Context to set non-blocking I/O for
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");
}
TypeDescription
int
0 OK, otherwise: error, non-blocking I/O not supported

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.

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

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

  1. int pubnub_set_proxy_manual(pubnub_t *p, enum pubnub_proxy_type protocol, char const *ip_address_or_url, uint16_t port);
    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.
pubnub_set_proxy_manual(pbp, pbpproxyHTTP_GET, "proxy.local", 3128);
TypeValueDescription
int0OK
!= 0Error, specified protocol not supported, invalid @p ip_address_or_url.

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.

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

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

  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub client context.
    duration_msintYesDuration of the timeout, in milliseconds
#include "pubnub_timers.h"
pubnub_set_transaction_timeout(pn, PUBNUB_DEFAULT_SUBSCRIBE_TIMEOUT);
TypeDescription
int0: OK (timeout set), otherwise: error, timers not supported

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.

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

  1. int pubnub_dns_set_primary_server_ipv4(struct pubnub_ipv4_address ipv4);
    ParametersTypeRequiredDescription
    ipv4Struct pubnub_ipv4_addressYesThe IPv4 address of the server to use. Set all 0 to not use this DNS server.
struct pubnub_ipv4_address addr = { { 8, 8, 8, 8 } };
If (0 != pubnub_dns_set_primary_server(addr)) {
    printf("Setting primary DNS server failed\n");
}
TypeValueDescription
int0OK.
int-1Error: Pubnub DNS module not used and can't set the primary DNS server.

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

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

  1. int pubnub_dns_set_primary_server_ipv4_str(char const* ipv4_str);
    ParametersTypeRequiredDescription
    ipv4_strchar const*YesThe IPv4 address in string (numbers and dots) notation.
If (0 != pubnub_dns_set_primary_server_str("8.8.8.8")) {
    printf("Setting primary DNS server failed\n");
}
TypeValueDescription
int0OK.
int-1Error: Pubnub DNS module not used and can't set the primary DNS server.

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.

  • @p p is a valid context

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

  1. void pubnub_ssl_set_usrdef_pem_cert(pubnub_t *p, char const *contents);
    ParameterTypeRequiredDescription
    ppubnub_t*YesThe context for which to set user-defined/in-memory PEM certificate.
    contentschar const*YesString 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.
static char const my_cert[] = "-----BEGIN CERTIFICATE-----\n"
…
    "-----END CERTIFICATE-----\n";

pubnub_ssl_set_usrdef_pem_cert(pbp, my_cert);
None.

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

  • Call this after pubnub_init() on the context

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

  1. int pubnub_set_proxy_authentication_username_password(pubnub_t *p, char const *username, char const *password);
    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.
pubnub_set_proxy_authentication_username_password(pbp, "bond", "007");
TypeValueDescription
int0OK
!= 0Error, setting username/password failed.

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

  • @p p is a valid context

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

  1. int pubnub_ssl_use_system_certificate_store(pubnub_t *p);
    ParameterTypeRequiredDescription
    ppubnub_t*YesThe context for which to use system certificate store.
if (0 != pubnub_ssl_use_system_certificate_store(pbp)) {
    puts("Using system certificate store not supported");
}
TypeValueDescription
int0succeeded
-1System certificate store usage not supported.

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.

  1. ParameterTypeRequiredDescription
    eenum pubnub_resYesPubnub result returned by a C-core function, for which the user wants to find out if retrying makes sense.
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;
        case pbccNotSet:
            puts("Publish failed, but we decided not to retry");
        break;
    }

    break;
}
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.

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.

 Changing the callback on the context during the running of the subscribe loop will break the loop.
 You should _not_ change the subscribe loop descriptor while the loop is running. Stop it first, with pubnub_subloop_stop().
  1. ParameterTypeRequiredDescription
    pbsldpubnub_subloop_t*YesThe subscribe loop descriptor of the loop to start.
pubnub_subloop_start(pbsld);
TypeValueDescription
enum pubnub_resPNR_OKSubscribe loop started.
otherIndicates 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.

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

  1. 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.
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;
}
TypeValueDescription
pubnub_subloop_t*NULLFailed to create a descriptor.
otherThe 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.

  1. ParameterTypeRequiredDescription
    ppubnub_t *YesThe Pubnub context to use for the loop.
    channelchar const*YesThe channel(s) to subscribe to.
pbsld = pubnub_subloop_define(pbp, "hello_world");
TypeValueDescription
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.

  1. 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.
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);
    }
}
TypeValueDescription
enum pubnub_resPNR_OKsuccess (message was fetched).
otherIndicates the reason for failure.
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 & date
08/19/2013 @ 9:20pm in UTC = 1376961606
timetoken = 1376961606 * 10000000
timetoken = 13769616060000000
To fetch Time you can use the following method(s) in Windows C SDK
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to pubnub client context
pubnub_time(ctx);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
    char const *gotten_time = pubnub_get();
}
The pubnub_time() function returns a string timetoken in the following format:

13769501243685161
Compares two UUIDs (left and right) and returns: - 0: equal - <0: left < right - >0: left > right
  1. ParameterTypeRequiredDescription
    leftstruct Pubnub_UUID const*Yesuuid to be compared
    rightstruct Pubnub_UUID const*Yesuuid to be compared
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");
TypeDescription
int
0 if equal, <0: left < right, >0: left > right
Returns UUID as a standard HEX-based representation
  1. ParameterTypeRequiredDescription
    uuidstruct Pubnub_UUID const*Yesuuid to be converted to string
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);
}
TypeDescription
struct Pubnub_UUID_String
String representation of uuid

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

  • @p p is a valid context

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

  1. void pubnub_ssl_dont_use_system_certificate_store(pubnub_t *p);
    ParameterTypeRequiredDescription
    ppubnub_t*YesThe context for which to use system certificate store.
pubnub_ssl_dont_use_system_certificate_store(pbp);
None.