Utility Methods API for PubNub Mbed SDK

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

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

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 at the time of this writing, this will use the C standard library random number generator, which is not of high quality. Also, you need to set a randomized seed, by calling srand(), otherwise the generated UUIDs will not be random at all. One way to do that is to get current time from Pubnub and use it for the seed. There is a helper function for this purpose: srand_from_pubnub_time().

Method(s)

int pubnub_generate_uuid_v4_random(struct Pubnub_UUID *uuid)

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

Basic Usage

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

Returns

Type	Description
int	0: 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 portable and can be made to work, with effort, on pretty much any platform, without the need to obtain unique identifiers yourself (like you need to do for v3 and v5).

Method(s)

int pubnub_generate_uuid_v1_time(struct Pubnub_UUID *o_uuid, uint16_t *io_clock_seq, uint8_t const i_timestamp[8], uint8_t const i_node[6]);

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

Basic Usage

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

Returns

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

Get the Current Origin

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

Method(s)

To Get the origin of a Pubnub context use:

char const* pubnub_get_origin(pubnub_t *p)

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

Basic Usage

To get the origin currently set for a context

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

Returns

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

Get the 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 mbed SDK:

int pubnub_transaction_timeout_get(pubnub_t *p)

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

Basic Usage

Get current transaction timeout

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

Returns

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

Parse Publish Result

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

Method(s)

enum pubnub_publish_res pubnub_parse_publish_result(char const *result)

Parameter	Type	Required	Description
result	char const*	Yes	Publish Result

Basic Usage

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

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

show all 23 lines

Returns

Type	Description
enum pubnub_publish_res	result of publish response parsing

PubNub Alloc

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

Method(s)

pubnub_t *pubnub_alloc(void)

Basic Usage

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

Returns

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

PubNub Cancel

Cancel an ongoing API transaction. The outcome of the transaction in progress, if any, will be PNR_CANCELLED.

Method(s)

void pubnub_cancel (pubnub_t *p)

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

Basic Usage

pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}
pubnub_init(ctx, "demo", "demo");
pubnub_publish(ctx, "hello_world", "\"Hello from Pubnub C-core docs!\"");
pubnub_cancel(ctx);

Returns

None.

PubNub Do Not Use HTTP Keep Alive

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

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

Method(s)

void pubnub_dont_use_http_keep_alive (pubnub_t* p)

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

Basic Usage

pubnub_dont_use_http_keep_alive(pbp);

Returns

None.

PubNub Free

Frees a previously allocated context, if it is not in a transaction. If a context is in a transaction, first cancel it (call pubnub_cancel()), then wait for the context to finish the cancelling. It's OK to call this function on a context whose transaction is not over and done, it will just fail, but will not affect the transaction in any way. You don't have to free a context when you finish a transaction. Just start a new one. Free a context if you're done doing Pubnub transactions for a long time.

Method(s)

int pubnub_free(pubnub_t *pb)

Parameter	Type	Required	Description
pb	pubnub_t*	Yes	Pointer to a context which to free

Basic Usage

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

Returns

Type	Description
int	0: OK, context freed; else: error, context untouched

PubNub Get

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

Method(s)

char const * pubnub_get (pubnub_t *p)

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

Basic Usage

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

Returns

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

PubNub Get Channel

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

Method(s)

char const * pubnub_get_channel (pubnub_t *pb)

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

Basic Usage

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

show all 17 lines

Returns

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

PubNub Get User Data

Returns the user data set with pubnub_register_callback().

Method(s)

void *pubnub_get_user_data(pubnub_t *pb)

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

Basic Usage

void* user_data = pubnub_get_user_data(ctx);

Returns

Type	Description
void*	user data set with pubnub_register_callback

PubNub Last HTTP Code

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

Method(s)

enum pubnub_res int pubnub_last_http_code(pubnub_t *p)

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

Basic Usage

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

Returns

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

PubNub Last Publish Result

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

Method(s)

char const *pubnub_last_publish_result(pubnub_t *p);

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

Basic Usage

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

Returns

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

PubNub Last Result

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

Also have a look at:

• pubnub_set_blocking_io
• pubnub_set_non_blocking_io

Method(s)

int pubnub_last_result(pubnub_t *p)

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

Basic Usage

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

Returns

Type	Description
enum pubnub_res	result of the last transaction in the context.

PubNub Last Time Token

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

Method(s)

char const *pubnub_last_time_token(pubnub_t *p);

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

Basic Usage

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

Returns

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

PubNub Leave

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

Method(s)

enum pubnub_res pubnub_leave (pubnub_t *p, const char *channel, const char *channel_group)

Parameter	Type	Required	Description
p	pubnub_t*	Yes	Pointer to PubNub client context. Can't be NULL.
channel	const char*	Optional	The string with the channel name (or comma-delimited list of channel names) to leave from.
channel_group	const char *	Optional	The 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

Type	Description
enum pubnub_res	PNR_STARTED on success, an error otherwise

PubNub Register Callback

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

Method(s)

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

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

Basic Usage

pubnub_register_callback(ctx, sample_callback, &user_data);

Returns

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

PubNub Res 2 string

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

Method(s)

char const* pubnub_res_2_string(enum pubnub_res e)

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

Basic Usage

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

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

show all 16 lines

Returns

Type	Description
char const*	String describing pubnub result

PubNub SDK Name

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

Method(s)

char const *pubnub_sdk_name(void)

This method has no argument

Basic Usage

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

Returns

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

PubNub SRAND Time

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

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

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

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

Method(s)

int srand_from_pubnub_time(pubnub_t *pbp);

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

Basic Usage

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

Returns

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

PubNub Uname

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

Method(s)

char const *pubnub_uname(void)

This method has no arguments

Basic Usage

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

Returns

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

PubNub Use HTTP Keep Alive

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

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

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

Method(s)

void pubnub_use_http_keep_alive (pubnub_t* p)

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

Basic Usage

pubnub_use_http_keep_alive(pbp);

Returns

None.

PubNub Version

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

Method(s)

char const *pubnub_version(void)

This method has no arguments

Basic Usage

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

Returns

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

Set blocking IO

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

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

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

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

Method(s)

int pubnub_set_blocking_io(pubnub_t *p)

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

Basic Usage

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

Returns

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

Set Non Blocking IO

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

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

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

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

Method(s)

int pubnub_set_non_blocking_io(pubnub_t *p)

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

Basic Usage

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

Returns

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

Set 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 mbed SDK:

int pubnub_set_transaction_timeout(pubnub_t *p, int duration_ms)

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

Basic Usage

Set the transaction timeout to the default subscribe timeout

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

Returns

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

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

enum pubnub_res pubnub_time (pubnub_t *p)

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

Basic Usage

Get PubNub Timetoken

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

Rest Response from Server

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

13769501243685161

UUID Compare

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

Method(s)

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

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

Basic Usage

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

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

UUID to String

Returns UUID as a standard HEX-based representation

Method(s)

struct Pubnub_UUID_String pubnub_uuid_to_string(struct Pubnub_UUID const *uuid)

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

Basic Usage

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

Returns

Type	Description
struct Pubnub_UUID_String	String representation of uuid