mbedmbedWindows CFreeRTOSPosix CCmbed Presence API Reference for Realtime Apps

Go to Publish & Subscribe


Requires Presence add-on XRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-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.
To call Here Now you can use the following method(s) in the mbed SDK:
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub client context.
    channelconst char*OptionalThe string with the channel name (or comma-delimited list of channel names) to get presence info for.
    channel_groupconst char*OptionalThe string with the channel name (or comma-delimited list of channel group names) to get presence info for.
// Sync
 
pubnub_here_now(
    ctx,
    "my_channel",
    NULL
);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
    char const *json_response = pubnub_get(ctx);
}
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']
}
Return Occupancy for all channels by calling the pubnub_global_here_now() function in your application.
To call Global Here Now you can use the following method(s) in the mbed SDK:
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub Client Context. Can't be NULL
// Sync

char const *msg;
enum pubnub_res res;

res = pubnub_global_here_now(pn);
if (res != PNR_STARTED) {
  printf("pubnub_global_here_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("Global Here Now result:");
  msg = pubnub_get(pn);
  puts(msg);
} else {
  printf("Global Here Now failed with code: %d\n", res);
  return -1;
}

return 0;
{
	"status": 200,
	"message": "OK",
	"payload": {
		"channels": {
			"81d8d989-b95f-443c-a726-04fac323b331": {
				"uuids": [
					"70fc1140-22b5-4abc-85b2-ff8c17b24d59"
				],
				"occupancy": 1
			},
			"81b7a746-d153-49e2-ab70-3037a75cec7e": {
				"uuids": [
					"91363e7f-584b-49cc-822c-52c2c01e5928"
				],
				"occupancy": 1
			},
			"c068d15e-772a-4bcd-aa27-f920b7a4eaa8": {
				"uuids": [
					"ccfac1dd-b3a5-4afd-9fd9-db11aeb65395"
				],
				"occupancy": 1
			}
		},
		"total_channels": 3,
		"total_occupancy": 3
	},
	"service": "Presence"
}

Options for extended here now, global or not, doesn't matter.

  1. struct pubnub_here_now_options { char const* channel_group; bool disable_uuids; bool state;};

    MemberTypeDescription
    channel_groupchar const*Channel group (a comma-delimited list of channel group names). If NULL, will not be used.
    disable_uuidsboolIf true will not give uuids associated with occupancy.
    stateboolIf true (and if disable_uuds is false), will give associated state alongside uuid info.

This returns the default options for here-now transactions. Will set channel_group = NULL, disable_uuids=true and state = false.

  1. struct pubnub_here_now_options pubnub_here_now_defopts(void);

    This method doesn't take any argument.

struct pubnub_here_now_options opts = pubnub_here_now_defopts();
TypeValueDescription
struct pubnub_here_now_optionsThe default options for 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.

  1. enum pubnub_res pubnub_here_now_ex(pubnub_t *p, const char *channel, struct pubnub_here_now_options opt);

    ParameterTypeRequiredDescription
    ppubnub_t*yesThe Pubnub context.
    channelchar const*yesThe string with the channel name (or comma-delimited list of channel names) to subscribe for.
    optstruct pubnub_here_now_optionsyesHere-now options.
struct pubnub_here_now_options opt = pubnub_here_now_defopts();
opt.state = 1;
pbresult = pubnub_here_now_ex(pn, "my_channel", opt);
TypeValueDescription
enum pubnub_resPNR_STARTEDSuccess.
otherIndicates the type of error.

This is to pubnub_here_now_ex() as pubnub_global_here_now() is to pubnub_here_now().

  1. enum pubnub_res pubnub_global_here_now_ex(pubnub_t *p, struct pubnub_here_now_options opt);

    ParameterTypeRequiredDescription
    ppubnub_t*yesThe Pubnub context.
    optstruct pubnub_here_now_optionsyesHere-now options.
struct pubnub_here_now_options opt = pubnub_global_here_now_defopts();
opt.state = 1;
pbresult = pubnub_global_here_now_ex(pn, opt);
TypeValueDescription
enum pubnub_resPNR_STARTEDSuccess.
otherIndicates the type of error.
Requires Presence add-on XRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-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.
 
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.
To call pubnub_where_now() you can use the following method(s) in the mbed SDK:
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub client context.
    uuidconst char*OptionalThe UUID of the user to get the channel presence. If NULL, the current UUID of the p context will be used.
You simply need to define the uuid and the callback function to be used to send the data to as in the example below.
// 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;
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.
{
	"channels": [
		"lobby",
		"game01",
		"chat"
	]
}
Requires Presence add-on XRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-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.
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub client context.
    channelchar const*OptionalThe string with the channel name (or comma-delimited list of channel names) to set state for.
    channel_groupchar const*OptionalThe string with the channel name (or comma-delimited list of channel group names) to set state for.
    uuidconst char*YesThe UUID of the user for which to set state for. If NULL, the current UUID of the p context will be used.
    statechar const*YesHas to be a JSON object
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub Client Context
    channelchar const*OptionalThe string with the channel name (or comma-delimited list of channel names) to get the state for.
    channel_groupchar const*OptionalThe string with the channel name (or comma-delimited list of channel group names) to get the state for.
    uuidconst char*OptionalThe UUID of the user for which to get the state for. If NULL, the current UUID of the p context will be used.
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);
}
The state API returns a JSON object containing key value pairs.
{
	first   : "Robert",
	last    : "Plant",
	age     : 59,
	region  : "UK"
}

Go to Channel Groups