Message Persistence API for PubNub Windows C SDK

Message Persistence provides real-time access to the history of all messages published to PubNub. Each published message is timestamped to the nearest 10 nanoseconds and is stored across multiple availability zones in several geographical locations. Stored messages can be encrypted with AES-256 message encryption, ensuring that they are not readable while stored on PubNub's network. For more information, refer to Message Persistence.

Messages can be stored for a configurable duration or forever, as controlled by the retention policy that is configured on your account. The following options are available: 1 day, 7 days, 30 days, 3 months, 6 months, 1 year, or Unlimited.

You can retrieve the following:

• Messages
• Message actions
• File Sharing (using File Sharing API)

History

This function fetches historical messages of a channel. Message Persistence 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.

Method(s)

To run History you can use the following method(s) in the Windows C SDK

enum pubnub_res pubnub_history (pubnub_t *p, const char *channel, const char *channel_group, unsigned count)

Parameter	Type	Required	Description
p	pubnub_t*	Yes	Pointer to Pubnub client context. Can't be NULL.
channel	const char*	Yes	The string with the channel name to fetch the history
count	unsigned	Yes	Maximum 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_token	bool	Yes	If true, include the timetoken for every message. default: false

Basic Usage

Retrieve the last 100 messages on a channel:

// Sync
enum pubnub_res res;
const char *msg;

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

if (PNR_OK == res) {
  puts("Got history! Messages:");
  for (;;) {
    msg = pubnub_get(pn);
    if (NULL == msg) {
      break;
    }
    puts(msg);

show all 44 lines

Rest Response from Server

An array is returned on success.

The pubnub_history() function returns a list of up to 100 messages, the timetoken of the first (oldest) message and the timetoken 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"
]

Message Counts

Message count per channel structure

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.

Declaration

struct pubnub_chan_msg_count {pubnub_chamebl_t channel; size_t message_count; };

Members

Members	Type	Description
channel	pubnub_chamebl_t	Channel name as a char memory block (aka Pascal string)
message_count	size_t	Number of messages for the channel

Count channels in message count response

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

Declaration

int pubnub_get_chan_msg_counts_size(pubnub_t* pb);

Parameters

Parameter	Type	Required	Description
pb	pubnub_t*	Yes	The Pubnub context in which to parse the response

Basic Usage

int n  = pubnub_get_chan_msg_counts_size(pb);
printf("There are %d channels in the message counts response\n", n);

Returns

Type	Value	Description
int	-1	Error (transaction still in progress or other)
	>= 0	The number of members of the channels JSON object)

Message Counts transaction

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

Message retention

For keys with unlimited message retention enabled, this transaction considers only messages published in the last 30 days.

Declaration

enum pubnub_res pubnub_message_counts(pubnub_t* pb, char const* channel, char const* timetoken);

Parameters

Parameter	Type	Required	Description
pb	pubnub_t*	Yes	The Pubnub context to use for transaction
channel	char const*	Yes	The string with the channel name (or comma-delimited list of channel names) to subscribe for.
timetoken	char const*	Yes	A 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.

Basic Usage

/** Obtain message count for
        channel 'one' since 15517035062228243 and
        channel 'two' since 15517035052228243. */
pbres = pubnub_message_counts(pb, "one,two", "15517035062228243,15517035052228243");

Returns

Type	Value	Description
enum pubnub_res	PNR_STARTED	Started
	PNR_OK	Finished with a success (can only happen in the sync interface)
	other	Failed, Indicates the type of error

Example: Single token for all channels

/** Obtain message count for channels
        'one' and 'two' since 15517035062228243 */
pbres = pubnub_message_counts(pb, "one,two", "15517035062228243");

Read all channel message counts

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.

Message count

For keys with unlimited message retention enabled, this transaction considers only messages published in the last 30 days.

Declaration

int pubnub_get_chan_msg_counts(pubnub_t* pb, size_t* io_count, struct pubnub_chan_msg_count* chan_msg_counters);

Parameters

Parameter	Type	Required	Description
pb	pubnub_t*	Yes	The Pubnub context to use for transaction
io_count	size_t*	Yes	On 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_counters	struct pubnub_chan_msg_count*	Yes	An array of channel message counters, allocated by the caller, filled in by this function.

Basic Usage

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);
    }
}

Returns

Type	Value	Description
int	0	Success (even if there are more channel message counts than is possible to write to @p chan_msg_counters)
	-1	Error, messages not read (transaction still in progress, format error...)

Example: Make sure we have room for all the channel message counters

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);
    }
}

Read counters for channels

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.

Message count

For keys with unlimited message retention enabled, this transaction considers only messages published in the last 30 days.

Declaration

int pubnub_get_message_counts(pubnub_t* pb, char const*channel, int* o_count);

Parameters

Parameter	Type	Required	Description
pb	pubnub_t*	Yes	The Pubnub context to use for transaction
channel	char const*	Yes	A comma-separated list of channels to read message counters from
o_count	int*	Yes	An array of message counters, allocated by the caller, filled in by this function.

Basic Usage

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]);
}

Returns

Type	Value	Description
int	0	Success (even if there are channel message counts int @p channel that are not there in the response or vice-versa)
	-1	Error, messages not read (transaction still in progress, format error...)