CPosix CPosix CWindows CFreeRTOSmbedPosix C Storage & Playback API Reference for Realtime Apps

PubNub's Storage & Playback feature enables developers to store messages as they are published, and retrieve them at a later time. Our storage layer is a time-series based database. Each published message is timestamped to the nearest 10 nanoseconds.

Learn more about our Storage & Playback feature here.

This function fetches historical messages of a channel.
PubNub Storage/Playback Service provides real-time access to an unlimited history for all messages published to PubNub. Stored messages are replicated across multiple availability zones in several geographical data center locations. Stored messages can be encrypted with AES-256 message encryption ensuring that they are not readable while stored on PubNub's network.
It is possible to control how messages are returned and in what order, for example you can:
  • Limit the number of messages to a specific quantity using the 4th argument parameter.
To run History you can use the following method(s) in the Posix C SDK
  1. ParameterTypeRequiredDescription
    ppubnub_t*YesPointer to Pubnub client context. Can't be NULL.
    channelconst char*YesThe string with the channel name to fetch the history
    countunsignedYesMaximum number of messages to get. If there are less than this available on the channel, you'll get less, but you can't get more.
    include_tokenboolYesIf true, include the time token for every message.

    default: false
Retrieve the last 100 messages on a channel:
// Sync
enum pubnub_res res;

pubnub_history(pn, "history_channel", 10, false);
res = pubnub_await(pn);

if (PNR_OK == res) {
  puts("Got history! Messages:");
  for (;;) {
    const char *msg = pubnub_get(pn);
    if (NULL == msg) {
      break;
    }
    puts(msg);
  }
} else {
  printf("Getting history failed with code: %d\n", res);
}

// Callback
void get_last_10_messages(pubnub_t *pn) {
  enum pubnub_res res;
  const char *msg;
 
  pubnub_register_callback(pn, sample_callback);
  pubnub_history(pn, "history_channel", 10, false);
  await();
  res = pubnub_last_result(pn);
 
  if (PNR_OK == res) {
    puts("Got history!");
    for (;;) {
      msg = pubnub_get(pn);
      if (NULL == msg) {
        break;
      }
      puts(msg);
    }
  } else {
    printf("Getting history failed with code: %d\n", res);
  }
}
An array is returned on success. The pubnub_history() function returns a list of up to 100 messages, the time token of the first (oldest) message and the time token of the last (newest) message in the resulting set of messages. The output below demonstrates the format for a pubnub_history() response:

[
	["message1", "message2", "message3",... ],
	"Start Time Token",
	"End Time Token"
]

Options for extended history.

  1. struct pubnub_history_options { bool string_token; int count; bool reverse; char const* start; char const* end; bool include_token; };

    MemberTypeDescription
    string_tokenboolIf false, the returned start and end Timetoken values will be returned as long ints. If true, the start and end Timetoken values will be returned as strings. Default is false.
    countintThe maximum number of messages to return per response. Has to be between 1 and 100 messages. Default is 100.
    reverseboolDirection of time traversal. Default is false, which means timeline is traversed newest to oldest.
    startchar const*If provided (not NULL), lets you select a “start date”, in Timetoken format. If not provided, it will default to current time. Page through results by providing a start OR end time token. Retrieve a slice of the time line by providing both a start AND end time token. start is exclusive – that is, the first item returned will be the one immediately after the start Timetoken value. Default is NULL.
    endchar const*If provided (not NULL), lets you select an “end date”, in Timetoken format. If not provided, it will provide up to the number of messages defined in the “count” parameter. Page through results by providing a start OR end time token. Retrieve a slice of the time line by providing both a start AND end time token. End is exclusive – that is, if a message is associated exactly with the end Timetoken, it will be included in the result. Default is NULL.
    include_tokenboolPass true to receive a timetoken with each history message. Defaults to false.

This returns the default options for publish V1 transactions. It's best to always call it to initialize the pubnub_history_options(), since it has several parameters.

  1. struct pubnub_history_options pubnub_history_defopts(void);

    This Method has not Argument.

struct pubnub_history_options opts = pubnub_history_defopts();
TypeValueDescription
struct pubnub_history_optionsThe default options for here-now.

The extended history. It is basically the same as the pubnub_history(), just adding a few options that will be sent.

  1. enum pubnub_res pubnub_history_ex(pubnub_t* pb, char const* channel, struct pubnub_history_options opt);

    ParameterTypeRequiredDescription
    pbpubnub_t*yesThe Pubnub context
    channelchar const*yesThe string with the channel name to get history for.
    optstruct pubnub_history_optionsyesHistory options.
struct pubnub_history_options opt = pubnub_history_defopts();
opt.reverse = true;
pbresult = pubnub_history_ex(pn, "my_channel", opt);
TypeValueDescription
enum pubnub_resPNR_STARTEDSuccess.
otherIndicates the type of error.

Contains channel name (as char memory block, aka Pascal string) and message count for messages received on the channel. The message counts are the number of messages published on one or more channels since a given time.

Used to store information retrieved by pubnub_message_counts() transaction.

  1. struct pubnub_chan_msg_count {pubnub_chamebl_t channel; size_t message_count; };

    MembersTypeDescription
    channelpubnub_chamebl_tChannel name as a char memory block (aka Pascal string)
    message_countsize_tNumber of messages for the channel

Returns the number of members (key->value pairs) of JSON object channels in the response to a message count transaction.

  1. int pubnub_get_chan_msg_counts_size(pubnub_t* pb);

    ParameterTypeRequiredDescription
    pbpubnub_t*YesThe Pubnub context in which to parse the response
