Utility Methods API for PubNub POSIX C SDK
The methods on this page are utility methods that don't fit into other categories.
Configure proxy to be used from the system
Sets the configuration for the Internet proxy, by reading from the system
configuration.
On some platforms (like Windows), there is some (de-facto) standard way of setting a proxy. On others, there may not be. C-core will try to do the best it can on a given platform.
This function can block for a significant time, if system configuration is to do autodiscovery of the proxy. So, call it only on start, restart, wake-up and similar events.
Preconditions
Call this after pubnub_init()
on the context.
Method(s)
To Configure proxy to be used from the system
you can use the following method(s) in the Posix C SDK:
Declaration
int pubnub_set_proxy_from_system(pubnub_t *p, enum pubnub_proxy_type protocol);
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
p | pubnub_t* | Yes | The context to set proxy configuration for. |
protocol | enum pubnub_proxy_type | Yes | Proxy protocol to use on @p p context. |
Basic Usage
pubnub_set_proxy_from_system(pbp, pbpproxyHTTP_GET);
Returns
Type | Value | Description |
---|---|---|
int | 0 | OK |
!= 0 | Error, specified protocol not supported or error in getting information from the system. |
Enums
Enum type: pubnub_res
Result codes for Functions and transactions.
Members
PNR_OK
Success. Transaction finished successfully.
PNR_ADDR_RESOLUTION_FAILED
Pubnub host name resolution failed. We failed to get an IP address from the PubNub host name (origin
). Most of the time, this comes down to a DNS error.
PNR_CONNECT_FAILED
Connecting to Pubnub server failed. Most often, this means a network outage, but could be many things. If using SSL/TLS
, it could be some of its errors.
PNR_CONNECTION_TIMEOUT
A time-out happened in the network. Mostly, this is because a network outage happened while being connected to the PubNub server, but could be other things.
PNR_TIMEOUT
Time-out before the request has completed. This is reported for a time-out detected by PubNub client itself, not some reported by others (that is, the TCP/IP
stack).
PNR_ABORTED
Connection to Pubnub aborted (in most cases, a TCP
reset was received).
PNR_IO_ERROR
Communication error (network or HTTP
response format).
PNR_HTTP_ERROR
HTTP
error. Call pubnub_last_http_code()
to get the error code.
PNR_FORMAT_ERROR
Unexpected input in received JSON
.
PNR_CANCELLED
Request cancelled by user.
PNR_STARTED
Transaction started. Await the outcome.
PNR_IN_PROGRESS
Transaction (already) ongoing. Can't start a new transaction while the old one is in progress.
PNR_RX_BUFF_NOT_EMPTY
Receive buffer (from previous transaction) not read, new subscription not allowed.
PNR_TX_BUFF_TOO_SMALL
The buffer is too small. Increase #PUBNUB_BUF_MAXLEN
.
PNR_INVALID_CHANNEL
Channel specification / name is invalid.
PNR_PUBLISH_FAILED
Publish transaction failed - error returned from Pubnub. To see the reason describing the failure, call pubnub_last_publish_result()
.
PNR_CHANNEL_REGISTRY_ERROR
A transaction related to channel registry failed - error returned from Pubnub. To see the reason describing the failure, get the value for key message
from the response (which is a JSON
object) and value for key status
for the numeric code of the error.
PNR_REPLY_TOO_BIG
Reply is too big to fit in our reply buffer. This same error is reported if the reply buffer is statically or dynamically allocated.
Enum type: pubnub_trans
Type of Pubnub operation/transaction.
Members
PBTT_NONE
No transaction at all.
PBTT_SUBSCRIBE
Subscribe operation/transaction.
PBTT_PUBLISH
Publish operation/transaction.
PBTT_LEAVE
Leave channel(s) operation/transaction.
PBTT_TIME
Time (get from Pubnub server) operation/transaction.
PBTT_HISTORY
History V2 (get message history for the channel from Pubnub server) operation/transaction.
PBTT_HERENOW
Here-now (get UUIDs of currently present users in channel(s)) operation/transaction.
PBTT_GLOBAL_HERENOW
Here-now (get UUIDs of currently present users in channel(s)) operation/transaction.
PBTT_WHERENOW
Where-now (get channels in which an user (identified by UUID) is currently present) operation/transaction.
PBTT_SET_STATE
Set state (for a user (identified by UUID) on channel(s)) operation/transaction.
PBTT_STATE_GET
Get state (for a user (identified by UUID) on channel(s)) operation/transaction.
PBTT_REMOVE_CHANNEL_GROUP
Remove a channel group (from the channel-registry) operation/transaction.
PBTT_REMOVE_CHANNEL_FROM_GROUP
Remove a channel from a channel group (in the channel-registry) operation/transaction.
PBTT_ADD_CHANNEL_TO_GROUP
Add a channel to a channel group (in the channel-registry) operation/transaction.
PBTT_LIST_CHANNEL_GROUP
Get a list of all channels in a channel group (from the channel-registry) operation/transaction.
Free a context, with waiting
Tries pubnub_free()
in a tight loop until either:
- it succeeds
- time specified in
@p
millisec elapses
Essentially, it waits for the context to finish its current transaction and then frees it.
This function is much more useful in the callback interface, especially after a pubnub_cancel()
.
This function is not useful at all in the sync interface if you're using only one thread with the @p
pbp context.
Also, if you want to do some other processing while waiting for the transaction to finish, don't use this function.
Method(s)
int pubnub_free_with_timeout(pubnub_t* pbp, unsigned millisec);
Parameter | Type | Required | Description |
---|---|---|---|
pbp | pubnub_t* | Yes | The Pubnub context which to free. |
millisec | unsigned | Yes | Max time to wait for freeing to succeed, in milliseconds . |
Basic Usage
if (0 != pubnub_free_with_timeout(pbp, 1000)) {
puts("Failed to free the context in due time");
}
Returns
Type | Value | Description |
---|---|---|
int | 0 | pubnub_free() succeeded. |
-1 | Failed to pubnub_free() in @p millisec. |