Presence API for PubNub POSIX C++ SDK

Presence enables you to track the online and offline status of users and devices in real time and 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 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:

Get a list of active UUIDs on a single channel​

here_now (std::string const &channel, std::string const &channel_group="")
ParameterTypeRequiredDescription
channelstd::string const &YesSpecifies channel for which to return active uuids.
channel_groupstd::string const &OptionalSpecifies channel_group for which to return active uuids.

Get a list of active UUIDs on multiple channels​

here_now (std::vector<std::string> const &channel, std::vector<std::string> const &channel_group)
ParameterTypeRequiredDescription
channelstd::string const &YesSpecifies channel vector for which to return active uuids.
channel_groupstd::string const &YesSpecifies channel_group vector for which to return active uuids.

Basic Usage​

Get a list of uuids subscribed to channel​

// Sync
void here_now(pubnub::context &pn) {
  enum pubnub_res res;

  res = pn.here_now("my_channel").await();

  if (PNR_OK == res) {
    std::cout << pn.get() << std::endl;
  } else {
    std::cout << "Here Now request failed" << std::endl;
  }
}

// Lambdas
void here_now(pubnub::context &pn) {
show all 36 lines

Rest Response from Server​

The here_now() function returns a list of uuids 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

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 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 where_now() you can use the following method(s) in the Posix C++ SDK:

where_now (std::string const &uuid="")
ParameterTypeRequiredDescription
uuidstd::string const &YesSpecifies uuid for which current subscribed channels info is required

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
static void where_now(pubnub::context &pn) {
  enum pubnub_res res;

  try {
    res = pn.where_now("my_uuid").await();

    if (PNR_OK == res) {
      std::cout <<  pn.get() << std::endl;
    } else {
      std::cout << "Failed with code " << res << std::endl;
    }
  } catch (std::exception &ex) {
    std::cout << "Exception: " << ex.what() << std::endl;
  }
show all 41 lines

Rest Response from Server​

The 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​
set_state (std::string const &channel, std::string const &channel_group, std::string const &uuid, std::string const &state)
ParameterTypeRequiredDescription
channelstd::string const &YesChannel to set state on
channel_groupstd::string const &YesChannel_group to set state on
uuidstd::string const &YesUUID
statestd::string const &YesSerialized JSON state
Set State with Options​
set_state (std::string const &channel, const &state, set_state_options options )
ParameterTypeRequiredDescription
channelstd::string const &YesChannel to set state on
statestd::string const &YesSerialized JSON state
optionsset_state_optionsYesExtra options for this call. Refer to the section below for more information.
set_state_options​
ParameterTypeRequiredDescription
channel_groupstd::stringOptionalThe string with the channel name (or comma-delimited list of channel group names) to set state for.
user_idstd::stringYesThe user_id of the user for which to set state for. If NULL, the current user_id is used.
heartbeatboolYesIf set to true, you can set the state and make a heartbeat call at the same time via the /heartbeat endpoint.
Get State​
state_get (std::string const &channel, std::string const &channel_group="", std::string const &uuid="")
ParameterTypeRequiredDescription
channelstd::string const &YesChannel to get state.
channel_groupstd::string const &OptionalChannel group to get the state.
uuidstd::string const &OptionalUUID

Basic Usage​

Set State​

static void set_state(pubnub::context &pn) {
  enum pubnub_res res;

  try {
    std::string state("{\"first\":\"Robert\", \"last\":\"Plant\", \"age\":59, \"region\":\"UK\"}");
    res = pn.set_state("my_channel", "", "my_uuid", state).await();

    if (PNR_OK == res) {
      std::cout <<  pn.get() << std::endl;
    } else {
      std::cout << "Failed with code " << res << std::endl;
    }
  } catch (std::exception &ex) {
    std::cout << "Exception: " << ex.what() << std::endl;
  }
show all 16 lines

Set State with Heartbeat​

std::cout << "Setting state with options" << std::endl;
  if (PNR_OK ==  pb.set_state(
      chan, "{\"x\":5}", pubnub::set_state_options().heartbeat(true)
    ).await()) {
      std::cout << "State was set: " << pb.get() << std::endl;
    }
    else {
        std::cout << "Setting state failed!" << std::endl;
    }

Get State​

static void get_state(pubnub::context &pn) {
  enum pubnub_res res;

  try {
    res = pn.state_get("my_channel", "", "my_uuid").await();

    if (PNR_OK == res) {
      std::cout <<  pn.get() << std::endl;
    } else {
      std::cout << "Failed with code " << res << std::endl;
    }
  } catch (std::exception &ex) {
    std::cout << "Exception: " << ex.what() << std::endl;
  }
}

Returns​

The state API returns a JSON object containing key value pairs.

{
    first   : "Robert",
    last    : "Plant",
    age     : 59,
    region  : "UK"
}

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)​

pb.heartbeat(std::string const& channel, std::string const& channel_group)
ParameterTypeRequiredDescription
channelstd::string const&OptionalThe string with the channel name (or comma-delimited list of channel names) to notify.
channel_groupstd::string const&OptionalThe string with the channel_group name (or comma-delimited list of channel group names) to notify.

Basic Usage​

res = pb.heartbeat(chan, NULL).await();
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.

Last updated on
On this page