int n  = pubnub_get_chan_msg_counts_size(pb);
printf("There are %d channels in the message counts response\n", n);
TypeValueDescription
int-1Error (transaction still in progress or other)
>= 0The number of members of the channels JSON object)

Starts the transaction pubnub_message_counts on the context @p pb for the list of channels @p channel for messages counts starting from @p timeoken which can be a single timetoken, or list of comma-separated timetokens (corresponding to the channel list).

 For keys with unlimited message retention enabled, this transaction considers only messages published in the last 7 days.
  1. enum pubnub_res pubnub_message_counts(pubnub_t* pb, char const* channel, char const* timetoken);

    ParameterTypeRequiredDescription
    pbpubnub_t*YesThe Pubnub context to use for transaction
    channelchar const*YesThe string with the channel name (or comma-delimited list of channel names) to subscribe for.
    timetokenchar const*YesA single token OR a comma-separated list of tokens. If single, will be used for all channels. If a list, has to have the same number of elements as @p channel and each will be used for its channel, in-order.
/** Obtain message count for
        channel 'one' since 15517035062228243 and
        channel 'two' since 15517035052228243. */
pbres = pubnub_message_counts(pb, "one,two", "15517035062228243,15517035052228243");
TypeValueDescription
enum pubnub_resPNR_STARTEDStarted
PNR_OKFinished with a success (can only happen in the sync interface)
otherFailed, Indicates the type of error
/** Obtain message count for channels
        'one' and 'two' since 15517035062228243 */
pbres = pubnub_message_counts(pb, "one,two", "15517035062228243");

On input, @p io_count is the number of allocated counters per channel (array dimension of @p chan_msg_counters). On output(@p io_count), number of counters per channel written. If there are more channel message counters in the answer than there are in the allocated array (can't fit all), that will not be considered an error, they will simply not be written to @p chan_msg_counters. To see how much elements there are (and allocate accordingly), use pubnub_get_chan_msg_counts_size().

This is an alternative to pubnub_get_message_counts(), useful for exploratory usage, as one can get all the channel message counters that are in the report, without keeping track of what were the requested channels.

 For keys with unlimited message retention enabled, this transaction considers only messages published in the last 7 days.
  1. int pubnub_get_chan_msg_counts(pubnub_t* pb, size_t* io_count, struct pubnub_chan_msg_count* chan_msg_counters);

    ParameterTypeRequiredDescription
    pbpubnub_t*YesThe Pubnub context to use for transaction
    io_countsize_t*YesOn input, the number of allocated counters per channel (array dimension of @p chan_msg_counters). On output, number of counters per channel written to @p chan_msg_counters.
    chan_msg_countersstruct pubnub_chan_msg_count*YesAn array of channel message counters, allocated by the caller, filled in by this function.
struct pubnub_chan_msg_count chan_msg_count[CHAN_COUNT];
size_t count = CHAN_COUNT;
int rslt = pubnub_get_chan_msg_counts(pb, &count, chan_msg_count);
if (0 == rslt) {
    size_t i;
    for (i = 0; i < count; ++i) {
        printf("  Channel    = '%.*s'\n", (int)chan_msg_count[i].channel.size, chan_msg_count[i].channel.ptr);
        printf("  Message count  = %z'\n", chan_msg_count[i].message_count);
    }
}
TypeValueDescription
int0Success (even if there are more channel message counts than is possible to write to @p chan_msg_counters)
-1Error, messages not read (transaction still in progress, format error...)
int n  = pubnub_get_chan_msg_counts_size(pb);
if (n > 0) {
    struct pubnub_chan_msg_count *pchmsc = malloc(n * sizeof *pchmsc);
    if (pchmsc != NULL) {
        size_t count = n;
        int rslt = pubnub_get_chan_msg_counts(pb, &count, pchmsc);
        if (0 == rslt) {
            printf("Got %z counters, should be the same as %d\n", count, n);
        }
        free(pchmsc);
    }
}

Reads message counters for the given channels (in @p channel) from the Pubnub response to pubnub_message_counts().

Array dimension for @p o_count is the number of channels from the comma-separated channel list @p channel and it (@p o_count array) is allocated by the caller.

Message counts order in @p o_count is corresponding to channel order in @p channel list respectively, even if the answer itself has the channels in a different order. If a requested channel is not found in the Pubnub response, the message counter in the respective @p o_count array member has a negative value.

If there is a channel name in the answer, not to be found in requested @p channel list, that is not considered an error.

This is an alternative to pubnub_get_chan_msg_count(), useful if we already maintain the list of channels and just want to get the message counters.

 For keys with unlimited message retention enabled, this transaction considers only messages published in the last 7 days.
  1. int pubnub_get_message_counts(pubnub_t* pb, char const*channel, int* o_count);

    ParameterTypeRequiredDescription
    pbpubnub_t*YesThe Pubnub context to use for transaction
    channelchar const*YesA comma-separated list of channels to read message counters from
    o_countint*YesAn array of message counters, allocated by the caller, filled in by this function.
int msg_count[2];
int rslt = pubnub_get_message_counts(pb, "one,two", msg_count);
if (0 == rslt) {
    printf("message counts: one -> %d, two -> %d\n", msg_count[0], msg_count[1]);
}
TypeValueDescription
int0Success (even if there are channel message counts int @p channel that are not there in the response or vice-versa)
-1Error, messages not read (transaction still in progress, format error...)