Presence API for PubNub Windows 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 Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
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.
Method(s)
To call Here Now
you can use the following method(s) in the Windows 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;
pubnub_here_now(pn, chan, NULL);
res = await(&user_data);
if (res == PNR_STARTED) {
printf("pubnub_last_result() returned unexpected: PNR_STARTED(%d)\n", res);
return -1;
}
if (PNR_OK == res) {
puts("Here Now result:");
msg = pubnub_get(pn);
puts(msg);
} else {
printf("Here Now failed with code: %d\n", res);
return -1;
}
return 0;
}
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']
}
Where Now
Requires Presence add-on Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
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.
Note
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 Windows 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);
return -1;
}
if (PNR_OK == res) {
puts("Were Now result:");
msg = pubnub_get(pn);
puts(msg);
} else {
printf("Were Now failed with code: %d\n", res);
return -1;
}
return 0;
// Callback
int where_now(pubnub_t *pn) {
char const *msg;
enum pubnub_res res;
pubnub_where_now(pn, "my_uuid");
res = await(&user_data);
if (res == PNR_STARTED) {
printf("pubnub_last_result() returned unexpected: PNR_STARTED(%d)\n", res);
return -1;
}
if (PNR_OK == res) {
puts("Where Now result:");
msg = pubnub_get(pn);
puts(msg);
} else {
printf("Where Now failed with code: %d\n", res);
return -1;
}
return 0;
}
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 Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
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)
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 |
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
pubnub_set_state(ctx, "hello_world", NULL, NULL, NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
printf("Set success\n");
}
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"
}