Posix C++ Misc API Reference for Realtime Apps
The methods on this page are utility methods that don't fit into other categories.
Class pubnub::subloop
Declaration
namespace pubnub { class subloop; }
Description
A helper class for a subscribe loop. Supports both a piecemal
, message-by-message, interface and a callback-like
interface.
Constructor
Declaration
subloop(context &ctx, std::string channel);
Description
Creates a subscribe loop, ready to do the looping. We assume that the @p
ctx
PubNub context will be valid throughout the lifetime of this object.
Parameters
Parameter Type Required Description ctx
pubnub::context
&Yes The PubNub context to use for the loop. channel
std::string Yes The channel(s) to subscribe to in the loop.
Basic Usage
pubnub::subloop sublup(ctx, "hello_world");
Enums
Enum type: pubnub_res
Result codes for Pubnub functions and transactions.
Members
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)
PNR_IO_ERROR
Communication error (network or HTTP
response format).
HTTP
error. Call pubnub_last_http_code()
to get the error code.
Unexpected input in received JSON
PNR_CANCELLED
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.
Enum type: pubnub_trans
Type of Pubnub operation/transaction
Members
No transaction at all PBTT_SUBSCRIBE
Subscribe operation/transaction PBTT_PUBLISH
Publish operation/transaction.
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
Execute the loop
Description
Executes a full subscribe loop
, calling the @p
f
functional object on each message received or on error in retrieving message(s). To stop the loop, return any integer != 0 from @p
f
.
Method(s)
Declaration
void loop(std::function<int(std::string, context&, pubnub_res)> f);
Parameters
Parameter Type Required Description f
std::function<int(std::string, context&, pubnub_res)> Yes Functional object to be called. First parameter is the message, second the context used for the loop and the third is the result of the transaction. Functional object should return 0
to continue the loop and anything != 0 to stop the loop.
Basic Usage
sublup.loop([](std::string msg, pubnub::context&, pubnub_res res) {
if (PNR_OK != res) {
std::cout << "Getting message failed with code: " << res;
return -1;
}
std::cout << "Got message: \n" << msg << std::endl;
return 0;
});
Returns
None
.
Fetch one message
Description
Fetches one message in 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)
Declaration
pubnub_res fetch(std::string &o_msg);
Parameters
Parameter Type Required Description o_msg
std::string & Yes String with the fetched message.
Basic Usage
std::string msg;
for (;;) {
enum pubnub_res res = sublup.fetch(msg);
if (res != PNR_OK) {
std::cout << "Fetching message failed with code: " << res;
break;
}
std::cout << "Got message: \n" << msg << std::endl;
}
Returns
Type | Value | Description |
---|---|---|
enum pubnub_res | PNR_OK | success (message was fetched). |
other | Indicates the reason for failure. |
Free a context, with waiting
Description
Tries pubnub_free()
in a tight loop until either:
- it succeeds
- time specified in
@p
millisec elapses
Essentially, it waits for the context to finish its current transaction and then frees it..
This function is much more useful in the callback interface, especially after a cancel()
This function is not useful at all in the sync interface if you're using only one thread with this context.
Also, if you want to do some other processing while waiting for the transaction to finish, don't use this function.
If the context is freed with this member function, it will not be freed in the destructor.
Method(s)
Declaration
int free_with_timeout(std::chrono::milliseconds duration);
Parameters
Parameter Type Required Description duration
std::chrono::milliseconds duration Yes Max time to wait for freeing to succeed, in milliseconds.
Basic Usage
if (0 != ctx.free_with_timeout(std::chrono::milliseconds(1000))) {
puts("Failed to free the context in due time");
}
Returns
Type | Value | Description |
---|---|---|
int | 0 | pubnub_free() succeeded. |
-1 | Failed to pubnub_free() in @p millisec. |
Free a context, without waiting
Description
Explicitly frees the context. Mostly provided for completeness, as destructor will also free the context, if needed.
If the context is freed with this member function, it will not be freed in the destructor.
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 free();
Parameters
This method doesn't take any argument.
Basic Usage
if (pn.free() != 0) {
std::cout << "Context not free, cancelation started\n";
}
else {
std::cout << "Context freed\n";
}
Returns
Type | Value | Description |
---|---|---|
int | 0 | OK, context freed. |
int | -1 | Context not freed, transaction cancel started. |
Get the Current Origin
Description
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:
std::string origin() const
Basic Usage
To get the origin currently set for a context:
std::cout << "Current origin: " << pn.origin() << std::endl;
Returns
Type | Description |
---|---|
std::string | The currently used origin for the context |
Get the Transaction Timeout
Description
Returns the current transaction timeout for the context.
Method(s)
To Get the transaction timeout
you can use the following method(s) in the Posix C++ SDK:
std::chrono::milliseconds transaction_timeout_get()
Basic Usage
Get current transaction timeout
std::cout <<"Current transaction timeout: " << pn.transaction_timeout_get() << std::endl;
Returns
Type | Description |
---|---|
std::chrono::milliseconds | Current transaction timeout, in milliseconds (should always be > 0) |
PubNub Cancel
Description
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 cancel();
Parameters
This method doesn't take any argument.
Basic Usage
if (PN_CANCEL_FINISHED == pn.cancel()) {
std::cout << "Cancel done\n";
}
else {
std::cout << "Cancellation started\n";
}
Returns
Type | Value | Description |
---|---|---|
enum pubnub_cancel_res | PN_CANCEL_STARTED | Cancel started, await the outcome. |
enum pubnub_cancel_res | PN_CANCEL_FINISHED | Cancelled, no need to await. |
PubNub Do Not Use HTTP Keep Alive
Description
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 use_http_keep_alive()
Method(s)
dont_use_http_keep_alive()
Basic Usage
dont_use_http_keep_alive()
Returns
None
.
PubNub Last HTTP Code
Description
Returns the HTTP reply code of the last transaction in the p
context.
Method(s)
last_http_code()
Basic Usage
res = pn.publish("my_channel", "\"hello\"").await();
if (PNR_OK == res) {
std::cout << pn.last_publish_result() << std::endl;
std::cout << "Last HTTP code: " << pn.last_http_code() << std::endl;
}
Returns
Type | Description |
---|---|
int | HTTP reply code of the last transaction in the p context. |
PubNub Leave
Description
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)
leave(std::string const &channel, std::string const &channel_group)
Parameter Type Required Description channel
std::string const & Yes channel
to invoke a leave event onchannel_group
std::string const & Yes channel group
to invoke a leave event onleave (std::vector< std::string > const &channel, std::vector< std::string > const &channel_group)
Parameter Type Required Description channel
std::vector <std::string> const & Yes channels to invoke a leave event on channel_group
std::vector <std::string> const & Yes channel group
to invoke a leave event on
Basic Usage
// Sync
void leave(pubnub::context &pn) {
enum pubnub_res res;
res = pn.leave("my_channel", "").await();
if (PNR_OK == res) {
std::cout << pn.get() << std::endl;
} else {
std::cout << "Request failed" << std::endl;
}
}
// Lambdas
void leave(pubnub::context &ipn) {
ipn.leave("my_channel", "").then([=](pubnub::context &pn, pubnub_res res) {
if (PNR_OK == res) {
std::cout << pn.get() << std::endl;
} else {
std::cout << "Request failed" << std::endl;
}
});
}
// Functions
void on_leave(pubnub::context &pn, pubnub_res res) {
if (PNR_OK == res) {
std::cout << pn.get() << std::endl;
} else {
std::cout << "Here Now request failed" << std::endl;
}
}
void leave(pubnub::context &pn) {
pn.leave("my_channel", "").then(on_leave);
}
Returns
Type | Description |
---|---|
enum pubnub_res | PNR_STARTED on success, an error otherwise |
PubNub Use HTTP Keep Alive
Description
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 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:
dont_use_http_keep_alive()
will not work for contexts that are inkeep alive
state. You need topubnub_cancel()
before you candont_use_http_keep_alive()
.- 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)
use_http_keep_alive()
Basic Usage
use_http_keep_alive()
Returns
None
.
Set blocking IO
Description
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)
void set_blocking_io(pubnub::blocking_io bio);
Parameter Type Required Description bio
pubnub::blocking_io
Yes Specifies bitwise option: pubnub::blocking
pubnub::non_blocking
Basic Usage
pn.set_blocking_io(pubnub::blocking_io);
Returns
None.
Set the Transaction Timeout
Description
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, context constructor 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 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 Posix C++ SDK:
int set_transaction_timeout(std::chrono::milliseconds duration)
Parameter Type Required Description duration
std::chrono::milliseconds Yes Duration of the timeout, in milliseconds
Basic Usage
Set the transaction timeout to the default subscribe timeout.
pn.set_transaction_timeout(std::chrono::seconds(510));
Returns
Type | Description |
---|---|
int | 0: OK (timeout set), otherwise: error, timers not supported |
Should a failed transaction be retried
Description
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)
Declaration
pubnub::tribool should_retry();
Parameters
This method doesn't take any argument.
Basic Usage
for (i = 0; i < my_retry_limit; ++i) {
futres futr = ctx.publish(chan, msg);
futr.await();
switch (futr.should_retry()) {
case false:
break;
case true:
Std::cout << "Publishing failed with code: << futr.last_result() << " (" << pubnub_res_2_string(futr.last_result()) >> ")\nRetrying...\n";
continue;
default:
puts("Publish failed, but we decided not to retry");
break;
}
break;
}
Returns
Type | Value | Description |
---|---|---|
pubnub::tribool | true | It's safe to retry, though there is no guarantee that it will help. |
false | It doesn't benefit you to re-try the same transaction. | |
pubnub::tribool::not_set | Retry might help, but, it also can make things worse. For example, for a #PNR_TIMEOUT , it may very well be that the message was delivered to PubNub, but, the response from PubNub never reached us due to some networking issue, resulting in a timeout. In that case, retrying would send the same message again, duplicating it. |
Time
Description
This function will return a 17 digit precision Unix epoch.
The timetoken is constructed using the following algorithm:
timetoken = (Unix epoch time in seconds) * 10000000
Example of creating a timetoken for a specific time and date
08/19/2013 @ 9:20pm in UTC = 1376961606
timetoken = 1376961606 * 10000000
timetoken = 13769616060000000
Method(s)
To fetch Time
you can use the following method(s) in Posix C++ SDK:
time()
Basic Usage
// Sync
void time(pubnub::context &pn) {
enum pubnub_res res;
res = pn.time().await();
if (PNR_OK == res) {
std::cout << pn.get() << std::endl;
} else {
std::cout << "Request failed" << std::endl;
}
}
// Lambdas
void time(pubnub::context &ipn) {
ipn.time().then([=](pubnub::context &pn, pubnub_res res) {
if (PNR_OK == res) {
std::cout << pn.get() << std::endl;
} else {
std::cout << "Request failed" << std::endl;
}
});
}
// Functions
void on_time(pubnub::context &pn, pubnub_res res) {
if (PNR_OK == res) {
std::cout << pn.get() << std::endl;
} else {
std::cout << "Request failed" << std::endl;
}
}
void time(pubnub::context &pn) {
pn.time().then(on_time);
}
Rest Response from Server
The time()
function returns a string timetoken in the following format:
13769501243685161