Presence API for PubNub POSIX C SDK
Presence enables you to track the online and offline status of users and devices in real time, as well as store custom state information. Presence provides authoritative information on:
- When a user has joined or left a channel
- Who, and how many, users are subscribed to a particular channel
- Which channel(s) an individual user is subscribed to
- Associated state information for these users
Learn more about our Presence feature here.
Here Now
Requires Presence add-on
This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.
You can obtain information about the current state of a channel including a list of unique user-ids currently subscribed to the channel and the total occupancy count of the channel by calling the pubnub_here_now() function in your application.
Cache
This method has a 3 second response cache time.
Method(s)
To call Here Now you can use the following method(s) in the Posix C SDK:
enum pubnub_res pubnub_here_now (pubnub_t *p, const char *channel, const char *channel_group)
| Parameter | Type | Required | Description |
|---|---|---|---|
p | pubnub_t* | Yes | Pointer to PubNub client context. |
channel | const char* | Optional | The string with the channel name (or comma-delimited list of channel names) to get presence info for. |
channel_group | const char* | Optional | The string with the channel name (or comma-delimited list of channel group names) to get presence info for. |
Basic Usage
Get a list of uuids subscribed to channel
// Sync
pubnub_here_now(ctx, "my_channel", NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
char const *json_response = pubnub_get(ctx);
}
//callback
int here_now(pubnub_t *pn) {
char const *chan = "my_channel";
char const *msg;
enum pubnub_res res;
Rest Response from Server
The pubnub_here_now() function returns a list of uuid s currently subscribed to the channel.
uuids:["String","String", ... ,"String"]- List of UUIDs currently subscribed to the channel.occupancy: Number- Total current occupancy of the channel.
{
occupancy : 4,
uuids : ['123123234t234f34fq3dq', '143r34f34t34fq34q34q3', '23f34d3f4rq34r34rq23q', 'w34tcw45t45tcw435tww3']
}
Extended Here Now
Extended Here Now Options structure
Options for extended here now.
Method(s)
Declaration
struct pubnub_here_now_options { char const* channel_group; bool disable_uuids; bool state;};
Members
| Member | Type | Description |
|---|---|---|
channel_group | char const* | Channel group (a comma-delimited list of channel group names). If NULL, will not be used. |
disable_uuids | bool | If true will not give uuids associated with occupancy. |
state | bool | If true (and if disable_uuds is false), will give associated state alongside uuid info. |
Initialize extended Here Now options
This returns the default options for here-now transactions. Will set channel_group = NULL, disable_uuids=true and state = false.
Method(s)
Declaration
struct pubnub_here_now_options pubnub_here_now_defopts(void);
Parameters
This method doesn't take any argument.
Basic Usage
struct pubnub_here_now_options opts = pubnub_here_now_defopts();
Returns
| Type | Value | Description |
|---|---|---|
struct pubnub_here_now_options | The default options for here-now. |
Extended Here Now
The extended here now. It is basically the same as the pubnub_here_now(), just adding a few options that will be sent. Also, channel_group parameter is moved to options, it is not a regular function parameter, but, it's behavior is otherwise the same.
Method(s)
Declaration
enum pubnub_res pubnub_here_now_ex(pubnub_t *p, const char *channel, struct pubnub_here_now_options opt);
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
p | pubnub_t* | yes | The Pubnub context. |
channel | char const* | yes | The string with the channel name (or comma-delimited list of channel names) to subscribe for. |
opt | struct pubnub_here_now_options | yes | Here-now options. |
Basic Usage
struct pubnub_here_now_options opt = pubnub_here_now_defopts();
opt.state = 1;
pbresult = pubnub_here_now_ex(pn, "my_channel", opt);
Returns
| Type | Value | Description |
|---|---|---|
enum pubnub_res | PNR_STARTED | Success. |
| other | Indicates the type of error. |
Where Now
Requires Presence add-on
This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.
You can obtain information about the current list of channels to which a UUID is subscribed to by calling the pubnub_where_now() function in your application.
Timeout events
If the app is killed/crashes and restarted (or the page containing the PubNub instance is refreshed on the browser) within the heartbeat window no timeout event is generated.
Method(s)
To call pubnub_where_now() you can use the following method(s) in the Posix C SDK:
enum pubnub_res pubnub_where_now (pubnub_t *p, const char *uuid)
| Parameter | Type | Required | Description |
|---|---|---|---|
p | pubnub_t* | Yes | Pointer to PubNub client context. |
uuid | const char* | Optional | The UUID of the user to get the channel presence. If NULL, the current UUID of the p context will be used. |
Basic Usage
You simply need to define the uuid and the callback function to be used to send the data to as in the example below.
Get a list of channels a UUID is subscribed to
// Sync
char const *msg;
enum pubnub_res res;
res = pubnub_where_now(pn, "my_uuid");
if (res != PNR_STARTED) {
printf("pubnub_where_now() returned unexpected: %d\n", res);
return -1;
}
res = pubnub_await(pn);
if (res == PNR_STARTED) {
printf("pubnub_await() returned unexpected: PNR_STARTED(%d)\n", res);
Rest Response from Server
The pubnub_where_now() function returns a list of channels a uuid is subscribed to.
channels:["String","String", ... ,"String"]- List of channels a uuid is subscribed to.
Example Response
{
"channels": [
"lobby",
"game01",
"chat"
]
}
User State
Requires Presence add-on
This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.
The state API is used to set/get key/value pairs specific to a subscriber uuid.
State information is supplied as a JSON object of key/value pairs.
Method(s)
Set State
enum pubnub_res pubnub_set_state (pubnub_t *p, char const *channel, char const *channel_group, const char *uuid, char const *state)
| Parameter | Type | Required | Description |
|---|---|---|---|
p | pubnub_t* | Yes | Pointer to PubNub client context. |
channel | char const* | Optional | The string with the channel name (or comma-delimited list of channel names) to set state for. |
channel_group | char const* | Optional | The string with the channel name (or comma-delimited list of channel group names) to set state for. |
uuid | const char* | Yes | The UUID of the user for which to set state for. If NULL, the current UUID of the p context will be used. |
state | char const* | Yes | Has to be a JSON object |
Get State
enum pubnub_res pubnub_state_get (pubnub_t *p, char const *channel, char const *channel_group, const char *uuid)
| Parameter | Type | Required | Description |
|---|---|---|---|
p | pubnub_t* | Yes | Pointer to Pubnub Client Context |
channel | char const* | Optional | The string with the channel name (or comma-delimited list of channel names) to get the state for. |
channel_group | char const* | Optional | The string with the channel name (or comma-delimited list of channel group names) to get the state for. |
uuid | const char* | Optional | The UUID of the user for which to get the state for. If NULL, the current UUID of the p context will be used. |
Basic Usage
Set State
pubnub_set_state(ctx, "hello_world", NULL, NULL, NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
printf("Set success\n");
}
Get State
pubnub_get_state(ctx, "my_channel", NULL, NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
char const *json_response = pubnub_get(ctx);
}
Returns
The state API returns a JSON object containing key value pairs.
{
first : "Robert",
last : "Plant",
age : 59,
region : "UK"
}
Extended Set State
Requires Presence add-on
This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.
Extended Set State Options structure
| Parameter | Type | Required | Description |
|---|---|---|---|
p | pubnub_t* | Yes | Pointer to PubNub client context. |
channel_group | char const* | Optional | The string with the channel name (or comma-delimited list of channel group names) to set state for. |
user_id | const char* | Yes | The user_id of the user for which to set state for. If NULL, the current user_id of the p context will be used. |
heartbeat | bool | Yes | If set to true, you can set the state and make a heartbeat call at the same time via the /heartbeat endpoint. |
Description
The extended state API is used to set/get key/value pairs specific to a subscriber user_id with extra options.
State information is supplied as a JSON object of key/value pairs.
Method(s)
Set State with options
enum pubnub_res pubnub_set_state_ex(pubnub_t* p,
const char* channel,
const char* state,
struct pubnub_set_state_options opts);
| Parameter | Type | Required | Description |
|---|---|---|---|
p | pubnub_t* | Yes | Pointer to PubNub client context. |
channel | char const* | Optional | The string with the channel name (or comma-delimited list of channel names) to set state for. |
state | char const* | Yes | Has to be a JSON object. |
opts | pubnub_set_state_options | Yes | Refer to Extended set state options structure. |
Basic Usage
Set State with Heartbeat
struct pubnub_set_state_options opt = pubnub_set_state_defopts();
opt.heartbeat = true;
pbresult = pubnub_set_state_ex(pn, "my_channel", "{}", opt);
Returns
The state API returns the result of the transaction.
State was set: {"status": 200, "message": "OK", "service": "Presence"}
Heartbeat
Requires Presence add-on
This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.
This method notifies channels and channel groups about a client's presence. You can send heartbeats to channels you are not subscribed to.
Method(s)
enum pubnub_res pubnub_heartbeat(pubnub_t* pb, const char* channel, const char* channel_group)
| Parameter | Type | Required | Description |
|---|---|---|---|
pb | pubnub_t* | Yes | Pointer to PubNub client context. |
channel | char const* | Optional | The string with the channel name (or comma-delimited list of channel names) to notify. |
channel_group | char const* | Optional | The string with the channel_group name (or comma-delimited list of channel group names) to notify. |
Basic Usage
res = pubnub_heartbeat(pbp, chan, NULL);
if (PNR_STARTED == res) {
res = pubnub_await(pbp);
}
if (PNR_OK == res) {
puts("Heartbeated! Got messages:");
}
else {
printf("Heartbeating failed with code: %d('%s')\n",
res,
pubnub_res_2_string(res));
}
Returns
This method returns a PubNub result enum or an error, depending on the status of the transaction.